Device Attribute Message Protocol
The Afero architecture uses a messaging protocol that is independent of the wireless technology used. This protocol provides a simple way for the client application to SET or GET attributes on the ASR module.
You will need the information on this page only if you are implementing the protocol yourself, not using afLib or afLib3 API. If you are using the API to communicate with ASR, the information below will be implemented for you.
The format of the messages is defined below:
||Message length including header
0x0B = Set
0x0C = Get
0x0D = Update
0 = Transaction initiated from peripheral
>0 = Transaction initiated from authenticator
||Variable-length attribute value
0x00 = Updated
0x01 = Interrupted; device-side UPDATE in progress or preempted by device-side UPDATE
0x02 = Unknown attribute ID
0x03 = Length exceeded
0x04 = Conflict; previous Set in progress
0x05 = Timeout; Set operation timed out
0xAA = Invalid state; Cloud received unrecognized state value
0x00 = Unknown
0x01 = Unsolicited Afero module-initiated or MCU-initiated Update; e.g., button press
0x02 = Response to Cloud-initiated Set
0x03 = Response to MCU-initiated Set
0x04 = Linking completed
0x05 = A bound attribute was changed
0x06 = Reserved
0x07 = Notify MCU that ASR rebooted; not sent to Cloud
0x08 = Response to local Set; e.g., when a scheduled event fires
0x09 = Reboot
0x0A = Cyclic redundancy check (CRC) failure; used to sync state between device and Cloud when attribute values no longer match
0xAA = Invalid reason; SET when the Cloud receives an UPDATE with either no reason or an invalid reason
||Variable-length attribute value
- A SET for a specific attribute can only be sent by a non-owner of the attribute.
- A GET for a specific attribute can only be sent by a non-owner of the attribute with the exception that an MCU can send a GET message to retrieve the value of its own attribute.
- An UPDATE for a specific attribute can only be sent by the owner of the attribute, except in the following cases:
- ASR is notifying the MCU of the default values of the MCU's attributes immediately following a reboot.
- ASR is sending back the result of an MCU get message for its own attribute.
- Request IDs are always zero unless the transaction is a GET or a SET originally from the service, or the transaction is an UPDATE for a SET or a GET originally from the service.
- For every SET or GET message the owner of a specific attribute receives, it must send a corresponding UPDATE. The owner must parrot back the request ID from the incoming SET or GET message.
- UPDATEs can also occur if the attribute change was initiated locally; for example, if the MCU changes one of its own attributes. In this case there is no corresponding SET or GET transaction.
The receiver of an UPDATE message never sends a response to the message with one exception: ASR can send an unsolicited Update Rejected message if the UPDATE message is bad in one of the following ways:
- Attribute ID is not owned by the sender (MCU is the only possible sender in this case).
- Attribute ID is not in the profile.
- The value length is larger than the length of the attribute in the profile.
- Only one SET or GET transaction for a given attribute can be in flight at a time. If a SET or GET transaction for an attribute has occurred and the corresponding UPDATE transaction has not yet occurred, further SETs or GETs for that attribute are rejected.
- GET transactions never originate from the service during normal use. However this could change in the future.
- All transports are half duplex. There is collision control if both sides try to send at the same time (the MCU always wins); but once the winner has been chosen, the winner is guaranteed to send the entire message.
UPDATEs sent in either direction must only happen one at a time; specifically:
- For the SPI transport, because ASR is the slave, it uses flow control to enforce this UPDATE rule.
- For the SPI transport, because the MCU is the master, it can enforce this rule by delaying the start of the transaction. This is natural in a single-threaded event loop type of environment.
- For the UART transport, both ASR and the MCU must be ready for a transaction to occur, making this rule easy to enforce.
- UPDATEs are allowed to interrupt SET and GET operations according to the design of the attribute store.
- afLib uses the a single transmit queue for SET, GET, and UPDATE operations. Each operation must finish before the next one is initiated. Therefore, only one SET, GET, or UPDATE operation from the MCU can occur at any one time. ASR has no such limitations.