Arduino Example Application  BLD4131-v2.13
Arduino Example Application Documentation

Arduino IDE Example Application

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.

Prerequisites

Hardware

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:

  • Log output goes to the UART used for programming the device.
  • The modem should be connected to a different hardware UART if available, otherwise software serial should be used. See the target specific setup in the example hardware_config.h files.

Application description (ThingstreamEcho and ThingstreamUDPEcho)

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.

Logging

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.

Problems with modem logging

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:

  • increase the size of the SerialTransportState.buffer[] (in src/serial_transport.cpp) to have space for the largest possible transmission (about 1k for UDP)
  • enable flow control on the modem uart
  • use a significantly faster baud rate for the debug uart relative to the modem uart

ThingstreamEcho

Uses the modem USSD transport, Thingstream_createModemUssdTransport(), to communicate with the Thingstream server.

ThingstreamUDPEcho

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.

Arduino build requires 'precompiled' library support

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.

Building and flashing the application from the Arduino IDE

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.

Building and flashing the application using PlatformIO

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:

mkdir test
cd test
platformio init --board leonardo
unzip ../library/Thingstream.zip -d lib
cp lib/Thingstream/examples/ThingstreamEcho/ThingstreamEcho.ino src/

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.


Release Notes

Release History

Release v2.8: 25-May-2021

  • Arduino: Add support for SODAQ SARA AFF and SFF
  • Arduino: Move board definitions to separate header file, `hardware_config.h`

Release v2.5: 29-Oct-2020

  • Arduino: Change example to use Thingstream_Application_subscribeCallback()

Release v2.4: 13-Aug-2020

  • Arduino: Add SDK modem and client logging to the examples

Release v2.3: 18-Jun-2020

  • Arduino: Add support for the Arduino MKR NB 1500
  • Arduino: Add support for STM32 targets
  • Arduino: Change the ESP32 test target to the LILYGO TTGO T-Call
  • Arduino: Add an example which uses the UDP/USSD dual protocol transport (modem2)
  • Arduino: Add 'lineBased' parameter to serial_transport_create()
  • Arduino: Remove use of SerialWrapper

Release v2.2: 20-Feb-2020

  • Arduino: Add support for PlatformIO 4

Release v2.1: 09-Jan-2020

  • Arduino: update example to use SDK v2 API

Release v1.43: 10-Sep-2019

  • Add support for Teensy 3.x boards

Release v1.36: 24-May-2019

  • Improve robustness of the ThingstreamEcho example
  • Provide an example platformio.ini for all tested targets

Release v1.31: 07-Feb-2019

  • Add support for ESP32 and atmega2560

Release v1.29: 06-Nov-2018

  • Add support for SAMD21 boards

Release v1.28: 18-Oct-2018

  • Add ESP8266 support to example

Release v1.23: 29-Jun-2018

  • Initial AVR ATMEGA example