Build a Beacon controlled by MCS Lite

In this tutorial, we'll show a scenario seen in common IoT application fields. Major components for this scenario are:

1. An IoT gateway by LinkIt Smart 7688, which equips rich resources for data manipulation and transmission. All nodes connected to it inside this field rely on this gateway to the internet.

2. IoT endpoint nodes by LinkIt 7697, which provides light-weight and power-efficient devices for endpoint deployment.

3. A user platform like a mobile phone, which is used to interact with endpoint nodes and/or the gateway control.

Credit

Icons made by Freepik and Gregor Cresnar from www.flaticon.com are licensed by CC 3.0 BY.

In the following sections, the setup of each component listed above will be explained and we hope this example helps developers to build your own system. Based on this configuration, it can be extended to a more generic setup for fitting into different IoT application scenarios.

IoT Gateway - LinkIt Smart 7688 as a private cloud server and a Wi-Fi repeater

A gateway is a more powerful device comparing to endpoint nodes. It is usually in charge of the data manipulation and transmission. Here a LinkIt Smart 7688 is set up as a MCS Lite server, which provides a local and private cloud service for handing data points generating within this private network. Moreover, this LinkIt Smart 7688 is configured as a Wi-Fi repeater for providing Internet connection to all devices in its local network. Two tutorials are listed below for configuring the LinkIt Smart 7688 as a MCS Lite server and a Wi-Fi repeater:

• Configure 7688 as a MCS Lite server

• Switch 7688 to Repeater Mode

And you need to refer to another tutorial for building a test device with MCS Lite for controlling the onboard LED of the LinkIt 7697, which is the setup will be used in this tutorial. The test device consists of

• A device id,

• A device key,

• An ON/OFF type display channel named switch_display, and

• An ON/OFF type control channel named switch_controller.

These information is needed when you prepare the Arduino sketch codes for the LinkIt 7697.

IoT Endpoint Node - LinkIt 7697 as a node device and a BLE beacon

There are two related tutorials for this topic:

• Control 7697 LED with MCS Lite

• Configure 7697 as an Eddystone URL beacon

Here an integrated example is shown for making a LinkIt 7697, which is controlled by MCS Lite, become a BLE beacon advertising the URL of the MCS Lite control page. As a result, whenever a user platform (e.g. a mobile phone) comes across with this node, the user can get the MCS Lite control page for this node automatically without typing the URL manually. The source codes come from the combination of the two 7697 tutorials mentioned above with modifications. In the following sections, all major modifications will be explained. For accessing the complete Arduino sketch file, go to the Appendix section in the end of this article.

Configure the AP information

At the beginning, you need to specify the SSID and password information about the IoT gateway so that the LinkIt 7697 can join the private network and access the local cloud service provided by MCS Lite.

// Assign AP ssid / password here 
#define _SSID "YOUR_AP_NAME" 
#define _KEY "YOUR_PASSWORD"

And the LinkIt 7697 will connect to the Wi-Fi AP in line 58, based on the information provided above:

Serial.print("WiFi.begin(");
Serial.print(_SSID);
Serial.print(",");
Serial.print(_KEY);
Serial.println(")...");
WiFi.begin(_SSID, _KEY);

Although it's not recommended and is with security concern, if you somehow want to connect to a Wi-Fi AP without requiring a password, you can modify the line 58 to make the LinkIt 7697 connect to it without a password:

Assign the device information for MCS Lite and the address of the MCS Lite server

In order to connect to the MCS Lite server, you need to specify the address for the server and the device id and the device key for making this LinkIt 7697 recognizable by the server. Edit line 14 in the sketch file for assigning correct information:

MCSLiteDevice mcs("YOUR_DEVICE_ID", "YOUR_DEVICE_KEY", "MCS_LITE_SERVER_ADDRESS", MCS_LITE_SERVICE_PORT);

The first and the second fields are for the device id and device key shown in the MCS Lite control console. The third and the fourth fields are the address and port information about the MCS Lite server. You can get these information after you've launched the service.

Define the MCS Lite channel information

When building the test device for this example, two channels are defined for displaying and controlling. Therefore they need to be declared in the sketch file for making the server identify them correctly:

MCSControllerOnOff led("switch_controller"); 
MCSDisplayOnOff remote("switch_display");

Setup the Eddystone URL for BLE advertisement

For making users easily access the control console of the MCS Lite service, the IoT endpoint node will advertise the URL of the MCS Lite control page via the BLE beacon mechanism. When your user platform (e.g. a mobile phone) supports BLE and has an APP which understands the Eddystone URL beacon, you can automatically get the URL of the MCS Lite control page for this endpoint device. In line 44, you need to assign the URL you want to advertise with the Eddystone format:

beaconData.configAsEddystoneURL(EDDY_HTTPS, "goo.gl/evYXvt");

Since there is a limitation about the allowable length of an Eddystone URL (17 bytes), you can use any URL shortening services to create a simplified URL used in the advertisement. In this example, the URL "http://mylinkit.local:3000" is mapped to "goo.gl/evYXvt". For detailed explanation for configuring an Eddystone URL, you can visit the "Using LinkIt 7697 as an Eddystone-URL Beacon" section in the 7697 Beacon tutorial.

User Platform Configuration

Note

Make sure the Wi-Fi and the BLE functions are turned on for the user platform and confirm it has connected to the IoT gateway before going into the following steps.

For recognizing the Eddystone advertisement, you need to install an application which supports the Eddystone URL beacon discovery. The Physical Web APP is one of those choices for getting this function in your mobile phone:

• Android download link

• iOS download link

After the installation is done, when you launch the APP and your phone is close to the LinkIt 7697, you can see the URL advertisement as below:

It is also available in the widget mode so you can see the advertisement in the widget view:

When you click the URL discovered by this APP, you'll be redirected to the link for accessing the control page:

After signing into the MCS Lite service, you can use your mobile phone to see and control the status of the onboard LED of the LinkIt 7697:

Appendix

Here is the complete Arduino sketch file for the program running on the LinkIt 7697:

#include <LWiFi.h>
#include <WiFiClient.h>
#include "MCS.h"

#include <LBLE.h>
#include <LBLEPeriphral.h>

// Assign AP ssid / password here
#define _SSID "YOUR_AP_NAME"
#define _KEY  "YOUR_PASSWORD"

// Assign device id / key of your test device
//MCSDevice mcs("YOUR_DEVICE_ID", "YOUR_DEVICE_KEY");
MCSLiteDevice mcs("YOUR_DEVICE_ID", "YOUR_DEVICE_KEY", "MCS_LITE_SERVER_ADDRESS", MCS_LITE_SERVICE_PORT);

// Assign channel id 
// The test device should have 2 channel
// the first channel should be "Controller" - "On/Off"
// the secord channel should be "Display" - "On/Off"
MCSControllerOnOff led("switch_controller");
MCSDisplayOnOff    remote("switch_display");

#define LED_PIN 7

void setup() {
  // setup Serial output at 9600
  Serial.begin(9600);

  // setup LED/Button pin
  pinMode(LED_PIN, OUTPUT);

  // Initialize BLE subsystem
  Serial.println("BLE begin");
  LBLE.begin();
  while (!LBLE.ready()) {
    delay(100);
  }
  Serial.println("BLE ready");
  
  // configure our advertisement data as iBeacon.
  LBLEAdvertisementData beaconData;

  // make an Eddystone-URL beacon that this board casts
  beaconData.configAsEddystoneURL(EDDY_HTTPS, "goo.gl/evYXvt");
  Serial.print("Start advertising Eddystone-URL");

  // start advertising it
  LBLEPeripheral.advertiseAsBeacon(beaconData);
  
  // setup Wifi connection
  while(WL_CONNECTED != WiFi.status())
  {
    Serial.print("WiFi.begin(");
    Serial.print(_SSID);
    Serial.print(",");
    Serial.print(_KEY);
    Serial.println(")...");
    WiFi.begin(_SSID);
  }
  Serial.println("WiFi connected !!");

  // setup MCS connection
  mcs.addChannel(led);
  mcs.addChannel(remote);
  while(!mcs.connected())
  {
    Serial.println("MCS.connect()...");
    mcs.connect();
  }
  Serial.println("MCS connected !!");

  // read LED value from MCS server
  while(!led.valid())
  {
    Serial.println("read LED value from MCS...");
    led.value();
  }
  Serial.print("done, LED value = ");
  Serial.println(led.value());
  digitalWrite(LED_PIN, led.value() ? HIGH : LOW);
}

void loop() {
  // call process() to allow background processing, add timeout to avoid high cpu usage
  mcs.process(100);
  
  // updated flag will be cleared in process(), user must check it after process() call.
  if(led.updated())
  {
    Serial.print("LED updated, new value = ");
    Serial.println(led.value());
    digitalWrite(LED_PIN, led.value() ? HIGH : LOW);
    if(!remote.set(led.value()))
    {
      Serial.print("Failed to update remote");
      Serial.println(remote.value());
    }
  }
  
  // check if need to re-connect
  while(!mcs.connected())
  {
    Serial.println("re-connect to MCS...");
    mcs.connect();
    if(mcs.connected())
      Serial.println("MCS connected !!");
  }
}