# Using LinkIt Remote

**LinkIt Remote** is a tool to easily create an iOS/Android remote UI for your LinkIt 7697 Arduino projects. It consists of two software:

* The Arduino **LRemote** library for LinkIt 7697, which allows you to declare remote UI controls in your Arduino project.
* The [**LinkIt Remote**](https://itunes.apple.com/us/app/linkit-remote/id1276900625?mt=8) iOS/Android application, which allows you to scan and connect to nearby LinkIt 7697 devices running the **LRemote** library, and send commands to them.

[![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FZ6ijVOqZqiKXphfhzdtf%2Fitunes-store-badge.png?alt=media\&token=4f1441e6-6442-402a-b3b9-718baceecad7)](https://apps.apple.com/us/app/linkit-remote/id1276900625) [![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2Fo6hBmOYTDlQw6ePxWCk9%2Fplay-store-badge.png?alt=media\&token=91f30c12-bedb-4285-a4a3-57a9e6df32f2)](https://play.google.com/store/apps/details?id=com.mediatek.labs.linkitremote)

The Arduino library and iOS/Android app communicates to each other through Bluetooth Low Energy.

![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2F59eqh0eU4NAxlFQO1kVo%2Fimage2017-9-5%2B15_35_46.png?alt=media\&token=f1ab535e-f49a-4f57-bd0c-d3973435d422)

### Example Sketch <a href="#usinglinkitremote-examplesketch" id="usinglinkitremote-examplesketch"></a>

1. To run the example, open Arduino IDE menu **File > Examples > LRemote > RemoteControl** example, and upload the sketch to LinkIt 7967.
2. Keep LinkIt 7697 powered on
3. Download and install [**LinkIt Remote**](https://itunes.apple.com/us/app/linkit-remote/id1276900625?mt=8) from the store link below:\
   [![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FZ6ijVOqZqiKXphfhzdtf%2Fitunes-store-badge.png?alt=media\&token=4f1441e6-6442-402a-b3b9-718baceecad7)](https://apps.apple.com/us/app/linkit-remote/id1276900625) [![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2Fo6hBmOYTDlQw6ePxWCk9%2Fplay-store-badge.png?alt=media\&token=91f30c12-bedb-4285-a4a3-57a9e6df32f2)](https://play.google.com/store/apps/details?id=com.mediatek.labs.linkitremote)
4. Launch the **LinkIt Remote** app, and a **"LinkIt 7"** or **"LinkIt 7697"** device should appear in the device list.

{% hint style="info" %}
Due to the limitation in BLE advertisement packet length, the device name may be truncated to "LinkIt 7". The device name will be fully displayed after connecting to it. iOS will cache the device name, so next time the app displays full device name. On an Android device, the device name is always truncated.
{% endhint %}

![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2Fx9YwSb9VR3OkvXDwS5mO%2FScreen%2BShot%2B2017-09-01%2Bat%2B14.38.33.png?alt=media\&token=7bd39867-0f99-48b3-998a-38b8e4ee4918)

5.Tap on the LinkIt 7697 item, the app connects to LinkIt 7697 and display the following remote UI control:

![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FZIF5FphgLxIfCwPTdqIA%2FScreen%2BShot%2B2017-09-01%2Bat%2B14.40.41.png?alt=media\&token=f4b4a23a-c2e8-4798-ae35-34014694d24b)

6.Now tap the **USR LED** switch button, the onboard USR LED on the LinkIt 7697 should now light up.

7.Open the Arduino Serial Monitor, and drag the **Value Slider**. The Serial Monitor will print the new values you just dragged to.

![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FbmCqYbwyelYUdfmIvluN%2Fimage2017-9-6%2B10_0_30.png?alt=media\&token=bdf53952-8182-4202-a6f5-5a16107d3c4c)

That's it - you now have a remote control UI to your Arduino device.

### Understanding the Example Sketch <a href="#usinglinkitremote-understandingtheexamplesketch" id="usinglinkitremote-understandingtheexamplesketch"></a>

The example we just demonstrated creates a BLE device named **LinkIt 7697**, and adds several GATT attributes that represents UI controls. The **LinkIt Remote** app parses these GATT attributes and displays the remote UI controls accordingly.

To use LRemote library, the first step is to configure the device. With **LRemote** library, you can simply set the device name, it's mobile UI orientation, and the **layout grid** size.&#x20;

```
  // Setup the Remote Control's UI canvas
  LRemote.setName("LinkIt 7697");
  LRemote.setOrientation(RC_PORTRAIT);
  LRemote.setGrid(3, 5);
```

In the example above,

* we configure a device named **LinkIt 7697**, and&#x20;
* assign the layout grid to be a **3 x 5** **portrait** grid. The grid is invisible on the Remote UI, and is used as a reference coordinate for control position and size, as shown below.

![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FSlbIDJ39eFD8soD09OsW%2Fgrid.png?alt=media\&token=85d370e5-8a34-4efd-9e2e-cca97ae81c0a)

After setting the grid, we can start adding UI controls to the grid. For example, to create the **USR LED** button, first we declare a **LRemoteSwitch** in the **global** scope, as shown below:

```
#include <LRemote.h>
 
LRemoteSwitch switchButton;
```

and then we configure the text label, size, and position of the switch button:

```
void setup() {
  // Add an on/off switch
  switchButton.setText("USR LED");
  switchButton.setPos(0, 1);
  switchButton.setSize(1, 1);
  switchButton.setColor(RC_BLUE);
  LRemote.addControl(switchButton);
}
```

* We set the text label as "**USR LED**"
* The position parameter is (0, 1), which maps to the first column and second row, as shown below

![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2F12BivjoPGgwGWFX3jd2b%2Fpos.png?alt=media\&token=33ac1f23-17cc-41a4-b0a1-b052f9a2f1e3)

* and we set the color to **RC\_BLUE**
* finally, we call **LRemote.addControl(switchButton)** to add the switch to the remote control UI

{% hint style="info" %}
You must declare the controls in **global scope** and then call **LRemote.addControl** in the setup() function. Otherwise the control will not appear correctly in the UI.
{% endhint %}

After setting up the controls, we call **LRemote.begin()** to start advertise our device.

```
  // Start broadcasting our remote contoller
  // This method implicitly initialized underlying BLE subsystem
  // to create a BLE peripheral, and then
  // start advertisement on it.
  LRemote.begin();
```

We can then use **LRemote.connected()** to check if the LinkIt Remote app has connected to our device:

```
  if(!LRemote.connected()) {
    Serial.println("waiting for connection");
    delay(1000);
  }
```

Once the **LinkIt Remote** app establishes the connection, it will retrieve our UI layout configuration, and display the switch button accordingly:

![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FwQja99HR9mCrdqcFHXqg%2Fimage2017-9-5%2B16_15_35.png?alt=media\&token=9fdd8b58-a3b4-465e-a5dc-76f025b4d07b)

The app sends commands to LinkIt 7697 if the user made changes to the remote UI. To process these commands, we call **LRemote.process()** in the loop() function to periodically check for new commands:

```
void loop() {

  // Process the incoming BLE write request
  // and translate them to control events
  LRemote.process();
 
  // ...
}
```

{% hint style="info" %}
Always call **LRemote.process()** before checking UI control values, e.g. **isValueChanged()** or **getValue().**
{% endhint %}

Once the commands are processed, the **LRemote** updates the values and state of each control. For a **LRemoteSwitch**, you can use

* **LRemoteSwitch::isValueChanged()** to check if the user has made changes to the switch
* **LRemoteSwitch::getValue()** to get the current value of the switch
  * **0** means the switch is **off**
  * **1** means the switch is **on**

The example code below turns on the USR LED once the user turns on the switch button in the app:

```
  if(switchButton.isValueChanged()){
    digitalWrite(LED_BUILTIN, switchButton.getValue());
  }
```

Sliders (**LRemoteSlider**) have the same set of APIs, except that **getValue()** returns the slider value instead.

Buttons(**LRemoteButton** and **LRemoteCircleButton**) have the same set of APIs, and

* **getValue()** returns **0** when the button is not being **pressed**
* **getValue()** returns **1** when the button is being **pressed**

You can also add **LRemoteLabel** that displays a one-line text. The user cannot interact with it, so it does not support the **getValue()** API.

### Open Source Libraries <a href="#usinglinkitremote-opensourcelibraries" id="usinglinkitremote-opensourcelibraries"></a>

Following open source libraries are used in LRemote library and LinkIt Remote app:

* [JoystickView](https://github.com/CatchZeng/JoystickView)
* [Arduino Queue](https://github.com/sdesalas/Arduino-Queue.h)
* [virtual-joystick-android](https://github.com/controlwear/virtual-joystick-android)
