The XPLR-IOT-1 uses the SARA-R5 module to connect to cellular networks.
If the SARA module has not been connected to a mobile network operator successfully before, it may take quite some time to register/connect to a network, when the command to connect is given or the user activates the Sensor Aggregation Main Function via cellular. During this time a lot of Registered/Not Registered messages may appear. This is normal.
If it takes too much time to Register somewhere, then it may be necessary to reset the device (if it does not timeout) and use AT commands to connect the module to a Mobile Network Operator for the first time. In order to be able to use SARA-R5 with u-blox m-center application, or send serial commands directly to it you should send the command:
modules SARAR5 power_on
By default SARA can connect to m-center after a reset, you just need to select the appropriate serial COM (see XPLR-IOT-1 hardware manual
To power down SARA you can use the command:
modules SARAR5 power_off
Note: The firmware is preconfigured to use the MQTT anywhere plan. However, it is possible that its setting is to use MQTT Flex (not using the Thingstream card). You can check the active plan by sending the command:
modules SARAR5 plans get_active
If the active plan is not MQTT Anywhere you can set it by sending the command:
modules SARAR5 plans anywhere
When the user wants to connect to Thingstream via Cellular, using the embedded Thingstream SIM card (eSIM - see XPLR-IOT-1 - User guide), the MQTT Anywhere Plan should be used. The eSIM should be activated in the Thingstream platform using the redemption code provided with XPLR-IOT-1.
After the redemption code is entered, the identity of the device created, should be copied to the XPLR-IOT-1 using the appropriate command. This essentially configures the MQTT-SN client. The following steps should be performed:
- In Thingstream platform: Add a new Thing in Thingstream platform by using the Enter redemption code option
- In Thingstream platform: Select the newly created thing in the “Things” menu
- In Thingstream platform: Copy the identity of the device (using the copy button)
- In XPLR-IOT-1 device: Use the following command and paste the device identity copied from the previous step
modules MQTTSN save anywhere <Identity> <Connection Duration in seconds>
Connection duration should be greater than sampling period of the sensors.
- Optional: Use the following command to check if the information is ok
modules MQTTSN type
Important Note: It is better to copy/paste of the credentials, rather than typing them
If a user wants to connect via Cellular to Thingstream platform using a third party SIM card (nano SIM, see XPLR-IOT-1 - User guide) and not the embedded SIM (eSIM) in the XPLR-IOT-1 device, then the MQTT Flex Plan should be used. Currently, MQTT Flex has been tested only with 1nce SIM cards in NB-IOT networks.
To setup MQTT Flex the user will also need to use m-center. The following steps should be followed:
- In Thingstream platform: Create a Flex Thing
- In Thingstream platform: Select the Flex thing create and download the client key and certificate from the credentials tab. Also copy the client ID (using the copy button)
- In XPLR-IOT-1: Reset XPLR-IOT-1 and power up SARA-R5 module by sending the command:
modules SARAR5 power_on
- In host PC: Connect m-center to XPLR-IOT-1 in interface 1
- In host PC : Use m-center File System tab to upload the client key & client certificates into the modem
Important Note: The files saved in SARAR5 should have the names:
- cert.pem for the client certificate
- cert.key for the client key Other filenames won’t work
- In XPLR-IOT-1: Power down SARA-R5 module by sending the command:
modules SARAR5 power_off
- In XPLR-IOT-1: Send the following command and paste the id copied from step 2:
modules MQTTSN save flex <Client Id>
- (Optional) In XPLR-IOT-1: check the saved settings with the following command:
modules MQTTSN type command
After that you should be ready to connect to Thingstream via Cellular, using a third party SIM card. The flex plan should be activated using the command:
modules SARAR5 plans flex
Configuration of the cellular module to connect to a Mobile Network Operator should also be performed, before trying to use the sensor aggregation main function.
Cellular is handled via SARAR5 module, so all commands having to do with Cellular connectivity are part of the SARA module. SARA is handled via the following commands:
- Power on/off
- Init/deinit
- Connect
Power on and off commands have already been discussed (see here)
Init command initializes the module so that it will be ready to connect to a cellular network. Initialization includes all operations necessary, such as powering up the module (if not already powered up), setting up ubxlib environment for connection etc.
Deinit does the exact opposite of init. It disconnects the module if connected and clears ubxlib status so that it can be used by another module if necessary.
If the module has been initialized the connect command just connects the module to the cellular Mobile network operator. Some configurations may be needed the first time the connection is established (see 4.1.3) If the init command has not been issued, it is called internally by the connect command.
Providing details about ubxlib usage is out of the scope of this operation, however in the following picture the normal usage flow of the Cellular module is presented and ubxlib functions called inside the calls of these functions are mentioned in italics.
Connection to MQTT-SN can only be achieved if an active Cellular connection is available. MQTT-SN is used via SARAR5 native MQTTSN client and is handled using ubxlib (via AT commands). For this reason, MQTTSN module can be considered as part of the cellular module in the sense of Sensor Aggregation Firmware, however is treated as a separate module with its own set of commands. These commands can be accessed by sending:
modules MQTTSN <open/close/connect/disconnect etc...>
The commands/operations available for MQTT module are:
- Open/close
- Connect/Disconnect
- Save
- Type
- Status
- Send
Open command prepares and sets up ubxlib and prepares the module to connect to an MQTTSN broker. In this firmware the broker is set up to be the Thingstream platform. Open command requires a connection to Cellular to start its function. If this connection is not available yet, it calls all necessary functions to establish a Cellular connection and if this fails it aborts its operation. Close just closes MQTTSN module. To be able to connect to MQTT again after a close command, the open command should be called again.
After MQTT open command, the connect command connects to MQTTSN broker. After this connection is established, the device can send messages to the broker and receive messages. Connect command can call all previous commands internally if needed to perform a connection (power up SARA, connect to Mobile network operator, open MQTTSN etc).
These commands are used to setup MQTTSN client for connection to a broker. See 4.1.4 and 4.1.5 for more details).
Just types the status of the module.
When connected to an MQTTSN broker this command allows you to send a message to a topic using any Quality of Service (see 5.4.5 for details on how to use this command)
The picture below shows how MQTTSN and Cellular module can be used (along with ubxlib functions called)
