Searching...

Matching results

Connecting HL module-based Arduino application to AirVantage

Objective

This tutorial describes how to create communication between AirVantage and Arduino-based system equiped with an AirPrime HL wireless module. The following use cases are covered:

• Sending custom data such as sensor values or application data from Arduino to AirVantage
• Sending commands or configuration from AirVantage to Arduino

To implement this solution, MQTT protocol will be used.

Let’s develop a simple Alarm system to better showcase the solution in 4 main steps:

1. Setup Arduino Hardware
2. Setup Arduino Software Development Environment
3. Define Arduino-AirVantage Interface
4. Develop a simple Alarm system

Prerequisite

Important Note: The current HL Shield is no longer available for sale. This tutorial is still available as it illustrates how to use an HL with AT commands to send MQTT messages.

1. HL Shield + Antenna + Power adaptor + USB cable MiniB-A
2. AirPrime HL series Module
3. SIM card with data call plan
4. Arduino Mega2560 + USB cable type B-A
5. USB Hub (3 ports or more) + TTL to Serial USB cable (E.g. TTL-232R)
6. LED + PIR Motion detection sensor
7. Female to female wiring cable
8. Have an account on AirVantage server : eu.airvantage.net

Part references used in this tutorial

Any issues ?

If you encounter any issue to set up your device, don’t hesitate to use the developer forum to benefit from the developer community experience.

Connecting the Debug cable

• Connect the TTL to Serial Debug cable to Arduino’s pin #8 and GND as shown in the previous photo
• Pins #2 and #8 of Arduino will be configured programmatically as an serial port for debug output purpose
• Refer to the datasheet of your TTL cable, to perform the following connection:
  • the TX wire cannot be connected to Arduino’s pin #2 (RX) as it is not accessible. Not an issue as Debug output does not make use of RX.
  • the RX wire must be connected to Arduino’s pin #8 (TX)
  • the Ground wire must be connected to Arduino’s GND pin
• Connect the TTL cable to USB Hub which is connected to your PC/Mac
  • If USB driver is missing, VCP driver for FTDI-based TTL cables can be downloaded here

In Step 1, we’ve covered how to:

1. Configure HL Shield and stack it over the Arduino Mega2560 board
2. Connect HL Module’s UART to your host USB port
3. Connect a debug cable (virtual serial port emulated on Arduino pin 2 & 8) to your host USB port
4. Reference to USB driver has also been provided

Setup Embedded Software Development Components

• Download and install Arduino IDE.
• Launch Arduino IDE
• Import SWIR_MQTTClient library, V0.92
  • Download the Arduino MQTTClient library for Sierra Wireless HL serie modules here
  • In Arduino IDE, go to Sketch menu, select Include Library, then Add .ZIP Library…
  • Select the SWIR_MQTTClient lib zip file as downloaded in the previous step (e.g. SWIR_MQTTClient V0.92.zip)
• Import Paho MQTTClient library
  • Download the prebuilt Arduino port of Paho MQTTClient here
  • In Arduino IDE, go to Sketch menu, select Include Library, then Add .ZIP Library…
  • Select the Paho MQTTCleint zip file as downloaded in the previous step (e.g. arduino_1.0.0.zip)

Setup Debug output

• Unplug all USB plugs on the HUB Hub, while maintaining this latter plugged to your host computer. The intent here is to disconnect the host from all Arduino/HL Shield USB cables. All virtual COM ports are thus released on the host.
• Debug trace log for Arduino app
  • Launch your favorite Serial monitor software or use the provided TestCom.exe
  • Plug the TTL to Serial USB cable to the USB Hub, a virtual COM port shall be mounted accordingly
  • Select this virtual COM port and choose 115200 baudrate to open this port in the Serial monitor application
• Output log for HL Module
  • Launch a second instance of your favorite Serial monitor software or use the provided TestCom.exe
  • Connect the HL Shield Main UART USB port to the USB Hub, a virtual COM port shall be mounted accordingly
  • Select this virtual COM port and choose 115200 baudrate to open this port in the Serial monitor application

TestCom.exe tip: When plugging/unplugging a USB device, the associated virtual COM port is displayed in TestCom. Identifying the virtual COM to be openned is then made easy in the 2 above steps.

In Step 2, we’ve covered the following:

1. Overview of the HL module-based Arduino system
2. Installation of :
   • Arduino IDE
   • MQTTClient adapter Library for Sierra Wireless HL Serie Modules
   • Paho MQTTClient Library
3. Setup output tracing to view:
   • Arduino application debug trace log
   • HL Module’s AT interface trace log

Alarm System Application Model

• An embedded application on device-side (e.g. Arduino) is interfacing with a server-side application on AirVantage in order to exchange predefined data over a predefined communication protocol and authentication scheme:
  • Server-side application is defined by an Application Model (a XML file)
  • AirVantage uses this XML file to figure out how to deal with the device about Communication Protocol, Authentication and Data Exchange (e.g. variable, settings, commands)

• Based on the use case as described in the previous section, the application model for our Alarm System is defined here :

  • The communication protocol is MQTT, and the authentication is based on the device’s IMEI

  <communication>
      <protocol comm-id="IMEI" type="MQTT" />
  </communication>
  

  • The downstream TurnOn action command and the upstream motion event are defined in an asset labeled My Home, exchanged over MQTT protocol:

  <data>
      <encoding type="MQTT">
          <asset default-label="My Home" id="home">
              <setting default-label="Motion Detected" path="motion" type="int"/>
              <command path="TurnOn" default-label="Turn on">
                  <parameter id="Alarm" default-label="Alarm" type="boolean" />
              </command>
          </asset>
      </encoding>
  </data>
  

• The Application Model for our Alarm System is now defined. Let’s create it on AirVantage with the 2 following procedures:

  Create Application Package

  • Save the the Alarm Application Model to file with app file extension (e.g. appmodel.app)
  • Zip the app file (e.g. appmodel.zip)

    The filename of this zip file is only used for uploading process. AirVantage does not keep track of this zip filename. Only the XML content will be tracked by AirVantage.

  • Log into AirVantage Web portal

  • Go on Develop Activity > My Apps

  • Click on the Release button

  

Making the First MQTT Connection

• Before developing the Alarm System application, let’s first try to make a MQTT connection between Arduino and AirVantage
• SWIR_MQTTClient Library provides a Quick Start sample Arduino sketch that is intended to be used as a starting point to easily build AirVantage-MQTT-ready application.
• This starting point Arduino application can publish data to and receive data from AirVantage… without typing a single line of code.
• In Arduino IDE, open the Quick Start sample sketch as follow: in File menu, go to Examples then SWIR_MQTTClient and select HL-AV_QuickStart

• Adjust the SIM PIN code and APN for your SIM card, change the following definitions in the sketch if necessary:

  #define APN                     "yourAPN"                   
  #define APN_LOGIN               ""                          //your APN login
  #define APN_PASSWORD            ""                          //your APN password
  #define SIM_PIN_CODE            0                           //default is 0000, it's an integer!
  

• Connect Arduino to USB Hub (to Host)

  • In Arduino IDE, Tools menu, go to Board and select Arduino Mega or Mega2560
  • In Tools menu, go to Port and select COMxx (Arduino Mega or Mega2560)

• Make sure that the HL Shield is powered off (unplug power adapter)

• Click the Upload icon on Arduino IDE, this will compile the sample sketch and upload the resulting binary to Arduino

• Arduino sample app will automatically run upon sketch upload completion

• Arduino app logs should be visible in the first serial monitor

• Start the HL Module: power on the HL shield then press and hold the red button for 1 second

• Arduino will attempt to establish MQTT session with AirVantage once data call is ready (module registered to network, CGREG = x,1 or x,5)

• HL Module AT logs should be visible in the second serial monitor

Verifying MQTT Connection

The MQTT connection outcome (fail and success cases) are described hereafter.

MQTT Connected

1. Connected to AirVantage
   • ”— MQTT connected —” log (in serial monitor) indicates a successful MQTT session
     
2. Sending data to AirVantage
   • This sample application posts ellapsed milliseconds (since Arduino started) to AirVantage. The data key name is MilliSec
   • To view the data being sent to AirVantage, log into AirVantage portal
   • Go to your system monitor page (i.e. Monitor activity, go to Systems, then select Your System)
   • Published data is visible in the Last Communication widget
     
3. Receiving data from AirVantage
   • This quick start sketch can also receive incoming data sent by AirVantage
   • Log into AirVantage portal
   • Go to your system monitor page (i.e. Monitor activity, go to Systems, then select Your System)
   • Click on dropdown box then select Custom Command
   • In the Application field, select the alarm application (i.e. arduino-alarm)
   • Choose a Command and define Parameters then click on Send Command
     
   • This data should be received by the Arduino, it is displayed in the serial monitor
   • Upon receiving command from AirVantage, the device should return an acknowlegment message back to AirVantage.
     This ack message is automatically published (by the SWIR_MQTTClient library) to the /acks/json topic, as shown below
     

In Step 3, we’ve covered how to:

1. Define the use case for the Alarm System which helps to figure out the data flow and type
2. Create the Alarm Application Model that defines the interface between Arduino and AirVantage
3. Make a first MQTT connection with AirVantage without coding
4. Register device in AirVantage and then Assign Alarm Application Model to it
5. Verify that Arduino can publish data to AirVantage
6. Verify that Arduino can receive data from AirVantage

Application Development Guideline

• The QuickStart sketch, provided by the SWIR_MQTTClient library, should be used as a starting point to develop a new application.
  It is structured as follow:
• Configuration
  • #define keyword is used to declare configurations which can adjusted by altering default values
  • e.g. APN, SIM PIN code, Baudrate, MQTT quality of service level, delays, etc
  • This is the right spot to declare additional data key names defined in your application model
• Global variables
  • SWIR_MQTTClient object instance is needed as it is the interface with the Library
  • A variable to keep track of the SIM status (ready or need SIM pin code)
  • You may declare more variables to fulfill your needs
• QuickStart sketch provides a boilerplate code to facilitate the integration with AirVantage
  • Check SIM pin, wait for readiness of data call, make MQTT connection, retry mechanism, perform regular task are handled in a proper sequence
  • You can customize the application as follow:
    • Add your one-time setup code in doCustomSetup() function, which is called by Arduino’s setup() function
    • Add your code to be executed on a regular basis when MQTT session is established in doCustomLoopTask(), called by Arduino’s loop()
      Usually, this is the placeholder to read sensor data and publish them to AirVantage
    • Add your code to execute incoming Commands from AirVantage in messageArrived() function
  • Helper functions are provided for your convenience:
    • PostData(keyName, value) to publish data (key/value) to AirVantage
    • SWI_TRACE macro to print debug trace to serial monitor

Coding the Alarm System

• Let’s code this application using the QuickStart sketch as a starting point, following the above guideline

  Note the Alarm scenario specific code below can be be activated by enabling the flag ALARM_SCENARIO (#define ALARM_SCENARIO)
  

• In Arduino IDE, go to File menu then select Save As… to save the QuickStart sketch as a new sketch (e.g. AlarmApp)

• Configuration:

  • Add these new definitions for LED and PIR pins

  #define ALARM_STATUS_LED_PIN    9   //the LED is wired to Arduino's digital pin #9              
  #define PIR_PIN                 10  //the PIR is wired to Arduino's digital pin #10
  

  • Change data key name to match the ones defined in the Alarm Application Model (defined in Step 3)
  • Data key names are prefixed with the asset id (i.e. home).

  #define PUBLISH_DATA_NAME       "home.motion"
  #define INCOMING_DATA_NAME      "home.TurnOn.Alarm"
  

• Global variables:

  • Declare this new global variable to track the Alarm status (on/off), default is off. Place this line before the setup() function.

  int     _isAlarmOn = 0;
  

• Configure the LED and PIR pins in the doCustomSetup() function

  void doCustomSetup()
  {
      pinMode(ALARM_STATUS_LED_PIN, OUTPUT);  //set LED pin as an OUTPUT
      pinMode(PIR_PIN, INPUT);                //set PIR pin as an INPUT
  }
  

• Publish the motion detection status to AirVantage in the doCustomLoopTask() function

  void doCustomLoopTask()
  {
      if (_isAlarmOn)
      {
          //At this point, the MQTT session has been established and the Alarm system has been armed
          if (digitalRead(PIR_PIN) == HIGH)
          {
              postData(PUBLISH_DATA_NAME, 1);     //Motion detected, let's post this event to AV
          }
          else
          {
              postData(PUBLISH_DATA_NAME, 0);     //No Motion detected, let's post this event to AV anyway
          }
      }
  }
  

• Handle AirVantage-originated Commands in the messageArrived() function

  void messageArrived(const char* szKey, const char* szValue, const char* szTimestamp)
  {
      SWIR_TRACE(F("\r\n>>> Message from AirVantage: %s = %s @ %s\r\n"), szKey, szValue, szTimestamp);
      //based on szKey and szValue let's turn on/off the alarm on/off LED
      String sKey = String(szKey);
      String sValue = String(szValue);
      if (sKey == INCOMING_DATA_NAME)
      {
          if (sValue == ON_VALUE)         
          {
              digitalWrite(ALARM_STATUS_LED_PIN, HIGH);   //Switch ON LED
              _isAlarmOn = 1;                             //Arm the Alarm System
          }
          else
          {
              digitalWrite(ALARM_STATUS_LED_PIN, LOW);    //Switch OFF LED
              _isAlarmOn = 0;                             //Disarm the Alarm System
  
  
              postData(PUBLISH_DATA_NAME, 0);             //Publish message : "home.motion = 0", for consistency
          }
  
  
          return 0;                                       //to indicate that the command has been handled
      }
  
  
      return 1;                                           //to indicate unknown command,
                                                          //this information will be returned to AirVantage within the ACK message
  }
  

Upload the Alarm sketch to Arduino

• Connect Arduino to USB Hub (to Host)
  • In Arduino IDE, Tools menu, go to Board and select Arduino Mega or Mega2560
  • In Tools menu, go to Port and select COMxx (Arduino Mega or Mega2560)
• Make sure that the HL Shield is powered off (unplug power adapter)
• Click the Upload icon on Arduino IDE, this will compile the sample sketch and upload the resulting binary to Arduino
• Arduino sample app will automatically run upon sketch upload completion
• Arduino app logs should be visible in the first serial monitor
• Start the HL Module: power on the HL shield then press and hold the red button for 1 second
• Arduino will attempt to establish MQTT session with AirVantage once data call is ready (module registered to network, CGREG = x,1 or x,5)
• HL Module AT logs should be visible in the second serial monitor

Testing the Alarm System

• Refer to Verifying MQTT Connection section in Step 3 to :
  • Check the MQTT connection with AirVantage
  • Remotely activate the Alarm system by sending Custom Command TurnOn.Alarm on AirVantage
  • View motion detection events posted to AirVantage

In Step 4, we’ve covered :

1. Arduino Hardware setup to fulfill the Alarm Use Case
2. The guideline to easily develop an AirVantage-MQTT-ready application
3. How to to develop the Alarm application using the QuickStart sketch as a starting point