aci_cmds.h

00001 /* Copyright (c) 2014, Nordic Semiconductor ASA
00002  *
00003  * Permission is hereby granted, free of charge, to any person obtaining a copy
00004  * of this software and associated documentation files (the "Software"), to deal
00005  * in the Software without restriction, including without limitation the rights
00006  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00007  * copies of the Software, and to permit persons to whom the Software is
00008  * furnished to do so, subject to the following conditions:
00009  *
00010  * The above copyright notice and this permission notice shall be included in all
00011  * copies or substantial portions of the Software.
00012  *
00013  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00014  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00015  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00016  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00017  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00018  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00019  * SOFTWARE.
00020  */
00021 
00022 /**
00023  * @file
00024  *
00025  * @ingroup aci
00026  *
00027  * @brief Definitions for the ACI (Application Control Interface) commands
00028  * @remarks
00029  *
00030  */
00031 
00032 #ifndef ACI_CMDS_H__
00033 #define ACI_CMDS_H__
00034 
00035 #include "aci.h "
00036 
00037 /**
00038  * @enum aci_cmd_opcode_t
00039  * @brief ACI command opcodes
00040  */
00041 typedef enum
00042 {
00043  /**
00044   * Enter test mode
00045   */
00046   ACI_CMD_TEST                    = 0x01,
00047  /**
00048   * Echo (loopback) test command
00049   */
00050   ACI_CMD_ECHO                    = 0x02,
00051  /**
00052   * Send a BTLE DTM command to the radio
00053   */
00054   ACI_CMD_DTM_CMD                 = 0x03,
00055   /**
00056   * Put the device to sleep
00057   */
00058   ACI_CMD_SLEEP                   = 0x04,
00059  /**
00060   * Wakeup the device from deep sleep
00061   */
00062   ACI_CMD_WAKEUP                  = 0x05,
00063  /**
00064   * Replace the contents of the internal database with
00065   * user provided data
00066   */
00067   ACI_CMD_SETUP                   = 0x06,
00068  /**
00069   * Read the portions of memory required to be restored after a power cycle
00070   */
00071   ACI_CMD_READ_DYNAMIC_DATA       = 0x07,
00072  /**
00073   * Write back the data retrieved using ACI_CMD_READ_DYNAMIC_DATA
00074   */
00075   ACI_CMD_WRITE_DYNAMIC_DATA      = 0x08,
00076   /**
00077   * Retrieve the device's version information
00078   */
00079   ACI_CMD_GET_DEVICE_VERSION      = 0x09,
00080  /**
00081   * Request the Bluetooth address and its type
00082   */
00083   ACI_CMD_GET_DEVICE_ADDRESS      = 0x0A,
00084   /**
00085   * Request the battery level measured by nRF8001
00086   */
00087   ACI_CMD_GET_BATTERY_LEVEL       = 0x0B,
00088  /**
00089   * Request the temperature value measured by nRF8001
00090   */
00091   ACI_CMD_GET_TEMPERATURE         = 0x0C,
00092  /**
00093   * Write to the local Attribute Database
00094   */
00095   ACI_CMD_SET_LOCAL_DATA          = 0x0D,
00096  /**
00097   * Reset the baseband and radio and go back to idle
00098   */
00099   ACI_CMD_RADIO_RESET          = 0x0E,
00100  /**
00101   * Start advertising and wait for a master connection
00102   */
00103   ACI_CMD_CONNECT                 = 0x0F,
00104  /**
00105   * Start advertising and wait for a master connection
00106   */
00107   ACI_CMD_BOND                    = 0x10,
00108  /**
00109   * Start advertising and wait for a master connection
00110   */
00111   ACI_CMD_DISCONNECT              = 0x11,
00112  /**
00113   * Throttles the Radio transmit power
00114   */
00115   ACI_CMD_SET_TX_POWER            = 0x12,
00116  /**
00117   * Trigger a connection parameter update
00118   */
00119   ACI_CMD_CHANGE_TIMING           = 0x13,
00120  /**
00121   * Open a remote pipe for data reception
00122   */
00123   ACI_CMD_OPEN_REMOTE_PIPE        = 0x14,
00124  /**
00125   * Transmit data over an open pipe
00126   */
00127   ACI_CMD_SEND_DATA               = 0x15,
00128  /**
00129   * Send an acknowledgment of received data
00130   */
00131   ACI_CMD_SEND_DATA_ACK           = 0x16,
00132  /**
00133   * Request data over an open pipe
00134   */
00135   ACI_CMD_REQUEST_DATA            = 0x17,
00136  /**
00137   * NACK a data reception
00138   */
00139   ACI_CMD_SEND_DATA_NACK          = 0x18,
00140  /**
00141   * Set application latency
00142   */
00143   ACI_CMD_SET_APP_LATENCY         = 0x19,
00144  /**
00145   * Set a security key
00146   */
00147   ACI_CMD_SET_KEY                 = 0x1A,
00148  /**
00149   * Open Advertising Pipes
00150   */
00151   ACI_CMD_OPEN_ADV_PIPE           = 0x1B,
00152  /**
00153   * Start non-connectable advertising
00154   */
00155   ACI_CMD_BROADCAST               = 0x1C,
00156  /**
00157   * Start a security request in bonding mode
00158   */
00159   ACI_CMD_BOND_SECURITY_REQUEST   = 0x1D,
00160  /**
00161   * Start Directed advertising towards a Bonded Peer
00162   */
00163   ACI_CMD_CONNECT_DIRECT          = 0x1E,
00164  /**
00165   * Close a previously opened remote pipe
00166   */
00167   ACI_CMD_CLOSE_REMOTE_PIPE       = 0x1F,
00168  /**
00169   * Invalid ACI command opcode
00170   */
00171   ACI_CMD_INVALID                 = 0xFF
00172 
00173 } _aci_packed_ aci_cmd_opcode_t;
00174 
00175 ACI_ASSERT_SIZE(aci_cmd_opcode_t, 1);
00176 
00177 /**
00178  * @struct aci_cmd_params_test_t
00179  * @brief  Structure for the ACI_CMD_TEST ACI command parameters
00180  */
00181 typedef struct
00182 {
00183   aci_test_mode_change_t test_mode_change; /**< enum aci_test_mode_change_t */
00184 } _aci_packed_ aci_cmd_params_test_t;
00185 
00186 ACI_ASSERT_SIZE(aci_cmd_params_test_t, 1);
00187 
00188 /**
00189  * @struct aci_cmd_params_echo_t
00190  * @brief  Structure for the ACI_CMD_ECHO ACI command parameters
00191  */
00192 typedef struct
00193 {
00194   uint8_t echo_data[ACI_ECHO_DATA_MAX_LEN];
00195 } _aci_packed_ aci_cmd_params_echo_t;
00196 
00197 ACI_ASSERT_SIZE(aci_cmd_params_echo_t, ACI_ECHO_DATA_MAX_LEN);
00198 
00199 /**
00200  * @struct aci_cmd_params_dtm_cmd_t
00201  * @brief  Structure for the ACI_CMD_DTM_CMD ACI command parameters
00202  */
00203 typedef struct
00204 {
00205   uint8_t                 cmd_msb;
00206   uint8_t                 cmd_lsb;
00207 } _aci_packed_ aci_cmd_params_dtm_cmd_t;
00208 
00209 /**
00210  * @struct aci_cmd_params_setup_t
00211  * @brief  Structure for the ACI_CMD_SETUP ACI command parameters
00212  */
00213 typedef struct
00214 {
00215   uint8_t                 setup_data[1];
00216 } _aci_packed_ aci_cmd_params_setup_t;
00217 
00218 ACI_ASSERT_SIZE(aci_cmd_params_setup_t, 1);
00219 
00220 /**
00221  * @struct aci_cmd_params_write_dynamic_data_t
00222  * @brief  Structure for the ACI_CMD_WRITE_DYNAMIC_DATA ACI command parameters 
00223  * @note Dynamic data chunk size in this command is defined to go up to ACI_PACKET_MAX_LEN - 3
00224  */
00225 typedef struct
00226 {
00227   uint8_t                 seq_no;
00228   uint8_t                 dynamic_data[1];
00229 } _aci_packed_ aci_cmd_params_write_dynamic_data_t;
00230 
00231 /**
00232  * @define aci_cmd_params_set_local_data_t
00233  * @brief  Structure for the ACI_CMD_SET_LOCAL_DATA ACI command parameters
00234  */
00235 typedef struct
00236 {
00237   aci_tx_data_t tx_data;
00238 } _aci_packed_ aci_cmd_params_set_local_data_t;
00239 
00240 /**
00241  * @struct aci_cmd_params_connect_t
00242  * @brief  Structure for the ACI_CMD_CONNECT ACI command parameters
00243  */
00244 typedef struct
00245 {
00246   uint16_t        timeout;  /**< 0x0000 (no timeout) to 0x3FFF */
00247   uint16_t        adv_interval;     /**< 16 bits of advertising interval for general discovery */
00248 } _aci_packed_ aci_cmd_params_connect_t;
00249 
00250 ACI_ASSERT_SIZE(aci_cmd_params_connect_t, 4);
00251 
00252 /**
00253  * @define aci_cmd_params_bond_t
00254  * @brief  Structure for the ACI_CMD_BOND ACI command parameters
00255  */
00256 typedef struct
00257 {
00258   uint16_t        timeout;  /**< 0x0000 (no timeout) to 0x3FFF */
00259   uint16_t        adv_interval;     /**< 16 bits of advertising interval for general discovery */
00260 } _aci_packed_ aci_cmd_params_bond_t;
00261 
00262 ACI_ASSERT_SIZE(aci_cmd_params_bond_t, 4);
00263 
00264 /**
00265  * @struct aci_cmd_params_disconnect_t
00266  * @brief  Structure for the ACI_CMD_DISCONNECT ACI command parameters
00267  */
00268 typedef struct
00269 {
00270   aci_disconnect_reason_t         reason; /**< enum aci_disconnect_reason_t */
00271 } _aci_packed_ aci_cmd_params_disconnect_t;
00272 
00273 ACI_ASSERT_SIZE(aci_cmd_params_disconnect_t, 1);
00274 
00275 /**
00276  * @struct aci_cmd_params_set_tx_power_t
00277  * @brief  Structure for the ACI_CMD_SET_TX_POWER ACI command parameters
00278  */
00279 typedef struct
00280 {
00281   aci_device_output_power_t   device_power; /**< enum aci_device_output_power_t */
00282 } _aci_packed_ aci_cmd_params_set_tx_power_t;
00283 
00284 ACI_ASSERT_SIZE(aci_cmd_params_set_tx_power_t, 1);
00285 /**
00286  * @struct aci_cmd_params_change_timing_t
00287  * @brief  Structure for the ACI_CMD_CHANGE_TIMING ACI command parameters
00288  */
00289 typedef struct
00290 {
00291   aci_ll_conn_params_t    conn_params;
00292 } _aci_packed_ aci_cmd_params_change_timing_t;
00293 
00294 ACI_ASSERT_SIZE(aci_cmd_params_change_timing_t, 8);
00295 
00296 /**
00297  * @struct aci_cmd_params_open_remote_pipe_t
00298  * @brief  Structure for the ACI_CMD_OPEN_REMOTE_PIPE ACI command parameters
00299  */
00300 typedef struct
00301 {
00302   uint8_t pipe_number;
00303 } _aci_packed_ aci_cmd_params_open_remote_pipe_t;
00304 
00305 /**
00306  * @struct aci_cmd_params_send_data_t
00307  * @brief  Structure for the ACI_CMD_SEND_DATA ACI command parameters
00308  */
00309 typedef struct
00310 {
00311   aci_tx_data_t tx_data;
00312 } _aci_packed_ aci_cmd_params_send_data_t;
00313 
00314 /**
00315  * @define aci_cmd_params_send_data_ack_t
00316  * @brief  Structure for the ACI_CMD_SEND_DATA_ACK ACI command parameters
00317  */
00318 typedef struct
00319 {
00320   uint8_t pipe_number;
00321 } _aci_packed_ aci_cmd_params_send_data_ack_t;
00322 
00323 /**
00324  * @struct aci_cmd_params_send_data_t
00325  * @brief  Structure for the ACI_CMD_SEND_DATA ACI command parameters
00326  */
00327 typedef struct
00328 {
00329   uint8_t pipe_number;
00330 } _aci_packed_ aci_cmd_params_request_data_t;
00331 
00332 /**
00333  * @define aci_cmd_params_send_data_nack_t
00334  * @brief  Structure for the ACI_CMD_SEND_DATA_NACK ACI command parameters
00335  */
00336 typedef struct
00337 {
00338   uint8_t pipe_number;
00339   uint8_t error_code;
00340 } _aci_packed_ aci_cmd_params_send_data_nack_t;
00341 
00342 ACI_ASSERT_SIZE(aci_cmd_params_send_data_nack_t, 2);
00343 
00344 /**
00345  * @define aci_cmd_params_set_app_latency_t
00346  * @brief  Structure for the ACI_CMD_SET_APP_LATENCY ACI command parameters
00347  */
00348 typedef struct
00349 {
00350   aci_app_latency_mode_t mode;
00351   uint16_t latency;
00352 } _aci_packed_ aci_cmd_params_set_app_latency_t;
00353 
00354 ACI_ASSERT_SIZE(aci_cmd_params_set_app_latency_t, 3);
00355 /**
00356  * @define aci_cmd_params_set_key_t
00357  * @brief  Structure for the ACI_CMD_SET_KEY ACI command parameters
00358  */
00359 typedef struct
00360 {
00361   aci_key_type_t key_type;
00362   union
00363   {
00364     uint8_t passkey[6];
00365     uint8_t oob_key[16];
00366   } key;
00367 } _aci_packed_ aci_cmd_params_set_key_t;
00368 
00369 ACI_ASSERT_SIZE(aci_cmd_params_set_key_t, 17);
00370 /**
00371  * @define aci_cmd_params_open_adv_pipe_t
00372  * @brief  Structure for the ACI_CMD_OPEN_ADV_PIPE ACI command parameters
00373  */
00374 typedef struct
00375 {
00376   uint8_t pipes[8];
00377 } _aci_packed_ aci_cmd_params_open_adv_pipe_t;
00378 
00379 /**
00380  * @define aci_cmd_params_broadcast_t
00381  * @brief  Structure for the ACI_CMD_BROADCAST ACI command parameters
00382  */
00383 typedef struct
00384 {
00385   uint16_t        timeout;  /**< 0x0000 (no timeout) to 0x3FFF */
00386   uint16_t        adv_interval;     /**< 16 bits of advertising interval for general discovery */
00387 } _aci_packed_ aci_cmd_params_broadcast_t;
00388 
00389 /**
00390  * @struct aci_cmd_params_close_remote_pipe_t
00391  * @brief  Structure for the ACI_CMD_CLOSE_REMOTE_PIPE ACI command parameters
00392  */
00393 typedef struct
00394 {
00395   uint8_t pipe_number;
00396 } _aci_packed_ aci_cmd_params_close_remote_pipe_t;
00397 
00398 /**
00399  * @struct aci_cmd_t
00400  * @brief  Encapsulates a generic ACI command
00401  */
00402 typedef struct
00403 {
00404   uint8_t len;        /**< Length of the ACI command */
00405   aci_cmd_opcode_t cmd_opcode; /**< enum aci_cmd_opcode_t -> Opcode of the ACI command */
00406   union
00407   {
00408     aci_cmd_params_test_t                       test;
00409     aci_cmd_params_echo_t                       echo;
00410     aci_cmd_params_dtm_cmd_t                    dtm_cmd;
00411     aci_cmd_params_setup_t                      setup;
00412     aci_cmd_params_write_dynamic_data_t         write_dynamic_data;
00413     aci_cmd_params_set_local_data_t             set_local_data;
00414     aci_cmd_params_connect_t                    connect;
00415     aci_cmd_params_bond_t                       bond;
00416     aci_cmd_params_disconnect_t                 disconnect;
00417     aci_cmd_params_set_tx_power_t               set_tx_power;
00418     aci_cmd_params_change_timing_t              change_timing;
00419     aci_cmd_params_open_remote_pipe_t           open_remote_pipe;
00420     aci_cmd_params_send_data_t                  send_data;
00421     aci_cmd_params_send_data_ack_t              send_data_ack;
00422     aci_cmd_params_request_data_t               request_data;
00423     aci_cmd_params_send_data_nack_t             send_data_nack;
00424     aci_cmd_params_set_app_latency_t            set_app_latency;
00425     aci_cmd_params_set_key_t                    set_key;
00426     aci_cmd_params_open_adv_pipe_t              open_adv_pipe;
00427     aci_cmd_params_broadcast_t                  broadcast;
00428     aci_cmd_params_close_remote_pipe_t          close_remote_pipe;
00429 
00430   } params;
00431 } _aci_packed_ aci_cmd_t;
00432 
00433 #endif // ACI_CMDS_H__
00434