BLE Network API

group BLE Network Function APIs

Hubble BLE Network Function APIs.

Defines

HUBBLE_BLE_UUID

Hubble BLE Network UUID.

This is the UUID should be listed in the services list.

HUBBLE_BLE_MAX_DATA_LEN

Maximum amount of data sendable in bytes.

This is the maximum length of data that can be sent with Hubble. If other services or service data are advertised then this number will be smaller for your application given the finite length of advertisements.

HUBBLE_BLE_ADV_HEADER_SIZE

Fixed header size of a Hubble BLE advertisement in bytes.

Every advertisement produced by hubble_ble_advertise_get contains this many fixed-overhead bytes (UUID prefix, device address, and authentication tag) before any caller-supplied data.

Use this to size the output buffer: 

uint8_t buf[HUBBLE_BLE_ADV_HEADER_SIZE + my_data_len];
size_t buf_len = sizeof(buf);
hubble_ble_advertise_get(data, my_data_len, buf, &buf_len);

The maximum possible output length is: 

HUBBLE_BLE_ADV_HEADER_SIZE + HUBBLE_BLE_MAX_DATA_LEN   // = 25 bytes

Functions

int hubble_ble_advertise_get(const uint8_t *input, size_t input_len, uint8_t *out, size_t *out_len)

Retrieves advertisements from the provided data.

This function processes the input data and creates the advertisement payload. The returned data should be used with Service Data - 16 bit UUID advertisement type (0x16).

It is also required to add Hubble 16-bit service UUID in the complete list of 16-bit service class UUID (0x03).

Example:

int status = hubble_ble_advertise_get(data, data_len, out, &out_len);

The following advertisement packet shows a valid example and where the returned data fits in.

| len   | ad type | data   | len                  | ad type | data       |
|-------+---------+--------+----------------------+---------+------------|
| 0x03  | 0x03    | 0xFCA6 | out_len + 0x01       | 0x16    | ad_data    |
|       |         |        | (ad type len)        |         |            |
|       |         |        | (out_len is adv_data |         |            |
|       |         |        |  len - returned by   |         |            |
|       |         |        |  this API)           |         |            |

Note

- This function is neither thread-safe nor reentrant. The caller must ensure proper synchronization.

  • The payload is encrypted using the key set by hubble_key_set

  • Legacy packet type (Extended Advertisements not supported)

Parameters:

  • input – Pointer to the input data.

  • input_len – Length of the input data.

  • out – Output buffer to place data into

  • out_len – in: Size of the out buffer in bytes. Must be at least HUBBLE_BLE_ADV_HEADER_SIZE + input_len. out: Actual advertisement length written.

Returns:

  • 0 on success

  • Non-zero on failure

uint32_t hubble_ble_advertise_expiration_get(void)

Gets the time remaining until the BLE advertisement expires.

Returns the number of milliseconds until the current BLE advertisement expires and a new one should be generated. This helps applications refresh their advertisements in synchronization with the EID rotation period.

Returns:

Milliseconds until the current advertisement expires.