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 milliseconds
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_PairingCfg_t

BLE pairing configuration.

Member Name Type Description
bonding bool Set to true if central wants to bond
securityType ATMO_BLE_SecurityModeLevel_t Security mode and level
centralKeys ATMO_BLE_KeyFlags_t Central key types available
peripheralKeys ATMO_BLE_KeyFlags_t Peripheral key types available

Type Definitions

Name Definition
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

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_PowerLevel_t

BLE transmit power.

Name Value
ATMO_BLE_PowerTx_Low 0x01
ATMO_BLE_PowerTx_Medium 0x02
ATMO_BLE_PowerTx_High 0x03
ATMO_BLE_PowerTx_Max 0x04

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_SecurityModeLevel_t

BLE security mode.

Name Value
ATMO_BLE_Security_Mode1Level1 0x00
ATMO_BLE_Security_Mode1Level2 0x01
ATMO_BLE_Security_Mode1Level3 0x02
ATMO_BLE_Security_Mode1Level4 0x03
ATMO_BLE_Security_Mode2Level1 0x04
ATMO_BLE_Security_Mode2Level2 0x05

enum ATMO_BLE_KeyFlags_t

BLE security key.

Name Value
ATMO_BLE_SecurityKeys_NoKey 0x00
ATMO_BLE_SecurityKeys_LTK 0x01
ATMO_BLE_SecurityKeys_IRK 0x02
ATMO_BLE_SecurityKeys_CSRK 0x04

enum ATMO_BLE_Property_t

BLE characteristic property.

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. You can register a callback on a specific event for any characteristic.

Name
ATMO_BLE_Characteristic_Written
ATMO_BLE_Characteristic_Subscribed
ATMO_BLE_Characteristic_Unsubscribed

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_GAPScanConfigure(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_ScanParams_t *params)

This routine configures scanning with the parameters provided.

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

ATMO_BLE_Status_t ATMO_BLE_GAPScanStart(ATMO_DriverInstanceHandle_t instance, uint32_t length)

This routine starts the device to scan for other devices.

Parameter Direction Type
length N/A uint32_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPScanStop(ATMO_DriverInstanceHandle_t instance)

This routine stops the device from scanning.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPScanSetData(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_ScanData_t *data)

This routine sets the scan response data for BLE.

Parameter Direction Type
data N/A ATMO_BLE_ScanData_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_GAPPair(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_GAPConnect(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_DeviceID_t scannedDeviceID)

This routine connects this device to another scanned device.

Parameter Direction Type
scannedDeviceID N/A ATMO_BLE_DeviceID_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPDisconnect(ATMO_DriverInstanceHandle_t instance)

This routine disconnects from a device.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPPowerLevelConfigure(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_PowerLevel_t advertisingTxPower, ATMO_BLE_PowerLevel_t connectionTxPower)

This routine overrides default Tx power levels.

Parameter Direction Type
connectionTxPower N/A ATMO_BLE_PowerLevel_t
advertisingTxPower N/A ATMO_BLE_PowerLevel_t
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 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_GATTSSendIndicate(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, uint16_t size, uint8_t *value)

This routine sends an indication 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)

This routine sends a notification to the GATT client.

Parameter Direction Type
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_GATTCDiscoverService(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_ServiceHandle_t serviceUUID, ATMO_BLE_ScanResults_t *result)

This routine executes a GATT service discovery for all or specific services. This will return from the service(s) from the gattdb.

Parameter Direction Type
result N/A ATMO_BLE_ScanResults_t *
serviceUUID N/A ATMO_BLE_ServiceHandle_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

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

This routine writes a value to a characteristic in the gattdb.

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_GATTCReadCharacteristic(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, uint16_t size, uint8_t *payload)

This routine reads a value from a characteristic in the gattdb.

Parameter Direction Type
payload 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_GATTCEnableNotification(ATMO_DriverInstanceHandle_t instance, ATMO_BLE_Handle_t handle, bool indicate)

This routine registers this device for notifications from a characteristic in gattdb.

Parameter Direction Type
indicate N/A bool
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_GAPRegisterCallbackConnected(ATMO_DriverInstanceHandle_t instance, ATMO_Callback_t cbFunc)

This routine registers a callback function to run when the device becomes connected.

Parameter Direction Type
cbFunc N/A ATMO_Callback_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t

ATMO_BLE_Status_t ATMO_BLE_GAPRegisterCallbackDisconnected(ATMO_DriverInstanceHandle_t instance, ATMO_Callback_t cbFunc)

This routine registers a callback function to run when the device becomes disconnected.

Parameter Direction Type
cbFunc N/A ATMO_Callback_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_BLE_Status_t