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 iOS/Android application, which allows you to scan and connect to nearby LinkIt 7697 devices running the LRemote library, and send commands to them.

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

Example Sketch

To run the example, open Arduino IDE menu File > Examples > LRemote > RemoteControl example, and upload the sketch to LinkIt 7967.
Keep LinkIt 7697 powered on
Launch the LinkIt Remote app, and a "LinkIt 7" or "LinkIt 7697" device should appear in the device list.

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.

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

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.

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

Understanding the Example Sketch

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.

  // 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
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.

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

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

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.

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:

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();
 
  // ...
}

Always call LRemote.process() before checking UI control values, e.g. isValueChanged() or getValue().

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

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

PreviousLBLEClient NextLRemote

Last updated 3 years ago

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); }

// 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();