tile_toa_module.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334
  1. /**
  2. * NOTICE
  3. *
  4. * Copyright 2020 Tile Inc. All Rights Reserved.
  5. * All code or other information included in the accompanying files ("Tile Source Material")
  6. * is PROPRIETARY information of Tile Inc. ("Tile") and access and use of the Tile Source Material
  7. * is subject to these terms. The Tile Source Material may only be used for demonstration purposes,
  8. * and may not be otherwise distributed or made available to others, including for commercial purposes.
  9. * Without limiting the foregoing , you understand and agree that no production use
  10. * of the Tile Source Material is allowed without a Tile ID properly obtained under a separate
  11. * agreement with Tile.
  12. * You also understand and agree that Tile may terminate the limited rights granted under these terms
  13. * at any time in its discretion.
  14. * All Tile Source Material is provided AS-IS without warranty of any kind.
  15. * Tile does not warrant that the Tile Source Material will be error-free or fit for your purposes.
  16. * Tile will not be liable for any damages resulting from your use of or inability to use
  17. * the Tile Source Material.
  18. *
  19. * Support: firmware_support@tile.com
  20. */
  21. /** @file tile_toa_module.h
  22. ** @brief Tile Over-the-air API module
  23. */
  24. #ifndef TILE_TOA_MODULE_H_
  25. #define TILE_TOA_MODULE_H_
  26. #include <stdint.h>
  27. #include <stdbool.h>
  28. /**
  29. * @defgroup toa_module Tile Over-the-air API module
  30. * @{
  31. * @ingroup TOA
  32. */
  33. /**
  34. * @brief TOA Max Payload Size.
  35. * This is the maximum Payload that can be carried by a TOA Command or Response.
  36. * It excludes the TOA_CMD/TOA_RSP Code and excludes the MIC.
  37. */
  38. #define TOA_MPS 14
  39. #define TILE_SESSION_KEY_LEN 16
  40. /**
  41. * Session information for a TOA channel
  42. */
  43. struct toa_channel_tag
  44. {
  45. uint8_t session_key[TILE_SESSION_KEY_LEN];
  46. uint32_t nonceA;
  47. uint32_t nonceT;
  48. uint16_t state;
  49. uint16_t check_delay;
  50. uint16_t ack_delay;
  51. };
  52. typedef struct toa_channel_tag toa_channel_t; //!< Structure containing session information for a TOA channel
  53. /**
  54. * Tile Over-the-air API module.
  55. *
  56. * This module is used by Tile Lib in order to implement its over-the-air
  57. * protocol.
  58. */
  59. struct tile_toa_module
  60. {
  61. /**
  62. * Tile ID -- 64-bit identifier for Tile Nodes.
  63. * Example: {0x1a, 0x95, 0xd9, 0x97, 0xf0, 0xf2, 0x66, 0x07}.
  64. */
  65. uint8_t* tile_id;
  66. /**
  67. * Auth Key -- 128-bit master key for Tile Nodes.
  68. * Example: {0x14, 0x27, 0xe3, 0x03, 0xa2, 0x51, 0xc5, 0xb5, 0x07, 0x2a, 0xa9, 0x81, 0xa9, 0x42, 0x8a, 0x43}.
  69. */
  70. uint8_t* auth_key;
  71. /**
  72. * Pointer to an array of @ref toa_channel_t structures. It is recommended
  73. * to use 4 channels, but if memory is a constraint then the number can be
  74. * decreased.
  75. */
  76. toa_channel_t* channels;
  77. /**
  78. * Pointer to a buffer for queueing TOA messages.
  79. */
  80. uint8_t* queue;
  81. /**
  82. * Size of buffer used for TOA queue. Recommended to be at least size
  83. * 100 for one channel, and add 40 for each additional channel.
  84. */
  85. uint16_t queue_size;
  86. /**
  87. * Number of channels contained in the channels array.
  88. */
  89. uint8_t num_channels;
  90. /**
  91. * Diagnostic info: counts the mic failures
  92. */
  93. uint8_t* mic_failure_count;
  94. /**
  95. * Diagnostic info: counts the authentication failures
  96. */
  97. uint8_t* auth_failure_count;
  98. /**
  99. * Diagnostic info: counts the Number of successfull TOA Channel Open (with a successfull authentication)
  100. */
  101. uint32_t* channel_open_count;
  102. /**
  103. * Diagnostic info: counts the number of TOA Authenticate Commands received
  104. */
  105. uint32_t* authenticate_count;
  106. /**
  107. * Diagnostic info: counts the number of TOA channel close triggered by TKA
  108. */
  109. uint16_t* tka_closed_channel_count;
  110. /**
  111. * Send a TOA Response.
  112. * @param[in] data: Pointer to the TOA Response.
  113. * @param[in] len: Length of the TOA Response.
  114. */
  115. int (*send_response)(uint8_t *data, uint16_t len);
  116. /**
  117. * Optional callback called when an association is happenning (can be set to NULL).
  118. * It is mostly needed for Commissioning Tiles using an Interim TileID, Key.
  119. *
  120. * @param[in] tile_id: 8-byte unique tile identification code.
  121. * @param[in] tile_auth_key: 16-byte authentication key.
  122. * @param[in] authorization_type: Pointer to authorization type.
  123. *
  124. * @param[out] authorization_type: set to the right value if an authorization is required (ie 1 for Button Press).
  125. *
  126. * @return See @ref TILE_ERROR_CODES.
  127. */
  128. int (*associate)(uint8_t* tile_id, uint8_t* tile_auth_key, uint8_t* authorization_type);
  129. };
  130. /** \ingroup TOA
  131. * @brief TOA feature error codes. Any feature which uses these error
  132. * codes will return the error in a standard format. This format is:
  133. *
  134. * TOA Response | Error Response | Offending Command | Error Code | Additional Payload
  135. * -------------|----------------|-------------------|------------|-------------------
  136. * 1 Byte | 1 Byte | 1 Byte | 1 Byte | Varies. Up to TOA_MPS - 4 bytes.
  137. *
  138. * Example 1: Say a TOFU_CTL_CMD_RESUME command is sent at a bad time. Then, the Tile would
  139. * respond with
  140. * TOA_RSP_TOFU_CTL | TOFU_CTL_RSP_ERROR | TOFU_CTL_CMD_RESUME | TOA_ERROR_INVALID_STATE
  141. * ------------------|----------------|---------------------|--------------------
  142. * 1 Byte | 1 Byte | 1 Byte | 1 Byte
  143. *
  144. */
  145. enum TOA_FEATURE_ERROR_CODES
  146. {
  147. TOA_ERROR_OK = 0x00,
  148. /**< This code is used when there's no error */
  149. TOA_ERROR_UNSUPPORTED = 0x01,
  150. /**< This code is used when the given command is not supported */
  151. TOA_ERROR_PARAMETERS = 0x02,
  152. /**< This code is used when the parameters to the command are invalid */
  153. TOA_ERROR_SECURITY = 0x03,
  154. /**< This code is used when the app has insufficient security privileges
  155. * to execute the given command */
  156. TOA_ERROR_INVALID_STATE = 0x04,
  157. /**< This code is used when the given command cannot be executed in
  158. * the current state of the Tile */
  159. TOA_ERROR_MEM_READ = 0x05,
  160. /**< This code is used when a memory read fail */
  161. TOA_ERROR_MEM_WRITE = 0x06,
  162. /**< This code is used when a memory write fails */
  163. TOA_ERROR_DATA_LENGTH = 0x07,
  164. /**< This code is used when a received data block is not the expected size */
  165. TOA_ERROR_INVALID_SIZE = 0x08,
  166. /**< This code is used when the app requests to write data of inappropriate size */
  167. TOA_ERROR_SIGNATURE = 0x09,
  168. /**< This code is used when a signature check fails */
  169. TOA_ERROR_CRC = 0x0A,
  170. /**< This code is used when a CRC check fails */
  171. TOA_ERROR_CRC2 = 0x0B,
  172. /**< This code is used when there are multiple CRC checks */
  173. TOA_ERROR_HASH = 0x0C,
  174. /**< This code is used when a hash check fails */
  175. TOA_ERROR_PRODUCT_HEADER = 0x0D,
  176. /**< This code is used when the product header is invalid. If this happens,
  177. * the Tile is in a very bad state. */
  178. TOA_ERROR_IMAGE_HEADER = 0x0E,
  179. /**< This code is used when a received image header is invalid */
  180. TOA_ERROR_SAME_IMAGE = 0x0F,
  181. /**< This code is used when the image to send matches the image already on the Tile */
  182. TOA_ERROR_INVALID_DATA = 0x10,
  183. /**< This code is used when the data sent to the Tile is invalid */
  184. TOA_ERROR_MEM_ERASE = 0x11,
  185. /**< This code is used when a memory erase fails */
  186. TOA_ERROR_RESOURCE_IN_USE = 0x12,
  187. /**< This code is used when there is an attempt to access a resource in use by someone else */
  188. };
  189. /** \ingroup TOA
  190. * @brief TOA Error Response Codes
  191. */
  192. enum TOA_ERROR_CODES
  193. {
  194. TOA_RSP_ERROR_SECURITY = 0x01,
  195. /**< Error Code sent by TOA Server when required security level for the command is not met (like authentication)
  196. Format:
  197. @ref TOA_RSP_ERROR_SECURITY Code | The TOA_CMD that failed
  198. ---------------------------------|-----------------------------
  199. 1 Byte | 1 Byte
  200. */
  201. TOA_RSP_ERROR_UNSUPPORTED = 0x02,
  202. /**< Error Code sent by TOA Server when an unsupported TOA Command is received
  203. Format:
  204. @ref TOA_RSP_ERROR_UNSUPPORTED Code | The TOA_CMD that failed
  205. ------------------------------------|-----------------------------
  206. 1 Byte | 1 Byte
  207. */
  208. TOA_RSP_ERROR_PARAMETERS = 0x03,
  209. /**< Error Code sent by TOA Server when a TOA Command with wrong parameters is received
  210. Format:
  211. @ref TOA_RSP_ERROR_PARAMETERS Code | The TOA_CMD that failed
  212. -----------------------------------|------------------------------
  213. 1 Byte | 1 Byte
  214. */
  215. TOA_RSP_ERROR_DROPPED_RSP = 0x04,
  216. /**< Error Code sent by TOA Server when 1 or more Responses were dropped, most likely due to an overflow.<br>
  217. The Client should close the connection when this happens.
  218. Format:
  219. @ref TOA_RSP_ERROR_DROPPED_RSP Code | The first TOA_RSP that was dropped
  220. -------------------------------------|----------------------------------------
  221. 1 Byte | 1 Byte
  222. */
  223. TOA_RSP_ERROR_NO_CID_AVAILABLE = 0x05,
  224. /**< Error Code sent by a TOA Server when there are no CIDs available for allocation.
  225. Format:
  226. @ref TOA_RSP_ERROR_NO_CID_AVAILABLE | TOA_CMD_OPEN_CHANNEL
  227. ------------------------------------|--------------------------
  228. 1 Byte | 1 Byte
  229. */
  230. TOA_RSP_ERROR_AUTHORIZATION = 0x06,
  231. /**< Error Code sent by a TOA Server when the required authorization level for the command is not met
  232. Format:
  233. @ref TOA_RSP_ERROR_AUTHORIZATION Code | The TOA_CMD that failed | The required Authorization Type
  234. --------------------------------------|------------------------------|--------------------------------
  235. 1 Byte | 1 Byte | 1 Byte (value 1 for Button Press)
  236. */
  237. TOA_RSP_SERVICE_UNAVAILABLE = 0x07,
  238. /**< Error Code sent by a TOA Server when the required service is unavailable (i.e. user trigger)
  239. Format:
  240. @ref TOA_RSP_SERVICE_UNAVAILABLE Code | The TOA_CMD that failed
  241. --------------------------------------|-----------------------------
  242. 1 Byte | 1 Byte
  243. */
  244. };
  245. /**
  246. * Register TOA module.
  247. */
  248. int tile_toa_register(struct tile_toa_module *module);
  249. /**
  250. ****************************************************************************************
  251. * @brief The underlying TOA transport is ready.
  252. * This is the case when TOA_RSP channel was enabled for notifications or indications.
  253. *
  254. * @param[in] ready 1 for ready, 0 for not ready.
  255. *
  256. ****************************************************************************************
  257. */
  258. void tile_toa_transport_ready(bool ready);
  259. /**
  260. ****************************************************************************************
  261. * @brief A TOA response was successfully sent to the TOA Client (and an other one can be sent).
  262. *
  263. ****************************************************************************************
  264. */
  265. void tile_toa_response_sent_ok(void);
  266. /**
  267. ****************************************************************************************
  268. * @brief An TOA Commands was received.
  269. *
  270. * @param[in] data pointer to data.
  271. * @param[in] datalen number of bytes of data.
  272. *
  273. ****************************************************************************************
  274. */
  275. void tile_toa_command_received(const uint8_t* data, uint8_t datalen);
  276. /**
  277. ****************************************************************************************
  278. * @brief Send an Authorized Notification.
  279. *
  280. * @param[in] authorization_type The type of authorization (ie Button press).
  281. * @param[in] authorization_time The time for which the authorization is valid.
  282. *
  283. ****************************************************************************************
  284. */
  285. int tile_toa_authorized(uint8_t authorization_type, uint16_t authorization_time);
  286. /** @} */
  287. #endif