Quality RTOS & Embedded Software

AWS Reference Integrations:
Embedded World track keynote:

Cellular Interface Demo


FreeRTOS offers a suite of networking stacks designed for IoT applications. Applications can access communication protocols at different levels - MQTT, HTTP, Secure Sockets, etc. Common connectivity technologies such as Ethernet, Wi-Fi and BLE have been integrated with the networking stacks of FreeRTOS, with a wide selection of microcontrollers and modules pre-integrated.

The demos in this project demonstrate how to establish mutually authenticated MQTT connections to MQTT brokers, such as AWS IoT Core, by using cellular connectivity. The demos use the Cellular Interface library sub-moduled from an external project. The Cellular Interface library exposes the capability of a few popular cellular modems through a uniform API.

The MQTT and HTTP libraries of FreeRTOS use an abstract Transport Interface to send/receive data in a generic way. The demos in this project offer an implementation of the Transport Interface on top of the uniform API exposed by the Cellular Interface library.

Hardware Setup

The demos in this project can be run in the FreeRTOS Windows Simulator. You will need a Windows PC and one of the supported cellular modems to run a demo. A version of Visual Studio, such as the free Community version of Visual Studio, will be needed to build the demos.

The FreeRTOS Windows simulator makes use of a COM port to communicate with the cellular module. Set up your cellular module communication with the following steps.

  • Connect the cellular module to your PC. Most cellular dev kits have a USB connector, so you can just connect it to your PC's USB port and look for the COM port in Window's Device Manager. For example, as shown below, you will see a new COM69 show up when you connect the modem. If your cellular dev kit does not have USB, use a USB adapter like one of these.

    Screenshot 1: Cellular module COM port in windows device manager

  • Use Putty or any other terminal tool to verify connection with the cellular module. Refer to you cellular module's manual for settings like baud rate, parity, and flow control. In the terminal tool, enter "ATE1". The modem should return "OK". Depending on your modem setting, you may also see an echo of "ATE1" as well. Enter "AT". The modem should return "OK".

  • Screenshot 2. Testing the COM port with AT commands in putty

Components and Interfaces

This project makes use of five (5) sub-modules from other GitHub projects, shown as yellow boxes in the diagram below.

Figure 1: Components and Interfaces
  • The Cellular Demo Application is largely the same functionality as the coreMQTT demo, with added logic to set up cellular as the transport. (The original coreMQTT demo was designed for Wi-Fi on the FreeRTOS Windows Simulator.) There is also a demo application that integrates 1nce Zero Touch Provisioning with the Cellular Interface library and coreMQTT for connecting to AWS IoT Core.
  • The Transport Interface is needed by the MQTT library (sub-moduled from the coreMQTT project) to send and receive packets.
  • The TLS porting interface is needed by the mbedTLS library to run on FreeRTOS.
  • The Comm Interface is used by the Cellular Interface library to communicate with cellular modems over a UART connection.

Developer References and API Documents

Please refer to the hosted doxygen.

Download the source code

The source code can be downloaded from FreeRTOS labs or by itself through Github.

To clone from Github using HTTPS:

git clone https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo.git --recurse-submodules
Using SSH:

git clone git@github.com:FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo.git --recurse-submodules
If you have downloaded the repo without using the --recurse-submodules argument, you need to run:

git submodule update --init --recursive

Source Code Organization

The demo project files for Visual Studio are named <xyz>_mqtt_mutual_auth_demo.sln, where xyz is the name of the cellular modem. They can be found on Github in the following directory:

There is also a demo for 1nce zero touch provisioning using the BG96 modem:

├── lib
│   ├── backoff_algorithm ( submodule : backoffAlgorithm )
│   ├── cellular ( submodule : FreeRTOS-Cellular-Interface)
│   ├── coreMQTT ( submodule : coreMQTT )
│   ├── FreeRTOS ( submodule : FreeRTOS-Kernel )
│   └── ThirdParty
│       └── mbedtls ( submodule : mbedtls )
├── projects
│   ├──  bg96_mqtt_mutual_auth_demo ( demo project for Quectel BG96 )
│   ├──  hl7802_mqtt_mutual_auth_demo ( demo project for Sierra Wireless HL7802 )
│   ├──  sara_r4_mqtt_mutual_auth_demo ( demo project for U-Blox Sara-R4 )
│   └──  1nce_bg96_zero_touch_provisioning_demo ( demo project for 1nce zero touch provisioning with BG96 )
└── source
    ├── cellular
    │   └── ( code for adapting the Cellular Interface Library with this demo )
    ├── coreMQTT
    │   └── ( code for adapting coreMQTT with this demo )
    ├── doc
    │   └── ( documentation )
    ├── FreeRTOS
    │   └── ( code for adapting FreeRTOS with this demo )
    ├── include
    │   └── ( Cellular API definitions )
    │   └── common ( reusable common code that implements the standard AT commands defined by 3GPP TS v27.007 )
    ├── mbedtls
    │   └── ( code for adapting mbedtls with this demo )
    ├── modules
    │   └── ( vendor-specific code that implements non-3GPP AT commands for each cellular modem )
    ├── test
    │   └── ( unit test and cbmc )
    ├── tools
    │   └── ( tools for Coverity static analysis and CMock )
    ├── main.c
    ├── cellular_setup.c
    ├── MutualAuthMQTTExample.c
    ├── demo_config.h
    ├── logging_levels.h
    ├── logging_stack.h
    ├── 1nce_zero_touch_provisioning.h
    └── 1nce_zero_touch_provisioning.c

Configure the Application Settings

Configure the cellular network

The following parameters in the cellular configuration, cellular_config.h, (located in "source/cellular/<cellular_module>/cellular_config.h") must be modified for your network environment.

Configuration Description Value
CELLULAR_COMM_INTERFACE_PORT The cellular communication interface makes use of a COM port on your computer to communicate with the cellular module on the Windows simulator. Your COM port connected to the cellular module.
CELLULAR_APN The default APN for network registration. Specify the value according to your network operator.
CELLULAR_PDN_CONTEXT_ID PDN context id for the cellular network. The default value is CELLULAR_PDN_CONTEXT_ID_MIN.
CELLULAR_PDN_CONNECT_TIMEOUT PDN connect timeout for network registration. The default value is 100000 milliseconds.

Configure the MQTT broker

The configuration to connect to an MQTT broker can be found in "source/demo_config.h". Refer to the documentation for the MQTT Mutual Authentication Demo for more information.

Note: The U-Blox SARA-R4 series support setting mobile network operators. Set CELLULAR_CONFIG_SARA_R4_SET_MNO_PROFILE in cellular_config.h according to your mobile network operator.

Configure the COM port settings

Refer to your cellular module's documentation for COM port settings. Update the settings in comm_if_windows.c if necessary.

Configure the other sub-modules

"source/FreeRTOS/FreeRTOSConfig.h", "source/mbedtls/mbedtls_config.h" and "source/coreMQTT/core_mqtt_config.h" contain configurations for their corresponding sub-modules.

Demo Execution Step flow

The demo app performs three types of operations. By searching for the names of the functions in the diagram below, you can find the exact places these operations are performed in the source code.

  1. Register to a cellular network. (See cellular_setup.c.)

  2. Establish a secure connection to AWS IoT with the MQTT broker. (See using_mbedtls.c.)

  3. Perform MQTT operations. (See MutualAuthMQTTExample.c.)

The following diagram illustrates the interactions between the demo app and other components.

Demo Flow
Demo Flow
Click image to enlarge

Build and run the MQTT mutual authentication demo

  1. In Visual Studio, open one of the mqtt_mutual_auth_demo.sln projects that matches your cellular modem.

  2. Compile and run.
The following is the console output of a successful execution of the bg96_mqtt_mutual_auth_demo.sln project.

[INFO] [CELLULAR] [commTaskThread:287] Cellular commTaskThread started
>>> Cellular SIM okay <<<
>>> Cellular GetServiceStatus failed 0, ps registration status 0 <<<
>>> Cellular module registered <<<
>>> Cellular module registered, IP address <<<
[INFO] [MQTTDemo] [prvConnectToServerWithBackoffRetries:583] Creating a TLS connection to xxxxx-ats.iot.us-west-2.amazonaws.com:8883.

[INFO] [MQTTDemo] [MQTTDemoTask:465] Creating an MQTT connection to xxxxx-ats.iot.us-west-2.amazonaws.com.

[INFO] [MQTTDemo] [prvCreateMQTTConnectionWithBroker:683] An MQTT connection is established with XXXXXXXXXX-ats.iot.us-west-2.amazonaws.com.
[INFO] [MQTTDemo] [prvMQTTSubscribeWithBackoffRetries:741] Attempt to subscribe to the MQTT topic testClient13:24:47/example/topic.

[INFO] [MQTTDemo] [prvMQTTSubscribeWithBackoffRetries:748] SUBSCRIBE sent for topic testClient13:24:47/example/topic to broker.

[INFO] [MQTTDemo] [prvMQTTProcessResponse:872] Subscribed to the topic testClient13:24:47/example/topic with maximum QoS 1.

[INFO] [MQTTDemo] [MQTTDemoTask:479] Publish to the MQTT topic testClient13:24:47/example/topic.

[INFO] [MQTTDemo] [MQTTDemoTask:485] Attempt to receive publish message from broker.

[INFO] [MQTTDemo] [prvMQTTProcessResponse:853] PUBACK received for packet Id 2.

[INFO] [MQTTDemo] [MQTTDemoTask:490] Keeping Connection Idle...

[INFO] [MQTTDemo] [MQTTDemoTask:479] Publish to the MQTT topic testClient13:24:47/example/topic.

[INFO] [MQTTDemo] [MQTTDemoTask:485] Attempt to receive publish message from broker.

[INFO] [MQTTDemo] [prvMQTTProcessIncomingPublish:908] Incoming QoS : 1

[INFO] [MQTTDemo] [prvMQTTProcessIncomingPublish:919]
Incoming Publish Topic Name: testClient13:24:47/example/topic matches subscribed topic.
Incoming Publish Message : Hello World!

Build and run the 1nce zero-touch-provisioning demo

1NCE is a global IoT Carrier that specializes in providing managed connectivity services for low bandwidth IoT applications. In this demo, the 1NCE service (a 1NCE sim card + AWS IoT device onboarding server) and a BG96 cellular module are used to demonstrate how to provision a device with zero-touch and to connect to AWS IoT core. Refer to the 1nce blueprint for FreeRTOS and, in particular, to this flow chart, to learn how the zero-touch-provisioning works.

  1. In Visual Studio, open the 1nce_bg96_zero_touch_provisioning_demo.sln project. In this Visual Studio solution file, the macro USE_1NCE_ZERO_TOUCH_PROVISIONING is defined. Please look for #ifdef USE_1NCE_ZERO_TOUCH_PROVISIONING in the source files to see the difference in how a device using the 1nce service is provisioned. Otherwise, this demo performs the same mutually authenticated MQTT operations as the other demos.

  2. Generate a self-signed certificate and its private key locally. Update "source/demo_config.h" with the certificate and private key. These are used to establish a TLS connection to the 1nce server. Note that the keys are placed in a header file for demonstration purposes only; production devices should use secure storage to store the keys.

  3. Get the Access Point Name (APN) for your SIM card from 1NCE. Update CELLULAR_APN in the file "cellular_config.h" for BG96, and follow the steps in "Configure Application Settings" above to finish the rest of the configuration.

  4. Compile and run.

Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.