7 Event handling

7.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.

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

7.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.

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

7.2 Event handling commands

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

Returns:

7.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.

7.2.1.2   OK{EOL}

If the event queue is empty, then the 'OK' response is followed immediately by {EOL}.

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
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.
≤ 999	-		RESERVED.
≥1000	-		Available for custom implementation.

7.2.1.3   Sleep, reset, and factory reset commands automatically clear all events pending.

7.3 Diagnostic commands

7.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.

Example 1:

AT+DIAG PING xxx.xxx.xxx.xxx    # Initiate a Ping of the IP address provided

Example 2:

AT+DIAG SCAN seconds    # Initiates a SCAN of nearby Wi-Fi access points with a timeout