Tile Over-the-air API Compatibility

nRF5 SDK v16.0.0
Macros | Enumerations

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:

  1. Pad the end of RAND_A and RAND_T until each is 16 bytes
  2. Run HMAC-SHA256 on RAND_A concatenated with RAND_T and keyed with the auth key
  3. 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:

  1. Pad the end of RAND_A and RAND_T until each is 16 bytes
  2. Run HMAC-SHA256 on RAND_A concatenated with RAND_T and keyed with the auth key
  3. 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