BLE Driver

The BLE driver is used for controlling advanced settings and Bluetooth Low Energy features such as advertising data, notifications, and GATT characteristics.

Data Structures

ATMO_BLE_AdvertisingParams_t

BLE Advertising Configuration Parameters

Member Name Type Description
advertisingInterval uint16_t Time in ms
type ATMO_BLE_AdvertisingType_t Type of advertising

ATMO_BLE_AdvertisingData_t

Manufacturer specific advertising data

Member Name Type Description
length uint8_t Payload length in bytes
payload uint8_t * Pointer to adv data buffer

ATMO_BLE_MacAddress_t

BLE MAC Address

Member Name Type Description
data uint8_t Raw MAC Address Data

ATMO_BLE_CharProperties_t

|Member Name|Type| |:———-|:—|

ATMO_BLE_PairingCfg_t

BLE Pairing Configuration

Member Name Type
type ATMO_BLE_PairingType_t
pairingKey uint32_t

Type Definitions

Name Definition Description
ATMO_BLE_ServiceHandle_t typedef uint16_t ATMO_BLE_ServiceHandle_t  
ATMO_BLE_Handle_t typedef uint16_t ATMO_BLE_Handle_t  
ATMO_BLE_GAPAddress_t typedef uint16_t ATMO_BLE_GAPAddress_t  
ATMO_BLE_Address_t typedef uint16_t ATMO_BLE_Address_t  
ATMO_BLE_DeviceID_t typedef uint16_t ATMO_BLE_DeviceID_t  
ATMO_BLE_Interface_t typedef uint16_t ATMO_BLE_Interface_t  
ATMO_BLE_ServiceID_t typedef uint16_t ATMO_BLE_ServiceID_t  
ATMO_BLE_DriverInstance_t typedef struct ATMO_BLE_DriverInstance_t ATMO_BLE_DriverInstance_t  

Enumerations

enum ATMO_BLE_Status_t

BLE Driver function return enumerations

Name Value Description
ATMO_BLE_Status_Success 0x0 Operation was successful
ATMO_BLE_Status_Fail -0x1 Operation failed
ATMO_BLE_Status_Initialized -0x2 Peripheral already initialized
ATMO_BLE_Status_Invalid -0x3 Invalid operation
ATMO_BLE_Status_NotSupported -0x4 Feature not supported by platform
ATMO_BLE_Status_Unspecified -0x5 Some other status not defined
ATMO_BLE_Status_Busy -0x20 Transfer in progress
ATMO_BLE_Status_Timeout -0x21 Transfer timed out

enum ATMO_BLE_Event_t

Name Value
ATMO_BLE_EVENT_Connected 0
ATMO_BLE_EVENT_Disconnected  
ATMO_BLE_EVENT_PairingRequested  
ATMO_BLE_EVENT_PairingFailed  
ATMO_BLE_EVENT_PairingSuccess  
ATMO_BLE_EVENT_NumEvents  

enum ATMO_BLE_AdvertisingType_t

BLE Advertising Type

Name Value Description
ATMO_BLE_ADV_TYPE_INDIRECT 0x00 General advertise
ATMO_BLE_ADV_TYPE_DIRECT 0x01 Advertise to specific device
ATMO_BLE_ADV_TYPE_NONCONNECT_INDIRECT 0x02 Advertise but device isn’t connectable
ATMO_BLE_ADV_TYPE_SCAN_INDIRECT 0x03 Similar to NONCONNECT with addition info via scan responses

enum ATMO_BLE_PairingType_t

BLE Security Mode

Name Value
ATMO_BLE_PairingType_JustWorks  
ATMO_BLE_PairingType_RandomKey  
ATMO_BLE_PairingType_UserKey  

enum ATMO_BLE_Property_t

Name Value
ATMO_BLE_Property_Broadcast 0x01
ATMO_BLE_Property_Read 0x02
ATMO_BLE_Property_WriteWithoutResponse 0x04
ATMO_BLE_Property_Write 0x08
ATMO_BLE_Property_Notify 0x10
ATMO_BLE_Property_Indicate 0x20
ATMO_BLE_Property_Auth 0x40
ATMO_BLE_Property_ExtProp 0x80

enum ATMO_BLE_Permission_t

BLE Characteristic Permission

Name Value
ATMO_BLE_Permission_Read 0x01
ATMO_BLE_Permission_ReadEncrypted 0x02
ATMO_BLE_Permission_ReadEncryptedMITM 0x04
ATMO_BLE_Permission_Write 0x10
ATMO_BLE_Permission_WriteEncrypted 0x20
ATMO_BLE_Permission_WriteEncryptedMITM 0x40
ATMO_BLE_Permission_WriteSigned 0x80
ATMO_BLE_Permission_WriteSIgnedMITM 0x100

enum ATMO_BLE_Characteristic_Event_t

BLE Characteristic Event. User can register callback on specific event for any characteristic.

Name Value
ATMO_BLE_Characteristic_Written  
ATMO_BLE_Characteristic_Subscribed  
ATMO_BLE_Characteristic_Unsubscribed  
ATMO_BLE_Characteristic_NumEvents  

Functions

ATMO_Status_t ATMO_BLE_AddDriverInstance(const ATMO_BLE_DriverInstance_t *driverInstance, ATMO_DriverInstanceData_t *driverInstanceData, ATMO_DriverInstanceHandle_t *instanceNumber)

Parameter Direction Type
instanceNumber N/A ATMO_DriverInstanceHandle_t *
driverInstanceData N/A ATMO_DriverInstanceData_t *
driverInstance N/A const ATMO_BLE_DriverInstance_t *
Return Type
ATMO_Status_t

ATMO_BLE_Status_t ATMO_BLE_PeripheralInit(ATMO_DriverInstanceHandle_t instance)

This routine initializes BLE.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_PeripheralDeInit(ATMO_DriverInstanceHandle_t instance)

This routine de-initializes BLE.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_SetEnabled(ATMO_DriverInstanceHandle_t instance, bool enabled)

Set the enabled/disabled status of the BLE driver

Parameter Direction Type
enabled N/A bool
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GetEnabled(ATMO_DriverInstanceHandle_t instance, bool *enabled)

Get the enabled/disabled status of the BLE driver

Parameter Direction Type
enabled N/A bool *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GetMacAddress(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_MacAddress_t *address)

This routine gets the device MAC address

Parameter Direction Type
address N/A ATMO_BLE_MacAddress_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPSetDeviceName(ATMO_DriverInstanceHandle_t instance, const char *name)

This routine sets the device name.

Parameter Direction Type
name N/A const char *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPAdvertisingStart(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_AdvertisingParams_t *params)

This routine starts advertising. If advertising is already running then it should turn off the current advertiment data and restart using the new advertisment data.

Parameter Direction Type
params N/A ATMO_BLE_AdvertisingParams_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPAdvertisingStop(ATMO_DriverInstanceHandle_t instance)

This routine stops advertising.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPSetAdvertisedServiceUUID(ATMO_DriverInstanceHandle_t instance, const char *uuid)

This routine sets the advertised service UUID

Parameter Direction Type
uuid N/A const char *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPAdverertisingSetManufacturerData(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_AdvertisingData_t *data)

This routine sets the advertising data if we want to change from default

Parameter Direction Type
data N/A ATMO_BLE_AdvertisingData_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPPairingCfg(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_PairingCfg_t *config)

This routine configures pairing parameters.

Parameter Direction Type
config N/A ATMO_BLE_PairingCfg_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPDisconnect(ATMO_DriverInstanceHandle_t instance)

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GATTSAddService(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t *handle, const char *serviceUUID)

This routine creates and starts a service

Parameter Direction Type
serviceUUID N/A const char *
handle N/A ATMO_BLE_Handle_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GATTSAddCharacteristic(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t *handle, ATMO_BLE_Handle_t serviceHandle, const char *characteristicUUID, uint8_t properties, uint8_t permissions, uint32_t maxLen)

This routine creates a characteristic

Parameter Direction Type
maxLen N/A uint32_t
permissions N/A uint8_t
properties N/A uint8_t
characteristicUUID N/A const char *
serviceHandle N/A ATMO_BLE_Handle_t
handle N/A ATMO_BLE_Handle_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GATTSGetCharacteristicValue(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, uint8_t *valueBuf, uint32_t valueBufLen, uint32_t *valueLen)

Get a pointer to the characteristic value

Parameter Direction Type
valueLen N/A uint32_t *
valueBufLen N/A uint32_t
valueBuf N/A uint8_t *
handle N/A ATMO_BLE_Handle_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GATTSRegisterCharacteristicCallback(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, ATMO_BLE_Characteristic_Event_t event, ATMO_Callback_t cbFunc)

Register callback for GATTS Characteristic Events

Parameter Direction Type
cbFunc N/A ATMO_Callback_t
event N/A ATMO_BLE_Characteristic_Event_t
handle N/A ATMO_BLE_Handle_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GATTSRegisterCharacteristicAbilityHandle(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, ATMO_BLE_Characteristic_Event_t event, unsigned int abilityHandler)

Register ability handle for GATTS Characteristic Events

Parameter Direction Type
abilityHandler N/A unsigned int
event N/A ATMO_BLE_Characteristic_Event_t
handle N/A ATMO_BLE_Handle_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GATTSSetCharacteristic(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, uint16_t length, uint8_t *value, ATMO_BLE_CharProperties_t *properties)

This routine writes to a characteristic in the gattdb.

Parameter Direction Type
properties N/A ATMO_BLE_CharProperties_t *
value N/A uint8_t *
length N/A uint16_t
handle N/A ATMO_BLE_Handle_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GATTSWriteDescriptor(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, uint16_t length, uint8_t *value, ATMO_BLE_CharProperties_t *properties)

This routine writes to a characteristic descriptor in gattdb.

Parameter Direction Type
properties N/A ATMO_BLE_CharProperties_t *
value N/A uint8_t *
length N/A uint16_t
handle N/A ATMO_BLE_Handle_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GATTSSendIndicate(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, uint16_t size, uint8_t *value)

This routine sends an indicate to the GATT Client

Parameter Direction Type
value N/A uint8_t *
size N/A uint16_t
handle N/A ATMO_BLE_Handle_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GATTSSendNotify(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, uint16_t size, uint8_t *value)

Parameter Direction Type
value N/A uint8_t *
size N/A uint16_t
handle N/A ATMO_BLE_Handle_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_RegisterEventCallback(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Event_t event, ATMO_Callback_t cb)

Parameter Direction Type
cb N/A ATMO_Callback_t
event N/A ATMO_BLE_Event_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_RegisterEventAbilityHandle(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Event_t event, unsigned int abilityHandle)

Parameter Direction Type
abilityHandle N/A unsigned int
event N/A ATMO_BLE_Event_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t