Sequans’ Calliope LTE Cat 1 chipset platform, which uniquely supports VoLTE and enables a wide range of industrial and consumer IoT applications, including asset tracking, alarm systems, telematics devices, retail applications, smart utility meters and more, is now certified and available for use on T-Mobile’s network. At the recently held GSMA Mobility Live in Atlanta (Nov. 1-2, 2016), Sequans, Ericsson and Gemalto together demonstrated a proof-of-concept of LTE Cat M1 technology. The demonstration, designed by Ericsson, depicted how a trucking company could use LTE Cat M1 to track its trucks on the road and manage fleet operations.
Sequans Monarch LTE Modem User Guide
Overview
ThingSpace is the Internet of Things (IoT) platform that offers a complete end-to-end solution for onboarding and activating your devices on the Verizon Wireless network. The ThingSpace client is integrated on the Sequans Monarch Category M1 (Cat-M1) LTE modem. The combination of the LTE Cat-M1 capabilities of the Monarch modem with Verizon’s 4G LTE network and ThingSpace offers a simplified approach for building, deploying and managing IoT devices and applications, which can be customized for a widerange of IoT uses including asset management, industrial automation, wearables, smart cities and more.
Features include:
- Proprietary ATtention (AT) commands to interact with the embedded ThingSpace client
- Very light MCU load, and no TCP/IP stack required
- Diagnostics
- Security
- Capability of cloud messaging
Before you begin
There are a few things you will need to do before you can get started.
1. Go to core.thingspace.verizon.com/portal
2. Use a company email to create a ThingSpace account.
3. Download the following tools:
| Item | Description | Version | Source/Vendor | Purpose | Link |
|---|---|---|---|---|---|
| 1 | Sequans modem drivers | VZM20Q-REV2-EVK-BBA1- RFA3-SKY6800031_VERIZONMQTT -NOLPM_LR5.1.1.0-34030 | Sequans | Modem drivers with ThingSpace integrated | XXX |
| 2 | Python | 2.7 | Python | Needed to test sample application on PC | https://www.python.org/ |
| 3 | NimbleLink Skywire Modem | NL-M1DK | NimbleLin | Cellular modem board with Sequans 3330 chipset | https://nimbelink.com/products/skywire-m1-dev-kit/ |
Setting up ThingSpace
The ThingSpace Software Development Kit (SDK) is included in the Sequans Monarch modem software. Please ensure you are using the correct software version. To update your Sequans modem firmware, please see the Flashing modem firmware section. Once you have the right firmware version on your modem, review the ATtention (AT) commands specific for ThingSpace.
Flashing modem firmware
Update your firmware to VZM20Q-REV2-EVK-BBA1-RFA3-SKY6800031_VERIZON-MQTT- NOLPM_LR5.1.1.0-34030 or later. See documentation with your corresponding module maker.
If you are using the NimbleLink Skywire CAT-M1 chip, see firmware update documentation here
Important notes
In order to use the Sequans Monarch modem on the Verizon network, you need to establish a PDN to connect to the ThingSpace server.
NOTE:
In some cases, (depending on the SIM card), you may need to attach first the Admin PDN (cid=2) before the establishment of Internet PDN.
Change Attach PDN (persistent configuration)
Integrating certificates
Certificates are required to establish a secure connection between the client and server. These certificates can be obtained directly from the ThingSpace Portal.
Click here for more information on Certificates.
How to download certificates
1. Login to ThingSpace and click the Credentials tab.
2. Download the certificates.
3. Add these “cacert.pem, client-cert.pem and client-key.pem” files to the datatx folder.
Sequans Non-Volatile Data Commands
The commands listed in this section allow writing and reading data (Certificate, etc.) to and from the non-volatile (NV) memory or to and from the Flash File System. Stored NV data will be persistent against device reboot and software upgrades.
| Command | Possible Response(s) |
|---|---|
| OK ERROR +CME ERROR: <err> |
| OK ERROR +CME ERROR: <err> |
| OK |
| +SQNSNVW: 'certificate”, (list of supported <index>), (list of supported <size>) |
This command allows you to write and delete data (Certificate, etc.) to/from the non-volatile (NV) memory. Write command usage & syntax may change depending on the type of data to store.
AT+SQNSNVW='certificate',<index>,<size><CR><LF><data>
This write command with 'certificate' type should be used to write the certificate to non-volatile memory. After the certificate is uploaded to your modem, public certificates are immediately available for all client secured IP connections (+SQNSUPGRADE, Secured socket). For secured socket in server mode, certificate <index> should be used to assign private certificate to secure server.
- An <index> will be used by the system to identify the certificate for future operations (delete, etc.)
- The <size> parameter corresponds to the exact number of bytes of the certificate to upload.
After AT+SQNSNVW write command issued, send certificates to the modem in Privacy-enhanced Electronic Mail (PEM) format. As soon as <size> bytes have been received, operation is automatically completed. If the certificate is successfully uploaded and verified, then the response is OK. If the certification upload fails, then an error code is reported. To delete a certificate, write a 0 byte certificate using certification ID as <index>.
AT+SQNSNVW='privatekey',<index>,<size><CR><LF><data>
This write command with 'privatekey' type will write a private key in PEM format to the non-volatile memory. Private keys are used by +SQNSJWTENCODE command.
NOTE:
Private RSA keys with password are not supported.
Adding ThingSpace Certificates to the Monarch modem
Before execution of any ThingSpace specific AT commands the TLS data must be uploaded to the device with following commands:
NOTE:
By default, the client ID will be an IMEI code from the device. All MQTT topics used for interactions between the ThingSpace cloud server are based on the client ID.
| Command | Description | Comment |
|---|---|---|
| ThingSpace Root CA | ThingSpace Root CA id must be 0 |
| Device private key | Device private key id must be 2 |
| Device certificate | Device certificate ID must be 1 |
NOTE:
ThingSpace provides certificates and private keys files with CRLF (carriage return and line feed) line-ending. The <size> of the certificate or the private key must be the size of the appropriate file after removing CR (carriage return) from it. To remove CR use linux command: tr -d 015 < file_with_cr > no_cr_file
Sending and receiving data
The Sequans Monarch ThingSpace integration leverages ATtention (AT) commands to simplify the integration effort with applications.
The logic of this solution can be viewed on the example below:
Configure MQTT ThingSpace Client: +VZWTSCFG
| Command | Possible Response |
|---|---|
| OK ERROR |
|
|
Description
This command allows you to configure your ThingSpace implementation modem with the ThingSpace server.
Defined values
<enabled>
1 or 0. To enable use 1, to disable use 0 respectively.
simpm.thingspace.verizon
ThingSpace server name. Make sure you loaded appropriate certificates before use.
8883
Port number. TLS is applied and cannot be removed. Default port 8883 is used, assigned by IANA.
<AT+SQNSMQTTCLIENTCONNECT>
Initiate MQTT connection to a broker.
Incoming Unsolicited Result Code (URC) for activation: +VZWTSUNITONBOARDREQ:
Possible Requests(s)
Description
This is an asynchronous URC indicating that wireless service has been activated for the device.
Reports Current Sensor Definition: +VZWTSUNITONBOARDRSP
| Command | Possible Response |
|---|---|
| OK ERROR |
|
|
Description
This predefined message will be reported after client has been successfully connected.
Defined values
<bytes>
Number of bytes used in JSON.
Incoming URC for command request: +VZWTSUNITCMDREQ
Possible Requests(s)
++VZWTSUNITCMDREQ=<UCD>,<CUUID>[,<CNAME>][,<VALUE>]
Description
This is an asynchronous URC which comes upon remote command request in topic
ThingspaceSDK/<IMEI>/ TSServerPublishCommand.
URC request examples:
+VZWTSUNITCMDREQ='GetOtp','00000000-0000-0000-C000-446655440000'
+VZWTSUNITCMDREQ='Set','00000000-0000-0000-C000-446655440000','unitState ','false'
+VZWTSUNITCMDREQ='Get','00000000-0000-0000-C000-446655440000','MovementEvent'
Defined values
<UCD>
Unit command. Set, Get, GetOtp, SetOtp
<CUUID>
Command uuid
<CNAME>
Characteristic name
<VALUE>
Characteristic value (for Set)
Responding to a Server Request: +VZWTSUNITCMDRSP
| Command | Possible Response |
|---|---|
| OK ERROR |
|
|
Description
Here is a response:
{
'unitCommand': '<UCD>',
'statusMsg': '<SMG>',
'statusCode': '<SCD>',
'commandUUID': '<SMG>',
}
Defined values
<UCD>
Unit command. Set, Get, GetOtp, SetOtp
<CUUID>
Command uuid
<SCD>
Status code
<SMG>
Status message
Responding to a Server Request with a Payload: +VZWTSUNITCMDPLDRSP
| Command | Possible Response |
|---|---|
| OK ERROR |
|
|
Description
Set response to specific request from the server.
Example response
{
'unitCommand': 'GetOtp',
'characteristicsName': 'DevcieInfo',
'commandUUID': '00000000-0000-0000-C000-446655440000',
'statusMsg': 'OK',
'statusCode': 200,
'payload': {
'DeviceInfo': {
'Baseband Version': '1.0.0',
'Build ID': 'abc123',
'Device ID': 'abc123',
'ICCID': '8991101200003204510',
'IMEI': '359223015426526',
'IMSI': '250-07-ХХХХХХХХХХ',
'Kernel Version': '4.x.y',
'Language': 'en',
'Last Power On': 'MM-DD-YYYY HH:MM:SS',
'Manufacturer': 'Verizon',
'Model': 'vas-model-1',
'Chipset': 'Sequans 3330',
'NFC': 'Off',
'Network Location Provider': 'Off',
'OS Version': '6.0.0',
'Rooted': 'yes',
'Screen Size': '1920*1080',
'Screen Timeout': '10',
'Standalone GPS': 'off',
'Time Zone': 3
}
}
}
Defined values
<UCD>
Unit command. Set, Get, GetOtp, SetOtp
<CUUID>
Command uuid
<SCD>
Status code
<SMG>
Status message
<plsize>
Payload size
<Payload>
JSON payload
Running the ThingSpace Sample App
Verizon provides a temperature sensor ThingSpace End Device application template script written in Python. You must install Python 2.7 or later and pyserial to run the script. This script automatically reports sensor, MCU, and modem diagnostic data to ThingSpace every 5 seconds. The temperatureSensor.py application simulates a temperature sensor (ts.device.sdk.thermometer) and reports temperatures periodically to the ThingSpace server. The TemperatureSensor.py script requires the pySerial module.
NOTE:
The modem needs to establish Internet PDN to connect the ThingSpace server.
See Flashing the modem firmware section for more information.
End-device is connected to the Monarch modem through UART0 (921600 bauds, HW flow control) and communicates using an AT interface. A debug PC can be connected to the Monarch console through UART1 (115200 bauds, no flow control).
For Monarch test kit usage, please refer to dedicated documentation:
- Sequans test kit user manual: VZM20Q-TestKitUserManual_B4-B13_Rev2.pdf
- Nimbelink test kit user manual: 30192_NL-M1DK_UserManual.pdf
usage: temperatureSensor.py [-h] [-p PORT] [-V] [-r BAUDRATE]
[--ca CA] [--cert CERT] [--key KEY]
[--uid UID] [--name NAME]
[--report REPORT]
Temperature sensor (ts.device.sdk.thermometer) Thingspace End Device application template script.
optional arguments:
-h, --help show this help message and exit
-p PORT, --port PORT serial port name (e.g., COM17 or /dev/ttyUSB1)
-V, --verbose Enable verbose mode
-r BAUDRATE, --baudrate BAUDRATE
serial port baud rate
--ca CA ThingSpace Root CA
--cert CERT ThingSpace Client Cert
--key KEY ThingSpace Client Key
--uid UID ThingSpace Device Uuid
--name NAME ThingSpace Device Name
--report REPORT Temperature reporting period in seconds (0 for no reporting)
Creating a device on ThingSpace
In order for the ThingSpace platform to receive data from your device and associate your device with a certificate, you need to create a new device on ThingSpace.
To create a new device on ThingSpace, visit the ThingSpace Portal Guide.
End-device connection
1. Connect the End-Device (test PC) to the Sequans test kit.
- UART0 (921600 bauds, HW flow control): AT command
- UART1 (115200 bauds, no flow control): Monarch console (Optional)
2. Power on the VZM20Q test kit.
3. Open the interactive shell to launch the ThingSpace End-Device sample application command line (temperatureSensor.py script)
To establish the connection, upload the Server CA certificate, client certificate and private key to the Monarch device.
To learn more about certificates see Integrating Certificates.
User can directly exercise AT commands or delegate the job to temperatureSensor.py script (automatizes usage of same AT command).
Configuring certificates with the temperature sensor script
You can use the temperatureSensoer.py script to load new certificates and keys to the modem. Each time certificates and keys are provided on the command line; ThingSpace certificates will be overwritten by new certificates and keys.
Launching the script without security data previously configured in the module will generate the following errors:
!WARN! ThingSpace Root CA certificate is absent, please upload it using --ca option
!WARN! ThingSpace Client certificate is absent, please upload it using --cert option
!WARN! ThingSpace Client private key is absent, please upload it using --key option
To load security material, use the command line options below:
> temperatureSensor.py -p COM20 -r 921600 --name mySuperThermometer --uid c49153be- de94-6f5d-eec0-8f94e1d98fc4 --ca thingspaceserver.pem --cert 358227051529086.cert.pem --key 358227051529086.private.keyThis command will upload certificates and keys to the LTE module, and check connections to ThingSpace.
NOTE:
In your terminal logs, '+VZWTSCONNECT: 1' state means that connection has been established successfully with the ThingSpace server.
Testing and Validation
ThingSpace logs are displayed in your modem terminal by default
NOTE:
You need to create a ThingSpace account and download and install the certificates before testing and validation.
temperatureSensor.py -p COM20 -r 921600 --name mySuperThermometer --uid c49153be-de94-6f5d- eec0-8f94e1d98fc4
Write : 'AT+VZWTSCONNECT?'
Read : '<LF><CR>'
Read : +VZWTSCONNECT: 1 '<LF><CR>'
Read : '<LF><CR>'
Read : 'OK<LF><CR>'
NOTE:
If you have not activated your device on ThingSpace, see the Activating Devices section of the ThingSpace Portal Guide
Device communication server testing
1. Launch the ThingSpace End-Device sample command line application (temperatureSensor.py script).
2. Wait for the connection (ensure certificates are added and the device is activated in ThingSpace).
temperatureSensor.py -p COM20 -r 921600 --name mySuperThermometer --uid c49153be-de94-6f5d- eec0-8f94e1d98fc4
[...]
Write : 'AT+VZWTSCONNECT?'
Read : '<LF><CR>'
Read : +VZWTSCONNECT: 1 '<LF><CR>'
Read : '<LF><CR>'
Read : 'OK<LF><CR>'
3. Open the ThingSpace portal Devices page.
4. Click on the device UID to access the Device Details page.
5. Select the Properties panel.
6. Use the drop-down menu to select a property you want to configure.
7. Click in the Value box and set a new value.
8. Click on the Add green button. The Set Device Properties widget appears.
9. Click on the Set green button. The response status will display when the action is complete on the server side.
10. End-Device receives set message.
Thu Dec 14 14:35:03 2017 >EXE> Read :
'+VZWTSUNITCMDREQ:'Set','358227051529086_g8u3qyiz','temperature','1234'
Download Sequans Network Software
11. Answer with Set OK message.
Device property SET request handler
CUUID: 358227051529086_g8u3qyiz
CNAME: 'temperature'
VALUE: 1234
Reset device temperature to 1234
Write : 'AT+VZWTSUNITCMDRSP='Set','358227051529086_g8u3qyiz','200','OK'
Read : '<LF><CR>'
Read : 'OK<LF><CR>'
12. Corresponding raw messages can be viewed on your device.
I [SQNSMQTT] sqnsmqtt_message_callback @ mqttclient.cc:331: MQTT RX: Received new message:'{'unitCommand':'Set','commandUUID':'358227051529086_g8u3qyiz','characteristicsName':'temper ature','value':'1234'}' from topic 'ThingspaceSDK/358227051529086/TSServerPublishCommand'
I [SQNSMQTT] sqnsmqtt_message_callback @ mqttclient.cc:338: Calling external handler (0x0x1c46ae60) for new incomming message for client (0) with result (0)
I [VZWTS] vzwOnNewIncommingMsgCbk @ vzwts_at.cc:420: Incoming message to 'TSServerPublishCommand' from the broker
I [VZWTS] atVzwTsUnitCmdRspHandler @ vzwts_at.cc:582: New JSON: {'unitCommand':'Set','commandUUID':'358227051529086_g8u3qyiz','statusCode':'200','statusMsg' :'OK'}
I [SQNSMQTT] sqnsmqtt_client_publish @ mqttclient.cc:705: MQTT TX: Client (0) publishing payload ({'unitCommand':'Set','commandUUID':'358227051529086_g8u3qyiz','statusCode':'200','statusMsg ':'OK'}) into topic (ThingspaceSDK/358227051529086_g8u3qyiz/UNITCmdResponse), with QoS 0 (at most once)
D [SQNSMQTT] sqnsmqtt_log_callback @ mqttclient.cc:264: Client 358227051529086 sending PUBLISH (d0, q0, r1, m3, 'ThingspaceSDK/358227051529086_g8u3qyiz/UNITCmdResponse', ... (98 bytes))
I [SQNSMQTT] sqnsmqtt_publish_callback @ mqttclient.cc:289: Publish confirmed. PUBLISH CONFIRMATION HANDLER DOES NOTHING BY DEFAULT, to override use publish_callback
Download Sequans Network Download
sku: NL-SW-LTE-SVZM20
The Skywire LTE-M embedded modem was the first modem to be end-device certified on the Verizon 4G LTE Network. This low-power, low-cost embedded modem features a U.FL port for antenna flexibility and is pin-compatible, enabling future-proof migration to new technologies.
Skywire embedded modems dramatically reduce the cost, risks and timelines of IoT product development. With known-good RF engineering and fully validated software, Skywire allows you to focus on your application and not engineering cellular radios. Standardized connectivity gives you flexibility to update and alternate radios for new geographies, carriers and technologies. Further, our embedded modems are “End-Device Certified”, meaning your end-product will not need to go through the complex process of carrier certification. This is critical for the first release of your product and each iteration as you obtain market feedback. Skywire modems significantly reduce time-to-market and are ideal for product development through large-scale production. All Skywire modems are patented and backed by industry leading documentation and expert-level product support.
The NL-SW-LTE-SVZM20 Skywire® modem is end of life. It is not recommended for new design (NRND).
Skywire FAQs
Skywire Modems Comparison Chart