8 Event handling - AWS IoT ExpressLink

8 Event handling

8.1 Introduction

Events are generated by internal or external occurrences that require the host controller's attention, such as the arrival of messages on one of the subscribed topics, but also error conditions that reflect an unexpected change in the module's internal state.

Events are appended to the module event queue. From there the host can fetch them in order of arrival (FIFO) by polling the event queue periodically (at regular intervals), or, if the EVENT pin is connected, after detecting a (rising edge) signal on the pin.

8.1.1.1   The event queue depth is an implementation dependent parameter that must be documented by the vendor in the module datasheet.

8.1.1.2   The EVENT pin is asserted (HIGH) when the event queue contains one or more events. The EVENT pin is automatically de-asserted as soon as the host processor has emptied the event queue.

8.1.1.3   When the event queue is full, and a new event occurs, the oldest event is discarded (circular buffer).

8.2 Event handling commands

8.2.1 EVENT?   »Request the next event in the queue«

Returns:
8.2.1.1   OK [{event_identifier} {parameter} {mnemonic [detail]}]{EOL}

When the queue contains one or more events, the module response returns the first event in order of arrival (FIFO). See Table 4 below for the predefined event types.

8.2.1.2   OK{EOL}

Acknowledgement of the command. No events where pending, a timer is started counting down time seconds.

The following table contains the definition of common event identifiers and error codes implemented by all ExpressLink modules; they should be considered reserved:

Table 4 - ExpressLink event codes

Event Identifier

Parameter

Mnemonic

Description

0

-

TIMEOUT

A timout occurred.

1

Topic Index

MSG

A message was received on the topic #.

2

0

STARTUP

The module has entered the active state.

3

0

CONLOST

Connection unexpectedly lost.

4

0

OVERRUN

Receive buffer Overrun (topic in detail).

5

0

OTA

OTA event (see the OTA? command for details).

6

Connection Hint

CONNECT

A connection was established or failed.

7

0

CONFMODE

CONFMODE exit with success.

8

Topic Index

SUBACK

A subscription was accepted.

9

Topic Index

SUBNACK

A subscription was rejected.

10

Topic Index

PUBACK

A QoS1 PUBACK was received.

11..19

-

-

RESERVED

20

Shadow Index

SHADOW INIT

Shadow[Shadow Index] interface was initialized successfully.

21

Shadow Index

SHADOW INIT FAILED

The SHADOW[Shadow Index] interface initialization failed.

22

Shadow Index

SHADOW DOC

A Shadow document was received.

23

Shadow Index

SHADOW UPDATE

A Shadow update result was received.

24

Shadow Index

SHADOW DELTA

A Shadow delta update was received.

25

Shadow Index

SHADOW DELETE

A Shadow delete result was received.

26

Shadow Index

SHADOW SUBACK

A Shadow delta subscription was accepted.

27

Shadow Index

SHADOW SUBNACK

A Shadow delta subscription was rejected.

28...39

-

-

RESERVED

40

0

BLE CONNECTED

A BLE Connection was established peripheral role.

41

0 or Hint Code

BLE DISCOVER COMPLETE

0 for successful; >0 vendor defined Hint Codes.

42

0 or Central Index

BLE CONNECTION LOST

Connection was terminated or 0 if peripheral role.

43

GATT Index

BLE SUBSCRIBE START

Subscription started on BLEGATT# while on peripheral mode.

44

GATT Index

BLE SUBSCRIBE STOP

Subscription terminated on BLEGATT# while on peripheral mode.

45

GATT Index

BLE READ REQUEST

Read operation requested at BLEGATT# while on peripheral mode.

46

GATT Index

BLE WRITE REQUEST

Write operation requested at BLEGatt# while on peripheral mode.

47

Subscription Index

SUBSCRIPTION RECEIVED

Subscription was received on BLECentral# connection.

48

BLECentral#

BLE PAIR

Pairing event (see Table 3 - Configuration dictionary non-persistent keys )

49

Auth Index

BLE AUTHORIZE

Authorizing event (see 13.3.6 BLE AUTH[#] [0/1]   »Authorize access to a characteristic« )

Auth Index encoding is defined below in 8.2.1.5.

50

Hint code

BLE EXCEPTION

An exception occurred in the BLE stack. Codes are vendor specific.

≤ 999

-

RESERVED.

≥1000

-

Available for custom implementation.

8.2.1.3   Sleep, reset, and factory reset commands

Clears all pending events.

8.2.1.4   Subscription Indexes

combine a BLECentral Index and BLEGATT Index according to the following formula:

Subscription Index = BLECentral Index *100 + BLEGATT Index

8.2.1.5   Authorization indexes combine a BLEGATT Index with an Operation Value

combine a BLECentral Index and BLEGATT Index according to the following formula:

Subscription Index = BLECentral Index *100 + BLEGATT Index

Auth Index = BLEGATT Index *100 + Operation Value

where Operation Value is:

  • 0 for Read

  • 1 for Read

8.2.1.6   Asynchronous generation of BLE EXCEPTION

A BLE EXCEPTION is generated asynchronously by the BLE stack and the Hint Codes provided must be documented by the vendor in the specific module datasheet.

8.2.2 EVENT! time   »Wait (blocking) for the next event or timeout«

This is a synchronous variant of the EVENT command meant to allow efficient event driven operation in systems that employ only the serial interface, without an additional event pin. The time parameter is mandatory and indicates the maximum amount of time (in seconds) the module will be waiting for an event. Setting time to 0 will set the timer to the maximum value allowed for the module (see 4.6.2 Response timeout).

The implementation of this command is optional.

Returns:
8.2.2.1   OK {event identifier} {parameter} {mnemonic [detail]}{EOL}

When the queue already contains one or more events, the module response returns immediately the first event in order of arrival (FIFO) identically to the asynchronous version of the command (EVENT?). See Table 4 - ExpressLink event codes for the decoding of event codes and corresponding event types. This ends the command, and a timer is not enabled.

If there is no event pending in the event queue, returns only an immediate acknowledgement.

8.2.2.2   OK {EOL}

Acknowledgement of the command. No events where pending, a timer is started counting down time seconds.

8.2.2.3   ERR4 PARAMETER ERROR{EOL}

If the time parameter is greater than the maximum duration allowed for any ExpressLink command (see 4.6.2 Response timeout).

When a new event is generated (for example: message received or BLE notification) the device returns the event identifier prefixed by a sequence of 4 white spaces {NewLine}.

8.2.2.4   \n\n\n\nOK {event identifier} {parameter} {mnemonic [detail]}{EOL}

An event was generated and reported, and the timer stopped as the command completed. The prefixing white spaces are meant to allow the host processor serial interface (UART) to resynchronize its clock, a feature that allows the host processor to enter a low power sleep mode and await for a new character to wake up. Note: it is common for such feature to cause the first character (or pair of) to be corrupted

8.2.2.5   To give the host time to prepare for a low power sleep phase and prevent race conditions, the first event generated is guaranteed to be reported by the ExpressLink module no sooner than 500ms after the acknowledgement response is delivered.

Should an event not be generated before the timer expires, a TIMEOUT event is generated instead.

8.2.2.6   \n\n\n\nOK {EOL}

The timer has expired, and an event is not generated. The event does not contain any parameter or description to reduce the length of the response and allow the host to re-issue immediately a new EVENT! command to maximize the power saving.

Example 1:

AT+EVENT! 0{EOL} #Wait for an event up to the longest possible time (120s) OK{EOL} # Acknowledgement, no events pending, start timer ... after >500ms … \n\n\n\nOK 1 5{EOL} #A message arrived on Topic #5, timer stopped … or after 120s … \n\n\n\nOK 0{EOL} #No event arrived and the timer has expired

Example 2:

AT+EVENT! 10{EOL} # wait up to 10s for an event OK 1 6{EOL} #An even was already in the queue, a message on Topic # 6

8.3 Diagnostic commands

8.3.1 DIAG {command} [optional parameters]   »Perform a diagnostic command«

A number of custom diagnostic commands can be added to assist the developer in their debugging efforts. These commands are vendor and model specific. See the manufacturer's datasheet for specific details.

Diagnostic commands are not checked as part of the ExpressLink qualification test suite.

Diagnostic commands must be documented in the vendor device datasheet.