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 Type - ECDSA-P256. More...

#define	OAD_MAX_BLOCK_SIZE 244

#define	OAD_MIN_INACTIVITY_TIME 4000

#define	OAD_SEC_AES_128_CBC 0x02

#define	OAD_SEC_ECDSA_P256 0x01
	OAD Security Type - AES-128-CBC.

#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)

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)

Detailed Description

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.

============================================================================

Header Include

The OAD Profile header should be included in an OAD enabled application as follows:

#include <profiles/oad/cc26xx/oad.h>

Overview

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:

Receiving image blocks and commands
Executing commands and writing blocks to flash
Reporting status to both local application and peer device
Metadata management
Checking the received image for integrity (CRC, etc)

General Behavior

For code examples, see the use cases below.

Initialzation

The application must plug a callback function that allows the OAD profile to queue an event or packet up for processing in the app thread context
static oadTargetCBs_t MyApp_oadCBs =
{
MyApp_processOadWriteCB // Write Callback.
};
Inside the oadWriteCB_t, the application should do the following:
Event_post(appEvent, event);
The application thread should additionally pend on the following OAD events
- OAD_QUEUE_EVT
- OAD_DL_COMPLETE_EVT
In the _init function of the a BLE-Stack enabled application thread, Do the following calls:
// Open the OAD module and add the OAD service to the application
if(OAD_SUCCESS != OAD_open(OAD_DEFAULT_INACTIVITY_TIME))
{
// Display or log the error
}
else
{
// Register the OAD callback with the application
OAD_register(&MyApp_oadCBs);
}

Useage

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.

Processing OAD_QUEUE_EVT

Inside the application task function, the queue event should be processed:

// OAD events
if(events & OAD_QUEUE_EVT)
{
    // Process the OAD Message Queue
    uint8_t status = OAD_processQueue();
    // If the OAD state machine encountered an error, print it
    if(status == OAD_DL_COMPLETE)
    {
        //Display or print the message
    }
    else if(status == OAD_IMG_ID_TIMEOUT)
    {
        // Display the error and terminate the link
        MAP_GAP_TerminateLinkReq(OAD_getactiveCxnHandle(),
                                    HCI_DISCONNECT_REMOTE_USER_TERM);
    }
    else if(status != OAD_SUCCESS)
    {
        // Display the error
    }
}

Processing OAD_DL_COMPLETE_EVT

At this time, the OAD is entirely complete and the system should be reset. The reset behavior is defined by the application.

Warning: The application should ensure the BLE-Stack has no pending items in its transmit buffer (i.e. final OAD response messages) before rebooting

Macro Definition Documentation

§ EXT_CTRL_OP_CODE

#define EXT_CTRL_OP_CODE ( pData ) (pData[0])

Macro to parse op-code from external control command

§ OAD_ATT_OVERHEAD

#define OAD_ATT_OVERHEAD 3

The ATT header overhead required to send a GATT_notifiation() This is used in calculating acceptable block sizes

§ OAD_BLK_NUM_HDR_SZ

#define OAD_BLK_NUM_HDR_SZ 4

The size of the OAD block number in a block write or block request

§ OAD_CCCD_CNT

#define OAD_CCCD_CNT OAD_CHAR_CNT

Number of CCCDs in the OAD service

§ OAD_CHAR_CNT

#define OAD_CHAR_CNT 3

Number of characteristics in the OAD service

§ OAD_DEFAULT_BLOCK_SIZE

#define OAD_DEFAULT_BLOCK_SIZE 20

Minimum OAD block size OAD Block size can range from [OAD_DEFAULT_BLOCK_SIZE,OAD_MAX_BLOCK_SIZE]

Note: OAD block size must be 4 Octet aligned

§ OAD_DEFAULT_INACTIVITY_TIME

#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

§ OAD_EFL_MAX_META

#define OAD_EFL_MAX_META 4

Maximum number of external flash image header entries

Note: this only applies to off-chip OAD

§ OAD_EXT_CTRL_CMD_NOT_SUPPORTED

#define OAD_EXT_CTRL_CMD_NOT_SUPPORTED 0xFF

Error code returned when an external control command is received with an invalid opcode.

§ OAD_IMAGE_ID_RSP_LEN

#define OAD_IMAGE_ID_RSP_LEN 0x01

Size of the payload in an image identify response.

§ OAD_IMG_ID_RETRIES

#define OAD_IMG_ID_RETRIES 3

Number of failed image IDs are allowed before OAD terminates the cxn

§ OAD_IMG_INFO_ONCHIP

#define OAD_IMG_INFO_ONCHIP 0x01

There are two flavors of the get image info command:

A short get info command: returns the image info for the image on the chip
A long get info command: return an array of image info structures from external flash

§ OAD_IMG_PG_INVALID

#define OAD_IMG_PG_INVALID 0xFF

OAD Security Type - ECDSA-P256.

Invalid image page (outside of device flash)

§ OAD_MAX_BLOCK_SIZE

#define OAD_MAX_BLOCK_SIZE 244

Maximum OAD block size OAD Block size can range from [OAD_DEFAULT_BLOCK_SIZE,OAD_MAX_BLOCK_SIZE]

Note: OAD block size must be 4 Octet aligned

§ OAD_MIN_INACTIVITY_TIME

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

§ OAD_WRITE_PERMIT

#define OAD_WRITE_PERMIT GATT_PERMIT_WRITE

This define controls whether the OAD profile requires BLE security By default, this is off.

Typedef Documentation

§ oadWriteCB_t

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

Parameters

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

Enumeration Type Documentation

§ oadEvent_e

enum oadEvent_e

Event internal to the OAD module, use in state machine processing

Enumerator
OAD_WRITE_IDENTIFY_REQ	Image identify received.
OAD_WRITE_BLOCK_REQ	Image block request/response event.
OAD_IMAGE_COMPLETE	OAD complete.
OAD_EXT_CTRL_WRITE_CMD	External Control Command received.
OAD_TIMEOUT	OAD peer timed out.

§ oadState_e

enum oadState_e

OAD state types

Enumerator
OAD_IDLE	OAD module is not performing any action.
OAD_VALIDATE_IMG	OAD module is checking an image.
OAD_CONFIG	OAD module is configuring for a download.
OAD_DOWNLOAD	OAD module is receiving an image.
OAD_CHECK_DL	OAD module is validating an received image.
OAD_COMPLETE	OAD module has completed a download.

Function Documentation

§ OAD_cancel()

void OAD_cancel ( void )

Cancel and active OAD and reset the state

§ OAD_close()

void OAD_close ( void )

Close the OAD and its flash_interface, reset the state

§ OAD_getactiveCxnHandle()

uint16_t OAD_getactiveCxnHandle ( )

Returns the active connection handle of the OAD session

Returns: handle - the 16-bit connection handle of the OAD session

§ OAD_getBlockSize()

uint16_t OAD_getBlockSize ( void )

Gets the block size currently used by the OAD module

Returns: The block size being used.

§ OAD_getSWVersion()

bool OAD_getSWVersion	(	uint8_t *	swVer,
		uint8_t	len
	)

Returns the currently running SW version field

Parameters

swVer	- pointer to array to copy version into
len	- number of bytes to copy

Returns

status - true if copy succeeded

false if copy failed (invalid parameter)

§ OAD_isUsrAppValid()

bool OAD_isUsrAppValid ( void )

Returns whether or not the user application is valid (on-chip OAD only)

Returns: user app status - true if the user app hasn't been erased.

§ OAD_open()

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.

Parameters

oadTimeout - the timeout on for a pending OAD operation (in ms)

Returns: Success or Failure

§ OAD_processQueue()

uint8_t OAD_processQueue ( void )

Process the OAD message queue/state machine

Returns: status of operation - OAD return status codes

§ OAD_register()

void OAD_register ( oadTargetCBs_t * pfnOadCBs )

Register a callback function with the OAD Target Profile.

Parameters

pfnOadCBs - struct holding function pointers to OAD application callbacks oadTargetCBs_t

§ OAD_setBlockSize()

uint8_t OAD_setBlockSize ( uint16_t mtuSize )

Sets the block size to be used during OAD based on a given MTU

Parameters

mtuSize - The negotiated MTU size

Returns: TRUE if operation is successful.

§ oadCreateFactoryImageBackup()

uint8_t oadCreateFactoryImageBackup ( void )

This function creates factory image backup of current running image

Returns: OAD_SUCCESS on successful erasure else OAD_FLASH_ERR

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Header Include

Overview

General Behavior

Initialzation

Useage

Processing OAD_QUEUE_EVT

Processing OAD_DL_COMPLETE_EVT

Macro Definition Documentation

§ EXT_CTRL_OP_CODE

§ OAD_ATT_OVERHEAD

§ OAD_BLK_NUM_HDR_SZ

§ OAD_CCCD_CNT

§ OAD_CHAR_CNT

§ OAD_DEFAULT_BLOCK_SIZE

§ OAD_DEFAULT_INACTIVITY_TIME

§ OAD_EFL_MAX_META

§ OAD_EXT_CTRL_CMD_NOT_SUPPORTED

§ OAD_IMAGE_ID_RSP_LEN

§ OAD_IMG_ID_RETRIES

§ OAD_IMG_INFO_ONCHIP

§ OAD_IMG_PG_INVALID

§ OAD_MAX_BLOCK_SIZE

§ OAD_MIN_INACTIVITY_TIME

§ OAD_WRITE_PERMIT

Typedef Documentation

§ oadWriteCB_t

Enumeration Type Documentation

§ oadEvent_e

§ oadState_e

Function Documentation

§ OAD_cancel()

§ OAD_close()

§ OAD_getactiveCxnHandle()

§ OAD_getBlockSize()

§ OAD_getSWVersion()

§ OAD_isUsrAppValid()

§ OAD_open()

§ OAD_processQueue()

§ OAD_register()

§ OAD_setBlockSize()

§ oadCreateFactoryImageBackup()