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.

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: Maximum length in out buffer, out: Advertisement length

Returns:

  • 0 on success

  • Non-zero on failure

group Hubble Network APIs

Hubble Network SDK APIs.

Functions

int hubble_init(uint64_t utc_time, const void *key)

Initializes the Hubble.

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

uint64_t current_utc_time = 1633072800000; // Example UTC time in milliseconds
static uint8_t master_key[CONFIG_HUBBLE_KEY_SIZE] = {...};
int ret = hubble_init(current_utc_time, master_key);
Parameters:

  • utc_time – The UTC time in milliseconds since the Unix epoch (January 1, 1970). Set to 0 to set later via hubble_utc_set

  • key – An opaque pointer to the key. If NULL, must be set with hubble_key_set before getting advertisements.

Returns:

  • 0 on success.

  • Non-zero on failure.

int hubble_utc_set(uint64_t utc_time)

Sets the current UTC time in the Hubble SDK.

Parameters:

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

Returns:

  • 0 on success.

  • Non-zero on failure.

int hubble_key_set(const void *key)

Sets the encryption key for advertisement data creation.

Parameters:

key – An opaque pointer to the key.

Returns:

  • 0 on success.

  • Non-zero on failure.

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_BLE_NONCE_BUFFER_LEN], 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_BLE_NONCE_BUFFER_LEN).

  • 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.