![]() |
Arduino Example Application
BLD4131-v2.13
|
Version: BLD4131-v2.13
This document describes the Arduino example applications, which demonstrate sending messages through Thingstream.
See Thingstream Client SDK for documentation of the Thingstream Client library.
These examples have been tested on the following platforms:
Name | MCU | Modem | Comments |
---|---|---|---|
Arduino Leonardo | atmega32u4 | none | insufficient space for UDP/modem2 |
Arduino UNO | atmega328p | none | insufficient space for UDP/modem2 |
Arduino M0 | SAMD21 | none | |
Arduino MKR ZERO | SAMD21 | none | |
Arduino MKR GSM 1400 | SAMD21 | SARA-U201 | |
Arduino MKR NB 1500 | SAMD21 | SARA-R410M | no USSD support |
Arduino Mega 2560 | atmega2560 | none | |
WeMos/LOLIN D1/mini | ESP8266 | none | |
LILYGO TTGO T-Call | ESP32 | SIM800L | |
Teensy 3.2 | MK20DX256 | none | |
Nucleo 64 L053R8 | STM32L053R8 | none | |
SODAQ SARA AFF R4 | SAMD21 | SARA-R4xx | no USSD support |
SODAQ SARA SFF R4 | SAMD21 | SARA-R4xx | no USSD support |
Modification may be required to build and run these examples. Please check the hardware_config.h
file included with each example.
Hardware assumptions and setup:
hardware_config.h
files.On reset or power-up, the application connects to the Thingstream server and subscribes to an example topic, then publishes a test message to that same topic. It waits for a minute, accepting incoming messages, and then publishes the test message again. The messages can be seen arriving in the Thingstream console, specifically on the Thing Details
page corresponding to the Thingstream SIM card used. Due to the topic subscription, the Thingstream server will also send the test message back to the device.
Rather than a continuous 'publish/wait for messages' cycle, practical applications would usually either disconnect for a set period or wait until an event requires further communication. It would likely reconnect specifying false
for the cleanSession
argument to Thingstream_Client_connect()
in order to reuse any subscriptions from the previous session.
The device could also stay connected by calling Thingstream_Client_ping()
periodically, which will send a PING
message to the server and keep the connection alive.
Progress logs and error messages can be seen via the Serial Monitor.
The serial transport
used by the application provides basic send/receive logging and timestamps. The amount of logging produced is controlled by the debugLevel
parameter to serial_transport_create()
.
The Thingstream SDK can also produce log output. Logging modem data may be helpful for debugging communication issues. Thingstream client calls may also be logged to monitor application progress. This type of logging can be enabled in the application by defining DEBUG_LOG_MODEM and/or DEBUG_LOG_CLIENT
The logging provided by the SDK is more comprehensive and user friendly than that offered by serial transport
however it is larger in terms of code size and memory usage and therefore might not be suitable for smaller targets.
SDK modem logging effectively replaces serial transport
logging so there is no need to use both.
In some circumstances DEBUG_LOG_MODEM
may cause loss of input data as a result of the blocking nature of the debug logging over slow serial. Possible solutions:
SerialTransportState.buffer[]
(in src/serial_transport.cpp
) to have space for the largest possible transmission (about 1k for UDP)Uses the modem USSD transport, Thingstream_createModemUssdTransport()
, to communicate with the Thingstream server.
Uses the UDP/USSD dual-protocol modem transport, Thingstream_createModem2Transport()
, to communicate with the Thingstream server. For boards that include a modem, THINGSTREAM_MODEM_INIT
is configured in hardware_config.h
. For other targets please define THINGSTREAM_MODEM_INIT
to the appropriate modem configuration routine. See Thingstream_createModem2Transport()
for full details.
The Thingstream SDK client is provided prebuilt and the following build instructions assume that the precompiled
property is supported.
The Arduino IDE uses a build tool arduino-builder
, which must be at least v1.4.0. Arduino IDE versions v1.8.6 and later support the feature.
The example is provided as an Arduino library in library/Thingstream.zip
Launch the Arduino IDE and use the Sketch
->Include Library
-> Add .ZIP Library
menu option to load the Thingstream library.
The Thingstream example should then be available on the File
-> Examples
menu (near the end of the list in the Examples from Custom Libraries
section). It is ready to Verify and Upload in the usual manner.
Add the Thingstream SDK client library and example to a suitable PlatformIO project. The easiest way to install the library is to extract Thingstream.zip
into the lib
folder.
Example for the Arduino Leonardo:
The Thingstream Arduino library contains an example configuration in extras/platformio.ini
, which shows the required settings for a number of supported platform and board combinations.
When using an existing platformio.ini
instead of the one provided, appropriate build flags must be included in order to link the precompiled libthingstream.a
. For example, on the Leonardo board, one would add build_flags = -Llib/Thingstream/src/atmega32u4 -lthingstream
to platformio.ini
, or specify the same flags in environment variable PLATFORMIO_BUILD_FLAGS
.
Please note that the Thingstream SDK client library contains multiple versions of libthingstream.a, one for each supported target architecture. Please consult the example file extras/platformio.ini
to see how the appropriate build flags can be set for a range of boards.
Then use the PlatformIO IDE or platformio
command to build the example and upload it to the target.