#include <ExpressLink.h>

Collaboration diagram for ExpressLink:

Classes
struct	Event

struct	OTAState

Public Types
enum	EventCode : int16_t { UNKNOWN = -2 , NONE = -1 , FIRST_EVENT_CODE = 1 , MSG = 1 , STARTUP = 2 , CONLOST = 3 , OVERRUN = 4 , OTA = 5 , CONNECT = 6 , CONFMODE = 7 , SUBACK = 8 , SUBNACK = 9 , SHADOW_INIT = 20 , SHADOW_INIT_FAILED = 21 , SHADOW_DOC = 22 , SHADOW_UPDATE = 23 , SHADOW_DELTA = 24 , SHADOW_DELETE = 25 , SHADOW_SUBACK = 26 , SHADOW_SUBNACK = 27 , LAST_EVENT_CODE }
	see https://docs.aws.amazon.com/iot-expresslink/latest/programmersguide/elpg-event-handling.html#elpg-event-handling-commands More...

enum	OTACode : int16_t { NoOTAInProgress = 0 , UpdateProposed = 1 , HostUpdateProposed = 2 , OTAInProgress = 3 , NewExpressLinkImageReady = 4 , NewHostImageReady = 5 }
	see https://docs.aws.amazon.com/iot-expresslink/latest/programmersguide/elpg-ota-updates.html#elpg-ota-commands More...

Public Member Functions
	ExpressLink (void)

bool	begin (Stream &s, int event=-1, int wake=-1, int reset=-1, bool debug=false)
	Initializes an ExpressLink interface. More...

bool	cmd (String command)
	Execute AT command and reads all response lines. Escaping and unescaping is handled automatically. Check class attribute `response` (if true returned) and `error` (if false returned). More...

bool	selfTest ()
	equivalent to sending AT and checking for OK response line More...

bool	connect (bool async=false)
	equivalent to: AT+CONNECT or AT+CONNECT! More...

bool	isConnected ()
	equivalent to: AT+CONNECT? and parsing the response for CONNECTED/DISCONNECTED More...

bool	isOnboarded ()
	equivalent to: AT+CONNECT? and parsing the response for STAGING/CUSTOMER More...

bool	disconnect ()
	equivalent to: AT+DISCONNECT More...

bool	reset ()
	soft-reboot of the module, equivalent to: AT+RESET More...

bool	factoryReset ()
	wipe all data and config, equivalent to: AT+FACTORY_RESET More...

bool	sleep (uint32_t duration, uint8_t sleep_mode=0)

Event	getEvent (bool checkPin=true)
	Gets the next pending Event, if available. More...

bool	subscribe (uint8_t topic_index, String topic_name)
	Subscribe to Topic#. More...

bool	unsubscribe (uint8_t topic_index)
	Unsubscribe from Topic#. More...

bool	get (uint8_t topic_index=-1)
	Request next message pending on the indicated topic. More...

bool	send (uint8_t topic_index, String message)
	Same as `ExpressLink::publish - use it instead.` More...

bool	publish (uint8_t topic_index, String message)
	Publish msg on a topic selected from topic list. More...

OTAState	otaGetState ()
	Fetches the current state of the OTA process. More...

bool	otaAccept ()
	Allow the OTA operation to proceed. More...

bool	otaRead (uint32_t count)
	Requests the next # bytes from the OTA buffer. More...

bool	otaSeek (uint32_t address=-1)
	Moves the read pointer to an absolute address. More...

bool	otaApply ()
	Authorize the ExpressLink module to apply the new image. More...

bool	otaClose ()
	The host OTA operation is completed. More...

bool	otaFlush ()
	The contents of the OTA buffer are emptied. More...

bool	shadowInit (uint8_t index=-1)
	Initialize communication with the Device Shadow service. More...

bool	shadowDoc (uint8_t index=-1)
	Request a Device Shadow document. More...

bool	shadowGetDoc (uint8_t index=-1)
	Retrieve a device shadow document. More...

bool	shadowUpdate (String new_state, uint8_t index=-1)
	Request a device shadow document update. More...

bool	shadowGetUpdate (uint8_t index=-1)
	Retrieve a device shadow update response. More...

bool	shadowSubscribe (uint8_t index=-1)
	Subscribe to a device shadow document. More...

bool	shadowUnsubscribe (uint8_t index=-1)
	Unsubscribe from a device shadow document. More...

bool	shadowGetDelta (uint8_t index=-1)
	Retrieve a Shadow Delta message. More...

bool	shadowDelete (uint8_t index=-1)
	Request the deletion of a Shadow document. More...

bool	shadowGetDelete (uint8_t index=-1)
	Request a Shadow delete response. More...

void	passthrough (Stream *destination)
	Enters Serial/UART passthrough mode. All serial communication is bridged between the ExpressLink UART and the passed `destination`. This function never returns. You can use it for debugging or over-the-wire firmware upgrades. More...

String	readLine (uint32_t count=1)

Public Attributes
ExpressLinkConfig	config

String	response

String	error

uint32_t	additionalLines

Static Public Attributes
static const uint32_t	BAUDRATE = 115200
	The default UART configuration shall be 115200, 8, N, 1 (baud rate: 115200; data bits: 8; parity: none; stop bits: 1). There is no hardware or software flow control for UART communications. See https://docs.aws.amazon.com/iot-expresslink/latest/programmersguide/elpg-commands.html#elpg-commands-introduction. More...

static const uint32_t	TIMEOUT = 120000
	The maximum runtime for every command must be listed in the datasheet. No command can take more than 120 seconds to complete (the maximum time for a TCP connection timeout). See https://docs.aws.amazon.com/iot-expresslink/latest/programmersguide/elpg-commands.html#elpg-response-timeout. More...

Protected Member Functions
void	escape (String &value)
	Escapes string in-place so it can be written to ExpressLink UART. More...

void	unescape (String &value)
	Unescapes string in-place after reading it from ExpressLink UART. More...

Friends
class	ExpressLinkConfig

Member Enumeration Documentation

◆ EventCode

enum ExpressLink::EventCode : int16_t

see https://docs.aws.amazon.com/iot-expresslink/latest/programmersguide/elpg-event-handling.html#elpg-event-handling-commands

Enumerator
UNKNOWN
NONE	Failed to parse response, Check `response` for full event. Not defined in ExpressLink TechSpec.
FIRST_EVENT_CODE	No event retrieved, queue was empty. Not defined in ExpressLink TechSpec.
MSG
STARTUP	A message was received on the topic #. Parameter=Topic Index.
CONLOST	The module has entered the active state. Parameter=0.
OVERRUN	Connection unexpectedly lost. Parameter=0.
OTA	Receive buffer Overrun (topic in detail). Parameter=0.
CONNECT	OTA event (see the OTA? command for details). Parameter=0.
CONFMODE	A connection was established or failed. Parameter=Connection Hint.
SUBACK	CONFMODE exit with success. Parameter=0.
SUBNACK	A subscription was accepted. Parameter=Topic Index.
SHADOW_INIT	A subscription was rejected. Parameter=Topic Index.
SHADOW_INIT_FAILED	Shadow[Shadow Index] interface was initialized successfully. Parameter=Shadow Index.
SHADOW_DOC	The SHADOW[Shadow Index] interface initialization failed. Parameter=Shadow Index.
SHADOW_UPDATE	A Shadow document was received. Parameter=Shadow Index.
SHADOW_DELTA	A Shadow update result was received. Parameter=Shadow Index.
SHADOW_DELETE	A Shadow delta update was received. Parameter=Shadow Index.
SHADOW_SUBACK	A Shadow delete result was received. Parameter=Shadow Index.
SHADOW_SUBNACK	A Shadow delta subscription was accepted. Parameter=Shadow Index.
LAST_EVENT_CODE	A Shadow delta subscription was rejected. Parameter=Shadow Index.

◆ OTACode

enum ExpressLink::OTACode : int16_t

see https://docs.aws.amazon.com/iot-expresslink/latest/programmersguide/elpg-ota-updates.html#elpg-ota-commands

Enumerator
NoOTAInProgress
UpdateProposed	No OTA in progress.
HostUpdateProposed	A new module OTA update is being proposed. The host can inspect the version number and decide to accept or reject it. The {detail} field provides the version information (string).
OTAInProgress	A new Host OTA update is being proposed. The host can inspect the version details and decide to accept or reject it. The {detail} field provides the metadata that is entered by the operator (string).
NewExpressLinkImageReady	OTA in progress. The download and signature verification steps have not been completed yet.
NewHostImageReady	A new module firmware image has arrived. The signature has been verified and the ExpressLink module is ready to reboot. (Also, an event was generated.)

Constructor & Destructor Documentation

◆ ExpressLink()

ExpressLink::ExpressLink ( void )

Member Function Documentation

◆ begin()

bool ExpressLink::begin	(	Stream &	u,
		int	event = `-1`,
		int	wake = `-1`,
		int	reset = `-1`,
		bool	d = `false`
	)

Initializes an ExpressLink interface.

Parameters

u	serial uart for AT commands (initialize separately with RX/TX pins)
event	GPIO pin where ExpressLink EVENT pin is connected, set to -1 if not connected (default)
wake	GPIO pin where ExpressLink WAKE pin is connected, set to -1 if not connected (default)
reset	GPIO pin where ExpressLink RESET pin is connected, set to -1 if not connected (default)
debug	uses the default `Serial` stream to print AT commands and responses. Only enable if `Serial` is connected to a different UART than the ExpressLink UART.

Returns: true on success, false on error

◆ cmd()

bool ExpressLink::cmd ( String command )

Execute AT command and reads all response lines. Escaping and unescaping is handled automatically. Check class attribute response (if true returned) and error (if false returned).

Parameters

command e.g., AT+CONNECT or SUBSCRIBE1 (with or without the AT+ prefix)

Returns: true on success, false on error

◆ connect()

bool ExpressLink::connect ( bool async = false )

equivalent to: AT+CONNECT or AT+CONNECT!

Parameters

async true to use non-blocking CONNECT!

Returns: true on success, false on error

◆ disconnect()

bool ExpressLink::disconnect ( )

equivalent to: AT+DISCONNECT

Returns: true on success, false on error

◆ escape()

void ExpressLink::escape ( String & value )

protected

Escapes string in-place so it can be written to ExpressLink UART.

Parameters

value string (will be modified)

◆ factoryReset()

bool ExpressLink::factoryReset ( )

wipe all data and config, equivalent to: AT+FACTORY_RESET

Returns: true on success, false on error

◆ get()

bool ExpressLink::get ( uint8_t topic_index = -1 )

Request next message pending on the indicated topic.

Equivalent to AT+GET{topic_index}.

Parameters

topic_index use -1 (default) for GET, or value for GETx

Returns: true on success, false on error

◆ getEvent()

ExpressLink::Event ExpressLink::getEvent ( bool checkPin = true )

Gets the next pending Event, if available.

Parameters

checkPin true (default) if the EVENT pin should be read; false if the AT+EVENT? command should be used

Returns: Event struct with event code and parameter, code==NONE if no event is pending

◆ isConnected()

bool ExpressLink::isConnected ( )

equivalent to: AT+CONNECT? and parsing the response for CONNECTED/DISCONNECTED

Returns: true if connected, false if disconnected

◆ isOnboarded()

bool ExpressLink::isOnboarded ( )

equivalent to: AT+CONNECT? and parsing the response for STAGING/CUSTOMER

Returns: true if onboarded to customer endpoint, false if staging endpoint

◆ otaAccept()

bool ExpressLink::otaAccept ( )

Allow the OTA operation to proceed.

Equivalent to AT+OTA ACCEPT<EOL>.

Returns: true on success, false on error

◆ otaApply()

bool ExpressLink::otaApply ( )

Authorize the ExpressLink module to apply the new image.

Equivalent to AT+OTA APPLY<EOL>.

Returns: true on success, false on error

◆ otaClose()

bool ExpressLink::otaClose ( )

The host OTA operation is completed.

Equivalent to AT+OTA CLOSE<EOL>.

Returns: true on success, false on error

◆ otaFlush()

bool ExpressLink::otaFlush ( )

The contents of the OTA buffer are emptied.

Equivalent to AT+OTA FLUSH<EOL>.

Returns: true on success, false on error

◆ otaGetState()

ExpressLink::OTAState ExpressLink::otaGetState ( )

Fetches the current state of the OTA process.

Equivalent to AT+OTA?.

Returns: OTA state with code and detail

◆ otaRead()

bool ExpressLink::otaRead ( uint32_t count )

Requests the next # bytes from the OTA buffer.

Equivalent to AT+OTA READ {count}<EOL>.

Retreive payload from ExpressLink::response

Parameters

count decimal value of number of bytes to read

Returns: true on success, false on error

◆ otaSeek()

bool ExpressLink::otaSeek ( uint32_t address = -1 )

Moves the read pointer to an absolute address.

Equivalent to AT+OTA SEEK<EOL> or AT+OTA SEEK {address}<EOL>.

Parameters

address decimal value for read pointer to seek to, or -1 to seek to beginning

Returns: true on success, false on error

◆ passthrough()

void ExpressLink::passthrough ( Stream * destination )

Enters Serial/UART passthrough mode. All serial communication is bridged between the ExpressLink UART and the passed destination. This function never returns. You can use it for debugging or over-the-wire firmware upgrades.

◆ publish()

bool ExpressLink::publish	(	uint8_t	topic_index,
		String	message
	)

Publish msg on a topic selected from topic list.

Equivalent to AT+SEND{topic_index} {message}.

Parameters

topic_index	the topic index to publish to
message	raw message to publish, typically JSON-encoded

Returns: true on success, false on error

◆ readLine()

String ExpressLink::readLine ( uint32_t count = 1 )

◆ reset()

bool ExpressLink::reset ( )

soft-reboot of the module, equivalent to: AT+RESET

Returns: true on success, false on error

◆ selfTest()

bool ExpressLink::selfTest ( )

equivalent to sending AT and checking for OK response line

Returns: true on success, false on error

◆ send()

bool ExpressLink::send	(	uint8_t	topic_index,
		String	message
	)

Same as ExpressLink::publish - use it instead.

Parameters

topic_index
message

Returns: true on success, false on error

◆ shadowDelete()

bool ExpressLink::shadowDelete ( uint8_t index = -1 )

Request the deletion of a Shadow document.

Equivalent to AT+SHADOW{index} DELETE<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ shadowDoc()

bool ExpressLink::shadowDoc ( uint8_t index = -1 )

Request a Device Shadow document.

Equivalent to AT+SHADOW{index} DOC<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ shadowGetDelete()

bool ExpressLink::shadowGetDelete ( uint8_t index = -1 )

Request a Shadow delete response.

Equivalent to AT+SHADOW{index} GET DELETE<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ shadowGetDelta()

bool ExpressLink::shadowGetDelta ( uint8_t index = -1 )

Retrieve a Shadow Delta message.

Equivalent to AT+SHADOW{index} GET DELTA<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ shadowGetDoc()

bool ExpressLink::shadowGetDoc ( uint8_t index = -1 )

Retrieve a device shadow document.

Equivalent to AT+SHADOW{index} GET DOC<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ shadowGetUpdate()

bool ExpressLink::shadowGetUpdate ( uint8_t index = -1 )

Retrieve a device shadow update response.

Equivalent to AT+SHADOW{index} GET UPDATE<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ shadowInit()

bool ExpressLink::shadowInit ( uint8_t index = -1 )

Initialize communication with the Device Shadow service.

Equivalent to AT+SHADOW{index} INIT<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ shadowSubscribe()

bool ExpressLink::shadowSubscribe ( uint8_t index = -1 )

Subscribe to a device shadow document.

Equivalent to AT+SHADOW{index} SUBSCRIBE<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ shadowUnsubscribe()

bool ExpressLink::shadowUnsubscribe ( uint8_t index = -1 )

Unsubscribe from a device shadow document.

Equivalent to AT+SHADOW{index} UNSUBSCRIBE<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ shadowUpdate()

bool ExpressLink::shadowUpdate	(	String	new_state,
		uint8_t	index = `-1`
	)

Request a device shadow document update.

Equivalent to AT+SHADOW{index} UPDATE {new_state}<EOL>.

Parameters

index shadow index. Use -1 (default), to select the unnamed shadow.

Returns: true on success, false on error

◆ sleep()

bool ExpressLink::sleep	(	uint32_t	duration,
		uint8_t	sleep_mode = `0`
	)

◆ subscribe()

bool ExpressLink::subscribe	(	uint8_t	topic_index,
		String	topic_name
	)

Subscribe to Topic#.

Equivalent to AT+CONF Topic{topic_index}={topic_name} followed by AT+SUBSCRIBE{topic_index}.

Parameters

topic_index	index to subscribe to
topic_name	name of topic (empty to skip setting topic in configuration dictionary)

Returns: true on success, false on error

◆ unescape()

void ExpressLink::unescape ( String & value )

protected

Unescapes string in-place after reading it from ExpressLink UART.

Parameters

value string (will be modified)

◆ unsubscribe()

bool ExpressLink::unsubscribe ( uint8_t topic_index )

Unsubscribe from Topic#.

Equivalent to AT+UNSUBSCRIBE{topic_index}.

Parameters

topic_index index to unsubscribe from

Returns: true on success, false on error

Friends And Related Function Documentation

◆ ExpressLinkConfig

friend class ExpressLinkConfig

friend

Member Data Documentation

◆ additionalLines

uint32_t ExpressLink::additionalLines

◆ BAUDRATE

const uint32_t ExpressLink::BAUDRATE = 115200

static

The default UART configuration shall be 115200, 8, N, 1 (baud rate: 115200; data bits: 8; parity: none; stop bits: 1). There is no hardware or software flow control for UART communications. See https://docs.aws.amazon.com/iot-expresslink/latest/programmersguide/elpg-commands.html#elpg-commands-introduction.

◆ config

ExpressLinkConfig ExpressLink::config

◆ error

String ExpressLink::error

◆ response

String ExpressLink::response

◆ TIMEOUT

const uint32_t ExpressLink::TIMEOUT = 120000

static

The maximum runtime for every command must be listed in the datasheet. No command can take more than 120 seconds to complete (the maximum time for a TCP connection timeout). See https://docs.aws.amazon.com/iot-expresslink/latest/programmersguide/elpg-commands.html#elpg-response-timeout.

The documentation for this class was generated from the following files:

src/ExpressLink.h
src/ExpressLink.cpp

Classes

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Friends

Member Enumeration Documentation

◆ EventCode

◆ OTACode

Constructor & Destructor Documentation

◆ ExpressLink()

Member Function Documentation

◆ begin()

◆ cmd()

◆ connect()

◆ disconnect()

◆ escape()

◆ factoryReset()

◆ get()

◆ getEvent()

◆ isConnected()

◆ isOnboarded()

◆ otaAccept()

◆ otaApply()

◆ otaClose()

◆ otaFlush()

◆ otaGetState()

◆ otaRead()

◆ otaSeek()

◆ passthrough()

◆ publish()

◆ readLine()

◆ reset()

◆ selfTest()

◆ send()

◆ shadowDelete()

◆ shadowDoc()

◆ shadowGetDelete()

◆ shadowGetDelta()

◆ shadowGetDoc()

◆ shadowGetUpdate()

◆ shadowInit()

◆ shadowSubscribe()

◆ shadowUnsubscribe()

◆ shadowUpdate()

◆ sleep()

◆ subscribe()

◆ unescape()

◆ unsubscribe()

Friends And Related Function Documentation

◆ ExpressLinkConfig

Member Data Documentation

◆ additionalLines

◆ BAUDRATE

◆ config

◆ error

◆ response

◆ TIMEOUT