nRF5 SDK v17.1.0
Modules | Data Structures | Macros | Enumerations | Functions
Tile Over-the-air API

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

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

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

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.


Documentation feedback | Developer Zone | Subscribe | Updated