/* Copyright (c) 2014, Nordic Semiconductor ASA * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in all * copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. */ /** * @file * * @defgroup aci aci * @{ * @ingroup lib * * @brief Definitions for the ACI (Application Control Interface) * @remarks * * Flow control from application mcu to nRF8001 * * Data flow control: * The flow control is credit based and the credit is initally given using the "device started" event. * A credit of more than 1 is given to the application mcu. * These credits are used only after the "ACI Connected Event" is sent to the application mcu. * * every send_data that is used decrements the credit available by 1. This is to be tracked by the application mcu. * When the credit available reaches 0, the application mcu shall not send any more send_data. * Credit is returned using the "credit event", this returned credit can then be used to send more send_data. * This flow control is not necessary and not available for Broadcast. * The entire credit available with the external mcu expires when a "disconnected" event arrives. * * Command flow control: * When a command is sent over the ACI, the next command shall not be sent until after a response * for the command sent has arrived. * */ #ifndef ACI_H__ #define ACI_H__ /** * Define an _aci_packed_ macro we can use in structure and enumerated type * declarations so that the types are sized consistently across different * platforms. In particular Arduino platforms using the GCC compiler and the * Nordic processors using the Keil compiler. * * It's really the GNU compiler platforms that need a special keyword to get * tight packing of values. On GNU platforms we can use the keyword: * __attribute__((__packed__)) * The thing is that while this keyword does the right thing with old and new * versions of the gcc (C) compiler it only works right with g++ (C++) compiler * versions that are version 4 or newer. */ #ifdef __GNUC__ # if __GNUC__ >= 4 # define _aci_packed_ __attribute__((__packed__)) # else # error "older g++ versions don't handle packed attribute in typedefs" # endif #else # define _aci_packed_ #endif /* * Define a macro that compares the size of the first parameter to the integer * value of the second parameter. If they do not match, a compile time error * for negative array size occurs (even gnu chokes on negative array size). * * This compare is done by creating a typedef for an array. No variables are * created and no memory is consumed with this check. The created type is * used for checking only and is not for use by any other code. The value * of 10 in this macro is arbitrary, it just needs to be a value larger * than one to result in a positive number for the array size. */ #define ACI_ASSERT_SIZE(x,y) typedef char x ## _assert_size_t[-1+10*(sizeof(x) == (y))] /** * @def ACI_VERSION * @brief Current ACI protocol version. 0 means a device that is not yet released. * A numer greater than 0 refers to a specific ACI version documented and released. * The ACI consists of the ACI commands, ACI events and error codes. */ #define ACI_VERSION (0x02) /** * @def BTLE_DEVICE_ADDRESS_SIZE * @brief Size in bytes of a Bluetooth Address */ #define BTLE_DEVICE_ADDRESS_SIZE (6) /** * @def ACI_PACKET_MAX_LEN * @brief Maximum length in bytes of a full ACI packet, including length prefix, opcode and payload */ #define ACI_PACKET_MAX_LEN (32) /** * @def ACI_ECHO_DATA_MAX_LEN * @brief Maximum length in bytes of the echo data portion */ #define ACI_ECHO_DATA_MAX_LEN (ACI_PACKET_MAX_LEN - 3) /** * @def ACI_DEVICE_MAX_PIPES * @brief Maximum number of ACI pipes */ #define ACI_DEVICE_MAX_PIPES (62) /** * @def ACI_PIPE_TX_DATA_MAX_LEN * @brief Maximum length in bytes of a transmission data pipe packet */ #define ACI_PIPE_TX_DATA_MAX_LEN (20) /** * @def ACI_PIPE_RX_DATA_MAX_LEN * @brief Maximum length in bytes of a reception data pipe packet */ #define ACI_PIPE_RX_DATA_MAX_LEN (22) /** * @def ACI_GAP_DEVNAME_MAX_LEN * @brief Maximum length in bytes of the GAP device name */ #define ACI_GAP_DEVNAME_MAX_LEN (20) /** * @def ACI_AD_PACKET_MAX_LEN * @brief Maximum length in bytes of an AD packet */ #define ACI_AD_PACKET_MAX_LEN (31) /** * @def ACI_AD_PACKET_MAX_USER_LEN * @brief Maximum usable length in bytes of an AD packet */ #define ACI_AD_PACKET_MAX_USER_LEN (31 - 3) /** * @def ACI_PIPE_INVALID * @brief Invalid pipe number */ #define ACI_PIPE_INVALID (0xFF) /** * @enum aci_pipe_store_t * @brief Storage type identifiers: local and remote */ typedef enum { ACI_STORE_INVALID = 0x0, ACI_STORE_LOCAL= 0x01, ACI_STORE_REMOTE= 0x02 } _aci_packed_ aci_pipe_store_t; /** * @enum aci_pipe_type_t * @brief Pipe types */ typedef enum { ACI_TX_BROADCAST = 0x0001, ACI_TX = 0x0002, ACI_TX_ACK = 0x0004, ACI_RX = 0x0008, ACI_RX_ACK = 0x0010, ACI_TX_REQ = 0x0020, ACI_RX_REQ = 0x0040, ACI_SET = 0x0080, ACI_TX_SIGN = 0x0100, ACI_RX_SIGN = 0x0200, ACI_RX_ACK_AUTO = 0x0400 } _aci_packed_ aci_pipe_type_t; ACI_ASSERT_SIZE(aci_pipe_type_t, 2); /** * @enum aci_bd_addr_type_t * @brief Bluetooth Address types */ typedef enum { ACI_BD_ADDR_TYPE_INVALID = 0x00, ACI_BD_ADDR_TYPE_PUBLIC = 0x01, ACI_BD_ADDR_TYPE_RANDOM_STATIC = 0x02, ACI_BD_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE = 0x03, ACI_BD_ADDR_TYPE_RANDOM_PRIVATE_UNRESOLVABLE = 0x04 } _aci_packed_ aci_bd_addr_type_t; /** * @enum aci_device_output_power_t * @brief Radio output power levels */ typedef enum { ACI_DEVICE_OUTPUT_POWER_MINUS_18DBM = 0x00, /**< Output power set to -18dBm */ ACI_DEVICE_OUTPUT_POWER_MINUS_12DBM = 0x01, /**< Output power set to -12dBm */ ACI_DEVICE_OUTPUT_POWER_MINUS_6DBM = 0x02, /**< Output power set to -6dBm */ ACI_DEVICE_OUTPUT_POWER_0DBM = 0x03 /**< Output power set to 0dBm - DEFAULT*/ } _aci_packed_ aci_device_output_power_t; /** * @enum aci_device_operation_mode_t * @brief Device operation modes */ typedef enum { ACI_DEVICE_INVALID =0x00, ACI_DEVICE_TEST =0x01, ACI_DEVICE_SETUP =0x02, ACI_DEVICE_STANDBY =0x03, ACI_DEVICE_SLEEP =0x04 } _aci_packed_ aci_device_operation_mode_t; /** * @enum aci_disconnect_reason_t * @brief Reason enumeration for ACI_CMD_DISCONNECT */ typedef enum { ACI_REASON_TERMINATE =0x01, /**< Use this to disconnect (does a terminate request), you need to wait for the "disconnected" event */ ACI_REASON_BAD_TIMING =0x02 /*