Time/Length/Value (TLV) Format

Most messages contain one or more TLV 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:

ClosedTLV Type Codes
TLV Type Name Description
0x01 Name

Property name, without NUL termination.
0x02 Integer 1-, 2-, 4-, or 8-byte signed integer value, in network byte order.
0x03 Unsigned Integer 1-, 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.
0x04 Binary Unstructured data bytes.
0x05 Text UTF-8 encoded text value, without NUL termination.
0x06 Configuration tokens UTF-8 encoded configuration tokens.
0x07 Error Error number, used in a NAK packet.
0x08 Format (optional) Set of flags how the current named value should be formatted.
0x0f Boolean One-byte value of 1 or 0.
0x10 Continuation token 4-byte value used in stepping through tables or lists.
0x11 Offset Byte offset of the start of the value TLV that follows. (For large datapoints.)
0x12 Length Total length of a datapoint value.
0x13 Location Location string identifying datapoint.
0x14 EOF End-of-file for datapoint, e.g., length is always 0.
0x16 Cents Fixed-point integer 100 times actual value. For example, 98.72 is 9872 decimal. Usually 4-bytes.
0x17 Nodes One-byte bitmap of destinations or sources for property updates. Bit 0 is device service, other bits assigned for local destinations.
0x18 Echo Indicates prop update is an echo. Length is always 0.
0x19 Feature Mask One-byte bitmap of the supported features in the MCU.
0x1a Factory Reset Configuration name indices.
0x1b Delete Configuration UTF-8 encoded configuration tokens.
0x1c Registration Contains single 1-byte value set to 1 or 0.
1 = device registered with a user
0 = device de-registered.
0x1d Event Mask Module sends this to indicate an event. Supported event: - standby power mode: Module goes into standby mode. (To wake up, reset MCU.)
0x1e Ack ID When 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.
0x20 Schedule Schedule property composed of Schedule-related TLVs.
0x21 to 0x33 Schedule TLV Schedule-related TLVs. See also the table of Schedule-Related TLV Type Codes.
0x34 Datapoint Metadata Key of the key-value pair metadata for a property datapoint update.
0x35 Wi-Fi Status

A 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

• Status code See the table of Status values in Wi-Fi status (0x35) event.

0x36 Wi-Fi Status Final Sends final Wi-Fi status to the MCU that the module is done trying to join a Wi-Fi. (Used for firmware version 2.8+.)
0x37 Binary message The value for the datapoint of a binary message property.
0x38 UTF-8 message The value for the datapoint of a string message property.
0x39 JSON message The value for the datapoint of a JSON message property.
0x3a Message type The specific type of message datapoint to create.
0x3b Back-off time The specified time to wait before re-trying, in milliseconds.
0x3c Batch ID The Datapoint ID number of datapoint in batch. This is used to correlate the resulting status to an individual datapoint.
0x3d Batch End If present, this indicates the last datapoint of a batch.
0x3e Time in milliseconds The UTC time since 1970-01-01T00:00:00 in milliseconds. The value is 8 bytes long and in network byte order.
ClosedSchedule-Related TLV Type Codes
TLV Type Name Description
0x21 UTC

Indicates date/time in schedules are UTC.
0x22 AND ANDs the top two conditions in schedule.
0x23 Disable Disables the schedule.
0x24 In_Range Stack is true if current time is in range.
0x25 At_Start Stack is true if current time is at start.
0x26 At_End Stack is true if current time is at end.
0x27 Start Date Date must be after value.
0x28 End Date (Date must be before value.
0x29 Days of Month 32-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.
0x2a Days of Week 7-bit mask indication which day of the week. Bit 0 is Sunday. Bit 7 is reserved.
0x2b Day Occur In Month Day Occurrence in Month. Bit 0 is the first occurrence.
0x2c Months of Year Months of Year, 1 through 12.
0x2d Start Time Each Day Start Time for each valid day of schedule.
0x2e End Time Each Day End Time for each valid day of schedule.
0x2f Duration Event duration.
0x30 (TBD) Time Before End Time must be <value> secs before end.
0x31 Interval Start every <value> secs from start.
0x32 Set Prop Value is a TLV pair of the action to take.
0x33 Version The version of the schedule.

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:

ClosedStatus Values in Wi-Fi Status (0x35) Event
TLV Type Name Description
0x00 Success Module joined Wi-Fi network identified by SSIDService Set Identifier.
0x01 Resource Unavailable

Resource unavailable to complete join operation (may be temporary).
0x02 Connection Timed Out Connection to APAccess Point 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.
0x03 Invalid Key Wi-Fi password supplied to module was not valid for configured security method on AP.
0x04 Network Not Found The 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.
0x05 Not Authenticated Attempt to authenticate with the AP failed. May indicate connection to the AP was lost, or provided password was incorrect.
0x06 Wrong Key Wi-Fi password was incorrect. Whether an AP indicates this error or a Not Authenticated error is specific to AP.
0x07 No IP Address Failed to obtain IP address from AP with DHCPDynamic Host Configuration Protocol.
0x08 No Route Failed to obtain default route from AP with DHCP.
0x09 No DNS Server Failed to obtain DNS Server address from AP with DHCP.
0x0a AP Disconnected AP disconnected from module. May indicate AP cannot reliably receive data from module, or AP was restarted or powered off.
0x0b Loss of Signal Module failed to receive consecutive beacons from AP. Module cannot reliably receive data from AP, or AP was restarted or powered off.
0x0c DNS lookup failed OEM-based hostname used to reach the ADSAyla Device Service was not resolved to an IP address.
0x0d ADS Connection Redirect Connection to ADS failed due to an HTTP redirect.
0x0e ADS Connection Timeout Connection to ADS timed out. May be a failure in network beyond Wi-Fi AP, or failure to communicate with AP.
0x0f No Profile Available Connection to the Wi-Fi network succeeded, but configuration was not saved, because too many configured Wi-Fi profiles.
0x10 Security Method Not Supported Module or Access Point does not support security method specified in Wi-Fi join request.
0x11 Network Type Unsupported Wi-Fi network type (e.g., Ad-Hoc, Enterprise) not supported by module.
0x12 Wi-Fi protocol error Access Point protocol not supported. Error can occur on attempt to connect to a personal hotspot, or device in tethering mode.
0x13 ADS authentication error Module failed to authenticate with ADS. Report error immediately to Ayla Customer Service (module code may need to be updated).
0x14 Operation In Progress Wi-Fi join operation still in progress. Subsequent status event indicate success or failure when join operation completes.
0x15 Setup Unsupported Module is in setup mode. Join Wi-Fi network only permitted in user mode.

 

 

 

Please click here to let us know how we're doing. Thank you.