ThingSpace is an 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 has been pre-integrated on the Qualcomm LTE CAT-M1 Modem. The combination of the LTE Cat-M1 capabilities of the 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 wide-range of IoT use cases including asset management, industrial automation, wearables, smart cities and more.
By the end of this guide, you will know how to install the ThingSpace Client on your device and how to use the sample application to send and receive data through ThingSpace.
Before you begin
There are a few things you will need to do before you can get started.
1. Create a ThingSpace account here.
2. Download the following tools:
Item | Description | Version | Source/Vendor | Purpose |
---|---|---|---|---|
1 | ARM Compiler toolchain (RealView Compilation Tools (RVCT)) | ARMCT505B106 | ARM Ltd. | ThingSpace Build |
2 | Module vendor diagnostic and support tools | XX | Module vendor | Flashing build, access to file system and collecting logs |
3 | SCons | 3.0.1. or higher | www.scons.org | Construction tool required to build |
4 | Python | ActiveState | ActiveState | Supports build scripts |
5 | USB Network driver combo | XX | Module vendor | Windows host USB drivers sfor QTI composite devices |
Login to core.thingspace.verizon.com/portal and submit a request to gain access to the ThingSpace Software Development Kit (SDK) for the Qualcomm 9206 modem.
Software Development Kit (SDK) library package
Folder structure
Here is the package folder structure:
Common Header Files: Consists of header files which are shared by both SDK and ThingSpace applications.
config_files – Contains application related configurations files
config.ini – This configuration file contains information related to the data model that is supported by application.
ts_app_autostart – This configuration fileʼs presence will start the application automatically after device bootup.
ts_sdk_config.ini – This configuration file contains the ThingSpace sever address and the APN used for the data call.
oem_app_path.ini – Contains the path to ThingSpace application binary location to be loaded as Downloadable Application Module (DAM)
SDK Library: ThingSpace SDK library for DAM and Kernel application
TS: ThingSpace sample application source
Ts_dam_img: SCons file to compile DAM Module.
ThingSpace build process as Downloadable Application Module (DAM) application
To build the ThingSpace and SDK library as a DAM please follow these steps:
1. Copy “TS\app” folder and “TS\txm_module_preamble.S” from TS Package SDK-Library to \src
2. Copy “SDK Library\SDK-DAM\ts_sdk.lib” from TS Package SDK-Library to \libs
3. Copy the header files from “Common Header Files” to \src\app\inc
4. Copy QAPI, ThreadX API, stringl header files to \include
5. Copy txm_lib.lib, timer_dam_lib.lib to \libs
NOTE: For ThingSpace application with actual sensors, remove the sensor simulate macro.
After organizing the folder structure as described and copying the necessary files, you are ready to compile the ThingSpace client.
From cmd line in:
$build_thingspace_app.bat
thingspace_app.bin gets created in \bin
Cleaning build:
$build_thingspace_app.bat -c
ThingSpace Sample app
Run the Sample app to send diagnostic data to the ThingSpace platform. Verify the results in your diagnostic tool logs.
1. Add config.ini file from the release package <TS Package/config_files /config.ini> into an alternate file location under the datatx folder.
2. Add ts_sdk_config.ini file from the release package <TS Package/config_files /ts_sdk_config.ini> into an alternate file location under the datatx folder.
This config file contains the following information:
Parameter | Default value | Description |
---|---|---|
apn | vzwinternet | APN for establishing the data call |
severip | simpm.thingspace.verizon.com | ThingSpace Server IP or URL |
serverport | 8883 | Standard MQTT port (1883 without security, 883 with security |
keepalive | 60 sec | Keepalive value for MQTT connection in seconds |
clean_session | true | Controls clean session for MQTT connection |
topics | Not present | TS-EP will subscribe to all the topics mentioned here. [“topic1”,“topic2”]If this item is not present, it will subscribe to only ThingSpace SDK/IMEI/TSServerPublishCommand. |
opt_interval | 86400 sec | Interval between sending OTP report in seconds |
3. Add ts_app_autostart file from release package <TS Package/config_files /ts_app_autostart> into an alternate file location under the datatx folder.
a. This is an empty file used for auto starting the application; with the presence of this file, the ThingSpace application starts automatically.
How to run ThingSpace as a Downloadable Application Module (DAM)
When using ThingSpace application as a Downloadable Application Module (DAM), copy the “thingspace_app.binʼ to an alternate file system under the datatx folder. The oem_app_path.ini which contains the location of “thingspace_app.binʼ on the device file system should be copied to the datatx folder.
int ts_oem_app_start()
{
int ret;
#ifdef QAPI_TXM_MODULE
if(TX_SUCCESS != txm_module_object_allocate((VOID *)&ts_thread_handle, sizeof(TX_THREAD)))
{
return - 1;
}
#endif
ret = tx_thread_create(ts_thread_handle, "ThingSpace APP Thread", vzw_client_thread, NULL,
ts_app_stack, TS_THREAD_STACK_SIZE, TS_THREAD_PRIORITY, TS_THREAD_PRIORITY, TX_NO_TIME_SLICE,
TX_AUTO_START);
if(ret != TX_SUCCESS)
{
IOT_INFO("TS_OEM : Thread creation failed\n");
}
return 0;
}
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.
Device messaging with ThingSpace allows you to route data from your embedded devices to other internet-connected services and extensions. It features a low-bandwidth ingestion protocol designed for resource-constrained devices. A message consists of a data payload and metadata. The payload is typically a text string, but can be binary data. Most diagnostic message data is automatically added on the server based on the message source, but you can also specify one or more topics. ThingSpace messages do include an overhead of on average 100 bytes.
Publishing data
Sending data from your device can be done easily using:
[
/**
* @brief Publish event to server
* @param topic_name Publish to topic_name
* @param pub_msg Message to be sent
* @param msg_expiry_time Maximum validity(in secs) of published message in pending queue
* If set as 0, message statys in queue till it is sent out
* @return ESUCCESS or EFAILURE
*/
int thingspace_publish_event(const char *topic_name, const char *pub_msg, uint32_t
msg_expiry_time);
]
By using the ThingSpace SDK, a baseline set of diagnostic data is sent from your device securely to our platform where it can be stored and consumed by your extension.
[
#include "ts_sdk.h" /*include SDK header file*/
#define PUB_MSG_EXPIRY_TIME (60) /*Pub message expiry time if queued*/
json_msg = vzw_json_set_onboard_msg(); //construct message body
if(json_msg != NULL) {
IOT_DEBUG("ThingSpaceApp : Sending UNITOnBoard message\n");
thingspace_publish_event(lh_pub_topic_onboard, json_msg, PUB_MSG_EXPIRY_TIME);
/*send message to server*/
tx_byte_release(json_msg);
} else {
IOT_DEBUG("ThingSpaceApp : Onboard msg creation failed\n");
}
]
Receiving data
Data can be sent through the ThingSpace portal to your end device or through an internet-connected services and extension.
[
/**
* @brief Invoked when message is receivied from server
* @param topic Topic on which message has arrived
* @param server_json_msg JSON message from ThingSpace sever
*/
typedef void (*thingspace_process_message_callback)(const char *topic, const char
*server_json_msg);
]
You can then take action on your device based on the received message.
[
/**
* @brief Message callback
* @param topic Topic name
* @param server_json_msg Server published message
*/
void message_callback(const char *topic, const char *server_json_msg)
{
char *json_msg = NULL;
int updates;
IOT_INFO("ThingSpaceApp : Message callback topic %s\n", topic);
if(strcmp(topic, lh_sub_servercmd_topic) != 0) {
IOT_INFO("ThingSpaceApp : Custom handling topic\n");
return;
}
vzw_json_process_server_cmd_msg((char *)server_json_msg, &cmd_resp_data);
if(flag != 1) {
if(dev_onboard_seq >= 2) {
flag = 1;
IOT_DEBUG(
"Flag is set to one, Dev provisioned. On board sequence completed\n");
thingspace_update_profile_cfg(flag, curr_sens_index, NULL);
}
}
updates = vzw_apply_updated_changes_to_hw(NULL, 0);
if((updates > 0) || unitonboard_pub_req) {
json_msg = vzw_json_create_last_device_state_msg();
thingspace_update_profile_cfg(flag, curr_sens_index, json_msg);
tx_byte_release(json_msg);
unitonboard_pub_req = false;
json_msg = vzw_json_set_onboard_msg();
if(json_msg != NULL) {
IOT_DEBUG("ThingSpaceApp : Sending UNITOnBoard message\n");
thingspace_publish_event(lh_pub_topic_onboard, json_msg, PUB_MSG_EXPIRY_TIME);
tx_byte_release(json_msg);
} else {
IOT_DEBUG("ThingSpaceApp : Onboard msg creation failed\n");
}
}
json_msg = vzw_json_create_cmd_resp_msg(&cmd_resp_data);
if(json_msg != NULL) {
IOT_DEBUG("ThingSpaceApp : Sending ServerCmdResponse message\n");
thingspace_publish_cmd_response(cmd_resp_data.uuid, json_msg, PUB_MSG_EXPIRY_TIME);
tx_byte_release(json_msg);
} else {
IOT_DEBUG("ThingSpaceApp : Resp msg creation failed\n");
}
}
]
Testing and validation will ensure your device can talk to and receive messages from the ThingSpace platform.
Viewing SDK logs
Create a ThingSpace account and download and install the certificates before any testing and validation. You should be able to see device logs from the ThingSpace SDK in your module vendor's diagnostic tools.