| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334 | /** * NOTICE *  * Copyright 2020 Tile Inc.  All Rights Reserved. * All code or other information included in the accompanying files ("Tile Source Material") * is PROPRIETARY information of Tile Inc. ("Tile") and access and use of the Tile Source Material * is subject to these terms. The Tile Source Material may only be used for demonstration purposes, * and may not be otherwise distributed or made available to others, including for commercial purposes. * Without limiting the foregoing , you understand and agree that no production use * of the Tile Source Material is allowed without a Tile ID properly obtained under a separate * agreement with Tile. * You also understand and agree that Tile may terminate the limited rights granted under these terms * at any time in its discretion. * All Tile Source Material is provided AS-IS without warranty of any kind. * Tile does not warrant that the Tile Source Material will be error-free or fit for your purposes. * Tile will not be liable for any damages resulting from your use of or inability to use * the Tile Source Material. * * Support: firmware_support@tile.com *//** @file tile_toa_module.h ** @brief Tile Over-the-air API module */#ifndef TILE_TOA_MODULE_H_#define TILE_TOA_MODULE_H_#include <stdint.h>#include <stdbool.h>/** * @defgroup toa_module Tile Over-the-air API module * @{ * @ingroup TOA *//** * @brief TOA Max Payload Size. * This is the maximum Payload that can be carried by a TOA Command or Response. * It excludes the TOA_CMD/TOA_RSP Code and excludes the MIC. */#define TOA_MPS  14#define TILE_SESSION_KEY_LEN 16/** * Session information for a TOA channel */struct toa_channel_tag{  uint8_t session_key[TILE_SESSION_KEY_LEN];  uint32_t nonceA;  uint32_t nonceT;  uint16_t state;  uint16_t check_delay;  uint16_t ack_delay;};typedef struct toa_channel_tag toa_channel_t;   //!< Structure containing session information for a TOA channel/** * Tile Over-the-air API module. * * This module is used by Tile Lib in order to implement its over-the-air * protocol. */struct tile_toa_module {  /**   * Tile ID -- 64-bit identifier for Tile Nodes.    *           Example: {0x1a, 0x95, 0xd9, 0x97, 0xf0, 0xf2, 0x66, 0x07}.   */  uint8_t*  tile_id;  /**   * Auth Key -- 128-bit master key for Tile Nodes.    *           Example: {0x14, 0x27, 0xe3, 0x03, 0xa2, 0x51, 0xc5, 0xb5, 0x07, 0x2a, 0xa9, 0x81, 0xa9, 0x42, 0x8a, 0x43}.   */  uint8_t*  auth_key;    /**   * Pointer to an array of @ref toa_channel_t structures. It is recommended   * to use 4 channels, but if memory is a constraint then the number can be   * decreased.   */  toa_channel_t*  channels;    /**   * Pointer to a buffer for queueing TOA messages.   */  uint8_t*  queue;  /**   * Size of buffer used for TOA queue. Recommended to be at least size   * 100 for one channel, and add 40 for each additional channel.   */  uint16_t  queue_size;  /**   * Number of channels contained in the channels array.   */  uint8_t num_channels;  /**  * Diagnostic info: counts the mic failures   */  uint8_t*  mic_failure_count;    /**  * Diagnostic info: counts the authentication failures   */  uint8_t*  auth_failure_count;    /**  * Diagnostic info: counts the Number of successfull TOA Channel Open (with a successfull authentication)   */  uint32_t* channel_open_count;    /**  * Diagnostic info: counts the number of TOA Authenticate Commands received   */  uint32_t* authenticate_count;    /**  * Diagnostic info: counts the number of TOA channel close triggered by TKA   */  uint16_t* tka_closed_channel_count;  /**   * Send a TOA Response.   * @param[in]  data:    Pointer to the TOA Response.   * @param[in]  len:     Length of the TOA Response.   */  int (*send_response)(uint8_t *data, uint16_t len);  /**   * Optional callback called when an association is happenning (can be set to NULL).   *  It is mostly needed for Commissioning Tiles using an Interim TileID, Key.   *   * @param[in]  tile_id: 8-byte unique tile identification code.   * @param[in]  tile_auth_key: 16-byte authentication key.   * @param[in]  authorization_type:  Pointer to authorization type.   *   * @param[out] authorization_type:  set to the right value if an authorization is required (ie 1 for Button Press).   *   * @return See @ref TILE_ERROR_CODES.   */  int (*associate)(uint8_t* tile_id, uint8_t* tile_auth_key, uint8_t* authorization_type);};/** \ingroup TOA * @brief 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 * */enum TOA_FEATURE_ERROR_CODES{  TOA_ERROR_OK              = 0x00,  /**< This code is used when there's no error */  TOA_ERROR_UNSUPPORTED     = 0x01,  /**< This code is used when the given command is not supported */  TOA_ERROR_PARAMETERS      = 0x02,  /**< This code is used when the parameters to the command are invalid */  TOA_ERROR_SECURITY        = 0x03,  /**< This code is used when the app has insufficient security privileges   * to execute the given command */  TOA_ERROR_INVALID_STATE   = 0x04,  /**< This code is used when the given command cannot be executed in   * the current state of the Tile */  TOA_ERROR_MEM_READ        = 0x05,  /**< This code is used when a memory read fail */  TOA_ERROR_MEM_WRITE       = 0x06,  /**< This code is used when a memory write fails */  TOA_ERROR_DATA_LENGTH     = 0x07,  /**< This code is used when a received data block is not the expected size */  TOA_ERROR_INVALID_SIZE    = 0x08,  /**< This code is used when the app requests to write data of inappropriate size */  TOA_ERROR_SIGNATURE       = 0x09,  /**< This code is used when a signature check fails */  TOA_ERROR_CRC             = 0x0A,  /**< This code is used when a CRC check fails */  TOA_ERROR_CRC2            = 0x0B,  /**< This code is used when there are multiple CRC checks */  TOA_ERROR_HASH            = 0x0C,  /**< This code is used when a hash check fails */  TOA_ERROR_PRODUCT_HEADER  = 0x0D,  /**< 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    = 0x0E,  /**< This code is used when a received image header is invalid */  TOA_ERROR_SAME_IMAGE      = 0x0F,  /**< This code is used when the image to send matches the image already on the Tile */  TOA_ERROR_INVALID_DATA    = 0x10,  /**< This code is used when the data sent to the Tile is invalid */  TOA_ERROR_MEM_ERASE       = 0x11,  /**< This code is used when a memory erase fails */  TOA_ERROR_RESOURCE_IN_USE = 0x12,  /**< This code is used when there is an attempt to access a resource in use by someone else */};/** \ingroup TOA * @brief TOA Error Response Codes */enum TOA_ERROR_CODES{  TOA_RSP_ERROR_SECURITY    = 0x01,  /**< Error Code sent by TOA Server when required security level for the command is not met (like authentication)  Format:  @ref TOA_RSP_ERROR_SECURITY Code | The TOA_CMD that failed  ---------------------------------|-----------------------------  1 Byte                           |  1 Byte  */  TOA_RSP_ERROR_UNSUPPORTED = 0x02,  /**< Error Code sent by TOA Server when an unsupported TOA Command is received  Format:  @ref TOA_RSP_ERROR_UNSUPPORTED Code | The TOA_CMD that failed  ------------------------------------|-----------------------------  1 Byte                              |  1 Byte  */  TOA_RSP_ERROR_PARAMETERS  = 0x03,  /**< Error Code sent by TOA Server when a TOA Command with wrong parameters is received  Format:    @ref TOA_RSP_ERROR_PARAMETERS Code | The TOA_CMD that failed  -----------------------------------|------------------------------  1 Byte                             |  1 Byte  */  TOA_RSP_ERROR_DROPPED_RSP = 0x04,  /**< 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:  @ref TOA_RSP_ERROR_DROPPED_RSP Code  | The first TOA_RSP that was dropped  -------------------------------------|----------------------------------------  1 Byte                               |  1 Byte  */  TOA_RSP_ERROR_NO_CID_AVAILABLE = 0x05,  /**< Error Code sent by a TOA Server when there are no CIDs available for allocation.  Format:  @ref TOA_RSP_ERROR_NO_CID_AVAILABLE | TOA_CMD_OPEN_CHANNEL  ------------------------------------|--------------------------  1 Byte                              | 1 Byte  */    TOA_RSP_ERROR_AUTHORIZATION = 0x06,  /**< Error Code sent by a TOA Server when the required authorization level for the command is not met  Format:  @ref 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 = 0x07,  /**< Error Code sent by a TOA Server when the required service is unavailable (i.e. user trigger)  Format:  @ref TOA_RSP_SERVICE_UNAVAILABLE Code | The TOA_CMD that failed  --------------------------------------|-----------------------------  1 Byte                                |  1 Byte  */};/** * Register TOA module. */int tile_toa_register(struct tile_toa_module *module);/** **************************************************************************************** * @brief The underlying TOA transport is ready. *  This is the case when TOA_RSP channel was enabled for notifications or indications. * * @param[in] ready       1 for ready, 0 for not ready. * **************************************************************************************** */void tile_toa_transport_ready(bool ready);/** **************************************************************************************** * @brief A TOA response was successfully sent to the TOA Client (and an other one can be sent). * **************************************************************************************** */void tile_toa_response_sent_ok(void);/** **************************************************************************************** * @brief An TOA Commands was received. * * @param[in] data       pointer to data. * @param[in] datalen    number of bytes of data. * **************************************************************************************** */void tile_toa_command_received(const uint8_t* data, uint8_t datalen);/** **************************************************************************************** * @brief Send an Authorized Notification. * * @param[in] authorization_type    The type of authorization (ie Button press). * @param[in] authorization_time    The time for which the authorization is valid. * **************************************************************************************** */int tile_toa_authorized(uint8_t authorization_type, uint16_t authorization_time);/** @} */#endif
 |