TI BLE5-Stack API Documentation
2.02.08.00
|
BLE Profile implementation of the TI over the air download solution. This file is responsible for processing data from the BLE-Stack, passing this data to the application, and processing queued OAD events as well as the OAD state machine. More...
Modules | |
OAD Events | |
OAD Extended Control Command op codes | |
OAD Service Indexes | |
OAD Service UUIDs | |
OAD return status codes | |
Files | |
file | oad.h |
This file contains OAD Profile header file. | |
Data Structures | |
struct | blockReqPld_t |
struct | blockSizeRspPld_t |
struct | deviceTypeRspPld_t |
struct | extImgEnableReq_t |
struct | genericExtCtrlRsp_t |
struct | imageInfo_t |
struct | imageInfoRspPld_t |
struct | imgIdentifyPld_t |
struct | oadTargetCBs_t |
struct | profileVerRsp_t |
struct | swVersionPld_t |
Macros | |
#define | EXT_CTRL_OP_CODE(pData) (pData[0]) |
#define | OAD_ATT_OVERHEAD 3 |
#define | OAD_BLK_NUM_HDR_SZ 4 |
#define | OAD_CCCD_CNT OAD_CHAR_CNT |
#define | OAD_CHAR_CNT 3 |
#define | OAD_DEFAULT_BLOCK_SIZE 20 |
#define | OAD_DEFAULT_INACTIVITY_TIME 10000 |
#define | OAD_EFL_MAX_META 4 |
#define | OAD_EXT_CTRL_CMD_NOT_SUPPORTED 0xFF |
#define | OAD_IMAGE_ID_RSP_LEN 0x01 |
#define | OAD_IMG_ID_RETRIES 3 |
#define | OAD_IMG_INFO_ONCHIP 0x01 |
#define | OAD_IMG_PG_INVALID 0xFF |
OAD Security Types. More... | |
#define | OAD_MAX_BLOCK_SIZE 244 |
#define | OAD_MIN_INACTIVITY_TIME 4000 |
#define | OAD_SEC_AES_128_CBC 0x02 |
OAD Security Type for AES 128. | |
#define | OAD_SEC_ECDSA_P256 0x01 |
OAD Security Type for ECDSA P256. | |
#define | OAD_WRITE_PERMIT GATT_PERMIT_WRITE |
Typedefs | |
typedef void(* | oadWriteCB_t) (uint8_t event, uint16_t arg) |
Enumerations | |
enum | oadEvent_e { OAD_WRITE_IDENTIFY_REQ, OAD_WRITE_BLOCK_REQ, OAD_IMAGE_COMPLETE, OAD_EXT_CTRL_WRITE_CMD, OAD_TIMEOUT } |
enum | oadState_e { OAD_IDLE, OAD_VALIDATE_IMG, OAD_CONFIG, OAD_DOWNLOAD, OAD_CHECK_DL, OAD_COMPLETE } |
Functions | |
void | OAD_cancel (void) |
void | OAD_close (void) |
bool | OAD_evenBitCount (uint32_t value) |
uint16_t | OAD_getactiveCxnHandle () |
uint16_t | OAD_getBlockSize (void) |
bool | OAD_getSWVersion (uint8_t *swVer, uint8_t len) |
bool | OAD_isUsrAppValid (void) |
uint8_t | OAD_open (uint32_t oadTimeout) |
uint8_t | OAD_processQueue (void) |
void | OAD_register (oadTargetCBs_t *pfnOadCBs) |
uint8_t | OAD_setBlockSize (uint16_t mtuSize) |
uint8_t | oadCreateFactoryImageBackup (void) |
BLE Profile implementation of the TI over the air download solution. This file is responsible for processing data from the BLE-Stack, passing this data to the application, and processing queued OAD events as well as the OAD state machine.
============================================================================
The OAD Profile header should be included in an OAD enabled application as follows:
This module is intended to handle OAD related functionality for the application. At a high level it is responsible for receiving and parsing OAD profile data and commands. This includes:
For code examples, see the use cases below.
After plugging the callbacks shown above, and initializing the OAD module the application will begin receive callbacks related to OAD_QUEUE_EVT and OAD_DL_COMPLETE_EVT.
Inside the application task function, the queue event should be processed:
At this time, the OAD is entirely complete and the system should be reset. The reset behavior is defined by the application.
#define EXT_CTRL_OP_CODE | ( | pData | ) | (pData[0]) |
Macro to parse op-code from external control command
#define OAD_ATT_OVERHEAD 3 |
The ATT header overhead required to send a GATT_notifiation() This is used in calculating acceptable block sizes
#define OAD_BLK_NUM_HDR_SZ 4 |
The size of the OAD block number in a block write or block request
#define OAD_CCCD_CNT OAD_CHAR_CNT |
Number of CCCDs in the OAD service
#define OAD_CHAR_CNT 3 |
Number of characteristics in the OAD service
#define OAD_DEFAULT_BLOCK_SIZE 20 |
Minimum OAD block size OAD Block size can range from [OAD_DEFAULT_BLOCK_SIZE,OAD_MAX_BLOCK_SIZE]
#define OAD_DEFAULT_INACTIVITY_TIME 10000 |
Default OAD inactivity timeout, the OAD state machine will cancel OAD if no activity is observed during this time.
The inactivity time is configurable via a parameter to OAD_open
#define OAD_EFL_MAX_META 4 |
Maximum number of external flash image header entries
#define OAD_EXT_CTRL_CMD_NOT_SUPPORTED 0xFF |
Error code returned when an external control command is received with an invalid opcode.
#define OAD_IMAGE_ID_RSP_LEN 0x01 |
Size of the payload in an image identify response.
#define OAD_IMG_ID_RETRIES 3 |
Number of failed image IDs are allowed before OAD terminates the cxn
#define OAD_IMG_INFO_ONCHIP 0x01 |
There are two flavors of the get image info command:
#define OAD_IMG_PG_INVALID 0xFF |
OAD Security Types.
Invalid image page (outside of device flash)
#define OAD_MAX_BLOCK_SIZE 244 |
Maximum OAD block size OAD Block size can range from [OAD_DEFAULT_BLOCK_SIZE,OAD_MAX_BLOCK_SIZE]
#define OAD_MIN_INACTIVITY_TIME 4000 |
Minimum OAD inactivity timeout, the OAD state machine will cancel OAD if no activity is observed during this time.
#define OAD_WRITE_PERMIT GATT_PERMIT_WRITE |
This define controls whether the OAD profile requires BLE security By default, this is off.
typedef void(* oadWriteCB_t) (uint8_t event, uint16_t arg) |
OAD Module Write Callback Function
This callback is used to signal to the application that the OAD profile has received data over the air or needs to process an event in its internal queue
event | The event that the OAD module is posting in the application Can either OAD_QUEUE_EVT or OAD_DL_COMPLETE_EVT |
arg | This is the bim_var if performing on-chip OAD, otherwise unused |
enum oadEvent_e |
Event internal to the OAD module, use in state machine processing
enum oadState_e |
OAD state types
void OAD_cancel | ( | void | ) |
Cancel and active OAD and reset the state
void OAD_close | ( | void | ) |
Close the OAD and its flash_interface, reset the state
bool OAD_evenBitCount | ( | uint32_t | value | ) |
This function checks if the value field has even number of 1's.
value | Value field to check for even number of 1's. |
uint16_t OAD_getactiveCxnHandle | ( | ) |
Returns the active connection handle of the OAD session
uint16_t OAD_getBlockSize | ( | void | ) |
Gets the block size currently used by the OAD module
bool OAD_getSWVersion | ( | uint8_t * | swVer, |
uint8_t | len | ||
) |
Returns the currently running SW version field
swVer | - pointer to array to copy version into |
len | - number of bytes to copy |
bool OAD_isUsrAppValid | ( | void | ) |
Returns whether or not the user application is valid (on-chip OAD only)
uint8_t OAD_open | ( | uint32_t | oadTimeout | ) |
Open the OAD module
Initializes the OAD Service by registering GATT attributes with the GATT server. Only call this function once.
oadTimeout | - the timeout on for a pending OAD operation (in ms) |
uint8_t OAD_processQueue | ( | void | ) |
Process the OAD message queue/state machine
void OAD_register | ( | oadTargetCBs_t * | pfnOadCBs | ) |
Register a callback function with the OAD Target Profile.
pfnOadCBs | - struct holding function pointers to OAD application callbacks oadTargetCBs_t |
uint8_t OAD_setBlockSize | ( | uint16_t | mtuSize | ) |
Sets the block size to be used during OAD based on a given MTU
mtuSize | - The negotiated MTU size |
uint8_t oadCreateFactoryImageBackup | ( | void | ) |
This function creates factory image backup of current running image