> For the complete documentation index, see [llms.txt](https://cavedu.gitbook.io/linkit-7697/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cavedu.gitbook.io/linkit-7697/linkit-7697-development-guide-for-arduino-ide/developer-guide/using-linkit-remote/lremote.md).

# LRemote

**LRemote** is a singleton object that allows user to design a remote control UI. It's main purpose is to hold the UI control settings and convert them to LBLE GATT attributes. 

{% hint style="danger" %}
**LRemote** initializes and uses **LBLE** library implicitly. Therefore, we suggest preventing mixing calls to LRemote and LBLE library.
{% endhint %}

To use it, 

* `#include <LRemote.h>` in your LinkIt 7697 Arduino sketch.
* Call **setName**(), **setGrid**() and **setOrientation**() to configure the device and remote UI canvas grid first.
* Add control objects with **addControls**() API.
* Call **begin**() to initiate the device and start advertisement to LinkIt Remote mobile app.
* Use **connected**() to check if the mobile app has connected.
* Call **process**() periodically to update control status and value.

### Methods <a href="#lremote-methods" id="lremote-methods"></a>

&#x20;setName()

&#x20;setGrid()

&#x20;setOrientation()

&#x20;addControl()

&#x20;begin()

&#x20;connected()

&#x20;process()

{% tabs %}
{% tab title="setName()" %}
Set the device name. Note that BLE advertisement have length limitation, so this name may be truncated when being advertised.

**Syntax**

**Parameters**

name: a **String** representing the name of the device.

**Returns**

none
{% endtab %}

{% tab title="setGrid()" %}
Set the canvas grid as a referencing coordinate for control position and size.

**Syntax**

**Parameters**

column: number of columns in the grid

row: number of rows in the grid

**Returns**

none
{% endtab %}

{% tab title=" setOrientation()" %}
Set desired UI orientation for the remote UI.

**Syntax**

**Parameters**

orientation: can be **RC\_PORTRAIT** or **RC\_LANDSCAPE**. The default value for orientation is portrait.

**Returns**

none
{% endtab %}

{% tab title="addControl()" %}
Add a UI control element to the canvas

**Syntax**

**Parameters**

control: an instance of the UI control classes, including:

* LRemoteButton
* LRemoteSlider
* LRemoteLabel
* LRemoteSwitch
* LRemoteCircleButton

Note that the control instance must have the same life span as LRemote - so these instances should be defined in **global scope**

Don't define UI control objects such as LRemoteButton in the local scope, e.g. inside the function body of **setup()** and **loop()**

**Returns**

none
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="begin()" %}
Initialize the underlying BLE device and start advertisement. This API implicitly calls **LBLE.begin()**

**Syntax**

none

**Returns**

none
{% endtab %}

{% tab title=" connected()" %}
Check if the LinkIt Remote app has connected.

**Syntax**

none

**Returns**

**true** if the LinkIt Remote app has connected to this device. **false** otherwise.
{% endtab %}

{% tab title=" process()" %}
Processes incoming commands from the LinkIt Remote mobile app. Call this API periodically in the **loop()** function.

&#x20;Syntax

none

**Returns**

none

Failing to call this API will cause incorrect state and value of the UI controls.
{% endtab %}
{% endtabs %}