BLE Network API Reference

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.

group Hubble Network APIs

Hubble Network SDK APIs.

Functions

int hubble_init(uint64_t initial_time, const void *key)

Initializes the Hubble SDK.

Calling this function is essential before using any other SDK APIs.

The interpretation of the initial_time parameter depends on the configured counter source:

Unix time mode (CONFIG_HUBBLE_COUNTER_SOURCE_UNIX_TIME):

initial_time is the time in milliseconds since Unix epoch
Value of 0 is invalid and will return an error
Time can be updated later via hubble_time_set()

Device uptime mode (CONFIG_HUBBLE_COUNTER_SOURCE_DEVICE_UPTIME):

initial_time is the initial counter value
Value of 0 starts the counter at epoch 0 (valid)
The counter increments based on uptime from this initial value
Useful for resuming from a known state after reboot

// Unix time mode example
uint64_t unix_time_ms = 1705881600000; // Current Unix Epoch time
int ret = hubble_init(unix_time_ms, master_key);

// Device uptime mode example (start at 0)
int ret = hubble_init(0, master_key);

// Device uptime mode example (resume from saved counter)
uint64_t saved_counter = load_from_flash();
int ret = hubble_init(saved_counter, master_key);

Parameters:

initial_time – For Unix time mode: Unix time in milliseconds since epoch. For device uptime mode: Initial counter value (0 = start at 0).
key – An opaque pointer to the master key buffer. The SDK stores this pointer directly and does not copy the key data. The caller must ensure the buffer remains valid for the lifetime of SDK usage (do not use stack or temporary buffers). The key size must match CONFIG_HUBBLE_NETWORK_KEY_256 or CONFIG_HUBBLE_NETWORK_KEY_128. If NULL, must be set with hubble_key_set before getting advertisements.

Returns:

0 on success.
Non-zero on failure.

int hubble_time_set(uint64_t unix_time)

Sets the current Unix time in the Hubble SDK.

Parameters:

unix_time – The Unix Epoch time in milliseconds since the Unix epoch (January 1, 1970).

Returns:

0 on success.
Non-zero on failure.

uint64_t hubble_time_get(void)

Gets the current time.

Gets the time in milliseconds since the Unix epoch (January 1, 1970).

Returns:

0 if time is not set.
current time since the Unix epoch.

int hubble_key_set(const void *key)

Sets the encryption key for advertisement data creation.

Parameters:

key – An opaque pointer to the master key buffer. The SDK stores this pointer directly and does not copy the key data. The caller must ensure the buffer remains valid for the lifetime of SDK usage. The key size must match CONFIG_HUBBLE_NETWORK_KEY_256 or CONFIG_HUBBLE_NETWORK_KEY_128.

Returns:

0 on success.
Non-zero on failure.

int hubble_counter_get(uint32_t *counter)

Get the current time counter value.

Returns the time counter based on the configured counter source:

Device uptime: Uses uptime-derived counter with initial offset, wrapping at HUBBLE_EID_POOL_SIZE (128) to produce values in [0, pool_size-1]
Unix time: Uses Unix time divided by rotation period (no wrapping)

Parameters:: counter – Pointer to store the time counter value
Returns:: 0 on success, negative error code on failure (Unix time mode only, if time not set)

group Hubble Network Crypto APIs

Hubble Network SDK Crypto APIs.

Cryptographic functions that need to be implemented by a crypto provider.

Functions

void hubble_crypto_zeroize(void *buf, size_t len)

Securely clear out a memory region.

This function is used to securely overwrite a memory buffer with zeros, ensuring that sensitive data is erased.

Parameters:

buf – Pointer to the input data.
len – Length of the input data.

int hubble_crypto_init(void)

Cryptographic initialization.

This function must be called before any other cryptographic function otherwise the behavior is undefined.

Returns:: 0 on success, non-zero on error.

int hubble_crypto_aes_ctr(const uint8_t key[CONFIG_HUBBLE_KEY_SIZE], uint8_t nonce_counter[HUBBLE_NONCE_BUFFER_SIZE], const uint8_t *data, size_t len, uint8_t *output)

Perform AES encryption in Counter (CTR) mode.

Parameters:

key – A pointer to the encryption key (size: CONFIG_HUBBLE_KEY_SIZE).
nonce_counter – A pointer to the nonce and counter buffer (size: HUBBLE_NONCE_BUFFER_SIZE).
data – A pointer to the input data buffer to be encrypted.
len – The length of the input data in bytes.
output – A pointer to the output buffer where the encrypted data will be stored. It must be at least the size of the input data in bytes.

Returns:

Returns 0 on success, or a non-zero error code on failure.

int hubble_crypto_cmac(const uint8_t key[CONFIG_HUBBLE_KEY_SIZE], const uint8_t *data, size_t len, uint8_t output[HUBBLE_AES_BLOCK_SIZE])

Computes the Cipher-based Message Authentication Code (CMAC).

Parameters:

key – The secret key used for CMAC calculation. The size of the key is defined by CONFIG_HUBBLE_KEY_SIZE.
data – Pointer to the input data for which the CMAC is calculated.
len – The length of the input data in bytes.
output – Pointer to the buffer where the CMAC (message authentication code) will be stored. This buffer must be large enough to hold the CMAC value (typically the size of the AES block, 16 bytes).

Returns:

0 on success, non-zero on error.