Module / MCU Interface

The Microcontroller Unit (MCU) connects to the Ayla Module using SPI (serial peripheral interface) or UART (universal asynchronous receiver/transmitter). Following provides overviews on the properties, datapoints, and protocols involved in the connection process.

Properties and Datapoints

The Ayla Module sends and receives name/value pairs between the MCU and the Ayla Device Service (ADS). Names are called properties. Values are called datapoints.

A property and its datapoints can represent anything that the MCU defines. The property may represent the state of a light or switch, a temperature sensor reading, the desired thermostat temperature, a moisture sensor, a schedule for a sprinkler system, an input to a calculation, or just about anything.

Property names are ASCII strings (up to 27 characters):

  • Upper and lower-case letters
  • Numbers
  • Hyphens (-)
  • Underscores (_)
  • Spaces or special characters are not allowed.
  • First character must be alphabetic.

Properties have a value data type, such as integer, Boolean, string (UTF-8), or binary. Property datapoints are values associated with the property (usually the most recent datapoint).

Most of these documented capabilities are for module configuration and are optional. The MCU may also perform module configuration during datapoints have values are less than 255 bytes (maximum that can be passed in a single message). A datapoint can be up to 4 GB long.

Protocols

A host MCU connects to an Ayla Module with SPI or UART. The interface is designed to work with variety of MCU sizes. Some modules may support only one of these modes. Most of the documented capabilities are for module configuration and are optional. The MCU may also perform module configuration during manufacturing.

Whether SPI or UART is used for communications, the three levels of protocols are:

  • Single-byte simple commands to get status or start a transfer.
  • Packet transfer command sequences.
  • Data or control protocol packets with a header and optional TLVs (type / length / value items)

The following diagram of the protocal hierarchy for SPI shows phases of a packet transfer sequence.

The first row shows the sequence. The Start sequence, pad, and status sequence are different for SPI and serial, but Length, Packet and CRC (cyclic redundancy check) are similar. Every packet transfer includes:

  • Start sequence (single-byte commands and status exchanges)
  • Length field
  • Packet being sent
  • Cyclic redundancy check (CRC)

Note: Padding bytes may be required before the status sequence is performed.

The first row also shows the packet and its encapsulation. The second row shows the header and TLVs forming the packet. The third row shows TLV contents (type, length, value).

SPI Protocol

The SPI (Serial Peripheral Interface) protocol has two roles called master and slave. The MCU is the SPI master and the module is the SPI slave.

With SPI, the MCU initiates all communications. When the module is initialized, the READY_N signal is asserted. It is recommended to wait for the READY_N signal before attempting to use SPI.

After initialization, every time the MCU sends a single-byte command to the module, the module returns a one-byte status in this format:

Bit 7 (MSB)6543210 (LSB)
InvalidADS BusyErrorAttentionBusy
  • Bit 7: Invalid (must be zero) - status values from message start byte. MCU checks this bit. If set, ignores the rest of the status. Helps detect bugs (for example, module sends all ones or MISO line is floating).
  • Bits 6 - 4: Reserved - MCU ignores these bits.
  • Bit 3: ADS Busy - if set, module cannot accept a data service operation.
  • Bit 0: Busy - module sets this after a command is recognized, and clears it on completion. A new command must not be sent unless a non-Busy status is seen first. As soon as the new command starts, Busy status should be set.

Following are descriptions of single-byte commands, packet transfers, and error cases/recovery:

Single-Byte Commands

Single-byte commands have the following format:

Bit 7 (MSB)65-0
TransferDirectionPayload Length
  • Bit 7: Transfer is set when command is a data transfer.
  • Bit 6: Direction - 0 = MCU to module, 1 = module to MCU.
  • Bits 5-0: Payload Length in 8-byte units.

With this format, these single-byte commands are defined:

  • NUL (0) - used to poll status.
  • Start Master Out: (0x80 thru 0xbf) - begin transfer from MCU to module.
  • Start Master In: (0xf1) - begin transfer from module to MCU.
  • Start Retry Master In: (0xf2) - (for error recovery) repeat of previous transfer from module to MCU.

All other commands are reserved.

Note: To form the Start Master Out command, round the packet length up to the next higher multiple of 8, then divide by 8 and add the constant 0x80. Length in the command allows module to start DMA before additional bytes are received. The packet length that forms the command does not include the command byte itself or the following two bytes of length, but does include the CRC.

Packet Transfers

The MCU initiates all transfers. The module notifies the MCU of a transfer by setting the attention bit and asserting the INTR_N signal. The MCU controls the clock and, when the data transfer completes, stops the clock. The following describes transfer sequences.

Packet Transfers from the MCU to the Module

Transfers from the MCU to module start with the Master Out command byte as follows:

  1. Wait not busy - the MCU sends 0 bytes to the module and receives the status. This is repeated until it sees a valid Status (bit 7 clear) and Not Busy (bit 0 clear). For some commands, ADS Busy (bit 3) must also be clear.
  2. Start - the MCU sends Start Master Out command. This contains the transfer length (8-byte multiples). Estimated length includes packet and CRC, rounded up to next multiple of 8. Opcode is 0x80 + (len + 7) / 8.
  3. Wait busy - Each time MCU sends Start command, it receives the module Status byte. This repeats until it sees the busy status (indicates module sees the command and is ready for the next part of the transfer).
  4. Length - MCU sends the length (in bytes, MSB first) of the packet and CRC. (Does not include command bytes or length.) Value may be 1 through 384, inclusive.
  5. Packet - MCU sends packet followed by CRC-8.
  6. Padding bytes - MCU sends zero bytes to pad transfer to the rounded-up length that was used in the command byte.
  7. Status - MCU sends zero bytes and waits for non-Busy status - and checks for Error status.

Packet Transfers from the Module to the MCU

Transfers from the module to the MCU start at the MCU after it recognizes an interrupt from the module and/or an Attention status from the module. The transfer sequence is:

  1. Wait not busy - the MCU sends 0 bytes to the module and receives the status. This is repeated until the MCU receives a valid Status (bit 7 clear) and Not Busy (bit 0 clear) and Attention (bit 1).
  2. Start - the MCU sends the Start Master In command, 0xf1. The received byte from module is examined. The MCU repeats this until 0xf1 byte is received.
  3. Module replies with Start - the module sends Start command byte to the MCU. This indicates the length bytes to follow.
  4. Length - the module sends transfer length (in bytes, MSB first), of packet and CRC-8. Value may be 1 through 384, inclusive.
  5. Payload - the MCU sends zero bytes to clock in the rest of the transfer. The module sends the packet and the CRC.

Retry Packet Transfers from the Module to the MCU

If the MCU detects a CRC error, the last transfer from the module can be re-tried (uses same procedure as initial receive transfer- except the start byte is 0xf2).

The MCU sends the 0xf2 start byte until it recognizes the 0xf1 byte from the module. The procedure is the same as Steps 3 through 5 under "Packet Transfers from the Module to the MCU" above.

Error Cases/Recovery

Possible error cases are as follows:

  • Slave overrun in data - The MCU sends data faster than the module can get the data from data registers. The module indicates that the transfer is complete with the status ERROR flag – and immediately ready for another transfer. When this occurs frequently – if using programmed I/O, slow the MCU transfer rate. If using DMA, reduce the SPI clock rate.
  • Slave overrun in length - same as above (Slave overrun in data). Slave unresponsive - If the module does not set Busy flag soon after the MCU sends the Start byte (indicates a failure in module firmware). Recovery action may involve a module reset.
  • Master underrun - the does not send expected length to module. This can occur if the MCU firmware error or module overrun in length transmission. If this occurs, the MCU can send zeros until the module Busy flag clears.
  • Slave underrun - On transfers (the module to the MCU), the MCU paces the transfer - and the module cannot supply data fast enough. Unlikely after length bytes are sent because module uses DMA. Problem is because data is still being transferred and MCU unable to determine a valid Status byte or just data. The MCU would detect this as a CRC error. When this occurs frequently – if using programmed I/O, slow the MCU transfer rate. If using DMA, reduce SPI clock rate.
  • CRC error - should not occur with functional hardware and software. If occurs in either direction, retry message several times - and count in error statistics.

UART Protocol

UART is an alternative to SPI. The module can be configured to use UART to communicate. For some MCUs, UART is more convenient. By default, UART operates at 115,200 bits/sec (the module can be configured with different speeds). UART uses 8-bit characters, odd parity, and 1 stop bit. The interface requires hardware flow control. Each side uses flow-control signals to send messages. The serial protocol has framed and encapsulated packets similar to SPI protocol packets. Following are descriptions of the framing, encapsulation, packet types, and error handling for UART.

Framing

Each packet is framed using a scheme similar to that used by PPP, as described in RFC-1622 section 4. Ayla does not use the address and control bytes that PPP defines, however. It isn’t necessary to be familiar with that RFC or PPP to understand the framing.

Each frame, in both directions, begins and ends with a flag byte (0x7e).

Any flag byte occurrence in a packet is replaced by the two-byte sequence 0x7d 0x5e. 0x7d is the escape byte. Any 0x7d in packet is replaced by 0x7d 0x5d. The second byte of this escape sequence is the original byte XORed with 0x20.

Only one flag byte is necessary between frames (sometimes a flag byte is sent at the frame beginning, if not sent in a while). Two flag bytes in a row imply an empty frame (to be discarded).

Encapsulation

Each packet is encapsulated with a packet type with a sequence number before the packet and a CRC-16 code after the packet. Then, the packet is framed. Following illustrates the protocol hierarchy for UART:

The encapsulation between flag bytes is shown in the following table:

Byte(s)NameMeaning
0TypePacket type code
1SeqSequence number
2 to n+1PayloadData or control packet
n+2 to n+3CRC-6Redundancy check for payload; MSB first

The packet (header and TLVs) are same as in SPI protocol.

CRC-16 is computed over all bytes after the flag byte, before byte-stuffing for transmit. This is done with a CRC-generator using the CCITT polynomial. It is initialized to 0xffff and computed with the payload’s MSB. CRC is placed in network byte order after the payload. A CRC payload check and the transmitted CRC results in a return value of 0.

To prepare a packet for transmission, the following process takes place:

  1. Start with the payload to be sent (for example, 7a 7b 7c 7d 7e).
  2. Prepend the ptype (e.g., 0x02) and sequence number (e.g., 0x01).
  3. Compute CRC-16 over the ptype, sequence number and payload and append it. (CRC in this case would be 0x9ffa). At this point, the frame is: 02 01 7a 7b 7c 7d 7e 9f fa. (5 bytes plus 4 bytes of overhead).
  4. Perform octet stuffing and add flag bytes. At this point, the frame is: 7e 02 01 7a 7b 7c 7d 5d 7d 5e 12 34 7e. These 13 bytes are sent. 5 (data) + 4 (length and CRC) + 2 (byte stuffing) + 2 (flag bytes) = 13.

Following is an example packet:

Packet Types

The table below lists the currently-defined packet types. All other packet types are reserved and should be ignored if received by the MCU.

PtypeNameMeaning
0x01DataThe packet is a data, control, or ping packet.
0x02AckAcknowledges packet receipt as indicated by the sequence ID.

Error Handling

Errors detectable on the serial protocol include CRC mismatch, invalid frames, invalid Ptype, overruns, and parity errors. These should be counted, but otherwise ignored.

A missing ACK (timeout) causes retransmission (at least the first two times it happens) on a given sequence ID. The module drops packets after two retries. The MCU may reset the module after too many retries, or take other appropriate action. The sender should ensure that the packet was transmitted and not just unable to be sent due to flow-control.

A packet received with the same sequence number as the previous packet (but not zero) should generate an ACK, but otherwise be dropped. This is how lost ACKs are handled.

The special sequence number zero indicates that the sender has restarted. Both the MCU and the module start with a zero-sequence number (after starting, zero is never reused) - called a "lollipop" sequence number scheme.

TLV Format

Most messages contain one or more Type-Length-Value items. The TLVs have the following format:

  • Byte 0: type code
  • Byte 1: length (N) of the value, not including type or length
  • Bytes 2 through (N+1): value

The following tables provide descriptions of TLV type codes, schedule-related TLV type codes, and status values in the Wi-Fi status (0x35) event:

Type Codes

Type CodeNameDescription
0x01NameProperty name, without NUL termination.
0x02Integer1-, 2-, 4-, or 8-byte signed integer value, in network byte order.
0x03Unsigned Integer1-, 2-, 4-, or 8-byte unsigned integer value in network byte order. Note that this type is never used in the protocol, only internally on the MCU. Unsigned integers greater than 231-1 are sent as 8-byte signed integers.
0x04BinaryUnstructured data bytes.
0x05TextUTF-8 encoded text value, without NUL termination.
0x06Configuration tokensUTF-8 encoded configuration tokens.
0x07ErrorError number, used in a NAK packet.
0x08Format(optional) Set of flags how the current named value should be formatted.
0x0fBooleanOne-byte value of 1 or 0.
0x10Continuation token4-byte value used in stepping through tables or lists.
0x11OffsetByte offset of the start of the value TLV that follows. (For large datapoints.)
0x12LengthTotal length of a datapoint value.
0x13LocationLocation string identifying datapoint.
0x14EOFEnd-of-file for datapoint, e.g., length is always 0.
0x16CentsFixed-point integer 100 times actual value. For example, 98.72 is 9872 decimal. Usually 4-bytes.
0x17NodesOne-byte bitmap of destinations or sources for property updates. Bit 0 is device service, other bits assigned for local destinations.
0x18EchoIndicates prop update is an echo. Length is always 0.
0x19Feature MaskOne-byte bitmap of the supported features in the MCU.
0x1aFactory ResetConfiguration name indices.
0x1bDelete ConfigurationUTF-8 encoded configuration tokens.
0x1cRegistration1-byte value. 1 = device registered with a user; 0 = device de-registered.
0x1dEvent MaskModule sends this to indicate an event. Supported event: - standby power mode: Module goes into standby mode. (To wake up, reset MCU.)
0x1eAck IDWhen from module to MCU: contains acknowledgement (ack) ID received for an ack-enabled property. When from MCU to module: contains ack ID, ack status and ack message.
0x20ScheduleSchedule property composed of Schedule-related TLVs.
0x21UTCIndicates date/time in schedules are UTC.
0x22ANDANDs the top two conditions in schedule.
0x23DisableDisables the schedule.
0x24In_RangeStack is true if current time is in range.
0x25At_StartStack is true if current time is at start.
0x26At_EndStack is true if current time is at end.
0x27Start DateDate must be after value.
0x28End Date(Date must be before value.
0x29Days of Month32-bit mask indicating which day of month. Bit 0 is the first day, bit 31 represents the last day of the month, which may be day 28, 29, 30, or 31, depending on the month and year.
0x2aDays of Week7-bit mask indication which day of the week. Bit 0 is Sunday. Bit 7 is reserved.
0x2bDay Occur In MonthDay Occurrence in Month. Bit 0 is the first occurrence.
0x2cMonths of YearMonths of Year, 1 through 12.
0x2dStart Time Each DayStart Time for each valid day of schedule.
0x2eEnd Time Each DayEnd Time for each valid day of schedule.
0x2fDurationEvent duration.
0x30 (TBD)Time Before EndTime must be <value> secs before end.
0x31IntervalStart every <value> secs from start.
0x32Set PropValue is a TLV pair of the action to take.
0x33VersionThe version of the schedule.
0x34Datapoint MetadataKey of the key-value pair metadata for a property datapoint update.
0x35Wi-Fi StatusA Wi-Fi status event - success or failure to join a Wi-Fi network. This TLV contains one-byte value of the number of characters in the SSID; n bytes containing the SSID as a UTF8 value; and a status code (see Wi-Fi Event Status Codes).
0x36Wi-Fi Status FinalSends final Wi-Fi status to the MCU that the module is done trying to join a Wi-Fi. (Used for firmware version 2.8+.)
0x37Binary messageThe value for the datapoint of a binary message property.
0x38UTF-8 messageThe value for the datapoint of a string message property.
0x39JSON messageThe value for the datapoint of a JSON message property.
0x3aMessage typeThe specific type of message datapoint to create.
0x3bBack-off timeThe specified time to wait before re-trying, in milliseconds.
0x3cBatch IDThe Datapoint ID number of datapoint in batch. This is used to correlate the resulting status to an individual datapoint.
0x3dBatch EndIf present, this indicates the last datapoint of a batch.
0x3eTime in millisecondsThe UTC time since 1970-01-01T00:00:00 in milliseconds. The value is 8 bytes long and in network byte order.

Refer to the <ayla_proto_mcu.h> header file in the API for definitions of these type codes.

Note: BCD TLVs are not currently implemented. The BCD TLV is coded as a one-byte number of digits before the decimal point, followed by 4-bit coded digits. Negative numbers start with the digit code 0xf. For example, TLV for the value -123.45 is shown in the example of a TLV representation below.

Following is an example of a TLV representation:

Wi-Fi Event Status Codes

Status CodeNameDescription
0x00SuccessModule joined Wi-Fi network identified by SSID
0x01Resource UnavailableResource unavailable to complete join operation (may be temporary).
0x02Connection Timed OutConnection to AP timed out. May indicate a few underlying causes – for example, inconsistent visibility of the AP due to range or noise; too many other APs in the vicinity; incorrect Wi-Fi password.
0x03Invalid KeyWi-Fi password supplied to module was not valid for configured security method on AP.
0x04Network Not FoundThe module could not find the network with the SSID specified. This can occur if there are many APs in the vicinity with strong signals and the scan failed to find the requested SSID.
0x05Not AuthenticatedAttempt to authenticate with the AP failed. May indicate connection to the AP was lost, or provided password was incorrect.
0x06Wrong KeyWi-Fi password was incorrect. Whether an AP indicates this error or a Not Authenticated error is specific to AP.
0x07No IP AddressFailed to obtain IP address from AP with DHCP.
0x08No RouteFailed to obtain default route from AP with DHCP.
0x09No DNS ServerFailed to obtain DNS Server address from AP with DHCP.
0x0aAP DisconnectedAP disconnected from module. May indicate AP cannot reliably receive data from module, or AP was restarted or powered off.
0x0bLoss of SignalModule failed to receive consecutive beacons from AP. Module cannot reliably receive data from AP, or AP was restarted or powered off.
0x0cDNS lookup failedOEM-based hostname used to reach the ADS was not resolved to an IP address.
0x0dADS Connection RedirectConnection to ADS failed due to an HTTP redirect.
0x0eADS Connection TimeoutConnection to ADS timed out. May be a failure in network beyond Wi-Fi AP, or failure to communicate with AP.
0x0fNo Profile AvailableConnection to the Wi-Fi network succeeded, but configuration was not saved, because too many configured Wi-Fi profiles.
0x10Security Method Not SupportedModule or Access Point does not support security method specified in Wi-Fi join request.
0x11Network Type UnsupportedWi-Fi network type (e.g., Ad-Hoc, Enterprise) not supported by module.
0x12Wi-Fi protocol errorAccess Point protocol not supported. Error can occur on attempt to connect to a personal hotspot, or device in tethering mode.
0x13ADS authentication errorModule failed to authenticate with ADS. Report error immediately to Ayla Customer Service (module code may need to be updated).
0x14Operation In ProgressWi-Fi join operation still in progress. Subsequent status event indicate success or failure when join operation completes.
0x15Setup UnsupportedModule is in setup mode. Join Wi-Fi network only permitted in user mode.

Packets

The most common packet format for all protocols include messages in either direction that start with a one-byte protocol number:

BitDescription
0x00Reserved for Ayla Configuration and Control Operations.
0x01Used for Ayla Data Operations.
0x02Used for SPI Ping test.

For most of these protocols, this is followed by a per-protocol opcode and payload data:

SPI Ping Protocol

The ping protocol is a simple way to test the SPI interface from the MCU. Any packet sent to the module with Protocol 2 is returned to the MCU. The procedure is to send the packet, then poll for ATTN in the status, and finally receive the identical reply packet.

Data Operations

The MCU or module can issue data operations. From the MCU, the request is sent to the Ayla Device Service (ADS) or the other server, as configured. From the module, requests can come from the ADS or from the module’s web server. The packet format is:

  • Byte 0: Protocol for data operations is 1.
  • Byte 1: Opcode
  • Bytes 2 - 3: Request ID associated with some responses and negative acknowledgements.
  • Bytes 4 - n: TLVs

Following are descriptions of data operations opcodes, examples of data messages from various operations, and an explanation of file datapoints (including how they are received and sent).

Data Opcodes

This section provides a description of each data operations.

OpcodeDirectionDescription
0x01Replaced by Opcode 0x09
0x02MCU ⟶ ModuleSend me a property value. The message can include a Name TLV to specify a particular property, or no Name TLV to specify all to-device properties. The module responds with Opcode 0x03.
0x03MCU ⟵ ModuleHere is the property value. The message contains a property value. If the message contains an Ack_ID TLV, the MCU must acknowledge receipt. A Nodes TLV in the message indicates the property value source. No Nodes TLV indicates the property value came from ADS. An EOF packet ends the message.
0x05MCU ⟵ ModuleHere is a NAK. The message contains an Error TLV. If the error is a failed property get or create, the message includes a property Name TLV. Node TLVs have a bitmask of failed destinations / sources. On some errors, especially AERR_BUSY_RETRY (0x19), a Back-off time TLV may be included, specifying the time to wait before retrying, in milliseconds.
0x06MCU ⟵ ModuleSend me a property. The message includes a Name TLV specifying the property. The MCU must respond with opcode 0x07. If the module does not provide a ATLV_NAME property, the MCU responds with a NAK and Feature Mask TLV (8-bit representation of MCU supported features). For the feature mask, use OR to put together the following values based on Host MCU-supported features:
  • 0x01 - LAN Mode
  • 0x02 - Host MCU OTA
  • 0x04 - Time Subscription
  • 0x08 - Datapoint Confirmation
0x07MCU ⟶ ModuleHere is the property. The message contains the property name and value.
0x08MCU ⟵ ModuleSend me the next property. The message contains a Continuation Token TLV. 0 means first property. If there are more properties, the response contains a continuation token. The value gets the next property in an MCU-maintained sequence.
0x09MCU ⟶ ModuleHere is the data service property value. The message contains a Name TLV, an optional Format TLV, a Value TLV, and, if a to-device property, an Echo TLV. A Nodes TLV in the message indicates datapoint destinations. No Nodes TLV indicates that the value should be sent to all currently reachable destinations. While ADS_BUSY status is set, do not use this operation. ADS_BUSY is set by this and remains set until ADS receives the new datapoint. This opcode can also send acknowledgment (ack) status of an ack-enabled property back to the MCU. This returns the ack ID received from the module for the datapoint update, ack status (success or failure), ack message (a unique number that indicates device execution results), property name and value, source of the datapoint (ATLV_NODES), and Echo TLVs (appended in case of datapoint acks). Echoes are delayed until the datapoint has been executed. (MCU is required to initiate echoes.) The module sends echoes to all destinations except datapoint source. An acknowledgment is sent to the source.
0x0AMCU ⟶ ModuleSend me a file/message datapoint. The message contains a Location TLV. It may also include an Offset TLV, Length TLV to limit response length, and ATLV_MSG_TYPE TLV to indicate MIME type.
0x0BMCU ⟵ ModuleHere is the file/message datapoint. The message contains a file or message datapoint.
0x0CMCU ⟶ ModuleCreate a file/message datapoint. The message contains a NAME TLV and, if a message datapoint, a ATLV_MSG_TYPE TLV to specify MIME type. This operation must be followed by 0x0F.
0x0DMCU ⟶ ModuleReceived file/message datapoint. The message contains a Location TLV.
0x0EMCU ⟶ ModuleAbort file/message datapoint operation. The message is empty.
0x0FMCU ⟶ ModuleHere is the file/message datapoint. The message contains a Location TLV, Offset TLV, Length TLV on first packet if the message won't fit into one packet, Value TLV (ATLV_BIN for file datapoints, and ATLV_MSG_BIN, ATLV_MSG_UTF8, or ATLV_MSG_JSON for message datapoints), and EOF TLV for the final message of a multipart datapoint send.
0x11MCU ⟵ ModuleHere is connectivity Status. The message contains ATLV_NODES TLV with a bitmask of all available destinations.
0x12MCU ⟵ ModuleAuto echo failed. The message contains Name TLV of the failed property echo.
0x13MCU ⟶ ModuleReady to listen. Incoming connectivity status messages (0x11 above) update MCU when module has established service connectivity. MCU sends out pending property echoes before this packet is sent.
0x14MCU ⟵ ModuleHere are errors. The message contains one or more Error TLVs. Opcode request ID is always 0. AERR_OVERFLOW is an example. The module sends AERR_OVERFLOW to the MCU when the MCU is too slow processing property value update. When the MCU receives AERR_OVERFLOW, Ayla recommends that the MCU request all to-device property values.
0x15MCU ⟵ ModuleProperty value was updated. This is used only in UART mode. It confirms a successful property post to ADS and/or mobile app.
0x16MCU ⟵ ModuleProperty value update is pending. When a property update is pending in ADS, module sends this to MCU.
0x17MCU ⟵ ModuleHere are events. The message contains one or more ordered TLVs with event information.
0x18MCU ⟶ ModuleBatch this datapoint. The message contains a Batch ID TLV, Property Name TLV, Time in milliseconds TLV, Property value TLV, and, optionally, Batch end TLV, indicating the final datapoint in the batch. ADS_BUSY is set by this opcode and remains set until the module is ready to receive the next datapoint. Do not use this Batch Send operation while ADS_BUSY status is set. A long string datapoint that is part of the batch is sent in multiple Batch Send operations, all with the same batch ID and Property Name, with a Length TLV in the first packet, an Offset TLV in the subsequent packets, and an EOF TLV in the final packet for that datapoint. Batch Send does not support metadata, echo flags, or message or file properties.
0x19MCU ⟵ ModuleHere is batch status. The message includes an Error TLV (may contain success), one or more Batch ID TLVs, and, optionally, Batch End TLV, indicating the final datapoint in the batch. The batch operation is complete when the batch status is received with the batch end TLV, or if a NAK is received after any Batch Send. Any datapoints for which status has not been received may not have been sent.

Example Messages

Send a property (MCU ⟶ Module)

Byte 012345678910111213141516
82000e0109123401046c6564300f0101CRC
StartLength (14)ProtocolOpcodeRequest IDName TLV, Length 4,
Value "led0"
Boolean TLV, Length 1, Value 1 

Start byte 0x82 indicates the packet is up to 16 bytes long. This may be repeated until Busy status is shown. Then, the length bytes, 0x000e, for 14 bytes of overall the payload length (includes the CRC, but not the start command or length bytes). Payload begins with protocol 1 (for Ayla Data protocol), followed by opcode 9, "Send TLV", and arbitrary request ID 0x1234. The Name and value TLVs follow:

  • Name TLV are type 1 (name), length 4, followed by the 4 bytes of the name "led0".
  • Value TLV (in this example) holds the one-byte Boolean value of 1, so the type is 15 and the length is 1.

Each TLV has only 1 byte for the "length". The maximum TLV length is 255 bytes (more than enough for most property types). If the application requires longer string values (ATLV_UTF8), refer to the Send Long Strings example.

Send a property with metadata (MCU ⟶ Module)

Byte 01234567891011121718192021222324
82000F0109123434046b657931050676616c756531
StartLength (31)ProtocolOpcodeRequest IDName TLV, Length 4,
Value "led0"
UTF8 TLV, Length 6, Value "value1"
25262728282930313233
01046c6564300f0101CRC
Name TLV,
Length 4,
Value "led0"
Boolean TLV, Length 1,
Value 1
 

Start byte 0x84 indicates that the packet is up to 32 bytes long. This may be repeated until the Busy status is shown. Length bytes, 0x001f, for 31 bytes of overall payload length (includes CRC, but not start command or length bytes. Payload begins with Protocol 1 (Ayla Data protocol), followed by opcode 9, "Send TLV", and arbitrary request ID 0x1234. Metadata TLV is next (must always precede name and value TLV). Datapoint metadata are key-value pairs. Metadata TLV contains the key and followed by UTF8 TLV with the value. Metadata TLV has type 52 (ATLV_DPMETA), length 4, followed by bytes of "key1". The UTF8 TLV of type 5, length 6, holds the bytes of "value1". The MCU can send up to four metadata key-value pairs. Maximum allowed length for Key is 16 bytes, and for Value is 32 bytes. Name and value TLVs:

  • Name TLV are type 1 (name), length 4, followed by the 4 bytes of the name "led0".
  • Value TLV (in this example) holds the one-byte Boolean value of 1, so the type is 15 and the length is 1.

Send long strings (MCU ⟶ Module)

The maximum string length is module-dependent. Current modules (version bc-1.8 +) limit strings to 1024 bytes. To send a string >255 bytes, multiple sequential packets are sent. The first packet includes ATLV_LEN TLV with a value of the string total size. Subsequent packets contain an ATLV_OFF TLV with value of offset. The final packet contains ATLV_EOF TLV (end of sequence). The Request ID is the same throughout the entire sequence. EOF TLV can also truncate a value earlier than specified in the ATLV_LEN TLV (in first packet). Following (numbers 1 - 3) shows the packet sequence that sends a string length of 515.

Packet 1

Byte 012345678910111213141516
A201100109123401047374726712020203
StartLength (272)ProtocolOpcodeRequest IDName TLV,
Length 4,
Value "stg"
Length TLV,
Length 2,
Value 515
17181920212223242526272829......274
05ff6162636465666768697071   CRC
Text TLV,
Length 255
Value "abcd……."
 

Packet 2

Byte 012345678910111213141516
A2011001091234010473747267110200ff
StartLength (272)ProtocolOpcodeRequest IDName TLV,
Length 4,
Value "stg"
Offset TLV,
Length 2,
Value 255
17181920212223242526272829......274
05ff6162636465666768697071   CRC
Text TLV,
Length 255
Value "abcd……."
 

Packet 3

Byte 012345678910111213141516
83001801091234010473747267110200ff
StartLength (24)ProtocolOpcodeRequest IDName TLV,
Length 4,
Value "stg"
Offset TLV,
Length 2,
Value 510
17181920212223242526
05056162636465140CRC
Text TLV,
Length 5,
Value "abcde"
EOF TLV,
Length 0
 

Receive a property (MCU ⟵ Module)

Byte 01234567891011121314151618
f1000f010334560102676f020400000123CRC
StartLength
(15)
ProtocolOpcodeRequest
ID
Name TLV,
Length 2,
Value "go"
Integer TLV,
Length 4,
Value 0x0000123
 
  • Start byte is 0xf1 (packet comes from module to MCU).
  • Payload length is 15 (0x0f) (does not include start byte and length).
  • Protocol is 1 (Ayla Data protocol).
  • Opcode 3, "Receive TLV" (request ID 0x3456).
  • Name and value TLVs (Name "go" has no zero padding. Value is a signed integer (type 2) of 4 bytes).

Receive a property with metadata (MCU ⟵ Module)

Byte 01234567891011121718192021222324
82000F0109123434046b657931050676616c756531
StartLength (31)ProtocolOpcodeRequest IDDatapoint Metadata TLV,
length 4
key "key1"
UTF8 TLV,
Length 6,
Value "value1"
25262728282930313233
01046c6564300f0101CRC
Name TLV,
length 4,
value "led0"
Boolean TLV, length 1,
value 1
 

Payload begins with Protocol 1 (Ayla Data protocol), followed by opcode 3 “receive TLV” and arbitrary request ID 0x1234. Next is the metadata TLV (always precedes name and value TLV). Datapoint metadata is sets of key-value pairs. Metadata TLV contains the key, followed by a UTF8 TLV (contains the value).

Metadata TLV has:

  • type 52 (ATLV_DPMETA)
  • length 4
  • "key1" bytes

UTF8 TLV is:

  • Type 5
  • Length 6
  • "value1" bytes"

The MCU can receive up to four metadata key-value pairs. Maximum allowed length for key is 16 bytes, and for value is 32 bytes.

Name and Value TLVs follow. Name TLV is:

  • Type 1 (name)
  • Length 4
  • Name "led0" (4 bytes)

The Value TLV (in this case) holds the one-byte Boolean value of 1:

  • Type 15
  • Length 1

Explicit acknowledgment of the datapoint

If the property is marked ack_enabled (the datapoint originates from any source - ADS or LAN app), the module passes ack_id to the MCU. After the datapoint is executed, the MCU sends ack (nested TLV format) to the module of success or failure.

Byte 012345678910111213141516
f1000f010334560102676f020400000123
StartLength
(15)
ProtocolOpcodeRequest
ID
Name TLV,
Length 2,
Value "go"
Integer TLV,
Length 4,
Value 0x0000123
17181920212223
050469643031CRC
Ack_ID TLV,
Length 4
Value "id01" (from ADS/LAN app)
 

ATLV_ACK_ID contains:

  • ack_id - associated with the datapoint
  • ack_status in ATLV_ERR (0 = success 1 = failure)
  • ack_message - integer format

The node TLV value identifies datapoint source. With this, the module marks the datapoint acknowledged on the source.

The property name/value and Echo TLV initiates echoes to all destinations except the datapoint source. Because the datapoint must be executed before echoed, the MCU initiates echoes.

File Datapoints

A file datapoint is longer than 255 bytes and requires multiple packets. On a network connection loss, packets can be re-sent or re-fetched. The data type is binary, and up to 4 GB. The protocol handles transfer of large property values (datapoints) differently than other ones. By design, the MCU knows which properties support file datapoints. The following two subsections describe the sequences that the MCU uses to receive and send file datapoints.

How the MCU Receives File Datapoints

  1. A file property value sent to the MCU from the module contains a Location TLV (not the value TLV). The Location TLV is a byte string, saved by MCU and used to request the file datapoint value.
  2. The MCU sends File Datapoint Request packet. The Location TLV is included. Optionally, an Offset TLV can be included.
  3. The module responds with one or more File Datapoint Response packets.
  • The contents include the Location TLV followed by the Binary Data TLV. The Offset TLV is included.
  • If the overall length of the datapoint is known, the first packet contains a Length TLV.
  • The final data packet contains the EOF TLV.
  1. The MCU receives the data values in a sequence. You cannot issue new requests while the transfer is in progress. If there are gaps in the sequence, this means that there is most likely an error.
  2. On transfer complete, the MCU should send the File Datapoint Fetched command. The module informs the ADS that the file datapoint was fetched.
  3. The MCU can abort a file download operation at any time through a File Datapoint Stop packet.

Note: No other property updates are sent to the MCU during an in-progress file download. The module notifies the MCU of the pending property updates with AD_PROP_NOTIFY opcode (in case the MCU wants to abort the file transfer to receive the update).

How the MCU Sends the File Datapoints

  1. The MCU sends File Datapoint Create command. This includes the property name TLV. If required, datapoint metadata is included.
  2. The module responds with the File Datapoint Response packet. This contains the new datapoint Location TLV, or (if unsuccessful) the Error TLV.
  3. The MCU sends the File Datapoint Send packet with the value’s initial bytes. This contains the following:
  • Location TLV
  • Offset TLV (for offset 0)
  • Length TLV (total length of value to be sent)
  • Binary data TLV
  1. The MCU sends additional File Datapoint Send packets. The Length TLV is not included, and the final command must be EOF TLV.
  2. At any time, the MCU can send File Datapoint Stop packet to abort the file upload operation.

Note: No other property updates are sent to the MCU during an in-progress file upload. The module notifies the MCU of the pending property updates with AD_PROP_NOTIFY opcode (in case the MCU wants to abort the file transfer to receive the update).

Message Datapoints

A message datapoint is a string, binary, or JSON value with length up to 4GB, although the service limit is currently lower, at 512 KB. Message datapoints are similar to file properties, but have some differences in overhead and retention in the Cloud. Each message property has a MIME type describing the type of all datapoints for the property. The currently supported MIME types are “text/plain” for string, “application/octet-string” for binary, and “application/json” for JSON. The MCU represents these MIME types with the TLV types ATLV_MSG_UTF8, ATLV_MSG_BIN, and ATLV_MSG_JSON. Sending and receiving message datapoints require multiple packets, similar to file datapoints. The protocol handles the transfer of message datapoints differently than other ones. By design, the MCU host code must know which properties have message datapoints.

How the MCU Receives Message Datapoints

  1. A message property value sent to the MCU from the module contains a Location TLV (not the value TLV). The Location TLV is a byte string, saved by the MCU and used to request the file datapoint value.
  2. The MCU sends File Datapoint Request packet. The Location TLV is included. The ATLV_MSG_TYPE TLV is included, specifying one of the supported MIME subtypes by the TLV type number. Optionally, an Offset TLV can be included.
  3. The module responds with one or more File Datapoint Response packets.
  • The contents include the Location TLV followed by a value TLV of the specified type.
  • The Offset TLV is included after the first packet.
  • If the datapoint overall length is known, the first packet contains a Length TLV, unless the entire value fits in the first packet.
  • The final data packet contains EOF TLV, unless the entire value fits in the first packet.
  1. The MCU receives the data values in a sequence. You cannot issue new requests while the transfer is in progress. If there are gaps in the sequence, this means that there is most likely an error.
  2. On transfer complete, unlike file datapoints, the MCU does not send the File Datapoint Fetched command.
  3. The MCU can abort a file download operation at any time through a File Datapoint Stop packet.

Note: No other property updates are sent to the MCU during an in-progress file download. The module notifies the MCU of the pending property updates with AD_PROP_NOTIFY opcode (in case the MCU wants to abort the file transfer to receive the update).

How the MCU Sends Message Datapoints

  1. The MCU sends File Datapoint Create command. This includes the property name TLV and an ATLV_MSG_TYPE TLV specifying the MIME type. If required, the datapoint metadata is included.
  2. The module responds with the File Datapoint Response packet. This contains the new datapoint Location TLV, or (if unsuccessful) the Error TLV.
  3. The MCU sends the File Datapoint Send packet with the value’s initial bytes. This contains the following:
  • Location TLV
  • Offset TLV (for offset 0)
  • Length TLV (the total length of the value to be sent)
  • Value data TLV of the appropriate datapoint type (e.g. ATLV_MSG_JSON)
  1. The MCU sends additional File Datapoint Send packets. The Length TLV is not included, and the final command must be EOF TLV.
  2. At any time, the MCU can send File Datapoint Stop packet to abort the message send operation.

Note: No other property updates are sent to the MCU during an in-progress message upload. The module notifies the MCU of the pending property updates with the AD_PROP_NOTIFY opcode (in case the MCU wants to abort the file transfer to receive the update). None of the message datapoint is saved in the cloud if the transfer is aborted.

Batch Datapoints

The batch datapoint operations allow the host MCU to send multiple datapoints with much less API overhead to the Ayla cloud. The datapoints may be collected in the MCU over a time period while the module is off or disconnected, and then sent later. The datapoints are individually timestamped to indicate when they were sampled. The batch can consist of as many datapoints as the host processor can store or generate, although there may be limits imposed by the module or the Cloud Service. When the batch is ready to be sent, one or more Batch Send messages is sent for each datapoint. String datapoints longer than 255 bytes need multiple messages.

Batch this datapoint (MCU ⟶ Module)

The integer value of 1000 is sent for the property "mv", with a timestamp.

Byte 0123456789109101112
84001a011812343c02100001026d76
StartLength (26)ProtocolOpcodeRequest IDBatch
ID 4096=0x1000
Name "mv"
13141516171819202122
3e080000016d08e95748
Timestamp milliseconds TLV = 1567812573000 (2019-09-06 23:29:33.000 UTC)
23242526272829
0204000003e8CRC
Integer, length 4, value 1000 = 0x3e8 

The start byte 0x82 indicates the packet is up to 16 bytes long. This may be repeated until the Busy status is shown. Then, the length bytes, 0x000e, for 14 bytes of overall the payload length (includes the CRC, but not the start command or length bytes). The payload begins with protocol 1 (for Ayla Data protocol), followed by opcode 0x18, "Batch Send", and arbitrary request ID 0x1234. The batch ID TLV indicates the ID of the datapoint, as assigned by the host, for the duration of this batch operation. This is to associate the response. The Name and value TLVs are as follows:

  • Name TLV are type 1 (name), length 4, followed by the 4 bytes of the name "led0".
  • Value TLV (in this example) holds the one-byte Boolean value of 1, so the type is 15 and the length is 1.

Each datapoint in the batch should use a different request ID, so that NAKs can be associated with the specific datapoint that caused them. When a long string datapoint is sent as part of the batch, multiple Batch Send operations are used, and the value TLV is preceded by a Length TLV in the first packet of the string. Each subsequent packet contains the Offset TLV, and the final one ends with an EOF TLV. Compare this to how long strings are sent normally. The only difference is the presence of the Batch ID TLV, and possible Batch EndTLV.

Here is batch status (MCU ⟵ Module)

After all batch datapoints have been sent, the host MCU should expect one or more Batch Status messages. This message is shown below without the SPI or UART transport bytes.

012345678910
011998760701003c021000
ProtocolOpcodeRequest IDError TLV (success)Batch ID 4096
1112131415161718192021222324252627
3c0210013c0210020701173c0210033d00
Batch ID 4097Batch ID 4098Error TLV 0x17
(unknown property)
Batch ID 4099Batch End TLV

This message shows that datapoints with batch IDs 4096, 4097, and 4098 were sent without error, but datapoint 4099 was identified as an unknown property by the service. The Batch End TLV indicates that this is the end of the status for the batch.

Control Operations

Control operations are messages between the MCU and module that perform actions on the module’s configuration and status. The message format is similar to the data operation message format:

  • Byte 0: Protocol for data operations is 0.
  • Byte 1: Opcode
  • Bytes 2 - 3: Request ID associated with some responses and negative acknowledgements.
  • Bytes 4 - n: TLVs

Control Opcodes

The control operations use protocol number 0 and the opcodes described in this section.

OpcodeDirectionDescription
0x01MCU ⟵ ModuleHere is configuration. The message contains Conf TLV + Value TLV pairs. This is a response to 0x02.
0x02MCU ⟶ ModuleSend me configuration.
0x03MCU ⟶ ModuleModify configuration items. The message contains Conf TLV + Value TLV pairs.
0x04MCU ⟶ ModuleSave running configuration to startup configuration.
0x05Reserved
0x06MCU ⟶ ModuleHere is a NAK meaning an error occurred on previous request.
0x07MCU ⟶ ModuleRestart with startup configuration.
0x08MCU ⟶ ModuleRestart with factory configuration which causes module to copy the factory configuration over the startup configuration, and restart.
0x09MCU ⟵ ModuleAn OTA is available.
0x0AMCU ⟶ ModuleInstall the OTA. The module de-asserts READY (and is unavailable for some time). After a time (at least 30 seconds), the module is reset. For battery-operated devices, the voltage must be appropriate for flash operations.
0x0BReserved
0x0CMCU ⟵ ModuleLog operation.
0x0DMCU ⟵ ModuleMCU OTA report or start.
0x0EMCU ⟵ ModuleHere is a chunk of firmware. The message contains an ATLV_OFF TLV and a ATLV_BIN TLV.
0x0FMCU ⟶ ModuleHere is the status of received chunk of firmware. To indicate an error, the message must contain a ATLV_ERR TLV with one of the following:
  • 0x02: AERR_LEN_ERR (TLV extends past end of received buffer).
  • 0x0d: ERR_INTERNAL (Internal error).
  • 0x0e: AERR_CHECKSUM (Checksum mismatch).
  • 0x0f: AERR_ALREADY (Already running new version).
  • 0x10: AERR_BOOT (MCU did not boot to new image).
0x10MCU ⟵ ModuleBoot this image. If the message contains a ATLV_UTF8 TLV specifying a version, the MCU should boot that version. If no TLV, the MCU should boot the most recently downloaded image.
0x11MCU ⟵ ModuleConfiguration has changed.
0x12MCU ⟶ ModuleJoin this Wi-Fi network. The message contains a ATLV_UTF8 TLV specifying SSID, ATLV_INT TLV specifying security level, and ATLV_BIN TLV specifying password.
0x13MCU ⟶ ModuleLeave and forget this Wi-Fi network. The message contains a ATLV_UTF8 TLV specifying SSID.

Configuration Tokens

The module uses the configuration variables with a hierarchical naming structure. The write configuration variable name is a set of names separated by slashes (similar to UNIX file names). For example, SSID for the first Wi-Fi prototype is /wifi/profile/0/ssid.

To save program space and time, each config token is encoded with one number. The above example is actually coded as 0x4, 0x25, 0, 0x26. The third token is the index of profile, 0.

The conf_tokens.h file has token numerical assignments in lines to invoke a CONF_TOKEN macro. That macro can be user-defined so that the token number and name is used as the programmer prefers. For example, the following line indicates the coding for the Wi-Fi token is 4: CONF_TOKEN(4, wifi).

File conf_token.h defines an enum conf_token with values for each token. For example, CT_wifi is set to 4.

The table below lists configuration token codes:

CodeToken Name
0x01enable
0x02ready
0x03sys
0x04wi-fi
0x05server
0x06client
0x07ssl
0x08status
0x09start
0x0acomplete
0x0bip
0x0cn
0x0dtime
0x0epower
0x0fuser
0x10version
0x11file
0x12name
0x13type
0x14model
0x15serial
0x16mfg_serial
0x17hostname
0x18timezone
0x19timezone_valid
0x1amfg_mode
0x1bdev_id
0x1csetup_mode
0x1dmfg_model
0x1esim
0x1freset
0x20region
0x21acc
0x22char
0x25profile
0x26ssid
0x27security
0x28none
0x29WEP
0x2aWPA
0x2bWPA2_Personal
0x2ckey
0x2dpri
0x2escan
0x2ftime_limit
0x30save_on_ap_connect
0x31save_on_server_connect
0x32max_perf
0x33en_bind
0x34ap_mode
0x35rssi
0x36bssid
0x37bars
0x38poll_interval
0x39addr
0x3amac_addr
0x3bant
0x43connected
0x44cert
0x45private_key
0x46ca
0x47GIF
0x48OEM
0x49log
0x4amod
0x4bmask
0x4cchan
0x4derror
0x4elink
0x4freg
0x50default
0x51min
0x52standby
0x53mode
0x54dhcp
0x55gw
0x56snapshot
0x57hist
0x58source
0x59WPS
0x5alisten
0x5binterval
0x5cauto
0x5dcurrent
0x5eawake_time
0x5fstandby_powered
0x60unconf_powered
0x61metric
0x62http
0x63tcp
0x64count
0x65locale
0x66lan
0x67setup_ios_app
0x68motify
0x69gpio
0x6aintr
0x6bdata
0x6cclock
0x6dmfi
0x6ehidden
0x70value
0x71prop
0x72port
0x73sched
0x74dst_active
0x75dst_change
0x76dst_valid
0x77dns
0x78hw
0x79rtc_src
0x7ahost
0x7buart
0x7cspi
0x7dspeed
0x7eeth

Configuration Tree

The configuration tree has the following components:

Configuration Sub-trees

The following table describes the top-level configuration sub-trees.

Sub-treeDescription
clientConnection to the Ayla Device Service (ADS)
ethEthernet device
gpiomodule I/O configuration
hwmodule hardware features
ipIP networking Wi-Fi
logdevice logging
metricmodule statistics
oemOEM name and model
powerpower management
servermodule internal web server
simInternal simulation/testing
sysoverall system configuration
wifiWi-Fi settings

Client Configuration Settings

The following table describes the client configuration settings:

VariableType
/client/enableBoolean
/client/poll_intervalInteger
/client/hostnameUTF-8
/client/regUTF-8
/client/reg/readyBoolean
/client/reg/startBoolean
/client/reg/intervalBoolean
/client/reg/setup_modeUTF-8
/client/ssl/enableBoolean
/client/server/regionUTF-8
/client/testBoolean

Client Module Registration

To register a module with the ADS, use a mobile application or the ADS web interface. As an alternative for MCUs with a user interface, complete the following steps to register the module (if it's already connected to the Internet and to the ADS):

  1. On a button press or touch-screen or other user action, indicate to the ADS client that a new registration key should be generated (set /client/reg/start to 1).
  2. On completion, a registration key is assigned to /client/reg. (This can be displayed to the user or sent to the ADS web server to register the device.
  3. Set /client/reg/interval to 1 requests ADS to open a 2-minute device registration window. (Similar to WPS push-button registration.)
  4. Get the Boolean value of /client/reg/ready. (1 = user registered, 0 = no registered user). The ADS must be accessible (see bit 0 in the available destinations mask as reported to the MCU via the Data Connectivity Status operation).
  5. Confirm registration status and the reg key is not available unless ADS is accessible. When /client/test is set to 1, ADS is informed that connections are for OEM testing (does not count as end-user first connection of device. (Setting does not persist - lasts only until the next reboot).

Ethernet Configuration Settings

The following table describes the Ethernet configuration settings:

VariableTypeAccessMeaning
/eth/enableBooleanr/wEnable client subsystem
/eth/mac_addrBinaryr/wThe MAC address for Ethernet device.

Note: The variables are not writeable until the module firmware version 1.7.

IP Configuration Settings

The following table describes the IP configuration settings:

VariableTypeAccessMeaning
/ip/n/<n>/addrIntegerr/wIP address
/ip/n/<n>/maskIntegerr/wNetmask
/ip/dhcp/enableBooleanr/wUse DHCP
/ip/dns/n/<n>Integerr/wDNS server addr
Integerr/wDefault Gateway

Note: DHCP must be disabled to write IP address, netmask, DNS addresses, and default gateway IP address..

Log Configuration Settings

The following table describes the log configuration settings:

VariableTypeAccessMeaning
/log/mod/<n>/maskIntegerr/wMask of enabled log severities
/log/snapshot/<n>/timeIntegerrTime (UTC) of snapshot <n> where 1=Default, 2=Client, 3=Conf, 4=Dns, 5=Netsim, 6=Notify, 7=Server, 8=Wi-Fi, 9=SSL, 10 - Log-client, 12=Sched

OEM Configuration Settings

OEM configuration settings are accessed only in setup mode to allow product manufacturer to add the OEM name and model. This information is used by ADS. The key verifies to ADS that the OEM and model belong to the specified OEM. The key is used to encrypt or sign a string that includes the OEM and model. The key is not stored by the module and if read returns undefined results. Whenever the OEM or model are set, the key must be re-written with a base-64 UTF-8 string. Ayla recommends that the key not be stored in the host MCU as shipped to customers. After setup, erase the key. The following table describes the OEM configuration settings:

VariableTypeAccessMeaning
/oem/oemUTF-8r/wDevice manufacturer name
/oem/modelUTF-8r/wDevice model name
/oem/keyFile/UTF-8wOEM validation string

Power Configuration Settings and Status

The following table describes the power configuration settings:

VariableTypeAccessMeaning
/power/modeIntegerr/wPower management mode values are:
  • CT_default
  • CT_min
  • CT_max_perf
  • CT_standby
/power/currentIntegerr/wActive power management mode.
/power/awake_timeIntegerr/wTime in seconds that the module should stay awake after activity.
/power/standby_poweredIntegerr/wTime in seconds that the module waits before standby after boot.
/power/unconf_poweredIntegerr/wTime (seconds) module waits before standby after boot when no Wi-Fi profiles are configured.

Module HTTP Server Configuration Settings

The following table describes the HTTP server configuration settings for the module:

VariableTypeAccessMeaning
/server/prop/time_limitIntegerr/wHTTP Server access to properties enable/disable. This variable enables a local HTTP client to access MCU properties (for a limited time) via the Wi-Fi module’s HTTP server. To take effect, Wi-Fi module must be in AP mode and not registered with a user. (Generally, this is used for device testing during manufacturing).
/server/security/enableBooleanr/wHTTP clear-text access in AP mode. This variable enhances AP mode server security on module. (Supported version 2.6+):
  • 0 = disables feature - module allows wifi setup through clear-text server requests and wifi javascript page.
  • 1 = enables feature - clear-text access is blocked, wifi javacript page not accessible.

Note: Wi-Fi setup can be done only using an encrypted session via the mobile app.

System Configuration and Status Settings

The following table describes the System Configuration and Status settings:

VariableTypeAccessMeaning
/hw/rtc_srcIntegerr/wRTC clock source selection:
  • 512 for LSI (low-speed internal oscillator).
  • 256 for LSE (external oscillator). Only exists for certain module types and is writable in setup mode only.
/sys/dev_idUTF-8rAyla DSN
/sys/mac_addrBinaryrMAC address
/sys/mfg_modeBooleanrManufacturing mode
/sys/mfg_mode/completeIntegerr/wTest completion time
/sys/mfg_modelUTF-8rModule mfg model name
/sys/mfg_serialUTF-8rModel mfg serial number
/sys/modelUTF-8rModel name
/sys/serialUTF-8rSerial number
/sys/setup_modeBooleanr/wSetup mode (write value must be 0)
/sys/timeIntegerr/wUTC time (in seconds since Jan 1st, 1970). If written by MCU, set with 0x1250 source.
/sys/time/priIntegerr/wSame as /sys/time but with 0x1280 source
/sys/timezoneIntegerr/wMinutes west of UTC
/sys/timezone_validBooleanr/wIf the timezone settings are valid
/sys/dst_activeBooleanr/wIf /sys/dst_change specifies the end of DST
/sys/dst_changeIntegerr/wUTC time when daylight savings time ends or begins
/sys/dst_validBooleanr/wIf DST settings are valid.
/sys/time/sourceIntegerrHow time was set
/sys/versionUTF-8rModule software version

Note: The MCU can set module time with sys/time or sys/time/pri. The only difference is the time source: The sys/time setting is subordinate to Ayla Cloud and can be overwritten by the cloud. The sys/time/pri setting cannot be overwritten by other sources.

The following table describes the different values of sys/time/source translation:

ValueMeaning
0x0000Clock has never been set
0x1130Clock set to an arbitrary default
0x1140Clock set by internal web server
0x1250Clock set by MCU (Lower Priority to ADS)
0x1260Clock set using ADS
0x1270Clock set using NTP
0x1280Clock set by MCU (Higher Priority to ADS)

Wi-Fi Configuration Settings

The following table describes the Wi-Fi configuration settings:

VariableTypeAccessMeaning
/wifi/powerIntegerr/wMaximum TX power (db)
/wifi/profile/startIntegerwProfile to activate
/wifi/profile/<n>/ssidUTF-8r/wSSID
/wifi/profile/<n>/securityInteger (token)r/wType of security to use
/wifi/profile/<n>/keyBinarywWi-Fi key
/wifi/profile/<n>/enableBooleanr/wEnable the profile
/wifi/regionIntegerr/wRegulatory region where Wi-Fi module operates
/wifi/scan/readyBooleanrScan results are ready
/wifi/scan/save_on_ap_connectBooleanr/wSave profile when it connects to an AP
/wifi/scan/save_on_server_connectBooleanr/wSave profile when it connects to ADS
/wifi/scan/startBooleanwStart Wi-Fi scan
/wifi/scan/nIntegerrTake a snapshot of current scan results
/wifi/scan/n/<n>/ssidUTF-8rScan result SSID
/wifi/scan/n/<n>/bssidBinaryrScan result BSSID
/wifi/scan/n/<n>/rssiIntegerrSignal (dbm)
/wifi/scan/n/<n>/barsIntegerrSignal strength in 0 to 5 "bars".
/wifi/scan/n/<n>/securityIntegerrSecurity type token
/wifi/scan/n/<n>/chanIntegerrScan result channel
/wifi/setup_ios_appUTF-8r/wCustom URI for iOS setup app. Writable in setup mode only.
/wifi/setup_mode/enableIntegerr/wStart or stop setup mode. Set bit 0 (value 1) to start Airkiss setup. Set bit 0 (value 0) to stop. Wi-Fi must be in AP mode.
/wifi/setup_mode/keyBinarywEncryption key for setup mode. Airkiss uses an AES 128-bit key which must be exactly 16 bytes.
/wifi/status/profileIntegerrProfile of connected AP
/wifi/status/rssiIntegerrSignal strength in dbm
/wifi/status/bssidBinaryrBSSID of connected AP
/wifi/WPSBooleanr/wWPS virtual button press

Additional details on the Wi-Fi configuration settings in the table above:

  • /wifi/enable is the master Wi-Fi enable:
    • If = 1, the Wi-Fi monitor tries to maintain a connection (or be in AP mode).
    • If= 0, Wi-Fi chip is powered off.
  • Antenna selection varies by model. For 43362-based modules, antenna inputs can be 0 or 1 - or 3 to automatically use the best antenna. All other values are reserved.
  • If /wifi/mac_addr is non-zero, it can be an alternative Wi-Fi mac address (primarily for testing). Otherwise, if zero, /sys/mac_addr is used.
  • There are 11 profiles:
    • Profiles0-9 are for known networks.
    • In AP mode, the module uses profile 10.
  • When /wifi/enable is set , the module tries to connect to configured profiles. The module then chooses an appropriate profile. To override the selection, set /wifi/profile/start to a value. The module drops the current connection and attempts to choose the profile with that index.
  • To start module in AP mode, set /wifi/profile/start to the AP profile’s index. This setting persists until module is configured with a new profile or it does a Wi-Fi scan.
  • There are up to 20 scan results, numbered 0 through 19. Some modules store fewer. When no scan is in progress, the results can be retrieved.
  • Before the scan results are fetched, the MCU must read the variable /wifi/scan/n. This does a ‘snapshot’ of current results. The module keeps serving scan information from this snapshot. A new scan removes old snapshot data. Another read /wifi/scan/n is required.
  • SSID in profiles and scan results are passed as a UTF-8 TLV. Any sequence up to 32 bytes is valid, even if some are not valid UTF-8 characters.
  • The module must be in AP mode to start Wi-Fi Protected Setup(WPS). WPS Push Button Configuration is supported.
    • The MCU can press virtual Push Button by writing ‘1’ to /wifi/WPS.
    • The button stays pressed until module finds a suitable AP advertising WPS (or after 120 seconds).
    • When WPS is finished, the button is released.
  • If the module finds a suitable AP, the module tries to join that network. The join progress is in Wi-Fi Connection History, if needed.
  • During manufacturing or setup modes, set /wifi/region to restrict Wi-Fi behavior (of the attached module) to region requirements. These are valid /wifi/region values:

    0Default region for the module
    1United States
    2China
    3EU
    4Japan
    5Canada
    6Australia

Wi-Fi Connection History

The following table describes the Wi-Fi connection history variables:

VariableTypeAccessMeaning
/wifi/powerBinaryrFirst and last bytes of the SSID. Non-zero if the history entry exists.
/wifi/hist/n/<n>/bssidBinaryrBSSID
/wifi/hist/n/<n>/dns/n/<n>IntegerrDNS server IP address
/wifi/hist/n/<n>/errorIntegerrerror code
/wifi/hist/n/<n>/timeIntegerrUTC of attempt
/wifi/hist/n/<n>/addrIntegerrIP address
/wifi/hist/n/<n>/maskIntegerrnetmask assigned
/wifi/hist/n/<n>/gwIntegerrgateway assigned

The Connection History saves the last three connection attempts. History index 0 is the latest entry. Connection error codes are:

CodeDescription
0No error.
1Resource problem, out of memory or buffers, perhaps temporary.
2Connection timed out.
3Invalid key.
4SSID not found.
5Not authenticated via 802.11 or failed to associate with the AP.
6Incorrect key.
7Failed to get IP address from DHCP.
8Failed to get default gateway from DHCP.
9Failed to get DNS server from DHCP.
10Disconnected by AP.
11Signal lost from AP (beacon miss).
12Device service host lookup failed.
13Device service GET was redirected.
14Device service connection timed out.
15No empty Wi-Fi profile slots.
16The security method used by the AP is not supported.
17The network type (e.g. ad-hoc) is not supported.
18The server responded in an incompatible way. The AP may be a Wi-Fi hotspot.
19Module failed to authenticate to device service.
20Connection attempt currently in progress. Check later for connection status.

Control Operations Log

The log control operations (control opcode 0x0c) message includes an Integer TLV with the function number followed by optional argument TLVs. The following table describes the log control functions:

FunctionNameMeaning
1AppendAppend message to the log. MCU appends messages to module’s log, and (f enabled) writes to the module’s serial port. Log level is specified by the message’s first character. Message is a UTF8 TLV and contains only printable ASCII characters 0x20 thru 0x7e. Message source is set to "mcu."
2Save SnapshotSaves the current log. The module saves the current log messages to the flash ROM for further diagnosis. Up to 8 log snapshots may be saved. If the save area is full, this command receives a NAK.
3Clear SnapshotClear all saved snapshots. The module erases the saved snapshots.
4SendSend current log to ADS. The module sends the current log to the ADS.
5Send SnapshotSend specified snapshot to ADS. The module sends a snapshot to the ADS. The snapshot number is specified using an Integer TLV. If no snapshot number is specified, the most recently saved one is sent.

Hardware Interface

The module provides several signals used by the MCUs with the Serial Peripheral Interface (SPI) protocol or Asynchronous Serial protocol (UART). MCUs using either interface can use the following signals:

  • RESET_N: This is both a module input and output and should be driven low by the MCU to reset the module. The module pulls up this signal.
  • READY_N: This open-drain signal goes low after the module is initialized and ready for SPI communications.
  • LINK_N: The output is low when the module connects to the Ayla Device Service (ADS). The output is high when the module cannot communicate with the ADS.
  • INTR_N: The pin is an open-drain, active-low interrupt output from the module. This signal is active when the module has an SPI message pending for the MCU. It is possible to poll the status without this line. However, if this line is used, the pin should be pulled up to 3.3v (not 5v) on the MCU.
  • WKUP: When the module’s current power-management level is standby, this signal can be driven low (which puts module into standby), and then brought high (wakes up module from low-power, standby state).

MCUs using the SPI protocol can use the following signals:

  • SPI Clock
  • SPI MOSI
  • SPI MISO
  • SPI SSN

The details of the SPI signals are specific to the particular module type. Following are typical configurations (variations may exist, but are rare):

  • The MCU provides the SPI clock. Currently the interface is tested at 3.2 MHz; however, higher rates up to 16 MHz should be possible.
  • The SPI interface is used in mode 1 (CPOL = 0, CPHA=1). The clock polarity is set so that it is normally low when idling, and the phase is set so that the receiver latches the data on the falling edge of the clock.
  • Transfers are sent with the MSB first.
  • The hardware SSN is honored and should be used. This assists with synchronizing the data. If this is not implemented by the host MCU, this should be pulled down.
  • On some modules, MISO output from the module is configured as an open-drain output. This permits a multi-slave configuration (so that the MCU can access other SPI peripherals on the same bus). The MCU should supply a pull-up resistor for MISO.

Did this page help you?