Thingstream Client Library  BLD4131-v2.13
Macros | Typedefs | Functions
modem2_transport.h File Reference

A modem driver (implemented as a ThingstreamTransport instance) that supports both USSD and UDP communication. More...

#include <stdbool.h>
#include "modem_transport.h"
#include "transport_api.h"

Macros

#define MODEM2_USSD_BUFFER_LEN
 
#define MODEM2_UDP_BUFFER_LEN
 
#define Thingstream_UssdInit
 
Modem2 Transport flags

Flags that can be passed to Thingstream_createModem2Transport()

#define MODEM_PREFER_USSD   (0x100)
 
#define MODEM_SKIP_INFO_INIT   (0x200)
 
#define MODEM2_LOG_PARSED   (0x400)
 
#define MODEM2_LOG_PARSING   (0x800)
 

Typedefs

typedef const struct ThingstreamModem2UdpConfig_s * ThingstreamModem2UdpInit(uint32_t version, struct ThingstreamModem2SharedState_s *gState)
 

Functions

ThingstreamTransportThingstream_createModem2Transport (ThingstreamTransport *inner, uint16_t flags, uint8_t *buffer, uint16_t bufSize, ThingstreamModem2UdpInit udpConfigInit, ThingstreamPrintf_t logger)
 
ThingstreamTransportResult Thingstream_Modem2_sendLine (ThingstreamTransport *self, const char *line, uint32_t millis)
 
uint32_t Thingstream_Modem2_getCUSDErrors (ThingstreamTransport *self, uint32_t andClear)
 
uint32_t Thingstream_Modem2_getSeriousErrors (ThingstreamTransport *self, uint32_t andClear)
 
ThingstreamTransportResult Thingstream_Modem2_setBearerMSS (ThingstreamTransport *self, uint16_t mss)
 
void Thingstream_Application_modemBinaryCallback (const uint8_t *data, uint16_t len)
 
void Thingstream__dontUseLineBufferTransportWithModem2 (void)
 

Detailed Description

A modem driver (implemented as a ThingstreamTransport instance) that supports both USSD and UDP communication.

This driver is used with a hardware specific modem configuration. See the list of supported modems.

Example code initializing the stack and sending a test message:

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
// add prototype for ThingstreamTransport to send/receive data to/from the
// uart connected to the modem hardware.
#include "serial_transport.h"
// add prototype for UDP hardware configurations
#include "modem2_config.h"
// add prototypes for the Thingstream stack components
#include "client_api.h"
// declare some buffers
static uint8_t ringBuf[250];
static uint8_t modemBuf[MODEM2_UDP_BUFFER_LEN];
// A macro to check if an error is reported and print/exit if problem found
#define ASSERT(truth) \
do \
{ \
if (!(truth)) \
{ \
printf("ASSERT fail @ %d\n", __LINE__); \
exit(1); \
} \
} while (0)
// a routine that constructs the Thingstream stack to use UDP protocol and
// the u-blox SARA-R4xx modem.
ThingstreamClient* create_thingstream_stack(uint16_t logFlags,
uint16_t modemFlags)
{
// create the lowest level transport (note that the arguments to
// serial_transport_create(...) are target specific and are defined
// in the target specific file serial_transport.h)
ThingstreamTransport* transport = serial_transport_create("/dev/ttyS0");
ASSERT(transport != NULL);
// wrap data received from the serial port with a ring buffer.
// The ring buffer can be called from the interrupt service routine of the
// serial driver.
// The buffer must be statically allocated.
ringBuf,
sizeof(ringBuf));
ASSERT(transport != NULL);
// wrap modem to/from serial activity with logger if required
if (logFlags != 0)
{
transport = Thingstream_createModemLogger(transport, printf, logFlags);
ASSERT(transport != NULL);
}
// wrap it into a modem transport
// The buffer must be statically allocated and is used to buffer data sent
// over UDP or USSD.
// When using UDP we suggest a buffer size of MODEM2_UDP_BUFFER_LEN
// but when only USSD the buffer size should be MODEM2_USSD_BUFFER_LEN.
transport = Thingstream_createModem2Transport(transport, modemFlags,
modemBuf, sizeof(modemBuf),
printf);
ASSERT(transport != NULL);
// wrap it with base64 encoding (mandatory for USSD, optional for UDP)
ASSERT(transport != NULL);
// wrap Thingstream protocol implementation
// If you wish to send/receive messages larger than the size of modemBuf then
// you should supply an additional buffer to this api.
transport = Thingstream_createProtocolTransport(transport, NULL, 0);
ASSERT(transport != NULL);
// wrap client to/from thingstream activity with logger if required
if (logFlags != 0)
{
transport = Thingstream_createClientLogger(transport, printf, logFlags);
ASSERT(transport != NULL);
}
// create the client utilizing the stack.
ASSERT(client != NULL);
// initialise the client before use
ASSERT(cRes == CLIENT_SUCCESS);
return client;
}
// A test application to create Thingstream stack using UDP transport
// protocol and send a test message.
int main(int argc, char **argv)
{
ThingstreamClient *client = create_thingstream_stack(0xff, 0);
cRes = Thingstream_Client_connect(client, true, 0, NULL);
ASSERT(cRes == CLIENT_SUCCESS);
cRes = Thingstream_Client_register(client, "Test", &topic);
ASSERT(cRes == CLIENT_SUCCESS);
const char *message = "Hello Thingstream Test";
cRes = Thingstream_Client_publish(client, topic, ThingstreamQOS0, false,
(uint8_t*)message, strlen(message));
ASSERT(cRes == CLIENT_SUCCESS);
// Check for any inbound messages
cRes = Thingstream_Client_ping(client);
ASSERT(cRes == CLIENT_SUCCESS);
}

Macro Definition Documentation

◆ MODEM2_LOG_PARSED

#define MODEM2_LOG_PARSED   (0x400)

If MODEM2_LOG_PARSED is in the flags passed to Thingstream_createModem2Transport() then the modem driver will log items that it successfully parsed from the bytes received from the underlying modem hardware.

This flag bit is ignored if the SDK has been built without the matching support.

◆ MODEM2_LOG_PARSING

#define MODEM2_LOG_PARSING   (0x800)

If MODEM2_LOG_PARSING is in the flags passed to Thingstream_createModem2Transport() then the modem driver will log parsing steps of bytes received from the underlying modem hardware.

Note that this produces a very large amount of logging.

This flag bit is ignored if the SDK has been built without the matching support.

◆ MODEM2_UDP_BUFFER_LEN

#define MODEM2_UDP_BUFFER_LEN

Recommended buffer size for udp sessions.

◆ MODEM2_USSD_BUFFER_LEN

#define MODEM2_USSD_BUFFER_LEN

Recommended buffer size for ussd-only sessions.

◆ MODEM_PREFER_USSD

#define MODEM_PREFER_USSD   (0x100)

If MODEM_PREFER_USSD is in the Thingstream_createModem2Transport() flags then the modem driver will prefer to use USSD for the network connection.

◆ MODEM_SKIP_INFO_INIT

#define MODEM_SKIP_INFO_INIT   (0x200)

If MODEM_SKIP_INFO_INIT is in the Thingstream_createModem2Transport() flags then the modem driver skip those commands in the init string that are for diagnostics and information.

Typedef Documentation

◆ ThingstreamModem2UdpInit

typedef const struct ThingstreamModem2UdpConfig_s* ThingstreamModem2UdpInit(uint32_t version, struct ThingstreamModem2SharedState_s *gState)

Type definition for the hardware specific configuration initialisation routine. When calling Thingstream_createModem2Transport() the application must select the appropriate routine to match the hardware.
See the list of modem initialisation routines.

For other modems please contact suppo.nosp@m.rt@t.nosp@m.hings.nosp@m.trea.nosp@m.m.io

Function Documentation

◆ Thingstream__dontUseLineBufferTransportWithModem2()

void Thingstream__dontUseLineBufferTransportWithModem2 ( void  )

The symbol Thingstream__dontUseLineBufferTransportWithModem2 is used for link-time checking.

If your application gets multiple definition (or duplicate symbol) errors for this symbol then your application may have attempted to create a SDK transport stack with both the modem2 transport and the line buffer transport.

These two transports are incompatible so your application should be using the ring buffer transport instead.

If your application needs to link both modem2 transport and line buffer transports (e.g. you are using line buffer outside the SDK transport stack) then please use Thingstream_createLineBufferTransport() instead of the legacy line_buffer_transport_create() api.

Deprecated:

◆ Thingstream_Application_modemBinaryCallback()

void Thingstream_Application_modemBinaryCallback ( const uint8_t *  data,
uint16_t  len 
)

This application supplied routine will be called when the modem transport receives binary data. If the application does not provide this routine then the binary data will be sent to the Thingstream_Application_modemCallback().

This feature is not supported for all modems, contact suppo.nosp@m.rt@t.nosp@m.hings.nosp@m.trea.nosp@m.m.io for more details.

Parameters
datathe binary data
lenthe length of the binary data

◆ Thingstream_createModem2Transport()

ThingstreamTransport* Thingstream_createModem2Transport ( ThingstreamTransport inner,
uint16_t  flags,
uint8_t *  buffer,
uint16_t  bufSize,
ThingstreamModem2UdpInit  udpConfigInit,
ThingstreamPrintf_t  logger 
)

Create an instance of the modem transport.

Parameters
innerthe inner transport instance to use
flagsa set of control flags. See common modem flags and modem2 flags. Set flags to '0' to get the default settings.
bufferthe transport buffer to be used by outer transports
bufSizethe size of the transport buffer.
When using UDP we suggest a buffer size of MODEM2_UDP_BUFFER_LEN
but when only USSD the buffer size should be MODEM2_USSD_BUFFER_LEN.
udpConfigInitthe initialisation routine for a particular udp modem.
See list of modem initialisation routines.
loggerthe function to use for debug logging
Returns
the modem transport instance

◆ Thingstream_Modem2_getCUSDErrors()

uint32_t Thingstream_Modem2_getCUSDErrors ( ThingstreamTransport self,
uint32_t  andClear 
)

Return the number of accumulated +CUSD: errors.

Parameters
selfthis Transport instance
andClearif non-zero, then clear the count.
Returns
the number of accumulated +CUSD: errors.

◆ Thingstream_Modem2_getSeriousErrors()

uint32_t Thingstream_Modem2_getSeriousErrors ( ThingstreamTransport self,
uint32_t  andClear 
)

Return the number of accumulated serious errors (those that trigger a modem reset to recover)

Parameters
selfthis Transport instance
andClearif non-zero, then clear the count.
Returns
the number of accumulated serious errors.

◆ Thingstream_Modem2_sendLine()

ThingstreamTransportResult Thingstream_Modem2_sendLine ( ThingstreamTransport self,
const char *  line,
uint32_t  millis 
)

Send the line to the modem and wait for an OK response. The application can implement Thingstream_Application_modemCallback() to receive any response from the modem caused by the sent line.

Parameters
selfthis instance of modem transport
linea null-terminated line to send to the modem ("\r\n" will be added)
millisthe maximum number of milliseconds to run
Returns
an integer status code (success / fail)

◆ Thingstream_Modem2_setBearerMSS()

ThingstreamTransportResult Thingstream_Modem2_setBearerMSS ( ThingstreamTransport self,
uint16_t  mss 
)

Set the maximum sector size for the UDP transmissions. This must be called before the Thingstream stack is initialised.

Parameters
selfthis Transport instance
mssthe maximum-sector-size for the UDP transmissions
ThingstreamClient
struct ThingstreamClient_s ThingstreamClient
Definition: client_api.h:50
Thingstream_uBloxSaraR4Init
ThingstreamModem2UdpInit Thingstream_uBloxSaraR4Init
Thingstream_createClientLogger
ThingstreamTransport * Thingstream_createClientLogger(ThingstreamTransport *inner, ThingstreamPrintf_t log, uint8_t level_mask)
log_client_transport.h
ThingstreamTransport implementation that logs thingstream requests made to the thingstream transport ...
Thingstream_Client_connect
ThingstreamClientResult Thingstream_Client_connect(ThingstreamClient *client, bool cleanSession, uint16_t keepAlive, const char *domainKey)
Thingstream_createBase64CodecTransport
ThingstreamTransport * Thingstream_createBase64CodecTransport(ThingstreamTransport *inner)
Thingstream_createModem2Transport
ThingstreamTransport * Thingstream_createModem2Transport(ThingstreamTransport *inner, uint16_t flags, uint8_t *buffer, uint16_t bufSize, ThingstreamModem2UdpInit udpConfigInit, ThingstreamPrintf_t logger)
Thingstream_Client_ping
ThingstreamClientResult Thingstream_Client_ping(ThingstreamClient *client)
Thingstream_createProtocolTransport
ThingstreamTransport * Thingstream_createProtocolTransport(ThingstreamTransport *inner, uint8_t *buffer, uint16_t len)
ThingstreamResult
ThingstreamResult
Definition: thingstream_result.h:34
client_api.h
The Thingstream Client API.
ThingstreamTopic
Definition: client_api.h:84
Thingstream_createClient
ThingstreamClient * Thingstream_createClient(ThingstreamTransport *transport)
modem2_config.h
Configuration files for modems with UDP support in the Thingstream SDK.
CLIENT_SUCCESS
@ CLIENT_SUCCESS
Definition: thingstream_result.h:36
ring_buffer_transport.h
ThingstreamTransport implementation that adds ring buffering on callbacks e.g. between a serial conne...
base64_codec_transport.h
Base64 codec implemented as a ThingstreamTransport instance.
thingstream_transport.h
Thingstream protocol implementation.
ThingstreamTransport
Definition: transport_api.h:147
ThingstreamQOS0
@ ThingstreamQOS0
Definition: client_api.h:133
Thingstream_createRingBufferTransport
ThingstreamTransport * Thingstream_createRingBufferTransport(ThingstreamTransport *inner, uint8_t *data, uint16_t size)
Thingstream_Client_register
ThingstreamClientResult Thingstream_Client_register(ThingstreamClient *client, const char *topicName, ThingstreamTopic *pOutTopic)
log_modem_transport.h
ThingstreamTransport implementation that logs traffic between modem and serial transports.
Thingstream_Client_publish
ThingstreamClientResult Thingstream_Client_publish(ThingstreamClient *client, ThingstreamTopic topic, ThingstreamQualityOfService_t qos, bool retained, uint8_t *payload, uint16_t payloadlen)
Thingstream_Client_init
ThingstreamClientResult Thingstream_Client_init(ThingstreamClient *client)
Thingstream_createModemLogger
ThingstreamTransport * Thingstream_createModemLogger(ThingstreamTransport *inner, ThingstreamPrintf_t log, uint8_t level_mask)
MODEM2_UDP_BUFFER_LEN
#define MODEM2_UDP_BUFFER_LEN
Definition: modem2_transport.h:268