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.


    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 :

    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.

    Step 1: Setting the IP Connectivity

    This step starts with connecting the HL module to your Raspberry, and verify that it is attached to a Linux virtual serial device port (e.g. /dev/ttyUSB0).

    AT Command interface should then be in place to enable the host application to control the HL Module.

    Finally, IP Connectivity is created using PPP dial-up to enable host applications to communicate with remote servers.

    Connect Hardware

    • Place the HL Module into the demo board’s module socket. To ensure the correct orientation of the HL Module, use the dot mark, printed on the top right corner, as reference. It should be aligned with the dot mark visible within the demo board socket. Then place the shielding cover on the module.
    • Connect the “UART1_MAIN” port of the HL demo board to your RaspberryPI, using a USB-to-Serial converter cable.
    • Connect the antenna to the “2G/3G/4G RF MAIN” connector.
    • Insert a SIM card into the “SIM1” slot.
    • Power-on the demo board with the power adaptor on “VBAT” jack

    Verify Hardware Connectivity

    • Your USB-to-Serial adapter should be listed when entering “lsusb” linux command on your host system.
    • Type in the “dmesg | grep tty” linux command. Check the log to identify the device port (e.g. /dev/ttyUSB0) that has been associated to the HL demo board

    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

    In the above hands-on sections, we were able to manually send AT-Commands, using minicom. This sub-section aims to facilitate the AT-Command support within your device application.

    Integration Helper
    • The aforementioned AT commands must be issued programmatically within your device application. And the response must be filtered and analyzed by the device application. For instance, the returned IMEI should be extracted from AT+CGSN response, IMEI is required to register the HL module on AirVantage platform.
    • For your convenience, a sample AT command line tool can be adapted and integrated into your device application to rapidly gain AT-Command capabilities and to control the HL module.
    • The provided sample AT command can also be used as is, as follow:
      ./hl-atcmd -d devicePort -b baudrate -f atcmd-filter at-cmd
      For instance:
      • ./hl-atcmd -d /dev/ttyUSB0 -b 115200 -f AT+CGSN AT+CGSN
        will return the filtered response which is the IMEI. Full response will be returned if no filter is specified.
      • ./hl-atcmd -d /dev/ttyUSB0 -b 115200 -f +KGSN: ‘AT+KGSN=“3”’
        will return the filtered response which is the Serial Number. Full response will be returned if no filter is specified.
      • SIM PIN may be entered as follow: ./hl-atcmd -d /dev/ttyUSB0 -b 115200 ‘AT+CPIN=“1234”’
      • Any AT-commands as documented in the AT-command specification can be executed using this command line (shell scriptable)
      • If the AT command is not responding, make sure that device port and the baudrate (AT+IPR?) are both correct.

    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

    Launch PPP

    • Start PPP daemon by specifying the filename of the pppOptionFile (located in /etc/ppp/peers directory) as follow

      sudo pppd call pppOptionFile &

    • The following statements in the log indicate a successful outcome of the PPP daemon:
      • “local IP address…”, “remote IP address…”, “ip-up finished”
      • PPP interface (e.g. ppp0) should be listed with associated IP address upon ifconfig commmand
    • IP connectivity can be assessed with a ping command (e.g. ping
    • When you will need to close the IP connectivity later, it is highly recommended not to stop the PPP daemon with CTRL-C. Proceed as following to properly terminate the PPP session:
      • Issue ps -ef | grep pppd in the console
      • Identify the pid associated to the running pppd process
      • Issue sudo kill -s SIGHUP pid so the pppd will have the modem to hangup properly the data call.

    Register System/Device (if not already done)

    At this point, if your device has not been registered on AirVantage server, please proceed as follow:

    Register System/Device

    • For PC/Ubuntu users, your internet connection is now handled by the HL module. It is recommended to use another PC to access AirVantage Web Portal
    • Log into AirVantage Web portal
    • Go to Register activity
    • Click on the “AirPrime HL Series” section
    • Select your HL series module
    • Fill the Serial Number field, as captured previously using AT+KGSN=3
    • Fill the IMEI field, as captured previously using AT+CGSN
    • Set a name and click on Register

    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

    Step 2: Design the Server Application

    An embedded application on device-side (e.g. RaspberryPI) is interfacing with a server-side application on AirVantage in order to exchange predefined data over a predefined communication protocol and authentication scheme.
    This step starts describing the Application Model concept which is used to define a server-side application.

    The Application Model XML file is customized to define the set data to be exchanged between the device and AirVantage.

    The finalized XML file is packaged as Application Package then released and published onto AirVantage, so that it can be associated to user-selected System/device(s).

    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 ( 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"?>
            name="AirVantage Greenhouse"
          <protocol comm-id="IMEI" type="MQTT" />
          <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" />

    Create Application Package

    • Save the the above Application Model to file with app file extension (e.g.
    • Zip the app file (e.g.

      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.

    Release Application

    • Select your zip file (e.g.
    • Open Advanced settings and select I want to publish my application after releasing it
    • Finally, click on Start

    Edit System/Device

    • Go on Inventory > Systems
    • Select your system and click on the Edit icon

    Search your Application

    • Click on Search application
    • In the new dialog box, select the My Application tab
    • Search your application using its name (AirVantage Greenhouse)

    Associate Application to your System/Device

    • Click on the application to select it
    • Click on the padlock and configure the password
    • Click on Save in the right top corner
    • Click on the Monitor icon to monitor your system
    • In the grid, select the newly created system and click on the “Activate” action

    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

    Step 3: MQTT data exchange with AirVantage Server

    MQTT is a lightweight publish/subscribe messaging protocol. A Device/Client application can publish a message to MQTT broker under a uniquely named topic. The server then instantly relays this message to other connected Device/Client applications having subscribed to the same named topic.

    One-to-one and one-to-many IoT messaging approaches mechanism can thus come to life.

    AirVantage server implements MQTT Broker functionalities. It has the ability to receive, to retain then to relay MQTT messages. AirVantage supports MQTT QoS Level 1 (messages delivered at least once with confirmation required).
    This section starts with hands-on steps showing you how to publish messages to and receive data from AirVantage, using Mosquitto command line tools. Key integration aspects of MQTT client into your device application is then highlighted.

    Any client implementing MQTT can be used to exchange data with AirVantage. In this tutorial, we will use Mosquitto, an open source solution implementing MQTT which can installed on the host (e.g. run the following command for RaspberryPI or PC running Ubuntu) as follow (internet access required):

    sudo apt-get install mosquitto-clients

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

    View Pusblished data on Web portal

    • Log into AirVantage Web portal
    • Go to Monitor > Systems
    • Search for your Systems/Device using filters (e.g. Label, IMEI)
    • Click on your System/Device to view monitoring page
    • Scroll down to “Last Communication” panel to view data published by the Device
    • “Timeline” option can be used to view history events related to Device communication with AirVantage server

    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 -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:
    • 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.
    • 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 -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
    • 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: (
        • 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>
    pinMode(0, OUTPUT);
    if (turnOnLight)
      digitalWrite(0, HIGH);
      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.


    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.