Tile Over-the-air API

nRF5 SDK v16.0.0
Modules | Data Structures | Macros | Enumerations | Functions | Variables

Tile Over-the-air Api: defines Tile communication protocol over the air. More...

Modules

Tile Library API
Tile Library Api.
Tile Over-the-air API Compatibility
Tile Over-the-air Common API
Oscillator Accuracy (in PPM)
Advertising Interval
Tile Diagnostics module
Tile Diagnostics module.
Tile mode
Tile Over-the-air API module

Data Structures

struct song_hdr_info_t
Song file header info portion. More...
struct song_hdr_sec_t
Song file header security info. More...
struct song_program_state_t
State of song programming. More...
struct song_metadata_t
Metadata info stored in flash. More...
struct song_info_cache_t
Cache for information related to the currently loaded song. More...
struct tile_song_tps_module_t
struct tile_song_module

Macros

#define TOA_CHANNEL_IDX (cid)   ((cid) - TOA_BROADCAST_CID - 1)
Helper defines for dealing with CIDs.
#define TOA_CHANNEL_MIN_CID ( TOA_BROADCAST_CID + 1)
#define TOA_CHANNEL_MAX_CID ( TOA_BROADCAST_CID + toa->num_channels)
#define TOA_DISCONNECT_TIME 5
Seconds until a GAP disconnection is issued after all TOA channels are closed.
#define BYTE (a, n)   (((a) >> ((n)*8)) & 0xFF)
Message packing helpers. More...
#define MKLE16 (x) BYTE ((uint16_t)(x), 0), BYTE ((uint16_t)(x), 1)
#define MKLE32 (x) MKLE16 ((uint32_t)(x)), MKLE16 (((uint32_t)(x)) >> 16)
#define TOA_EXTERN_DECL (ret, fname, args)   extern ret (*fname)args
Declare a function visible externally. More...
#define TOA_EXTERN_IMPL (ret, fname, args)
Define an externally-visible function implementation. More...
#define TOA_EXTERN_LINK (fname)   fname = fname ## _linked
Link an externally-visible function.
#define SONG_METADATA_SIZE (sizeof(struct song_metadata_t ))
#define SONG_INFO_SIZE (sizeof(struct song_hdr_info_t ))
#define SONG_SECURITY_SIZE (sizeof(struct song_hdr_sec_t ))
#define SONG_HEADER_SIZE (SONG_INFO_SIZE + SONG_SECURITY_SIZE)
#define SONG_HASH_SIZE 32
#define SONG_SIG_SIZE 64
#define SONG_CRC16_SIZE 2
#define TILE_PROGRAMMABLE_SONG_LENGTH 1024
#define TILE_SONG_BLOCK_SIZE 128
#define TILE_SONG_BUFFER_SIZE TILE_SONG_BLOCK_SIZE + SONG_CRC16_SIZE
#define TILE_SONG_VERSION 1
#define TILE_SONG_VALID 0xAA

Enumerations

enum BDADDR_CMD {
BDADDR_CMD_READ_FEATURES = 0x01,
BDADDR_CMD_READ_VAL = 0x02
}
enum BDADDR_RSP {
BDADDR_RSP_READ_FEATURES_OK = 0x01,
BDADDR_RSP_READ_VAL_OK = 0x02
}
enum TOA_CHANNEL_STATE_BITFIELD {
TOA_CHANNEL_ASSIGNED = 0x01,
TOA_CHANNEL_AUTHENTICATED = 0x02,
TOA_CHANNEL_TKA_ENABLED = 0x04,
TOA_CHANNEL_WAIT4ACK = 0x08
}
TOA channels states bitfield.
enum TILE_SONG {
TILE_SONG_1_CLICK = 0x00,
TILE_SONG_FIND = 0x01,
TILE_SONG_ACTIVE = 0x02,
TILE_SONG_SLEEP = 0x03,
TILE_SONG_WAKEUP = 0x04,
TILE_SONG_FACTORY_TEST = 0x05,
TILE_SONG_MYSTERY = 0x06,
TILE_SONG_SILENT = 0x07,
TILE_SONG_BUTTON = 0x08,
TILE_SONG_WAKEUP_PART = 0x09,
TILE_SONG_DT_SUCCESS = 0x0a,
TILE_SONG_DT_FAILURE = 0x0b,
TILE_SONG_2_CLICK = 0x0c,
TILE_SONG_1_BIP = 0x0d,
TILE_SONG_2_BIP = 0x0e,
TILE_SONG_3_BIP = 0x0f,
TILE_SONG_4_BIP = 0x10,
TILE_SONG_5_BIP = 0x11,
TILE_SONG_6_BIP = 0x12,
TILE_SONG_7_BIP = 0x13,
TILE_SONG_DT_HB = 0x14,
TILE_SONG_MAX = 0x15,
TILE_SONG_STOP = 0xFF
}
Tile Song numbers.
enum NOTES {
REST = 0x00,
C0 ,
CS0 ,
D0 ,
DS0 ,
E0 ,
F0 ,
FS0 ,
G0 ,
GS0 ,
A0 ,
AS0 ,
B0 ,
C1 ,
CS1 ,
D1 ,
DS1 ,
E1 ,
F1 ,
FS1 ,
G1 ,
GS1 ,
A1 ,
AS1 ,
B1 ,
C2 ,
CS2 ,
D2 ,
DS2 ,
E2 ,
F2 ,
FS2 ,
G2 ,
GS2 ,
A2 ,
AS2 ,
B2 ,
C3 ,
CS3 ,
D3 ,
DS3 ,
E3 ,
F3 ,
FS3 ,
G3 ,
GS3 ,
A3 ,
AS3 ,
B3 ,
C4 ,
CS4 ,
D4 ,
DS4 ,
E4 ,
F4 ,
FS4 ,
G4 ,
GS4 ,
A4 ,
AS4 ,
B4 ,
C5 ,
CS5 ,
D5 ,
DS5 ,
E5 ,
F5 ,
FS5 ,
G5 ,
GS5 ,
A5 ,
AS5 ,
B5 ,
C6 ,
CS6 ,
D6 ,
DS6 ,
E6 ,
F6 ,
FS6 ,
G6 ,
GS6 ,
A6 ,
AS6 ,
B6 ,
C7 ,
CS7 ,
D7 ,
DS7 ,
E7 ,
F7 ,
FS7 ,
G7 ,
GS7 ,
A7 ,
AS7 ,
B7 ,
C8 ,
CS8 ,
D8 ,
DS8 ,
E8 ,
F8 ,
FS8 ,
G8 ,
GS8 ,
A8 ,
AS8 ,
B8 ,
C9 ,
CS9 ,
D9 ,
DS9 ,
E9 ,
F9 ,
FS9 ,
G9 ,
GS9 ,
A9 ,
AS9 ,
B9
}
enum TOA_FEATURE_ERROR_CODES {
TOA_ERROR_OK = 0x00,
TOA_ERROR_UNSUPPORTED = 0x01,
TOA_ERROR_PARAMETERS = 0x02,
TOA_ERROR_SECURITY = 0x03,
TOA_ERROR_INVALID_STATE = 0x04,
TOA_ERROR_MEM_READ = 0x05,
TOA_ERROR_MEM_WRITE = 0x06,
TOA_ERROR_DATA_LENGTH = 0x07,
TOA_ERROR_INVALID_SIZE = 0x08,
TOA_ERROR_SIGNATURE = 0x09,
TOA_ERROR_CRC = 0x0A,
TOA_ERROR_CRC2 = 0x0B,
TOA_ERROR_HASH = 0x0C,
TOA_ERROR_PRODUCT_HEADER = 0x0D,
TOA_ERROR_IMAGE_HEADER = 0x0E,
TOA_ERROR_SAME_IMAGE = 0x0F,
TOA_ERROR_INVALID_DATA = 0x10,
TOA_ERROR_MEM_ERASE = 0x11,
TOA_ERROR_RESOURCE_IN_USE = 0x12
}
TOA feature error codes. Any feature which uses these error codes will return the error in a standard format. This format is: More...
enum TOA_ERROR_CODES {
TOA_RSP_ERROR_SECURITY = 0x01,
TOA_RSP_ERROR_UNSUPPORTED = 0x02,
TOA_RSP_ERROR_PARAMETERS = 0x03,
TOA_RSP_ERROR_DROPPED_RSP = 0x04,
TOA_RSP_ERROR_NO_CID_AVAILABLE = 0x05,
TOA_RSP_ERROR_AUTHORIZATION = 0x06,
TOA_RSP_SERVICE_UNAVAILABLE = 0x07
}
TOA Error Response Codes. More...

Functions

static void WRLE16 (uint8_t *a, const uint16_t x)
static void WRLE32 (uint8_t *a, const uint32_t x)
static uint16_t RDLE16 (const uint8_t *a)
Message unpacking helpers. More...
static uint32_t RDLE32 (const uint8_t *a)
void toa_set_feature (uint16_t bit)
uint8_t toa_get_feature (uint16_t bit)
void toa_clear_feature (uint16_t bit)
void toa_init (void)
bool is_toa_authenticated (void)
void toa_process_command (const uint8_t *data, uint8_t datalen)
void toa_write_ok (void)
void toa_process_cccd (uint16_t cccd)
void toa_send_attempt (void)
void toa_send_connectionless_response (uint8_t *token, uint8_t response, uint8_t *data, uint8_t datalen)
void toa_send_response (uint8_t cid, uint8_t response, uint8_t *data, uint8_t datalen)
void toa_send_broadcast (uint8_t response, uint8_t *data, uint8_t datalen)
void toa_send_connectionless_response_error (uint8_t *token, uint8_t error, uint8_t command)
void toa_send_response_error (uint8_t cid, uint8_t error, uint8_t command)
void toa_send_response_error_param (uint8_t cid, uint8_t error, uint8_t command, uint8_t param)
void toa_channel_close (uint8_t cid, uint8_t reason, uint8_t *payload, uint8_t payload_length)
void toa_disconnect (void)
int tile_song_register (struct tile_song_module *module)
void song_begin_done (uint8_t error)
void song_block_done (uint8_t error)
void song_complete_done (uint8_t error)
void song_quality (uint8_t quality)

Variables

uint8_t sca
uint8_t toaRspNotif

Detailed Description

Tile Over-the-air Api: defines Tile communication protocol over the air.

Tile Song Module.

TOA is a transport using 2 GATT characteristics.

  • TOA commands are received by the server using GATT Write without Response on Characteristic TOA_CMD.
  • TOA responses are transmited using GATT Notify on characteristic TOA_RSP.
  • TOA Client sends TOA_CMD and TOA Server sends TOA_RSP .
  • TOA is a multiplexer for supporting independent Upper Layer, these can be seen as TOA channels.
  • TOA is stateless and does not guarantee a command will provide a response. The Upper Layer may guarantee this.
  • TOA supports a notification mechanism, which means an Upper Layer may send a response message when no command was sent.

Multi-End-Point and Legacy TOA
There are 2 versions of TOA: Legacy TOA and Multi_End_Point TOA (MEP_TOA).
Support for either version is discovered through Characteristic discovery (as these use different BLE characteristics).

The main difference between the 2 are as follows:
  • Community Find:
    • MEP_TOA Supports a Command to Authenticate over a connectionless channel (for Community Find).
    • When MEP_TOA is not supported, Community Find authentication is achieved through Legacy Authentication (over legacy characteristics)
  • TOA Channel Open:
    • MEP_TOA Supports a Command to Open a channel (sent over a connectionless channel).
    • When MEP_TOA is not supported, Community Find authentication is achieved through Legacy Authentication (over legacy characteristics)
    • Legacy TOA requires Legacy Authentication (over legacy characteristics) prior to opening the TOA Channel.
    • On Legacy TOA, configuring TOA_RSP Characterisitc for notifications opens the channel.
    • On MEP_TOA, configuring MEP_RSP Characterisitc for notifications is done before sending any TOA Comamnd.
  • TOA Commands and Format:
    • MEP_TOA adds a Channel ID (CID) Byte at the beginning of TOA Commands and Responses.

Macro Definition Documentation

#define BYTE ( a,
n
) (((a) >> ((n)*8)) & 0xFF)

Message packing helpers.

Extract a particular byte from an integer

#define MKLE16 ( x ) BYTE ((uint16_t)(x), 0), BYTE ((uint16_t)(x), 1)

Convert an integer into the elements of a byte array, in little-Endian. Example: uint8_t msg[] = {TOA_RSP_X, MKLE32(myUint32Var), MKLE16(myUint16Var) };

#define SONG_CRC16_SIZE   2

Size of the Block CRC

#define SONG_HASH_SIZE   32

Size of the song hash

#define SONG_SIG_SIZE   64

Size of the song signature

#define TILE_PROGRAMMABLE_SONG_LENGTH   1024

Maximum length of the programmable song section in flash

#define TILE_SONG_BLOCK_SIZE   128

Size of data in a data block

#define TILE_SONG_BUFFER_SIZE TILE_SONG_BLOCK_SIZE + SONG_CRC16_SIZE

Size of intermediate buffer for programming

#define TILE_SONG_VALID   0xAA

Flag indicating a song is valid

#define TILE_SONG_VERSION   1

Version field, to allow future format changes to take place

#define TOA_EXTERN_DECL ( ret,
fname,
args
) extern ret (*fname)args

Declare a function visible externally.

The following three macros should be used to allow TOA features to be completely unlinked at link time. This is done by making everything within a TOA feature static, and only exposing those static functions to the outside world through externally visible function pointers. These macros assist in this process, and should be used as follows:

  1. All externally visible functions should be declared with TOA_EXTERN_DECL in the header for the TOA feature.
  2. Each function declared with TOA_EXTERN_DECL should be implemented using TOA_EXTERN_IMPL in the .c file for the feature, e.g. TOA_EXTERN_IMPL(void, tmd_process_command, (uint8_t *data, uint8_t datalen)) { // Do stuff here }
  3. Each function declared with TOA_EXTERN_DECL should be linked in the feature's register function with TOA_EXTERN_LINK .
#define TOA_EXTERN_IMPL ( ret,
fname,
args
)
Value:
ret (*fname)args = 0; \
static ret fname ## _linked args

Define an externally-visible function implementation.

Enumeration Type Documentation

enum NOTES

Enumerate notes from C0 to B9

Tile songs are created as a sequence of pairs, (note, duration). Each value in the pair is one byte. A song ends with the pair (REST, REST).

enum TOA_ERROR_CODES

TOA Error Response Codes.

Enumerator
TOA_RSP_ERROR_SECURITY 
 Error Code sent by TOA Server when required security level for the command is not met (like authentication)

Format:

TOA_RSP_ERROR_SECURITY Code The TOA_CMD that failed
1 Byte 1 Byte
TOA_RSP_ERROR_UNSUPPORTED 
 Error Code sent by TOA Server when an unsupported TOA Command is received

Format:

TOA_RSP_ERROR_UNSUPPORTED Code The TOA_CMD that failed
1 Byte 1 Byte
TOA_RSP_ERROR_PARAMETERS 
 Error Code sent by TOA Server when a TOA Command with wrong parameters is received

Format:

TOA_RSP_ERROR_PARAMETERS Code The TOA_CMD that failed
1 Byte 1 Byte
TOA_RSP_ERROR_DROPPED_RSP 
 Error Code sent by TOA Server when 1 or more Responses were dropped, most likely due to an overflow.<br>

The Client should close the connection when this happens. Format:

TOA_RSP_ERROR_DROPPED_RSP Code The first TOA_RSP that was dropped
1 Byte 1 Byte
TOA_RSP_ERROR_NO_CID_AVAILABLE 
 Error Code sent by a TOA Server when there are no CIDs available for allocation.

Format:

TOA_RSP_ERROR_NO_CID_AVAILABLE TOA_CMD_OPEN_CHANNEL
1 Byte 1 Byte
TOA_RSP_ERROR_AUTHORIZATION 
 Error Code sent by a TOA Server when the required authorization level for the command is not met

Format:

TOA_RSP_ERROR_AUTHORIZATION Code The TOA_CMD that failed The required Authorization Type
1 Byte 1 Byte 1 Byte (value 1 for Button Press)
TOA_RSP_SERVICE_UNAVAILABLE 
 Error Code sent by a TOA Server when the required service is unavailable (i.e. user trigger)

Format:

TOA_RSP_SERVICE_UNAVAILABLE Code The TOA_CMD that failed
1 Byte 1 Byte
enum TOA_FEATURE_ERROR_CODES

TOA feature error codes. Any feature which uses these error codes will return the error in a standard format. This format is:

TOA Response Error Response Offending Command Error Code Additional Payload
1 Byte 1 Byte 1 Byte 1 Byte Varies. Up to TOA_MPS - 4 bytes.

Example 1: Say a TOFU_CTL_CMD_RESUME command is sent at a bad time. Then, the Tile would respond with

TOA_RSP_TOFU_CTL TOFU_CTL_RSP_ERROR TOFU_CTL_CMD_RESUME TOA_ERROR_INVALID_STATE
1 Byte 1 Byte 1 Byte 1 Byte
Enumerator
TOA_ERROR_OK

This code is used when there's no error

TOA_ERROR_UNSUPPORTED

This code is used when the given command is not supported

TOA_ERROR_PARAMETERS

This code is used when the parameters to the command are invalid

TOA_ERROR_SECURITY

This code is used when the app has insufficient security privileges to execute the given command

TOA_ERROR_INVALID_STATE

This code is used when the given command cannot be executed in the current state of the Tile

TOA_ERROR_MEM_READ

This code is used when a memory read fail

TOA_ERROR_MEM_WRITE

This code is used when a memory write fails

TOA_ERROR_DATA_LENGTH

This code is used when a received data block is not the expected size

TOA_ERROR_INVALID_SIZE

This code is used when the app requests to write data of inappropriate size

TOA_ERROR_SIGNATURE

This code is used when a signature check fails

TOA_ERROR_CRC

This code is used when a CRC check fails

TOA_ERROR_CRC2

This code is used when there are multiple CRC checks

TOA_ERROR_HASH

This code is used when a hash check fails

TOA_ERROR_PRODUCT_HEADER

This code is used when the product header is invalid. If this happens, the Tile is in a very bad state.

TOA_ERROR_IMAGE_HEADER

This code is used when a received image header is invalid

TOA_ERROR_SAME_IMAGE

This code is used when the image to send matches the image already on the Tile

TOA_ERROR_INVALID_DATA

This code is used when the data sent to the Tile is invalid

TOA_ERROR_MEM_ERASE

This code is used when a memory erase fails

TOA_ERROR_RESOURCE_IN_USE

This code is used when there is an attempt to access a resource in use by someone else

Function Documentation

static uint16_t RDLE16 ( const uint8_t * a )
inline static

Message unpacking helpers.

Convert little-Endian uint8_t array to integer.

void song_begin_done ( uint8_t error )

Call when the song programming begin command has completed.

NOTE: Only required if TPS is supported.

void song_block_done ( uint8_t error )

Call when the song programming block ready command has completed. tileSongBuffer is expected to contain the valid song block data when this function is called. The reason is TileLib will check the CRC again in this function. This allows the application to implement a read back of the data from flash to verify integrity.

NOTE: Only required if TPS is supported.

void song_complete_done ( uint8_t error )

Call when the song programming complete command has completed.

NOTE: Only required if TPS is supported.

void song_quality ( uint8_t quality )

Report song quality to Tile Lib.

NOTE: This is optional.

Parameters
[in] quality The of the song. In order to work with the Tile quality detection, this should rougly correspond to millivolt drop on the battery when a note is played.
int tile_song_register ( struct tile_song_module * module )

Register the song module.

static void WRLE16 ( uint8_t * a ,
const uint16_t x
)
inline static

Write an integer into a byte array, in little-Endian.