nRF5 SDK v16.0.0
Modules | Data Structures | Macros | Enumerations | Functions | Variables
Tile Over-the-air API
External BLE Libraries

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.

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)
inlinestatic

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]qualityThe 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 
)
inlinestatic

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

Documentation feedback | Developer Zone | Subscribe | Updated