Tile Over-the-air API

nRF5 SDK v17.0.2
Modules | Data Structures | Macros | Enumerations | Functions

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

Modules

Tile Library API
Tile Library Api.
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 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 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 TILE_SONG_DURATION {
TILE_SONG_DURATION_NOPLAY = 0x00,
TILE_SONG_DURATION_ONCE = 0xFE,
TILE_SONG_DURATION_FOREVER = 0xFF
}
TILE_SONG_DURATION Duration to play the Tile Song for. The duration is in seconds and here are special values. More...
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

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 tile_service_init (void)
Initialize Tile service. Store advertising data configuration from the application. More...
void tile_on_ble_evt ( ble_evt_t const *p_evt, void *p_context)
void tile_get_adv_params (uint16_t *uuid, uint16_t *interval)
uint16_t tile_get_adv_uuid (void)

Detailed Description

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

Tile Song Module.

Macro Definition Documentation

#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

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 TILE_SONG_DURATION

TILE_SONG_DURATION Duration to play the Tile Song for. The duration is in seconds and here are special values.

Enumerator
TILE_SONG_DURATION_NOPLAY

Do not play anything

TILE_SONG_DURATION_ONCE

Play the Song just once

TILE_SONG_DURATION_FOREVER

Play the song forever, till someone stops it

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

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 tile_service_init ( void )

Initialize Tile service. Store advertising data configuration from the application.

Note
This function must be called before ble_advertising_init
int tile_song_register ( struct tile_song_module * module )

Register the song module.