Core functions for getting a connected CA-821x/Chili device and establishing a communications link. More...
Functions | |
| ca_error | ca821x_util_init (struct ca821x_dev *pDeviceRef, ca821x_errorhandler errorHandler, union ca821x_util_init_extra_arg arg) |
| Generic function to initialise an available ca821x device. More... | |
| ca_error | ca821x_util_init_path (struct ca821x_dev *pDeviceRef, ca821x_errorhandler errorHandler, enum ca821x_exchange_type exchangeType, const char *path) |
| Generic function to initialise a specific device as found via ca821x_util_enumerate or other mechanism. More... | |
| void | ca821x_util_deinit (struct ca821x_dev *pDeviceRef) |
| Generic function to deinitialise an initialised ca821x device. More... | |
| ca_error | ca821x_util_enumerate (util_device_found aCallback, bool enumerate_uart, void *aContext) |
| Function to enumerate all of the connected devices, calling aCallback with a struct describing each one. More... | |
| ca_error | ca821x_util_reset (struct ca821x_dev *pDeviceRef) |
| Generic function to attempt a hard reset of the ca821x chip. More... | |
| ca_error | ca821x_util_dispatch_poll () |
| Generic function to poll the receive queue and call callbacks for received commands. More... | |
| ca_error | ca821x_util_start_upstream_dispatch_worker () |
| Start the upstream_dispatch worker, which asynchronously calls the message callbacks (such as MCPS_DATA_indication) as they are received. More... | |
| ca_error | ca821x_util_stop_upstream_dispatch_worker () |
| Stop the upstream_dispatch worker, so callbacks will no longer be triggered from a separate thread. More... | |
| ca_error | exchange_register_user_callback (exchange_user_callback callback, struct ca821x_dev *pDeviceRef) |
| Registers the callback to call for any non-ca821x commands that are sent over the interface. More... | |
| ca_error | exchange_wait_send_complete (time_t timeout_s, struct ca821x_dev *pDeviceRef) |
| Query whether the given exchange has any messages pending being sent in its send queue. More... | |
| ca_error | exchange_user_command (uint8_t cmdid, uint8_t cmdlen, uint8_t *payload, struct ca821x_dev *pDeviceRef) |
| Sends a user-defined command over the connected interface. More... | |
Detailed Description
Core functions for getting a connected CA-821x/Chili device and establishing a communications link.
Function Documentation
◆ ca821x_util_deinit()
| void ca821x_util_deinit | ( | struct ca821x_dev * | pDeviceRef | ) |
Generic function to deinitialise an initialised ca821x device.
This will free any resources that were allocated by ca821x_util_init.
Calling on an uninitialised pDeviceRef produces undefined behaviour.
- Parameters
-
[in] pDeviceRef Device reference to be deinitialised.
◆ ca821x_util_dispatch_poll()
| ca_error ca821x_util_dispatch_poll | ( | ) |
Generic function to poll the receive queue and call callbacks for received commands.
This function should only be used if ca821x_util_start_upstream_dispatch_worker has not been called. If ca821x_util_start_upstream_dispatch_worker has been called, the callbacks will be called immediately and asynchronously from another thread.
It is recommended that if the return value is CA_ERROR_SUCCESS, this function should be called again.
- Returns
- status
- Return values
-
CA_ERROR_SUCCESS A message was pending and has been processed CA_ERROR_NOT_FOUND No messages pending dispatch CA_ERROR_INVALID_STATE This function cannot be used as the exchange is in asynchronous mode - all dispatch callbacks will be called from a separate thread.
◆ ca821x_util_enumerate()
| ca_error ca821x_util_enumerate | ( | util_device_found | aCallback, |
| bool | enumerate_uart, | ||
| void * | aContext | ||
| ) |
Function to enumerate all of the connected devices, calling aCallback with a struct describing each one.
The struct passed to aCallback will only be valid for the duration that the function is called. This function will not return until every callback has been called.
- Parameters
-
aCallback The callback to call with each result enumerate_uart Whether or not this function should enumerate devices connected to COM ports. aContext The generic void pointer to provide to the callback when it is called
- Return values
-
CA_ERROR_SUCCESS Enumeration successful CA_ERROR_NOT_FOUND No devices found
◆ ca821x_util_init()
| ca_error ca821x_util_init | ( | struct ca821x_dev * | pDeviceRef, |
| ca821x_errorhandler | errorHandler, | ||
| union ca821x_util_init_extra_arg | arg | ||
| ) |
Generic function to initialise an available ca821x device.
This includes initialisation of the api and an exchange. Use of these generic functions over using a specific exchange allows more flexibility.
Calling twice on the same pDeviceRef without a deinit produces undefined behaviour.
Also see ca821x_util_init_path for initialising a specific device.
- Parameters
-
[in] pDeviceRef Device reference to be initialised. Must point to allocated memory, but does not have to be initialised. The memory is cleared and initialised internally. [in] errorHandler A function pointer to an error handling function. This callback will be triggered in the event of an unrecoverable error. [in] arg Additional information, such as a serial number, com port or additional flag. See ca821x_util_init_extra_arg union for more info.
- Return values
-
CA_ERROR_SUCCESS Device was initialised successfully CA_ERROR_ALREADY Device was already initialised CA_ERROR_NOT_FOUND Device could not be initialised
◆ ca821x_util_init_path()
| ca_error ca821x_util_init_path | ( | struct ca821x_dev * | pDeviceRef, |
| ca821x_errorhandler | errorHandler, | ||
| enum ca821x_exchange_type | exchangeType, | ||
| const char * | path | ||
| ) |
Generic function to initialise a specific device as found via ca821x_util_enumerate or other mechanism.
See ca821x_util_init for basic description, as this function carries out the same purpose, but for a specific device.
- Parameters
-
[in] pDeviceRef Device reference to be initialised. Must point to allocated memory, but does not have to be initialised. The memory is cleared and initialised internally. [in] errorHandler A function pointer to an error handling function. This callback will be triggered in the event of an unrecoverable error. exchangeType The exchange type (eg usb, uart, kernel) to be used. Obtained from ca821x_util_enumerate. path The exchange-specific path to the desired device. Obtained from ca821x_util_enumerate.
- Return values
-
CA_ERROR_SUCCESS Device was initialised successfully CA_ERROR_ALREADY Device was already initialised CA_ERROR_NOT_FOUND Device could not be initialised CA_ERROR_INVALID_ARGS Exchange type not recognised
◆ ca821x_util_reset()
| ca_error ca821x_util_reset | ( | struct ca821x_dev * | pDeviceRef | ) |
Generic function to attempt a hard reset of the ca821x chip.
Calling on an uninitialised pDeviceRef produces undefined behaviour.
- Parameters
-
[in] pDeviceRef Device reference for device to be reset.
- Return values
-
CA_ERROR_SUCCESS The device has been reset successfully CA_ERROR_FAIL The device could not be reset
◆ ca821x_util_start_upstream_dispatch_worker()
| ca_error ca821x_util_start_upstream_dispatch_worker | ( | ) |
Start the upstream_dispatch worker, which asynchronously calls the message callbacks (such as MCPS_DATA_indication) as they are received.
These callbacks will be triggered from a separate posix thread. Appropriate pthread locking should be used by the application or else the application logic could suffer from threading related issues.
This should not be used in conjunction with ca821x_util_dispatch_poll. Use ca821x_util_dispatch_poll if you don't want to deal with pthreads, at the expense of having to poll a function in the application.
- Returns
- status
- Return values
-
CA_ERROR_ALREADY upstream dispatch worker already running. CA_ERROR_FAIL Failed to start thread CA_ERROR_SUCCESS Success
◆ ca821x_util_stop_upstream_dispatch_worker()
| ca_error ca821x_util_stop_upstream_dispatch_worker | ( | ) |
Stop the upstream_dispatch worker, so callbacks will no longer be triggered from a separate thread.
- Returns
- status
- Return values
-
CA_ERROR_ALREADY upstream dispatch worker already stopped. CA_ERROR_FAIL Failed to stop thread CA_ERROR_SUCCESS Success
◆ exchange_register_user_callback()
| ca_error exchange_register_user_callback | ( | exchange_user_callback | callback, |
| struct ca821x_dev * | pDeviceRef | ||
| ) |
Registers the callback to call for any non-ca821x commands that are sent over the interface.
Commands are still limited to the cascoda tlv format, and must use a command ID that is not currently used by the ca821x-spi protocol.
- Parameters
-
[in] callback Function pointer to an user-command-handling callback [in] pDeviceRef Pointer to initialised ca821x_device_ref struct
- Return values
-
CA_ERROR_SUCCESS Callback successfully registered CA_ERROR_FAIL Could not register callback
◆ exchange_user_command()
| ca_error exchange_user_command | ( | uint8_t | cmdid, |
| uint8_t | cmdlen, | ||
| uint8_t * | payload, | ||
| struct ca821x_dev * | pDeviceRef | ||
| ) |
Sends a user-defined command over the connected interface.
This is not useful for direct CA-821x communication, as the api commands handle this. This can be used to implement custom commands on the chili modules, when communicating over USB or UART, for example.
Synchronous commands are not supported using this mechanism.
- Parameters
-
[in] cmdid Command ID to be used by command [in] cmdlen Length of the payload [in] payload Pointer to a buffer containing the payload data with length cmdlen [in] pDeviceRef The device reference to communicate with
- Returns
- ca_error
◆ exchange_wait_send_complete()
| ca_error exchange_wait_send_complete | ( | time_t | timeout_s, |
| struct ca821x_dev * | pDeviceRef | ||
| ) |
Query whether the given exchange has any messages pending being sent in its send queue.
- Parameters
-
timeout_s timeout in seconds, or 0 for nonblocking mode pDeviceRef Device reference to check the exchange of.
- Return values
-
CA_ERROR_SUCCESS All pending transmissions to the device are complete CA_ERROR_BUSY All pending transmissions are not complete (returned due to timeout or non-blocking)
