Lamp-Da 0.1
A compact lantern project
Loading...
Searching...
No Matches
ble.h
Go to the documentation of this file.
1
20#ifndef HAL_BLE_H
21#define HAL_BLE_H
22
23#include <stdint.h>
24#include <stdbool.h>
25#include <stddef.h>
26#include <array>
27
28namespace lampda {
29namespace hal {
31namespace ble {
32
33//
34#define BLE_MAX_PERIPHERAL_CONNECTIONS 1
35
36/* ========== Error Codes ========== */
37#define HAL_BLE_SUCCESS (0)
38#define HAL_BLE_ERROR_GENERIC (-1)
39#define HAL_BLE_ERROR_INVALID_PARAM (-2)
40#define HAL_BLE_ERROR_NOT_SUPPORTED (-3)
41#define HAL_BLE_ERROR_NO_MEMORY (-4)
42#define HAL_BLE_ERROR_BUSY (-5)
43#define HAL_BLE_ERROR_TIMEOUT (-6)
44#define HAL_BLE_ERROR_ALREADY_INIT (-7)
45#define HAL_BLE_ERROR_NOT_INIT (-8)
46
48#define HAL_BLE_GAP_ADDR_LEN (6)
49
50/* ========== UUID Handling ========== */
51
60{
63};
64
69{
71 union
72 {
73 uint16_t uuid16;
74 uint8_t uuid128[16];
75 } value;
76};
77
78/* ========== GATT (Generic Attribute Profile) ========== */
79
85enum class hal_ble_gatt_perm_t : uint8_t
86{
87 READ = 0x01,
88 READ_ENCRYPTED = 0x02,
89 WRITE = 0x04,
90 WRITE_ENCRYPTED = 0x08,
91};
92
98enum class hal_ble_gatt_prop_t : uint8_t
99{
100 READ = 0x01,
101 WRITE_NO_RSP = 0x02,
102 WRITE = 0x04,
103 NOTIFY = 0x08,
104 INDICATE = 0x10,
105 BROADCAST = 0x20,
106};
107
111enum class hal_ble_pairing_result : uint8_t
112{
113 SUCCESS = 0,
115 TIMEOUT,
116 AUTH_REQ,
120};
121
124enum class hal_ble_adress_type : uint8_t
125{
126 INVALID,
127 PUBLIC,
131 ANONYMOUS,
133};
134
136{
138 std::array<uint8_t, HAL_BLE_GAP_ADDR_LEN> addr = {0};
139};
140
146using hal_ble_conn_handle_t = uint16_t;
147
155using hal_ble_write_callback_t = void (*)(hal_ble_conn_handle_t conn_handle, const uint8_t* data, uint16_t length);
156
168using hal_ble_read_callback_t = int32_t (*)(hal_ble_conn_handle_t conn_handle,
169 uint16_t char_handle,
170 uint8_t* data,
171 uint16_t max_length);
172
178using hal_ble_char_handle_t = uint16_t;
179
186{
189 uint16_t max_length;
190 uint8_t* initial_value;
191 uint16_t initial_length;
197 const char* descriptor;
198};
199
206{
208};
209
210/* ========== Security & Pairing ========== */
211
222
230using hal_ble_secure_cb_t = void (*)(hal_ble_conn_handle_t conn_handle);
231
238{
242};
243
252
253/* ========== GAP (Generic Access Profile) - Advertising ========== */
254
261{
265 uint16_t timeout_s;
267};
268
275{
278 uint16_t conn_latency;
280};
281
289using hal_ble_conn_state_cb_t = void (*)(hal_ble_conn_handle_t conn_handle);
298using hal_ble_disconn_state_cb_t = void (*)(hal_ble_conn_handle_t conn_handle, uint8_t reason);
299
306{
310};
311
312/* ========== Initialization & Lifecycle ========== */
313
323int32_t hal_ble_init(const char* device_name, const hal_ble_event_callbacks_t* callbacks);
324
332int32_t hal_ble_deinit(void);
333
340
341/* ========== GATT Database Setup ========== */
342
357int32_t hal_ble_add_service(hal_ble_service_t* service, const bool addToAdvertised);
358
371
385int32_t hal_ble_set_characteristic_value(hal_ble_char_handle_t char_handle, const uint8_t* data, uint16_t length);
386
397int32_t hal_ble_get_characteristic_value(hal_ble_char_handle_t char_handle, uint8_t* data, uint16_t max_length);
398
399/* ========== Notifications & Indications ========== */
400
415int32_t hal_ble_notify(hal_ble_char_handle_t char_handle, const uint8_t* data, uint16_t length);
416
433 hal_ble_char_handle_t char_handle,
434 const uint8_t* data,
435 uint16_t length);
436
437/* ========== Advertising Control ========== */
438
452
461
468
469/* ========== Connection Management ========== */
470
480
485
495
496/* ========== Security & Pairing ========== */
497
508
521
531
532/* ========== Device Information ========== */
533
542int32_t hal_ble_set_device_name(const char* name);
543
551int32_t hal_ble_get_device_name(char* name, uint16_t max_length);
552
563int32_t hal_ble_set_tx_power(int8_t tx_power_dbm);
564
571
572/* ========== Debugging & Status ========== */
573
580
588
598
603
608
609/* ========== Platform Capabilities ========== */
610
617{
618 HAL_BLE_FEATURE_BONDING,
619 HAL_BLE_FEATURE_LE_SECURE_CONNECTIONS,
622};
623
631
632/* ========== Constants ========== */
633
634#define HAL_BLE_INVALID_HANDLE (0xFFFF)
635#define HAL_BLE_MAX_DEVICE_NAME_LEN (31)
636#define HAL_BLE_MAX_ADV_DATA_LEN (31)
637#define HAL_BLE_MAX_CHARACTERISTICS (32)
638#define HAL_BLE_MAX_SERVICES (16)
639#define HAL_BLE_MIN_MTU (23)
640#define HAL_BLE_MAX_MTU (247)
642namespace services {
643
645namespace battery {
646
648void init(const uint8_t batteryLevel, const bool addToAdvertised);
649
651void write_battery_level(const uint8_t batteryLevel);
652
654void notify_battery_level(const uint8_t batteryLevel);
655
656} // namespace battery
657
659namespace uart {
660
662void init(const bool addToAdvertised);
663
666
669
671char read();
672
674void flush();
675
677size_t write(const char* const buffer, size_t bufferSize);
678
679} // namespace uart
680
681namespace system_infos {
682
683struct Infos
684{
685 const char* model;
686 const char* firmwareRev;
687 const char* hardwareRev;
688 const char* softwareRev;
689 const char* manufacturer;
690};
691
692void init(const Infos& sysInfos, const bool addToAdvertised);
693
694} // namespace system_infos
695
696} // namespace services
697
698} // namespace ble
699} // namespace hal
700} // namespace lampda
701
702#endif // HAL_BLE_H
uint8_t * initial_value
Definition: ble.h:190
int32_t hal_ble_notify(hal_ble_char_handle_t char_handle, const uint8_t *data, uint16_t length)
Send Notification to All Connected Centrals.
hal_ble_gatt_perm_t wPermissions
Definition: ble.h:194
uint8_t uuid128[16]
Definition: ble.h:74
int32_t hal_ble_clear_bonds(void)
Clear All Stored Bonds (Forget Paired Centrals)
int32_t hal_ble_set_characteristic_value(hal_ble_char_handle_t char_handle, const uint8_t *data, uint16_t length)
Update Characteristic Value.
hal_ble_read_callback_t read_cb
Definition: ble.h:195
uint16_t uuid16
Definition: ble.h:73
hal_ble_uuid_t uuid
Definition: ble.h:188
uint8_t hal_ble_get_connection_count(void)
Get Number of Active Connections.
bool is_notified_enabled()
Return true uart notify is activated.
int32_t hal_ble_add_service(hal_ble_service_t *service, const bool addToAdvertised)
Add a Service to GATT Database.
bool restartOnDisconnect
Definition: ble.h:266
int32_t hal_ble_start_pairing(hal_ble_conn_handle_t conn_handle)
Initiate Pairing from Peripheral Side.
bool include_tx_power
Definition: ble.h:264
hal_ble_disconn_state_cb_t on_disconnect
Definition: ble.h:308
uint16_t hal_ble_char_handle_t
Characteristic Descriptor Handle Storage.
Definition: ble.h:178
void init(const bool addToAdvertised)
Start the uart service.
char read()
Read a character (blocking)
bool hal_ble_is_initialized(void)
Check if BLE Stack is Initialized.
uint16_t max_conn_interval_ms
Definition: ble.h:277
uint16_t interval_max_ms
Definition: ble.h:263
void(*)() hal_ble_advertising_stops_cb_t
Advertising stopped callback.
Definition: ble.h:251
int32_t hal_ble_start_advertising(const hal_ble_adv_params_t *adv_params)
Start Advertising (Peripheral Becomes Discoverable)
bool is_available()
Return true if a char is available to read.
int32_t(*)(hal_ble_conn_handle_t conn_handle, uint16_t char_handle, uint8_t *data, uint16_t max_length) hal_ble_read_callback_t
Callback fired when Central reads a characteristic.
Definition: ble.h:171
int32_t hal_ble_init(const char *device_name, const hal_ble_event_callbacks_t *callbacks)
Initialize BLE Stack.
uint16_t interval_min_ms
Definition: ble.h:262
int32_t hal_ble_set_tx_power(int8_t tx_power_dbm)
Set TX Power (Transmit Power)
gap_addr_t hal_ble_get_address(hal_ble_conn_handle_t conn_handle)
Return the adress of the connected device.
uint16_t timeout_s
Definition: ble.h:265
bool hal_ble_has_feature(hal_ble_feature_t feature)
Check if Feature is Supported.
hal_ble_adress_type
Definition: ble.h:125
void(*)(hal_ble_conn_handle_t conn_handle) hal_ble_secure_cb_t
Connection secured Callback.
Definition: ble.h:230
bool hal_ble_is_connected(hal_ble_conn_handle_t conn_handle)
Get Connection State.
int8_t hal_ble_get_tx_power(void)
Get TX Power.
uint16_t conn_latency
Definition: ble.h:278
void(*)(hal_ble_conn_handle_t conn_handle) hal_ble_conn_state_cb_t
Connection State Change Callback.
Definition: ble.h:289
int32_t hal_ble_get_characteristic_value(hal_ble_char_handle_t char_handle, uint8_t *data, uint16_t max_length)
Read Current Characteristic Value.
bool mitm_required
Definition: ble.h:241
int32_t hal_ble_disconnect(hal_ble_conn_handle_t conn_handle)
Disconnect a Connected Central.
int32_t hal_ble_deinit(void)
Deinitialize BLE Stack.
int32_t hal_ble_set_security_config(const hal_ble_sec_config_t *sec_config)
Configure Security Parameters.
int8_t hal_ble_get_rssi(hal_ble_conn_handle_t conn_handle)
Get Connection Signal Strength (RSSI)
std::array< uint8_t, HAL_BLE_GAP_ADDR_LEN > addr
48-bit address, LSB format
Definition: ble.h:138
int32_t hal_ble_indicate(hal_ble_conn_handle_t conn_handle, hal_ble_char_handle_t char_handle, const uint8_t *data, uint16_t length)
Send Indication to a Specific Connected Central.
uint16_t hal_ble_conn_handle_t
Characteristic Read/Write Callback Context.
Definition: ble.h:146
hal_ble_gatt_prop_t properties
Definition: ble.h:192
bool hal_ble_can_load_bound_key(hal_ble_conn_handle_t conn_handle)
hal_ble_gatt_perm_t rPermissions
Definition: ble.h:193
bool hal_ble_is_advertising(void)
Check if Currently Advertising.
void flush()
Flush the rx queue.
hal_ble_write_callback_t write_cb
Definition: ble.h:196
hal_ble_char_handle_t handle
Definition: ble.h:187
uint16_t initial_length
Definition: ble.h:191
void(*)(hal_ble_conn_handle_t conn_handle, hal::ble::hal_ble_pairing_result code) hal_ble_pairing_complete_cb_t
Pairing Completed Callback.
Definition: ble.h:221
uint16_t max_length
Definition: ble.h:189
int32_t hal_ble_get_device_name(char *name, uint16_t max_length)
Get Device Name.
void(*)(hal_ble_conn_handle_t conn_handle, const uint8_t *data, uint16_t length) hal_ble_write_callback_t
Callback fired when Central writes to a characteristic.
Definition: ble.h:155
hal_ble_pairing_complete_cb_t on_pairing_done
Definition: ble.h:239
void notify_battery_level(const uint8_t batteryLevel)
notify the connected device of a battery level (0-100)
void init(const uint8_t batteryLevel, const bool addToAdvertised)
Init the service, with an initial value (0-100)
hal_ble_secure_cb_t on_secured
Definition: ble.h:240
int32_t hal_ble_add_characteristic(hal_ble_characteristic_t *characteristic)
Add a Characteristic to the Current Service.
uint16_t min_conn_interval_ms
Definition: ble.h:276
hal_ble_feature_t
Query BLE Feature Support.
Definition: ble.h:617
hal_ble_conn_handle_t hal_ble_get_connection_handle()
Return the current connection handle.
void write_battery_level(const uint8_t batteryLevel)
update battery level (0-100)
int32_t hal_ble_get_mtu(hal_ble_conn_handle_t conn_handle)
Get Current MTU (Maximum Transmission Unit) Size.
hal_ble_adress_type type
address type
Definition: ble.h:137
hal_ble_advertising_stops_cb_t on_advertising_stops
Definition: ble.h:309
hal_ble_conn_state_cb_t on_connect
Definition: ble.h:307
size_t write(const char *const buffer, size_t bufferSize)
Write a buffer to connected device.
hal_ble_uuid_t uuid
Definition: ble.h:207
int32_t hal_ble_set_device_name(const char *name)
Set Device Name.
void(*)(hal_ble_conn_handle_t conn_handle, uint8_t reason) hal_ble_disconn_state_cb_t
Disconnection State Change Callback.
Definition: ble.h:298
const char * descriptor
Definition: ble.h:197
uint16_t supervision_timeout_ms
Definition: ble.h:279
int32_t hal_ble_stop_advertising(void)
Stop Advertising.
@ RANDOM_PRIVATE_RESOLVABLE
Random private resolvable address.
@ RANDOM_STATIC
Random static (identity) address.
@ ANONYMOUS
An advertiser may advertise without its address. This type of advertising is called anonymous.
@ RANDOM_PRIVATE_NON_RESOLVABLE
Random private non-resolvable address.
@ INVALID
Public (identity) address.
@ PUBLIC
Public (identity) address.
hal_ble_gatt_prop_t
GATT Characteristic Properties.
Definition: ble.h:99
hal_ble_pairing_result
pairing result code
Definition: ble.h:112
@ AUTH_REQ
Authentication requirements not met.
@ REPEATED_ATTEMPTS
Too little time elapsed since last attempt.
@ PAIRING_NOT_SUPP
Pairing not supported.
hal_ble_gatt_perm_t
GATT (Generic Attribute Profile) Attribute Permissions.
Definition: ble.h:86
hal_ble_uuid_type_t
UUID (Universally Unique Identifier) type.
Definition: ble.h:60
Program scope.
Definition: control_fixed_modes.hpp:14
Definition: ble.h:136
Advertising Parameters.
Definition: ble.h:261
GATT Characteristic Definition.
Definition: ble.h:186
Connection Parameters.
Definition: ble.h:275
BLE Event Callback Collection.
Definition: ble.h:306
Security Configuration.
Definition: ble.h:238
GATT Service Definition.
Definition: ble.h:206
UUID structure (supports both 16-bit and 128-bit)
Definition: ble.h:69