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