lib_aci.h File Reference

Include dependency graph for lib_aci.h:

Go to the source code of this file.

Data Structures
struct	_aci_packed_
	Structure for the ACI_CMD_SET_LOCAL_DATA ACI command parameters. More...
struct	services_pipe_type_mapping_t

Functions
Functions for library management
void	lib_aci_debug_print (bool enable)
	Function to enable printing of all ACI commands sent and ACI events received. More...
void	lib_aci_pin_reset (void)
	Function to pin reset the nRF8001. More...
void	lib_aci_init (aci_state_t *aci_stat, bool debug)
	Initialization function. More...
uint8_t	lib_aci_get_nb_available_credits (aci_state_t *aci_stat)
	Gets the number of currently available ACI credits. More...
uint16_t	lib_aci_get_cx_interval_ms (aci_state_t *aci_stat)
	Gets the connection interval in milliseconds. More...
uint16_t	lib_aci_get_cx_interval (aci_state_t *aci_stat)
	Gets the connection interval in multiple of 1.25 ms. More...
uint16_t	lib_aci_get_slave_latency (aci_state_t *aci_stat)
	Gets the current slave latency. More...
bool	lib_aci_is_pipe_available (aci_state_t *aci_stat, uint8_t pipe)
	Checks if a given pipe is available. More...
bool	lib_aci_is_pipe_closed (aci_state_t *aci_stat, uint8_t pipe)
	Checks if a given pipe is closed. More...
bool	lib_aci_is_discovery_finished (aci_state_t *aci_stat)
	Checks if the discovery operation is finished. More...
ACI Commands available in all modes
bool	lib_aci_sleep (void)
	Sets the radio in sleep mode. More...
bool	lib_aci_radio_reset (void)
	Resets the radio. More...
bool	lib_aci_direct_connect (void)
	Radio starts directed advertising to bonded device. More...
bool	lib_aci_device_version (void)
	Gets the radio's version. More...
bool	lib_aci_get_address (void)
	Gets the device address. More...
bool	lib_aci_get_temperature (void)
	Gets the temperature. More...
bool	lib_aci_get_battery_level (void)
	Gets the battery level. More...
ACI commands available in Sleep mode
bool	lib_aci_wakeup (void)
	Wakes up the radio. More...
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. More...
bool	lib_aci_set_tx_power (aci_device_output_power_t tx_power)
	Sets the radio's TX power. More...
bool	lib_aci_connect (uint16_t run_timeout, uint16_t adv_interval)
	Tries to connect to a peer device. More...
bool	lib_aci_bond (uint16_t run_timeout, uint16_t adv_interval)
	Tries to bond with a peer device. More...
bool	lib_aci_disconnect (aci_state_t *aci_stat, aci_disconnect_reason_t reason)
	Disconnects from peer device. More...
bool	lib_aci_set_local_data (aci_state_t *aci_stat, uint8_t pipe, uint8_t *value, uint8_t size)
	Sets Local Data. More...
bool	lib_aci_broadcast (const uint16_t timeout, const uint16_t adv_interval)
	Sends Broadcast message to the radio. More...
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. More...
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. More...
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. More...
bool	lib_aci_open_remote_pipe (aci_state_t *aci_stat, uint8_t pipe)
	Opens a remote pipe. More...
bool	lib_aci_close_remote_pipe (aci_state_t *aci_stat, uint8_t pipe)
	Closes a remote pipe. More...
bool	lib_aci_send_data (uint8_t pipe, uint8_t *value, uint8_t size)
	Sends data on a given pipe. More...
bool	lib_aci_request_data (aci_state_t *aci_stat, uint8_t pipe)
	Requests data from a given pipe. More...
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. More...
bool	lib_aci_change_timing_GAP_PPCP (void)
	Sends a L2CAP change connection parameters request with the connection predefined preffered connection parameters. More...
bool	lib_aci_send_ack (aci_state_t *aci_stat, const uint8_t pipe)
	Sends acknowledgement message to peer. More...
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. More...
bool	lib_aci_read_dynamic_data (void)
	Sends ReadDynamicData command to the host. More...
bool	lib_aci_write_dynamic_data (uint8_t sequence_number, uint8_t *dynamic_data, uint8_t length)
	Sends WriteDynamicData command to the host. More...
ACI commands available while connected in Bond mode
bool	lib_aci_bond_request (void)
	Sends a SMP Security Request. More...
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. More...
ACI commands available in Test mode
bool	lib_aci_echo_msg (uint8_t message_size, uint8_t *message_data)
	Sends an echo message. More...
bool	lib_aci_dtm_command (uint8_t dtm_command_msbyte, uint8_t dtm_command_lsbyte)
	Sends an DTM command. More...
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. More...
bool	lib_aci_event_peek (hal_aci_evt_t *p_aci_evt_data)
	Peeks an ACI event from the ACI Event Queue. More...
void	lib_aci_flush (void)
	Flushes the events in the ACI command queues and ACI Event queue. More...
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.
#define	EVT_CMD_RESPONSE_MIN_LENGTH   3
#define	PIPES_ARRAY_SIZE   ((ACI_DEVICE_MAX_PIPES + 7)/8)
#define	DISCONNECT_REASON_CX_TIMEOUT   0x08
#define	DISCONNECT_REASON_CX_CLOSED_BY_PEER_DEVICE   0x13
#define	DISCONNECT_REASON_POWER_LOSS   0x14
#define	DISCONNECT_REASON_CX_CLOSED_BY_LOCAL_DEVICE   0x16
#define	DISCONNECT_REASON_ADVERTISER_TIMEOUT   0x50
	ACI_ASSERT_SIZE (hal_aci_evt_t, 34)

Function Documentation

void lib_aci_debug_print

(

bool

enable

)

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

Here is the call graph for this function:

void lib_aci_pin_reset

(

void

)

Pin resets the nRF8001 also handles differences between development boards

Here is the call graph for this function:

void lib_aci_init	(	aci_state_t *	aci_stat,
		bool	debug
	)

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

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

Here is the call graph for this function:

Here is the caller graph for this function:

uint8_t lib_aci_get_nb_available_credits

(

aci_state_t *

aci_stat

)

Returns

Number of ACI credits.

uint16_t lib_aci_get_cx_interval_ms

(

aci_state_t *

aci_stat

)

Returns

Connection interval in milliseconds.

uint16_t lib_aci_get_cx_interval

(

aci_state_t *

aci_stat

)

Returns

Connection interval in multiple of 1.25 ms.

uint16_t lib_aci_get_slave_latency

(

aci_state_t *

aci_stat

)

Returns

Current slave latency.

bool lib_aci_is_pipe_available	(	aci_state_t *	aci_stat,
		uint8_t	pipe
	)

Parameters

pipe	Pipe to check.

Returns

True if the pipe is available, otherwise false.

bool lib_aci_is_pipe_closed	(	aci_state_t *	aci_stat,
		uint8_t	pipe
	)

Parameters

pipe	Pipe to check.

Returns

True if the pipe is closed, otherwise false.

bool lib_aci_is_discovery_finished

(

aci_state_t *

aci_stat

)

Returns

True if the discovery is finished.

bool lib_aci_sleep

(

void

)

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.

Here is the call graph for this function:

bool lib_aci_radio_reset

(

void

)

The function sends a BasebandReset command to the radio.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_direct_connect

(

void

)

The function sends a DirectedConnect command to the radio.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_device_version

(

void

)

This function sends a GetDeviceVersion command.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_get_address

(

void

)

This function sends a GetDeviceAddress command.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_get_temperature

(

void

)

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.

Here is the call graph for this function:

bool lib_aci_get_battery_level

(

void

)

This function sends a GetBatteryLevel command.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_wakeup

(

void

)

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.

Here is the call graph for this function:

bool lib_aci_test

(

aci_test_mode_change_t

enter_exit_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_mode

  Enter a Test mode, or exit Test mode.

  Returns

  True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_set_tx_power

(

aci_device_output_power_t

tx_power

)

This function sends a SetTxPower command.

Parameters

tx_power

TX power to be used by the radio.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_connect	(	uint16_t	run_timeout,
		uint16_t	adv_interval
	)

This function sends a Connect command to the radio.

Parameters

run_timeout	Maximum advertising time in seconds (0 means infinite).
adv_interval	Advertising interval (in multiple of 0.625 ms).

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_bond	(	uint16_t	run_timeout,
		uint16_t	adv_interval
	)

This function sends a Bond command to the radio.

Parameters

run_timeout	Maximum advertising time in seconds (0 means infinite).
adv_interval	Advertising interval (in multiple of 0.625 ms).

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_disconnect	(	aci_state_t *	aci_stat,
		aci_disconnect_reason_t	reason
	)

This function sends a Disconnect command to the radio.

Parameters

reason

Reason for disconnecting.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

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

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

ACI	state structure
pipe	Pipe number on which the data should be set.
value	Pointer to the data to set.
size	Size of the data to set.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_broadcast	(	const uint16_t	timeout,
		const uint16_t	adv_interval
	)

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

Parameters

timeout	Time, in seconds, to advertise before exiting to standby mode (0 means infinite). Valid values: 0 to 16383.
adv_interval	Advertising 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.

Here is the call graph for this function:

bool lib_aci_open_adv_pipe

(

const uint8_t

pipe

)

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

pipe	The pipe that has to be placed in advertising service data.

Returns

True if the Open Adv Pipe message is sent successfully to the radio.

Here is the call graph for this function:

bool lib_aci_open_adv_pipes

(

const uint8_t *const

adv_service_data_pipes

)

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_pipes

Pipe 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.

Here is the call graph for this function:

bool lib_aci_set_app_latency	(	uint16_t	latency,
		aci_app_latency_mode_t	latency_mode
	)

This function sends a setApplicationLatency command.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_open_remote_pipe	(	aci_state_t *	aci_stat,
		uint8_t	pipe
	)

This function sends an OpenRemotePipe command.

Parameters

pipe	Number of the pipe to open.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_close_remote_pipe	(	aci_state_t *	aci_stat,
		uint8_t	pipe
	)

This function sends an CloseRemotePipe command.

Parameters

pipe	Pipe number to close.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

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

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

pipe	Pipe number on which the data should be sent.
value	Pointer to the data to send.
size	Size of the data to send.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_request_data	(	aci_state_t *	aci_stat,
		uint8_t	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

pipe	Pipe number on which the data is requested.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

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

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_interval	Minimum connection interval requested, in multiple of 1.25 ms.
maximum_cx_interval	Maximum connection interval requested, in multiple of 1.25 ms.
slave_latency	requested slave latency.
timeout	requested slave timeout, in multiple of 10 ms.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_change_timing_GAP_PPCP

(

void

)

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.

Here is the call graph for this function:

bool lib_aci_send_ack	(	aci_state_t *	aci_stat,
		const uint8_t	pipe
	)

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

pipe	Pipe number for which the acknowledgement is to be sent.

Returns

True if the ack was sent successfully. False otherwise.

Here is the call graph for this function:

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

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

Parameters

pipe	Pipe number for which the nack is to be sent.
error_code	Error code to be sent in the NACk.

Returns

True if the nack was sent successfully. False otherwise.

Here is the call graph for this function:

bool lib_aci_read_dynamic_data

(

void

)

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.

Here is the call graph for this function:

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

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_number	Sequence number of the dynamic data to be sent.
dynamic_data	Pointer to the dynamic data.
length	Length of the dynamic data.

Returns

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

Here is the call graph for this function:

bool lib_aci_bond_request

(

void

)

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.

Here is the call graph for this function:

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

This function sends an SetKey command to the radio.

Parameters

key_rsp_type	Type of key.
key	Pointer to the key to set.
len	Length of the key.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_echo_msg	(	uint8_t	message_size,
		uint8_t *	message_data
	)

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

Parameters

message_size	Length of the data to send.
message_data	Pointer to the data to send.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_dtm_command	(	uint8_t	dtm_command_msbyte,
		uint8_t	dtm_command_lsbyte
	)

This function sends an DTM command to the radio.

Parameters

dtm_command_msbyte	Most significant byte of the DTM command.
dtm_command_lsbyte	Least significant byte of the DTM command.

Returns

True if the transaction is successfully initiated.

Here is the call graph for this function:

bool lib_aci_event_get	(	aci_state_t *	aci_stat,
		hal_aci_evt_t *	aci_evt
	)

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_stat	pointer to the state of the ACI.
p_aci_data	pointer 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

Here is the call graph for this function:

Here is the caller graph for this function:

bool lib_aci_event_peek

(

hal_aci_evt_t *

p_aci_evt_data

)

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.

Here is the call graph for this function:

Here is the caller graph for this function:

void lib_aci_flush

(

void

)

Here is the call graph for this function: