added debugging

Fork of BLE_nRF8001 by RedBearLab

Embed: (wiki syntax)

« Back to documentation index

Lib_aci

Lib_aci

Library for the logical part of the Application Controller Interface (ACI) More...

Data Structures

struct  _aci_packed_
 aci_cmd_params_set_local_data_t More...

Functions for library management

void lib_aci_debug_print (bool enable)
 Function to enable printing of all ACI commands sent and ACI events received.
void lib_aci_pin_reset (void)
 Function to pin reset the nRF8001.
void lib_aci_init (aci_state_t *aci_stat, bool debug)
 Initialization function.
uint8_t lib_aci_get_nb_available_credits (aci_state_t *aci_stat)
 Gets the number of currently available ACI credits.
uint16_t lib_aci_get_cx_interval_ms (aci_state_t *aci_stat)
 Gets the connection interval in milliseconds.
uint16_t lib_aci_get_cx_interval (aci_state_t *aci_stat)
 Gets the connection interval in multiple of 1.25 ms.
uint16_t lib_aci_get_slave_latency (aci_state_t *aci_stat)
 Gets the current slave latency.
bool lib_aci_is_pipe_available (aci_state_t *aci_stat, uint8_t pipe)
 Checks if a given pipe is available.
bool lib_aci_is_pipe_closed (aci_state_t *aci_stat, uint8_t pipe)
 Checks if a given pipe is closed.
bool lib_aci_is_discovery_finished (aci_state_t *aci_stat)
 Checks if the discovery operation is finished.

ACI Commands available in all modes

bool lib_aci_sleep (void)
 Sets the radio in sleep mode.
bool lib_aci_radio_reset (void)
 Resets the radio.
bool lib_aci_direct_connect (void)
 Radio starts directed advertising to bonded device.
bool lib_aci_device_version (void)
 Gets the radio's version.
bool lib_aci_get_address (void)
 Gets the device address.
bool lib_aci_get_temperature (void)
 Gets the temperature.
bool lib_aci_get_battery_level (void)
 Gets the battery level.

ACI commands available in Sleep mode

bool lib_aci_wakeup (void)
 Wakes up the radio.

ACI commands available in Active mode

bool lib_aci_test (aci_test_mode_change_t enter_exit_test_mode)
 Sets the radio in test mode.
bool lib_aci_set_tx_power (aci_device_output_power_t tx_power)
 Sets the radio's TX power.
bool lib_aci_connect (uint16_t run_timeout, uint16_t adv_interval)
 Tries to connect to a peer device.
bool lib_aci_bond (uint16_t run_timeout, uint16_t adv_interval)
 Tries to bond with a peer device.
bool lib_aci_disconnect (aci_state_t *aci_stat, aci_disconnect_reason_t reason)
 Disconnects from peer device.
bool lib_aci_set_local_data (aci_state_t *aci_stat, uint8_t pipe, uint8_t *value, uint8_t size)
 Sets Local Data.
bool lib_aci_broadcast (const uint16_t timeout, const uint16_t adv_interval)
 Sends Broadcast message to the radio.

Open Advertising Pipes.

bool lib_aci_open_adv_pipe (const uint8_t pipe)
 Sends a command to the radio to set the input pipe to be placed in Advertisement Service Data.

Open Advertising Pipes

bool lib_aci_open_adv_pipes (const uint8_t *const adv_service_data_pipes)
 Sends a command to the radio to set the pipes to be placed in Advertisement Service Data.

ACI commands available in Connected mode

bool lib_aci_set_app_latency (uint16_t latency, aci_app_latency_mode_t latency_mode)
 Sets a given application latency.
bool lib_aci_open_remote_pipe (aci_state_t *aci_stat, uint8_t pipe)
 Opens a remote pipe.
bool lib_aci_close_remote_pipe (aci_state_t *aci_stat, uint8_t pipe)
 Closes a remote pipe.
bool lib_aci_send_data (uint8_t pipe, uint8_t *value, uint8_t size)
 Sends data on a given pipe.
bool lib_aci_request_data (aci_state_t *aci_stat, uint8_t pipe)
 Requests data from a given pipe.
bool lib_aci_change_timing (uint16_t minimun_cx_interval, uint16_t maximum_cx_interval, uint16_t slave_latency, uint16_t timeout)
 Sends a L2CAP change connection parameters request.
bool lib_aci_change_timing_GAP_PPCP (void)
 Sends a L2CAP change connection parameters request with the connection predefined preffered connection parameters.
bool lib_aci_send_ack (aci_state_t *aci_stat, const uint8_t pipe)
 Sends acknowledgement message to peer.
bool lib_aci_send_nack (aci_state_t *aci_stat, const uint8_t pipe, const uint8_t error_code)
 Sends negative acknowledgement message to peer.
bool lib_aci_read_dynamic_data (void)
 Sends ReadDynamicData command to the host.
bool lib_aci_write_dynamic_data (uint8_t sequence_number, uint8_t *dynamic_data, uint8_t length)
 Sends WriteDynamicData command to the host.

ACI commands available while connected in Bond mode

bool lib_aci_bond_request (void)
 Sends a SMP Security Request.
bool lib_aci_set_key (aci_key_type_t key_rsp_type, uint8_t *key, uint8_t len)
 Set the key requested by the 8001.

ACI commands available in Test mode

bool lib_aci_echo_msg (uint8_t message_size, uint8_t *message_data)
 Sends an echo message.
bool lib_aci_dtm_command (uint8_t dtm_command_msbyte, uint8_t dtm_command_lsbyte)
 Sends an DTM command.
bool lib_aci_event_get (aci_state_t *aci_stat, hal_aci_evt_t *aci_evt)
 Gets an ACI event from the ACI Event Queue.
bool lib_aci_event_peek (hal_aci_evt_t *p_aci_evt_data)
 Peeks an ACI event from the ACI Event Queue.
void lib_aci_flush (void)
 Flushes the events in the ACI command queues and ACI Event queue.
bool lib_aci_event_queue_full (void)
 Return full status of the Event queue.
bool lib_aci_event_queue_empty (void)
 Return empty status of the Event queue.
bool lib_aci_command_queue_full (void)
 Return full status of Command queue.
bool lib_aci_command_queue_empty (void)
 Return empty status of Command queue.

Detailed Description

Library for the logical part of the Application Controller Interface (ACI)


Function Documentation

bool lib_aci_bond ( uint16_t  run_timeout,
uint16_t  adv_interval 
)

Tries to bond with a peer device.

This function sends a Bond command to the radio.

Parameters:
run_timeoutMaximum advertising time in seconds (0 means infinite).
adv_intervalAdvertising interval (in multiple of 0.625 ms).
Returns:
True if the transaction is successfully initiated.

Definition at line 348 of file lib_aci.cpp.

bool lib_aci_bond_request ( void   )

Sends a SMP Security Request.

This function send a BondRequest command to the radio. This command triggers a SMP Security Request to the master. If the master rejects with a pairing failed or if the bond timer expires the connection is closed.

Returns:
True if the transaction is successfully initiated.

Definition at line 552 of file lib_aci.cpp.

bool lib_aci_broadcast ( const uint16_t  timeout,
const uint16_t  adv_interval 
)

Sends Broadcast message to the radio.

The Broadcast message starts advertisement procedure using the given interval with the intention of broadcasting data to a peer device.

Parameters:
timeoutTime, in seconds, to advertise before exiting to standby mode (0 means infinite). Valid values: 0 to 16383.
adv_intervalAdvertising interval (in multiple of 0.625 ms). Valid values: 160 to 16384 (which corresponds to an interval from 100 ms to 10.24 s).
Returns:
True if the broadcast message is sent successfully to the radio.

Definition at line 653 of file lib_aci.cpp.

bool lib_aci_change_timing ( uint16_t  minimun_cx_interval,
uint16_t  maximum_cx_interval,
uint16_t  slave_latency,
uint16_t  timeout 
)

Sends a L2CAP change connection parameters request.

This function sends a ChangeTiming command to the radio. This command triggers a "L2CAP change connection parameters" request to the master. If the master rejects or accepts but doesn't change the connection parameters within 30 seconds, a timing event with the unchanged connection parameters is sent by the radio. If the request is accepted and the master changes connection parameters, a timing event with the new connection parameters is sent by the radio. If the master doesn't reply to the request within 60 seconds, the radio disconnects.

Parameters:
minimun_cx_intervalMinimum connection interval requested, in multiple of 1.25 ms.
maximum_cx_intervalMaximum connection interval requested, in multiple of 1.25 ms.
slave_latencyrequested slave latency.
timeoutrequested slave timeout, in multiple of 10 ms.
Returns:
True if the transaction is successfully initiated.

Definition at line 449 of file lib_aci.cpp.

bool lib_aci_change_timing_GAP_PPCP ( void   )

Sends a L2CAP change connection parameters request with the connection predefined preffered connection parameters.

This function sends a ChangeTiming command to the radio. This command triggers a "L2CAP change connection parameters" request to the master. If the master rejects or accepts but doesn't change the connection parameters within 30 seconds, a timing event with the unchanged connection parameters is sent by the radio. If the request is accepted and the master changes connection parameters, a timing event with the new connection parameters is sent by the radio. If the master doesn't reply to the request within 60 seconds, the radio disconnects. The timing parameters used are the Timing parameters in the GAP settings in the nRFgo Studio. The Timing parameters as stored as the GAP Preferred Peripheral Connection Parameters.

Returns:
True if the transaction is successfully initiated.

Definition at line 461 of file lib_aci.cpp.

bool lib_aci_close_remote_pipe ( aci_state_t *  aci_stat,
uint8_t  pipe 
)

Closes a remote pipe.

This function sends an CloseRemotePipe command.

Parameters:
pipePipe number to close.
Returns:
True if the transaction is successfully initiated.

Definition at line 495 of file lib_aci.cpp.

bool lib_aci_command_queue_empty ( void   )

Return empty status of Command queue.

Definition at line 746 of file lib_aci.cpp.

bool lib_aci_command_queue_full ( void   )

Return full status of Command queue.

Definition at line 751 of file lib_aci.cpp.

bool lib_aci_connect ( uint16_t  run_timeout,
uint16_t  adv_interval 
)

Tries to connect to a peer device.

This function sends a Connect command to the radio.

Parameters:
run_timeoutMaximum advertising time in seconds (0 means infinite).
adv_intervalAdvertising interval (in multiple of 0.625 ms).
Returns:
True if the transaction is successfully initiated.

Definition at line 313 of file lib_aci.cpp.

void lib_aci_debug_print ( bool  enable )

Function to enable printing of all ACI commands sent and ACI events received.

This function shall be used to enable or disable the debug printing. Debug printing is disabled by default.

Definition at line 725 of file lib_aci.cpp.

bool lib_aci_device_version ( void   )

Gets the radio's version.

This function sends a GetDeviceVersion command.

Returns:
True if the transaction is successfully initiated.

Definition at line 289 of file lib_aci.cpp.

bool lib_aci_direct_connect ( void   )

Radio starts directed advertising to bonded device.

The function sends a DirectedConnect command to the radio.

Returns:
True if the transaction is successfully initiated.

Definition at line 282 of file lib_aci.cpp.

bool lib_aci_disconnect ( aci_state_t *  aci_stat,
aci_disconnect_reason_t  reason 
)

Disconnects from peer device.

This function sends a Disconnect command to the radio.

Parameters:
reasonReason for disconnecting.
Returns:
True if the transaction is successfully initiated.

Definition at line 323 of file lib_aci.cpp.

bool lib_aci_dtm_command ( uint8_t  dtm_command_msbyte,
uint8_t  dtm_command_lsbyte 
)

Sends an DTM command.

This function sends an DTM command to the radio.

Parameters:
dtm_command_msbyteMost significant byte of the DTM command.
dtm_command_lsbyteLeast significant byte of the DTM command.
Returns:
True if the transaction is successfully initiated.

Definition at line 711 of file lib_aci.cpp.

bool lib_aci_echo_msg ( uint8_t  message_size,
uint8_t *  message_data 
)

Sends an echo message.

This function sends an Echo command to the radio. lib_aci places the Echp ACI command in the ACI command queue

Parameters:
message_sizeLength of the data to send.
message_dataPointer to the data to send.
Returns:
True if the transaction is successfully initiated.

Definition at line 532 of file lib_aci.cpp.

bool lib_aci_event_get ( aci_state_t *  aci_stat,
hal_aci_evt_t *  aci_evt 
)

Gets an ACI event from the ACI Event Queue.

This function gets an ACI event from the ACI event queue. The queue is updated by the SPI driver for the ACI running in the interrupt context

Parameters:
aci_statpointer to the state of the ACI.
p_aci_datapointer to the ACI Event. The ACI Event received will be copied into this pointer.
Returns:
True if an ACI Event was copied to the pointer.

Update the state of the ACI with the ACI Events -> Pipe Status, Disconnected, Connected, Bond Status, Pipe Error

Definition at line 563 of file lib_aci.cpp.

bool lib_aci_event_peek ( hal_aci_evt_t *  p_aci_evt_data )

Peeks an ACI event from the ACI Event Queue.

This function peeks at the top event in the ACI event queue. In polling mode, this function will query the nRF8001 for pending events, but unlike lib_aci_event_get() it will not dequeue the event from the local queue, but will instead only peek at it.

Returns:
True if an ACI Event was copied to the pointer.

Definition at line 558 of file lib_aci.cpp.

bool lib_aci_event_queue_empty ( void   )

Return empty status of the Event queue.

Definition at line 736 of file lib_aci.cpp.

bool lib_aci_event_queue_full ( void   )

Return full status of the Event queue.

Definition at line 741 of file lib_aci.cpp.

void lib_aci_flush ( void   )

Flushes the events in the ACI command queues and ACI Event queue.

Definition at line 720 of file lib_aci.cpp.

bool lib_aci_get_address ( void   )

Gets the device address.

This function sends a GetDeviceAddress command.

Returns:
True if the transaction is successfully initiated.

Definition at line 374 of file lib_aci.cpp.

bool lib_aci_get_battery_level ( void   )

Gets the battery level.

This function sends a GetBatteryLevel command.

Returns:
True if the transaction is successfully initiated.

Definition at line 388 of file lib_aci.cpp.

uint16_t lib_aci_get_cx_interval ( aci_state_t *  aci_stat )

Gets the connection interval in multiple of 1.25 ms.

Returns:
Connection interval in multiple of 1.25 ms.

Definition at line 235 of file lib_aci.cpp.

uint16_t lib_aci_get_cx_interval_ms ( aci_state_t *  aci_stat )

Gets the connection interval in milliseconds.

Returns:
Connection interval in milliseconds.

Definition at line 222 of file lib_aci.cpp.

uint8_t lib_aci_get_nb_available_credits ( aci_state_t *  aci_stat )

Gets the number of currently available ACI credits.

Returns:
Number of ACI credits.

Definition at line 217 of file lib_aci.cpp.

uint16_t lib_aci_get_slave_latency ( aci_state_t *  aci_stat )

Gets the current slave latency.

Returns:
Current slave latency.

Definition at line 241 of file lib_aci.cpp.

bool lib_aci_get_temperature ( void   )

Gets the temperature.

This function sends a GetTemperature command. lib_aci calls the lib_aci_transaction_finished_hook() function when the temperature is received.

Returns:
True if the transaction is successfully initiated.

Definition at line 381 of file lib_aci.cpp.

void lib_aci_init ( aci_state_t *  aci_stat,
bool  debug 
)

Initialization function.

This function shall be used to initialize/reset ACI Library and also Resets the nRF8001 by togging the reset pin of the nRF8001. This function will reset all the variables locally used by ACI library to their respective default values.

Parameters:
boolTrue if the data was successfully queued for sending, false if there is no more space to store messages to send.

Definition at line 178 of file lib_aci.cpp.

bool lib_aci_is_discovery_finished ( aci_state_t *  aci_stat )

Checks if the discovery operation is finished.

Returns:
True if the discovery is finished.

Definition at line 96 of file lib_aci.cpp.

bool lib_aci_is_pipe_available ( aci_state_t *  aci_stat,
uint8_t  pipe 
)

Checks if a given pipe is available.

Parameters:
pipePipe to check.
Returns:
True if the pipe is available, otherwise false.

Definition at line 70 of file lib_aci.cpp.

bool lib_aci_is_pipe_closed ( aci_state_t *  aci_stat,
uint8_t  pipe 
)

Checks if a given pipe is closed.

Parameters:
pipePipe to check.
Returns:
True if the pipe is closed, otherwise false.

Definition at line 83 of file lib_aci.cpp.

bool lib_aci_open_adv_pipe ( const uint8_t  pipe )

Sends a command to the radio to set the input pipe to be placed in Advertisement Service Data.

This function sends a command to the radio that places the pipe in advertisement service data. To start advertising service data, call this function before Connecting, Broadcasting or Bonding to peer. The data that should be sent in the advertisement packets must be set using the lib_aci_set_local_data function. This function can be called during advertising to enable/disable broadcast pipes.

Parameters:
pipeThe pipe that has to be placed in advertising service data.
Returns:
True if the Open Adv Pipe message is sent successfully to the radio.

Definition at line 688 of file lib_aci.cpp.

bool lib_aci_open_adv_pipes ( const uint8_t *const   adv_service_data_pipes )

Sends a command to the radio to set the pipes to be placed in Advertisement Service Data.

This function will send a command to the radio that will set the pipes to be placed in advertisement Service Data. To start advertising service data, this function should be called before Connecting, Broadcasting or Bonding to peer. This function can be called during advertising to enable/disable broadcast pipes. Use this as an alternative to lib_aci_open_adv_pipe to avoid multiple function calls for placing multiple pipes in the adv data.

Parameters:
adv_service_data_pipesPipe bitmap, where '1' indicates that the corresponding Valid Values: 0000000000000000 to FEFFFFFFFFFFFF7F (See the ACI Pipe Status Evt bitmap in the nRF8001 datasheet TX_BROADCAST pipe data is to be placed in Advertising Service Data fields
Returns:
true if the Open Adv Pipe message was sent successfully to the radio.

Definition at line 675 of file lib_aci.cpp.

bool lib_aci_open_remote_pipe ( aci_state_t *  aci_stat,
uint8_t  pipe 
)

Opens a remote pipe.

This function sends an OpenRemotePipe command.

Parameters:
pipeNumber of the pipe to open.
Returns:
True if the transaction is successfully initiated.

Definition at line 468 of file lib_aci.cpp.

void lib_aci_pin_reset ( void   )

Function to pin reset the nRF8001.

Pin resets the nRF8001 also handles differences between development boards

Definition at line 731 of file lib_aci.cpp.

bool lib_aci_radio_reset ( void   )

Resets the radio.

The function sends a BasebandReset command to the radio.

Returns:
True if the transaction is successfully initiated.

Definition at line 275 of file lib_aci.cpp.

bool lib_aci_read_dynamic_data ( void   )

Sends ReadDynamicData command to the host.

This function sends ReadDynamicData command to host. The host is expected to send CommandResponse back with the dynamic data. The application is expected to call this function in a loop until all the dynamic data is read out from the host. As long as there is dynamic data to be read from the host, the command response for this message has its status field set to ACI_STATUS_TRANSACTION_CONTINUE (0x01). The application may chose to store this read out data in a non-volatile memory location and later chose to write it back using the function lib_aci_write_dynamic_data.

Returns:
True if the command was sent successfully through the ACI. False otherwise.

Definition at line 698 of file lib_aci.cpp.

bool lib_aci_request_data ( aci_state_t *  aci_stat,
uint8_t  pipe 
)

Requests data from a given pipe.

This function sends a RequestData command to the radio. This function memorizes credit uses, and check that enough credits are available. After this command, the radio sends back either a DataReceivedEvent or a PipeErrorEvent.

Parameters:
pipePipe number on which the data is requested.
Returns:
True if the transaction is successfully initiated.

Definition at line 422 of file lib_aci.cpp.

bool lib_aci_send_ack ( aci_state_t *  aci_stat,
const uint8_t  pipe 
)

Sends acknowledgement message to peer.

This function sends SendDataAck command to radio. The radio is expected to send either Handle Value Confirmation or Write response depending on whether the data is stored remotely or locally.

Parameters:
pipePipe number for which the acknowledgement is to be sent.
Returns:
True if the ack was sent successfully. False otherwise.

Definition at line 628 of file lib_aci.cpp.

bool lib_aci_send_data ( uint8_t  pipe,
uint8_t *  value,
uint8_t  size 
)

Sends data on a given pipe.

This function sends a SendData command with application data to the radio. This function memorizes credit use, and checks that enough credits are available.

Parameters:
pipePipe number on which the data should be sent.
valuePointer to the data to send.
sizeSize of the data to send.
Returns:
True if the transaction is successfully initiated.

Definition at line 395 of file lib_aci.cpp.

bool lib_aci_send_nack ( aci_state_t *  aci_stat,
const uint8_t  pipe,
const uint8_t  error_code 
)

Sends negative acknowledgement message to peer.

This function sends SendDataNack command to radio. The radio is expected to send Error Response to the peer.

Parameters:
pipePipe number for which the nack is to be sent.
error_codeError code to be sent in the NACk.
Returns:
True if the nack was sent successfully. False otherwise.

Definition at line 640 of file lib_aci.cpp.

bool lib_aci_set_app_latency ( uint16_t  latency,
aci_app_latency_mode_t  latency_mode 
)

Sets a given application latency.

This function sends a setApplicationLatency command.

Returns:
True if the transaction is successfully initiated.

Definition at line 247 of file lib_aci.cpp.

bool lib_aci_set_key ( aci_key_type_t  key_rsp_type,
uint8_t *  key,
uint8_t  len 
)

Set the key requested by the 8001.

This function sends an SetKey command to the radio.

Parameters:
key_rsp_typeType of key.
keyPointer to the key to set.
lenLength of the key.
Returns:
True if the transaction is successfully initiated.

Definition at line 522 of file lib_aci.cpp.

bool lib_aci_set_local_data ( aci_state_t *  aci_stat,
uint8_t  pipe,
uint8_t *  value,
uint8_t  size 
)

Sets Local Data.

This command updates the value of the characteristic value or the characteristic descriptor stored locally on the device. Can be called for all types of pipes as long as the data is stored locally.

Parameters:
ACIstate structure
pipePipe number on which the data should be set.
valuePointer to the data to set.
sizeSize of the data to set.
Returns:
True if the transaction is successfully initiated.

Definition at line 296 of file lib_aci.cpp.

bool lib_aci_set_tx_power ( aci_device_output_power_t  tx_power )

Sets the radio's TX power.

This function sends a SetTxPower command.

Parameters:
tx_powerTX power to be used by the radio.
Returns:
True if the transaction is successfully initiated.

Definition at line 365 of file lib_aci.cpp.

bool lib_aci_sleep ( void   )

Sets the radio in sleep mode.

The function sends a sleep command to the radio. If the radio is advertising or connected, it sends back an error, then use lib_aci_radio_reset if advertising or disconnect if in a connection.

Returns:
True if the transaction is successfully initiated.

Definition at line 268 of file lib_aci.cpp.

bool lib_aci_test ( aci_test_mode_change_t  enter_exit_test_mode )

Sets the radio in test mode.

This function sends a Test command to the radio. There are two Test modes available:

  • UART: DTM commands are received over UART.
  • ACI: DTM commands are received over ACI. The same command is used to exit the test mode When receiving a DeviceStartedEvent the radio has entered the new mode.
    Parameters:
    enter_exit_test_modeEnter a Test mode, or exit Test mode.
    Returns:
    True if the transaction is successfully initiated.

Definition at line 259 of file lib_aci.cpp.

bool lib_aci_wakeup ( void   )

Wakes up the radio.

This function sends a Wakeup command to wake up the radio from sleep mode. When woken up the radio sends a DeviceStartedEvent and a CommandResponseEvent.

Returns:
True if the transaction is successfully initiated.

Definition at line 358 of file lib_aci.cpp.

bool lib_aci_write_dynamic_data ( uint8_t  sequence_number,
uint8_t *  dynamic_data,
uint8_t  length 
)

Sends WriteDynamicData command to the host.

This function sends WriteDynamicData command to host. The host is expected to send CommandResponse with the status of this operation. As long as the status field in the CommandResponse is ACI_STATUS_TRANSACTION_CONTINUE (0x01), the hosts expects more dynamic data to be written. This function should ideally be called in a cycle, until all the stored dynamic data is sent to the host. This function should be called with the dynamic data obtained from the response to a ReadDynamicData (see lib_aci_read_dynamic_data) command.

Parameters:
sequence_numberSequence number of the dynamic data to be sent.
dynamic_dataPointer to the dynamic data.
lengthLength of the dynamic data.
Returns:
True if the command was sent successfully through the ACI. False otherwise.

Definition at line 705 of file lib_aci.cpp.