aci.h

/* Copyright (c) 2010 Nordic Semiconductor. All Rights Reserved.
 *
 * The information contained herein is property of Nordic Semiconductor ASA.
 * Terms and conditions of usage are described in detail in NORDIC
 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
 *
 * Licensees are granted free, non-transferable use of the information. NO
 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
 * the file.
 *
 * $LastChangedRevision$
 */

/**
 * @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 "pipes 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__

/**
 * @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_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_pipe_type_t;

/**
 * @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_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_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_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 /*<Use this to disconnect and inform the peer, that the timing on the link is not acceptable for the device, you need to wait for the "disconnected" event */
} aci_disconnect_reason_t;

/**
 * @enum aci_test_mode_change_t
 * @brief Device test mode control
 */
typedef enum
{
  ACI_TEST_MODE_DTM_UART    = 0x01,
  ACI_TEST_MODE_DTM_ACI     = 0x02,
  ACI_TEST_MODE_EXIT        = 0xFF
  
} aci_test_mode_change_t;

/**
 * @enum aci_permissions_t
 * @brief Data store permissions
 */
typedef enum 
{
  ACI_PERMISSIONS_NONE               =0x00,
  ACI_PERMISSIONS_LINK_AUTHENTICATED =0x01
} aci_permissions_t;

/**
 * @def ACI_VS_UUID_128_MAX_COUNT
 * @brief Maximum number of 128-bit Vendor Specific 
 *        UUIDs that can be set
 */
#define ACI_VS_UUID_128_MAX_COUNT  64 /** #0 reserved for invalid, #1 reservered for BT SIG and a maximum of 1024 bytes (16*64) */ 

/**
 * @struct aci_ll_conn_params_t
 * @brief Link Layer Connection Parameters
 */
typedef struct
{
  uint16_t min_conn_interval;   /**< Minimum connection interval requested from peer */
    #define ACI_PPCP_MIN_CONN_INTVL_NONE  0xFFFF
    #define ACI_PPCP_MIN_CONN_INTVL_MIN   0x0006
    #define ACI_PPCP_MIN_CONN_INTVL_MAX   0x0C80
  uint16_t max_conn_interval;   /**< Maximum connection interval requested from peer */
    #define ACI_PPCP_MAX_CONN_INTVL_NONE  0xFFFF
    #define ACI_PPCP_MAX_CONN_INTVL_MIN   0x0006
    #define ACI_PPCP_MAX_CONN_INTVL_MAX   0x0C80
  uint16_t slave_latency;       /**< Connection interval latency requested from peer */
    #define ACI_PPCP_SLAVE_LATENCY_MAX    0x03E8
  uint16_t timeout_mult;        /**< Link supervisor timeout multiplier requested from peer */
    #define ACI_PPCP_TIMEOUT_MULT_NONE    0xFFFF
    #define ACI_PPCP_TIMEOUT_MULT_MIN     0x000A
    #define ACI_PPCP_TIMEOUT_MULT_MAX     0x0C80
} aci_ll_conn_params_t;

/**
 * @def aci_gap_ppcp_t
 * @brief GAP Peripheral Preferred Connection Parameters
 */
#define aci_gap_ppcp_t aci_ll_conn_params_t

/**
 * @def ACI_AD_LOC_SVCUUID_16_MAX_COUNT
 * @brief Maximum number of 16-bit UUIDs that can
 *        be inserted in the Services tag of AD
 */
#define ACI_AD_LOC_SVCUUID_16_MAX_COUNT  5

/**
 * @def ACI_AD_LOC_SVCUUID_128_MAX_COUNT
 * @brief Maximum number of 128-bit UUIDs that can
 *        be inserted in the Services tag of AD
 */
#define ACI_AD_LOC_SVCUUID_128_MAX_COUNT  1

/**
 * @def ACI_AD_SOL_SVCUUID_16_MAX_COUNT
 * @brief Maximum number of UUIDs that can
 *        be inserted in the Solicited Services tag of AD
 */
#define ACI_AD_SOL_SVCUUID_16_MAX_COUNT  5

/**
 * @def ACI_AD_SOL_SVCUUID_128_MAX_COUNT
 * @brief Maximum number of UUIDs that can
 *        be inserted in the Solicited Services tag of AD
 */
#define ACI_AD_SOL_SVCUUID_128_MAX_COUNT  1

/**
 * @def ACI_SEC_ENCKEY_SIZE_MIN
 * @brief Minimum encryption key size
 */
#define ACI_SEC_ENCKEY_SIZE_MIN        7
/**
 * @def ACI_SEC_ENCKEY_SIZE_MAX
 * @brief Maximum encryption key size
 */
#define ACI_SEC_ENCKEY_SIZE_MAX        16
/**
 * @def ACI_CUSTOM_AD_TYPE_MAX_COUNT
 * @brief Maximum number of custom ad types
 */
#define ACI_CUSTOM_AD_TYPE_MAX_COUNT 8
/**
 * @def ACI_CUSTOM_AD_TYPE_MAX_DATA_LENGTH
 * @brief Maximum custom ad type data size
 */
#define ACI_CUSTOM_AD_TYPE_MAX_DATA_LENGTH 20

/**
 * @struct aci_tx_data_t
 * @brief Generic ACI transmit data structure
 */
typedef struct
{
  uint8_t pipe_number;
  uint8_t aci_data[ACI_PIPE_TX_DATA_MAX_LEN];
} aci_tx_data_t;

/**
 * @struct aci_rx_data_t
 * @brief Generic ACI receive data structure
 */
typedef struct
{
  uint8_t pipe_number;
  uint8_t aci_data[ACI_PIPE_RX_DATA_MAX_LEN];
} aci_rx_data_t;

/**
 * @enum aci_hw_error_t
 * @brief Hardware Error codes
 */
typedef enum
{
  ACI_HW_ERROR_NONE     = 0x00,
  ACI_HW_ERROR_FATAL    = 0x01
} aci_hw_error_t;

/**
 * @enum aci_clock_accuracy_t
 * @brief Bluetooth Low Energy Clock Accuracy
 */
typedef enum
{
  ACI_CLOCK_ACCURACY_500_PPM = 0x00,
  ACI_CLOCK_ACCURACY_250_PPM = 0x01,
  ACI_CLOCK_ACCURACY_150_PPM = 0x02,
  ACI_CLOCK_ACCURACY_100_PPM = 0x03,
  ACI_CLOCK_ACCURACY_75_PPM  = 0x04,
  ACI_CLOCK_ACCURACY_50_PPM  = 0x05,
  ACI_CLOCK_ACCURACY_30_PPM  = 0x06,
  ACI_CLOCK_ACCURACY_20_PPM  = 0x07
} aci_clock_accuracy_t;

/**
 * @enum aci_app_latency_mode_t
 * @brief Application latency modes
 */
typedef enum
{
  ACI_APP_LATENCY_DISABLE = 0,
  ACI_APP_LATENCY_ENABLE = 1
} aci_app_latency_mode_t;

/**
 * @enum gatt_format_t
 * @brief GATT format definitions
 */
typedef enum 
{
  ACI_GATT_FORMAT_NONE        = 0x00, /**< No characteristic format available */
  ACI_GATT_FORMAT_BOOLEAN     = 0x01, /**< Not Supported */
  ACI_GATT_FORMAT_2BIT        = 0x02, /**< Not Supported */
  ACI_GATT_FORMAT_NIBBLE      = 0x03, /**< Not Supported */
  ACI_GATT_FORMAT_UINT8       = 0x04,
  ACI_GATT_FORMAT_UINT12      = 0x05,
  ACI_GATT_FORMAT_UINT16      = 0x06,
  ACI_GATT_FORMAT_UINT24      = 0x07,
  ACI_GATT_FORMAT_UINT32      = 0x08,
  ACI_GATT_FORMAT_UINT48      = 0x09,
  ACI_GATT_FORMAT_UINT64      = 0x0A,
  ACI_GATT_FORMAT_UINT128     = 0x0B,
  ACI_GATT_FORMAT_SINT8       = 0x0C,
  ACI_GATT_FORMAT_SINT12      = 0x0D,
  ACI_GATT_FORMAT_SINT16      = 0x0E,
  ACI_GATT_FORMAT_SINT24      = 0x0F,
  ACI_GATT_FORMAT_SINT32      = 0x10,
  ACI_GATT_FORMAT_SINT48      = 0x11,
  ACI_GATT_FORMAT_SINT64      = 0x12,
  ACI_GATT_FORMAT_SINT128     = 0x13,
  ACI_GATT_FORMAT_FLOAT32     = 0x14,
  ACI_GATT_FORMAT_FLOAT64     = 0x15,
  ACI_GATT_FORMAT_SFLOAT      = 0x16,
  ACI_GATT_FORMAT_FLOAT       = 0x17,
  ACI_GATT_FORMAT_DUINT16     = 0x18,
  ACI_GATT_FORMAT_UTF8S       = 0x19,
  ACI_GATT_FORMAT_UTF16S      = 0x1A,
  ACI_GATT_FORMAT_STRUCT      = 0x1B
} aci_gatt_format_t;

/**
 * @brief GATT Bluetooth namespace
 */
typedef enum 
{
  ACI_GATT_NAMESPACE_INVALID  = 0x00,
  ACI_GATT_NAMESPACE_BTSIG    = 0x01 /**< Bluetooth SIG */
} aci_gatt_namespace_t;

/**
 * @brief Security key types
 */
typedef enum
{
  ACI_KEY_TYPE_INVALID  = 0x00,
  ACI_KEY_TYPE_PASSKEY  = 0x01
} aci_key_type_t;

/**
 * @enum aci_bond_status_code_t
 * @brief Bond status code
 */
typedef enum
{
 /**
  * Bonding succeeded
  */
  ACI_BOND_STATUS_SUCCESS                             = 0x00,
 /**
  * Bonding failed
  */
  ACI_BOND_STATUS_FAILED                              = 0x01,
 /**
  * Bonding error: Timeout can occur when link termination is unexpected or did not get connected OR SMP timer expired
  */
  ACI_BOND_STATUS_FAILED_TIMED_OUT                    = 0x02,
 /**
  * Bonding error: Passkey entry failed
  */
  ACI_BOND_STATUS_FAILED_PASSKEY_ENTRY_FAILED        = 0x81,
 /**
  * Bonding error: OOB unavailable
  */
  ACI_BOND_STATUS_FAILED_OOB_UNAVAILABLE             = 0x82,
 /**
  * Bonding error: Authentication request failed
  */
  ACI_BOND_STATUS_FAILED_AUTHENTICATION_REQ          = 0x83,
 /**
  * Bonding error: Confirm value failed
  */
  ACI_BOND_STATUS_FAILED_CONFIRM_VALUE               = 0x84,
 /**
  * Bonding error: Pairing unsupported
  */
  ACI_BOND_STATUS_FAILED_PAIRING_UNSUPPORTED         = 0x85,
 /**
  * Bonding error: Invalid encryption key size
  */
  ACI_BOND_STATUS_FAILED_ENCRYPTION_KEY_SIZE         = 0x86,
 /**
  * Bonding error: Unsupported SMP command
  */
  ACI_BOND_STATUS_FAILED_SMP_CMD_UNSUPPORTED         = 0x87,
 /**
  * Bonding error: Unspecified reason
  */
  ACI_BOND_STATUS_FAILED_UNSPECIFIED_REASON          = 0x88,
 /**
  * Bonding error: Too many attempts
  */
  ACI_BOND_STATUS_FAILED_REPEATED_ATTEMPTS           = 0x89,
 /**
  * Bonding error: Invalid parameters
  */
  ACI_BOND_STATUS_FAILED_INVALID_PARAMETERS          = 0x8A

} aci_bond_status_code_t;

/**
 * @enum aci_bond_status_source_t
 * @brief Source of a bond status code
 */
typedef enum
{
  ACI_BOND_STATUS_SOURCE_INVALID                  = 0x00,
  ACI_BOND_STATUS_SOURCE_LOCAL                    = 0x01,
  ACI_BOND_STATUS_SOURCE_REMOTE                   = 0x02

} aci_bond_status_source_t;

/**
 * @enum aci_status_code_t
 * @brief ACI status codes
 */
typedef enum
{
 /**
  * Success
  */
  ACI_STATUS_SUCCESS                                        = 0x00,
 /**
  * Transaction continuation status
  */
  ACI_STATUS_TRANSACTION_CONTINUE                           = 0x01,
 /**
  * Transaction completed
  */
  ACI_STATUS_TRANSACTION_COMPLETE                           = 0x02,
 /**
  * Extended status, further checks needed
  */
  ACI_STATUS_EXTENDED                                       = 0x03,
 /**
  * Unknown error.
  */
  ACI_STATUS_ERROR_UNKNOWN                                  = 0x80,
 /**
  * Internal error.
  */
  ACI_STATUS_ERROR_INTERNAL                                 = 0x81,
 /**
  * Unknown command
  */
  ACI_STATUS_ERROR_CMD_UNKNOWN                              = 0x82,
 /**
  * Command invalid in the current device state
  */
  ACI_STATUS_ERROR_DEVICE_STATE_INVALID                     = 0x83,     
 /**
  * Invalid length
  */
  ACI_STATUS_ERROR_INVALID_LENGTH                           = 0x84,    
 /**
  * Invalid input parameters
  */
  ACI_STATUS_ERROR_INVALID_PARAMETER                        = 0x85,    
 /**
  * Busy 
  */
  ACI_STATUS_ERROR_BUSY                                     = 0x86,
 /**
  * Invalid data format or contents
  */
  ACI_STATUS_ERROR_INVALID_DATA                             = 0x87,
 /**
  * CRC mismatch
  */
  ACI_STATUS_ERROR_CRC_MISMATCH                             = 0x88,
 /**
  * Unsupported setup format
  */
  ACI_STATUS_ERROR_UNSUPPORTED_SETUP_FORMAT                 = 0x89,
 /**
  * Invalid sequence number during a write dynamic data sequence
  */
  ACI_STATUS_ERROR_INVALID_SEQ_NO                           = 0x8A,
 /**
  * Setup data is locked and cannot be modified
  */
  ACI_STATUS_ERROR_SETUP_LOCKED                             = 0x8B,
 /**
  * Setup error due to lock verification failure
  */
  ACI_STATUS_ERROR_LOCK_FAILED                              = 0x8C,
 /**
  * Bond required: Local Pipes need bonded/trusted peer
  */
  ACI_STATUS_ERROR_BOND_REQUIRED                            = 0x8D,
 /**
  * Command rejected as a transaction is still pending
  */
  ACI_STATUS_ERROR_REJECTED                                 = 0x8E,  
  /**
  * Pipe Error Event : Data size exceeds size specified for pipe : Transmit failed
  */
  ACI_STATUS_ERROR_DATA_SIZE                                = 0x8F,
 /**
  * Pipe Error Event : Invalid pipe
  */
  ACI_STATUS_ERROR_PIPE_INVALID                             = 0x90,
 /**
  * Pipe Error Event : Credit not available
  */
  ACI_STATUS_ERROR_CREDIT_NOT_AVAILABLE                     = 0x91,
 /**
  * Pipe Error Event : Peer device has sent an error on an pipe operation on the remote characteristic
  */
  ACI_STATUS_ERROR_PEER_ATT_ERROR                           = 0x92,
 /**
  * Connection was not established before the BTLE advertising was stopped
  */
  ACI_STATUS_ERROR_ADVT_TIMEOUT                             = 0x93,
 /**
  * Peer has triggered a Security Manager Protocol Error
  */
  ACI_STATUS_ERROR_PEER_SMP_ERROR                           = 0x94,
 /**
  * Pipe Error Event : Pipe type invalid for the selected operation
  */
  ACI_STATUS_ERROR_PIPE_TYPE_INVALID                        = 0x95,
 /**
  * Pipe Error Event : Pipe state invalid for the selected operation
  */
  ACI_STATUS_ERROR_PIPE_STATE_INVALID                       = 0x96,
 /**
  * Invalid key size provided
  */
  ACI_STATUS_ERROR_INVALID_KEY_SIZE                         = 0x97,
 /**
  * Invalid key data provided
  */
  ACI_STATUS_ERROR_INVALID_KEY_DATA                         = 0x98,
 /**
  * Reserved range start
  */
  ACI_STATUS_RESERVED_START                                 = 0xF0,
 /**
  * Reserved range end
  */
  ACI_STATUS_RESERVED_END                                   = 0xFF

} aci_status_code_t;

/**
 * @}
 */

#endif // ACI_H__