Tile Over-the-air API Compatibility

Macros
#define	TOA_CONNECTIONLESS_CID   0
	CID for TOA connectionless channel.
#define	TOA_TOKEN_LEN   4
	Size of the token included with each connectionless command/response.
#define	TOA_BROADCAST_CID   1
	CID for TOA broadcast messages. Broadcast messages are unidirectional, from Server to Client. Broadcast messages contain a MIC. The parameters for the broadcast session key may be requested by an authenticated Client at any time.
#define	TOA_BROADCAST_TOKEN   0xFFFFFFFF
	Token to use on the Conectionless CID to send broadcast Responses. When supported, TOA Clients will process any response using this token.
#define	TILE_AUTH_RAND_A_LEN   14
	Defines related to authentication.
#define	TILE_AUTH_RAND_T_LEN   10
#define	TILE_SRES_LEN   4
#define	TILE_RAND_A_LEN   14
#define	TILE_RAND_T_LEN   13
#define	TILE_RAND_T_FIXED_LEN   10
#define	TILE_MIC_LEN   4
#define	TOA_FEATURE_BYTES   3
	TOA SUPPORTED FEATURES BITFIELD.
#define	TOA_CLIENT_FEATURE_BYTES   1
	TOA CLIENT SUPPORTED FEATURES BITFIELD.

Enumerations
enum	TOA_RSP {   TOA_RSP_RESERVED = 0x00,   TOA_RSP_READY = 0x01,   TOA_RSP_TOFU_CTL = 0x02,   TOA_RSP_ASSERT = 0x03,   TOA_RSP_BDADDR = 0x04,   TOA_RSP_ERROR = 0x05,   TOA_RSP_TDT = 0x06,   TOA_RSP_SONG = 0x07,   TOA_RSP_PPM = 0x08,   TOA_RSP_ADV_INT = 0x09,   TOA_RSP_TKA = 0x0a,   TOA_RSP_TAC = 0x0b,   TOA_RSP_TDG = 0x0c,   TOA_RSP_TMD = 0x0d,   TOA_RSP_TCU = 0x0e,   TOA_RSP_TIME = 0x0f,   TOA_RSP_TEST = 0x10,   TOA_RSP_TFC = 0x11,   TOA_RSP_OPEN_CHANNEL = 0x12,   TOA_RSP_CLOSE_CHANNEL = 0x13,   TOA_RSP_TDI = 0x14,   TOA_RSP_AUTHENTICATE = 0x15,   TOA_RSP_TMF = 0x16,   TOA_RSP_TLIL = 0x17,   TOA_RSP_TEF = 0x18,   TOA_RSP_TRM = 0x19,   TOA_RSP_TPC = 0x1A,   TOA_RSP_ASSOCIATE = 0x1B,   TOA_RSP_AUTHORIZED = 0x1C }
	TOA Response Codes TOA_RSP Format: More...
enum	TOA_CMD {   TOA_CMD_TOFU_CTL = 0x01,   TOA_CMD_TOFU_DATA = 0x02,   TOA_CMD_BDADDR = 0x03,   TOA_CMD_TDT = 0x04,   TOA_CMD_SONG = 0x05,   TOA_CMD_PPM = 0x06,   TOA_CMD_ADV_INT = 0x07,   TOA_CMD_TKA = 0x08,   TOA_CMD_TAC = 0x09,   TOA_CMD_TDG = 0x0a,   TOA_CMD_TMD = 0x0b,   TOA_CMD_TCU = 0x0c,   TOA_CMD_TIME = 0x0d,   TOA_CMD_TEST = 0x0e,   TOA_CMD_TFC = 0x0f,   TOA_CMD_OPEN_CHANNEL = 0x10,   TOA_CMD_CLOSE_CHANNEL = 0x11,   TOA_CMD_READY = 0x12,   TOA_CMD_TDI = 0x13,   TOA_CMD_AUTHENTICATE = 0x14,   TOA_CMD_TMF = 0x15,   TOA_CMD_TLIL = 0x16,   TOA_CMD_TEF = 0x17,   TOA_CMD_TRM = 0x18,   TOA_CMD_TPC = 0x19,   TOA_CMD_ASSOCIATE = 0x1A }
	TOA Command Codes TOA_CMD Format: More...
enum	TOA_CHANNEL_CLOSE_REASONS {   CLOSE_REASON_NO_ERROR = 0x00,   CLOSE_REASON_MIC_FAILURE = 0x01,   CLOSE_REASON_TKA_MISSING = 0x02,   CLOSE_REASON_BROADCAST_MIC_FAIL = 0x03 }
	Reason codes for TOA_RSP_CLOSE_CHANNEL and TOA_CMD_CLOSE_CHANNEL. More...
enum	TOA_SUPPORTED_FEATURES {   TOA_FEATURE_TOFU = 0,   TOA_FEATURE_BDADDR = 1,   TOA_FEATURE_TDT = 2,   TOA_FEATURE_SONG = 3,   TOA_FEATURE_PPM = 4,   TOA_FEATURE_ADV_INT = 5,   TOA_FEATURE_OLD_TKA = 6,   TOA_FEATURE_TAC = 7,   TOA_FEATURE_UNUSED = 8,   TOA_FEATURE_TKA = 9,   TOA_FEATURE_TDG = 10,   TOA_FEATURE_TMD = 11,   TOA_FEATURE_TCU = 12,   TOA_FEATURE_TIME = 13,   TOA_FEATURE_TEST = 14,   TOA_FEATURE_TMA = 15,   TOA_FEATURE_TFC = 16,   TOA_FEATURE_TPS = 17,   TOA_FEATURE_TMF = 18,   TOA_FEATURE_TLIL = 19,   TOA_FEATURE_TEF = 20,   TOA_FEATURE_TRM = 21,   TOA_FEATURE_TPC = 22,   TOA_FEATURE_TSQ = 23 }
	TOA SUPPORTED FEATURES. More...
enum	TOA_CLIENT_SUPPORTED_FEATURES { TOA_CLIENT_FEATURE_TDE = 0 }
	TOA CLIENT SUPPORTED FEATURES. More...

Detailed Description

TOA compatibility Requirements:

• TOA Server:
  • TOA Server shall ignore (without behavioral impact) any unknown TOA_CMD and respond with error TOA_RSP_ERROR_UNSUPPORTED.
  • TOA Server shall ignore (without behavioral impact) any unknown additional parameters after any TOA_CMD payload.
• TOA Client:
  • TOA Client shall ignore (without behavioral impact) any unknown TOA_RSP.
  • TOA Client shall ignore (without behavioral impact) any unknown additional parameters after any TOA_RSP payload.
  • There is no mandatory TOA feature and the TOA Client shall support that any TOA feature is not supported (like Tile mode or TILE_SONG for instance).

Enumeration Type Documentation

enum TOA_CHANNEL_CLOSE_REASONS

Reason codes for TOA_RSP_CLOSE_CHANNEL and TOA_CMD_CLOSE_CHANNEL.

Enumerator
CLOSE_REASON_NO_ERROR	Clean close. No payload.
CLOSE_REASON_MIC_FAILURE	Could not verify MIC. Payload format: Nonce value Expected MIC 4 bytes 4 bytes
CLOSE_REASON_TKA_MISSING	Did not receive TKA ack. No payload.
CLOSE_REASON_BROADCAST_MIC_FAIL	The Client received a broadcast with an invalid MIC. Payload format: Client NonceB value Expected MIC 4 bytes 4 bytes

enum TOA_CLIENT_SUPPORTED_FEATURES

TOA CLIENT SUPPORTED FEATURES.

Bit	Feature
bit 0	TDE : Can receive TDE events
bit 1	RFU
bit 2	RFU
bit 3	RFU
bit 4	RFU
bit 5	RFU
bit 6	RFU
bit 7	RFU

enum TOA_CMD

TOA Command Codes
TOA_CMD Format:

TOA_CMD Code	Payload	MIC
1 Byte	Up to TOA_MPS Bytes (Max Payload Size)	4 Bytes

TOA_MPS is provided by the TOA Server in the TOA_RSP_READY response.
TOA Server shall respond to an unknow TOA_CMD by a TOA_RSP_ERROR with ErrorCode TOA_RSP_ERROR_UNSUPPORTED.
TOA Server shall silently ignore any extra unknown parameter at the end of a command.

Enumerator
TOA_CMD_TOFU_CTL	TOFU Control Command
TOA_CMD_TOFU_DATA	TOFU_DATA Command<br> TOFU Data Channel is separated from the TOFU Control Channel for efficiency reasons. Note that TOFU Data Can only be sent when TOFU is ready. Format: TOA_CMD_TOFU_DATA Code TOFU Data 1 Byte Varies (Up to TOA_MPS Bytes)
TOA_CMD_BDADDR	BDADDR Command
TOA_CMD_TDT	TDT Command
TOA_CMD_SONG	SONG Command
TOA_CMD_PPM	PPM Command
TOA_CMD_ADV_INT	ADV_INT Command
TOA_CMD_TKA	TKA Command
TOA_CMD_TAC	TAC Command
TOA_CMD_TDG	TDG Command
TOA_CMD_TMD	TMD Command
TOA_CMD_TCU	TCU Command
TOA_CMD_TIME	TIME Command
TOA_CMD_TEST	TEST Command
TOA_CMD_TFC	TFC Command
TOA_CMD_OPEN_CHANNEL	OPEN_CHANNEL Command. This Command is Mandatory over MEP_TOA and forbidden on Legacy TOA Available on TOA_CONNECTIONLESS_CID. Format: TOA_CMD_OPEN_CHANNEL RAND_A 1 byte 14 bytes
TOA_CMD_CLOSE_CHANNEL	CLOSE_CHANNEL Command. This Command is Mandatory over MEP_TOA and forbidden on Legacy TOA Format: TOA_CMD_CLOSE_CHANNEL TOA_CHANNEL_CLOSE_REASONS code Payload 1 byte 1 byte Varies
TOA_CMD_READY	READY Command. This Command is Mandatory over MEP_TOA and forbidden on Legacy TOA Format: TOA_CMD_READY TOA_MPS TOA_CLIENT_SUPPORTED_FEATURES 1 byte 1 byte Varies
TOA_CMD_TDI	TDI Command. This Command is Mandatory over MEP_TOA and forbidden on Legacy TOA Available on TOA_CONNECTIONLESS_CID.
TOA_CMD_AUTHENTICATE	AUTHENTICATE Command. This Command is Mandatory over MEP_TOA and forbidden on Legacy TOA Available on TOA_CONNECTIONLESS_CID. Format: TOA_CMD_AUTHENTICATE RAND_A 1 byte 14 bytes
TOA_CMD_TMF	TMF Command
TOA_CMD_TLIL	TLIL Command
TOA_CMD_TEF	TEF Command
TOA_CMD_TRM	TRM Command
TOA_CMD_TPC	TPC Command
TOA_CMD_ASSOCIATE	ASSOCIATE Command. This Command is Mandatory over MEP_TOA and forbidden on Legacy TOA Available on TOA_CONNECTIONLESS_CID. Will trigger either a TOA_RSP_ASSOCIATE or a TOA_RSP_ERROR with error code TOA_RSP_ERROR_AUTHORIZATION Format: @ref TOA_CMD_ASSOCIATE | RAND_A --------------------------|--------- 1 byte | 14 bytes

enum TOA_RSP

TOA Response Codes
TOA_RSP Format:

TOA_RSP Code	Payload	MIC
1 Byte	Up to TOA_MPS Bytes (Max Payload Size)	4 Bytes

TOA_MPS is defined by the TOA Server and is provided in the TOA_RSP_READY Response
TOA Client shall silently ignore an unkown TOA_RSP.
TOA Client shall silently ignore any extra unknown parameter at the end of a response.

Enumerator
TOA_RSP_RESERVED	reserved, not used.
TOA_RSP_READY	This Response is sent when a @ref TOA_CMD_READY command is received. <br> Note: For Legacy TOA, this response is sent as soon as notification has been enabled on TOA_RSP characteristic. Format: TOA_RSP_READY Code TOA_MPS Supported Features Byte 0, 1 and 2 TOA Broadcast Nonce RFU 1 Byte 1 Byte 3 Bytes, check TOA_SUPPORTED_FEATURES 4 Bytes Varies, Reserved for Future Use
TOA_RSP_TOFU_CTL	TOFU Control Response
TOA_RSP_ASSERT	ASSERT Response
TOA_RSP_BDADDR	BDADDR Response
TOA_RSP_ERROR	This Response is sent when something goes wrong. <br> see TOA_ERROR_CODES for a description of the possible errors and their parameters Format: TOA_RSP_ERROR Code TOA_ERROR_CODES Parameters 1 Byte 1 Byte Varies
TOA_RSP_TDT	TDT Response
TOA_RSP_SONG	SONG Response
TOA_RSP_PPM	PPM Response
TOA_RSP_ADV_INT	ADV_INT Response
TOA_RSP_TKA	TKA Response
TOA_RSP_TAC	TAC Response
TOA_RSP_TDG	TDG Response
TOA_RSP_TMD	TMD Response
TOA_RSP_TCU	TCU Response
TOA_RSP_TIME	TIME Response
TOA_RSP_TEST	TEST Response
TOA_RSP_TFC	TFC Response
TOA_RSP_OPEN_CHANNEL	OPEN_CHANNEL Response. This Response is Mandatory over MEP_TOA and forbidden on Legacy TOA Used on TOA_CONNECTIONLESS_CID. Format: TOA_RSP_OPEN_CHANNEL Allocated CID RAND_T 1 byte 1 byte 13 bytes
TOA_RSP_CLOSE_CHANNEL	CLOSE_CHANNEL Response. This Response is Mandatory over MEP_TOA and forbidden on Legacy TOA Format: TOA_RSP_CLOSE_CHANNEL TOA_CHANNEL_CLOSE_REASONS code Payload 1 byte 1 byte Varies
TOA_RSP_TDI	TDI Response. Used on TOA_CONNECTIONLESS_CID.
TOA_RSP_AUTHENTICATE	AUTHENTICATE Response. This Response is Mandatory over MEP_TOA and forbidden on Legacy TOA Used on TOA_CONNECTIONLESS_CID. Format: TOA_RSP_AUTHENTICATE RAND_T SRES_T 1 byte 10 bytes 4 bytes To generate SRES_T, follow the following steps: Pad the end of RAND_A and RAND_T until each is 16 bytes Run HMAC-SHA256 on RAND_A concatenated with RAND_T and keyed with the auth key Take bytes 4:7. These bytes are SRES_T.
TOA_RSP_TMF	TMF Response
TOA_RSP_TLIL	TLIL Response
TOA_RSP_TEF	TEF Response
TOA_RSP_TRM	TRM Response
TOA_RSP_TPC	TPC Response
TOA_RSP_ASSOCIATE	ASSOCIATE Response. This Response is Mandatory over MEP_TOA and forbidden on Legacy TOA Used on TOA_CONNECTIONLESS_CID. Format: TOA_RSP_ASSOCIATE RAND_T SRES_T 1 byte 10 bytes 4 bytes To generate SRES_T, follow the following steps: Pad the end of RAND_A and RAND_T until each is 16 bytes Run HMAC-SHA256 on RAND_A concatenated with RAND_T and keyed with the auth key Take bytes 4:7. These bytes are SRES_T.
TOA_RSP_AUTHORIZED	AUTHORIZED Response. This Response is Mandatory over MEP_TOA and forbidden on Legacy TOA Used on TOA_CONNECTIONLESS_CID. It is a broadcast Response so it is sent using the TOA_BROADCAST_TOKEN Format: TOA_RSP_AUTHORIZED Authorization Type Authorization Timer 1 byte 1 Byte (value 1 for Button Press) 2 bytes (in seconds)

enum TOA_SUPPORTED_FEATURES

TOA SUPPORTED FEATURES.

BYTE 0:

Bit	Feature
bit 0	TOFU : Tile Over the air Firmware Upgrade
bit 1	BDADDR : Tile BDADDR Access
bit 2	TDT : Tile Double Tap
bit 3	TILE_SONG : Tile Song Feature
bit 4	Oscillator Accuracy (in PPM) : Low Power Clock Accuracy Control
bit 5	Advertising Interval : Advertising Interval Control
bit 6	OLD_TKA (obsolete) : Tile Keep Alive compatibility with FW 1.9
bit 7	TAC : Tile Accelerometer Feature (Evaluation/disabled)

BYTE 1:

Bit	Feature
bit 0	Unused, fixed to 0 (may cause unwanted behavior in previous app versions)
bit 1	TKA : Tile Keep Alive Feature
bit 2	TDG : Tile Diagnostic Access
bit 3	TMD : Tile Mode Control
bit 4	TCU : Tile Connection Update Control
bit 5	TIME : Tile Time-keeper
bit 6	TEST : Tile TEST Feature
bit 7	TMA

BYTE 2:

Bit	Feature
bit 0	TFC : Tile Flow Control - DEPRECATED
bit 1	TPS : Tile Programmable Songs
bit 2	TMF : Tile Manufacturing
bit 3	TLIL : Tile Lock-If-Lost
bit 4	TEF : Tile Experimental Framework
bit 5	TRM : Tile RSSI Monitoring
bit 6	TPC : Tile Power Control
bit 7	TSQ : Tile Song Quality