> 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-arduinoide/kai-fa-zhi-nan/shi-yong-linkit-remote/lremote-api.md).

# LRemote API

**LRemote** 這個程式庫主要用來讓使用者創造並且設定手機上的 LinkIt Remote 遙控介面。此程式庫的主要功能便是儲存使用者設定的介面參數，並將其傳送到手機端，以及接收來自手機端的指令。

{% hint style="danger" %}
**LRemote** 會隱含使用 **LBLE** 程式庫，所以我們建議不要將這兩個程式庫混合使用，以免彼此干擾。
{% endhint %}

要使用這個類別的話，請依循下列步驟：

* `在 Arduino 檔案當中引入 #include <LRemote.h>`&#x20;
* 呼叫 **setName**(), **setGrid**() and **setOrientation**() 來設定裝置的名稱與介面的排版網格
* 在全域變數定義控制元件，然後用 **addControls**() 來將控制元件加入到遙控器介面當中
* 呼叫 **begin**() 來啟動遙控器裝置，並等待 LinkIt Remote 手機程式連線
* 用 **connected**() 來確認是否有手機程式連接
* 定期呼叫 **process**() 來處理來自手機的指令，並且更新控制元件的數值

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

&#x20;setName()

&#x20;setGrid()

&#x20;setOrientation()

addControl()

begin()

connected()

process()

{% tabs %}
{% tab title="setName()" %}
設定裝置名稱。請注意，因為低功耗藍牙的廣播資訊有長度限制，所以裝置名稱可能會被裁剪。

**Syntax**

**Parameters**

name: **String** 型別，代表裝置名稱

**Returns**

none
{% endtab %}

{% tab title="setGrid()" %}
設定遙控器介面的排版用網格。

**Syntax**

**Parameters**

column: 網格等分為列的數目

row: 網格等分為行的數目

**Returns**

none
{% endtab %}

{% tab title=" setOrientation()" %}
設定想要的遙控器介面的方向

**Syntax**

**Parameters**

orientation: 可以是 **RC\_PORTRAIT** （直向）或是 **RC\_LANDSCAPE** （橫向）。預設的方向是直向。

**Returns**

none
{% endtab %}

{% tab title="addControl()" %}
將控制元件加入顯示畫面之中

**Syntax**

**Parameters**

control: 下列這些控制元件類別之一的物件：

* LRemoteButton
* LRemoteSlider
* LRemoteLabel
* LRemoteSwitch
* LRemoteCircleButton

需要注意的是，傳遞給 addControl 參數的物件，其生命週期一定要比 LRemote 長，所以建議將控制元件的物件宣告為**全域變數**

請注意切勿將宣告為區域變數（local scope）的控制元件物件傳遞給 addControl，否則可能會導致嚴重的錯誤。

**Returns**

none
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="begin()" %}
初始化底層的藍牙子系統以及 GATT 伺服器，並開始廣播本機資訊。此 API 會隱含呼叫 **LBLE.begin()**

**Syntax**

none

**Returns**

none
{% endtab %}

{% tab title="connected()" %}
檢查是否有手機的 LinkIt Remote 程式連線到此裝置。

**Syntax**

none

**Returns**

**true** 代表 LinkIt Remote 手機程式已經連線到此裝置 ，**false** 則否。
{% endtab %}

{% tab title="process()" %}
處理來自 LinkIt Remote 手機程式的各種指令。請在 Arduino 程式的 loop() 函式中，持續的呼叫此方法。

**Syntax**

none

**Returns**

none

如果沒有呼叫此方法，那麼 LRemote 當中的 UI 控制元件的狀態以及數值將無法正確更新。
{% endtab %}
{% endtabs %}