Searching...

Matching results

Getting started with HL module on RaspberryPI or Linux-based system

This tutorial describes how to create a communication with AirVantage Cloud from a Linux-based system equiped with a HL wireless module. The Linux-based system may be a RasberryPI or an Ubuntu PC. The following use cases are covered:

• Sending some custom data such as sensor value or application data from the Linux-based system to the AirVantage Cloud
• Sending some commands or configuration from AirVantage Cloud to the Linux-based system

To implement this solution, MQTT protocol will be used

To achieve the above objective, following main steps are covered:

1. How to setup your device: Hardware connection, AT command interface and IP connectivity
2. How to register your device on AirVantage
3. How to communicate with AirVantage using MQTT

Although, the guideline has been tested on Raspberry PI, it can easily be adapted to other Linux-based system.

Prerequisite

1. HL demo board + Antena + Power adaptor
2. AirPrime HL series Module
3. SIM card with data call plan
4. USB-to-Serial Converter
5. Host system with Linux-based OS (e.g. RaspberryPI/Raspian, PC/Ubuntu, Mac/MacOS, etc)
6. 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.

Check AT-Command Interface

• Use a serial terminal (e.g. minicom) to make sure that the AT interface can be established. To install minicom proceed as follow (internet access required):

  sudo apt-get install minicom

• Initialize the serial terminal to open the device port (e.g. /dev/ttyUSB0) on which the HL module is attached to, for instance:

  sudo minicom -D /dev/ttyUSB0

• The following AT commands shall be entered within minicom to perform some sanity checking:
  • AT : expected response OK. If not, make sure the board is powered on (the VBAT led should be on) and check minicom baudrate setting (default HL baudrate should be 115200), using minicom -s
  • AT+CPIN? : expected response READY
    • if not, SIM PIN may be entered using the AT+CPIN command. e.g. AT+CPIN=“1234”
  • AT+IPR? : the operating baudrate should be returned, please use this baudrate in the remaining tutorial
  • AT+CREG? : to check the network registration status, expected response +CREG:x,1 (registered, home network) or +CREG:x,5 (roaming)
  • AT+CGREG? : to check the GPRS registration status, expected response +CGREG:x,1 (registered, home network) or +CGREG:x,5 (roaming)
  • AT+CSQ : returns “RSSI”,“BER”. RSSI indicates the signal strength in dBm, a value of 99 reflects no signal detected or not known
• Issue AT+CGSN command to retrieve module’s IMEI, please note the IMEI, it will be used in upcoming tutorial steps
• Issue AT+KGSN=3 command to retrieve module’s Serial Number, please note the S/N for future use

AT Commands Integration in the Device

Setup PPP

• PPP daemon (pppd) is available on Linux-based system
• It can be installed on RaspberryPI as follow (internet access required):

  sudo apt-get install ppp

• PPP dial-up configuration is defined by a pppOptionFile, located in the /etc/ppp/peers directory. It is depending on a chatscript file (in /etc/chatscripts directory).
• The content of pppOptionFile is carrier specific and can be generated with pppconfig utility, refer to “man pppconfig” pages.
• Orange-France specific pppOptionFile and chatscript are provided here as example.

  Note that the device port and the baud rate are stated in the option file

Register System/Device (if not already done)

In Step 1, we’ve covered how to:

1. Connect HL Module to RaspberryPI
2. Send AT Commands to HL Module
3. Retrieve HL Modules’s IMEI & Serial Number using AT+CGSN & AT+KGSN=3 commands
4. Use PPP dial-up to obtain IP Connectivity
5. Register the Device on AirVantage using HL Module’s IMEI as identifier

Define Server-side Application

• 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)
• Create an Application Model XML file on your desktop/laptop (e.g. start with the example described below)

Without Application Model, the server will ignore all communication from your device.

Define Data Model

• Below is a sample Application Model XML file defining the server-side application for the Greenhouse embedded application:
  • In the app:application tag, the type attribute defines the unique identifier (com.test.airvantage.app) of the application whose name is AirVantage Greenhouse with a revision number 0.0.1
  • The Device-Server communication protocol is MQTT, as defined by the Type attibute of the subsequent communication/protocol tag.
  • The data model is described in the <data> tag. It has an asset (“machine”) comprising two variables (“temperature” & “humidity”) of type double, and one “TurnOn” command to control a “Light” parameter of type boolean

You can modify the content of <data> to define a custom data model that your device application will be sending to or receiving from AirVantage. You’ll also have to define appropriate values for Type, name and revision attributes of app:application tag.

<?xml version="1.0" encoding="ISO-8859-1"?>
<app:application 
        xmlns:app="http://www.sierrawireless.com/airvantage/application/1.0" 
        type="com.test.airvantage.app" 
        name="AirVantage Greenhouse"
        revision="0.0.1">
  <capabilities>

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

    <data>
      <encoding type="MQTT">
        <asset default-label="Greenhouse" id="machine">
          <variable default-label="Temperature" path="temperature" type="double"/>
          <variable default-label="Humidity" path="humidty" type="double"/>
          <command path="TurnOn" default-label="Turn on">
            <parameter id="Light" default-label="Light" type="boolean" />
          </command>
        </asset>
      </encoding>
    </data>
  </capabilities>
</app:application>

In Step 2, we’ve covered how to:

1. Define the server-side application using Application Model
2. Customize Data Model that your device application will be sending to or receiving from AirVantage
3. Create the Application Package
4. Release and Publish the server-side application (package)
5. Assign the server-side application to support the client-side application in the Device

Publish MQTT Messages

• MQTT messaging content exchanged between the Device and AirVantage Server is defined by Application Model and the payload should be JSON encoded:

  • Each sample of a variable has a timestamp (elapsed ms since Jan-1970) and a value. It is possible to send a collection (or array) of sample at once.
  • The variable is identified by it’s asset id and the path
  • For instance, the following MQTT message to be published contains 2 samples of Temperature and Humidity variable as defined in Step 2-“Define Data Model”:

  [
    { "machine.temperature": [
      {"timestamp": 1425937636000, "value":"21"},
      {"timestamp": 1425939843000, "value":"20.9"} ]
    },
    { "machine.humidity": [
      {"timestamp": 1425937636000, "value":"37"},
      {"timestamp": 1425939843000, "value":"38"} ]
    }
  ]
  

  • The above message shall be published to topic: “%IMEI/messages/json”, where %IMEI is the IMEI of the module as retrieved in Step 1

• Publish message to AirVantage, using Mosquitto command line:

  • Save the above sample JSON message into a file (e.g. pub-msg.txt)
  • Publish the file’s content to AirVantage, as follow
    mosquitto_pub -h eu.airvantage.net -t %IMEI/messages/json -f pub-msg.txt -u %IMEI -P %password
    (where %IMEI is the IMEI of the module as retrieved in Step 1, %password is the password defined in Step 2)

Subscribing to MQTT topic

• In order to receive data from AirVantage, the device application must subscribe to the topic: “%IMEI/tasks/json”
• Let’s do this using Mosquitto command line as follow:

mosquitto_sub -h eu.airvantage.net -t %IMEI/tasks/json -u %IMEI -P %password
(where %IMEI is the IMEI of the module as retrieved in Step 1, %password is the password defined in Step 2) * Incoming data will be displayed as they arrive… now let’s send some data

Sending MQTT data to Device from Web portal

• Go to Monitor > Systems
• Search for your Device using filters (e.g. Label, IMEI)
• Click on your Device to view monitoring page
• Click on the “More” button (located on top right), then select “Custom Command”
• Base on the Greenhouse Application Model (excerpt below), the “Turn On” command can be sent to the Device from AirVantage Web portal:

<command path="TurnOn" default-label="Turn on">
<parameter id="Light" default-label="Light" type="boolean" />

• Select the action in the Command listbox and specify the corresponding parameters (e.g. Turn on Light)
• Click “Send Command” to fire the MQTT message to your Device

Receiving MQTT Messages

• The incoming MQTT message should be displayed by the previous mosquitto_sub command as follow:

[{
  "uid":"9142df4c0b884683993521a3d5cf97f1",
  "timestamp":1426022121930,
  "command":{"id":"machine.TurnOn","params":{"Light":true}}
}]

• This message is JSON encoded and must be decoded by the Device (handled by the callback function) as follow:
  • uid is the unique id of this MQTT message
  • timestamp is the jan-1970 ms elapsed timestamp of this message
  • command object is composed of :
    • id: asset id (machine) and the command path (TurnOn)
    • parameter id (Light) set to true

Acknowledging incoming MQTT Messages

• Upon receiving an incoming MQTT command message (sent by AirVantage), the Device shall return an acknowledge message. This latter must enclose “uid” and “status” keys, the optional “message” key may be provided. Below is a sample ack message to the incoming message as shown in the previous section.

[{
  "uid":"9142df4c0b884683993521a3d5cf97f1",
  "status":"OK"
}]

• This ack message is JSON encoded and must be published to “%IMEI/acks/json” Topic:
  • uid is the unique id of the incoming MQTT command message to be acknowledged
  • status being OK or ERROR
  • optional message key may be included to provided information on the error
• Publish ack message to AirVantage, using Mosquitto command line:
  • Paste the above sample ACK JSON message to a text editor, and replace the uid value by the one located in the incoming message (displayed by mosquitto_sub)
  • Save the ack message content a file (e.g. ack-msg.txt)
  • Publish the file’s content to AirVantage, as follow
    mosquitto_pub -h eu.airvantage.net -t %IMEI/acks/json -f ack-msg.txt -u %IMEI -P %password
    (where %IMEI is the IMEI of the module as retrieved in Step 1, %password is the password defined in Step 2)

MQTT Client Integration in the Device

In the above hands-on steps, we were able to manually send messages to and receive data from AirVantage, using Mosquitto command line tools. This sub-section provides additional highlights on the integration of MQTT client into your device application. Addressing RaspberryPI’s GPIO is also briefly described.

MQTT Client Integration in the Device

• The device application must implement MQTT Client functionalities in order to programmatically publish messages and to receive messages pertaining to subscribed topics. The specification can be found on http://mqtt.org
• There are various MQTT libraries available on the web that can be leveraged to easily gain MQTT support in the device application.
• Most MQTT Client libraries expose 4 main functions:
  1. Open Connection
     • The device application should call this function first with the following parameters:
     • AirVantage MQTT server URL and port number: (eu.airvantage.net:1883)
     • Device IMEI (retrieved in step 1, “Send AT commands”), for authentication purposes
     • Password (as defined in step 2, “Associate your Application to your System/Device”)
  2. Message Publishing
     • The device application calls this function to publish the provided MQTT message (to be formatted as shown in step 3.2) to the specified Topic (URI style)
     • The publishing topic shall be “%IMEI/messages/json”, where %IMEI is the IMEI of the module as retrieved in Step 1
  3. Topic Subscription
     • The device app calls this function along with a Topic to subscribe to and a callback function to decode and parse the incoming MQTT message pertaining to the topic
     • The subscription topic shall be “%IMEI/tasks/json”, where %IMEI is the IMEI of the module as retrieved in Step 1
     • Incoming message published to “%IMEI/tasks/json” topic, should be acknowledged by publishing an ack message to Topic “%IMEI/acks/json”
  4. Close Connection
• Note that, in the previous hands-on section, the publishing command (mosquitto_pub) and subscription command (mosquitto_sub), are both encapsulated by Open connection and Close connection operations

Controlling RaspberryPI's GPIO

Controlling RaspberryPI’s GPIO

• The wiringPI library can be easily integrated into the RaspberryPI in order to control GPIO.
• For instance, to turn on a LED wired to the GPIO-0 of the RaspberryPI when the device receives the above TurnOn Light command
• Below is the sample code:

#include <wiringPi.h>
...
wiringPiSetup();
pinMode(0, OUTPUT);
...
if (turnOnLight)
{
  digitalWrite(0, HIGH);
}
else
{
  digitalWrite(0, LOW);
}

Troubleshooting & Testing

Refer to this tutorial for further information on how to troubleshoot the connection and to interact with system/device

In Step 3, we’ve covered how to:

1. MQTT Client integration into device and connection with AirVantage
2. Formatting, encoding and Publishing MQTT message
3. Viewing and collecting posted data on AirVantage
4. Sending MQTT data to Device from AirVantage
5. Subscribing, receiving, decoding incoming MQTT messages
6. Sending command to RaspberryPI’s GPIO port

MQTT Sample Code

As described in the previous steps, enabling MQTT support in the device application requires the integration of MQTT protocol (may leveraging existing libraries). It also requires the implementation of JSON payload encoding/decoding and parsing/mapping of sensor/actuator/application data to the data model as defined in the application model.

Refer to below sample applications (C code) for integration reference.

Greenhouse

This sample (used in the above steps) publishes emulated Temperature and Humidity to AirVantage, and receives “TurnOn” command from AirVantage.

You may adapt this code to fit your needs.

MQTT Spooler

This app automatically converts CVS data to MQTT messages prior publishing to server. It also automatically converts incoming MQTT messages (pertaining to a subscribed Topic) to CSV data. This app could be reused as a quick integration option (no need to deal with MQTT code) with your existing sensor/actuator based application.