Modem API Reference
The Blecon Device SDK provides a developer interface to the Blecon modem.
Overview
Macros
Enumerations
Data Structures
Callbacks structure to populate by user.
Callbacks structure to populate by user for requests.
A structure used to build a request based on its attributes.
Functions
Create new internal modem instance.
Destroy internal modem instance.
Create new external modem instance.
Destroy external modem instance.
Initialise Blecon.
Set-up Blecon.
Set callbacks.
Get information about the modem.
Set application-related data.
Announce the device ID to surrounding hotspots.
Initiate a connection to the Blecon infrastructure.
Terminate the current connection, or cancel the connection attempt.
Check if a connection is established.
Get the device's ID in URL form.
Get the device's ID in UUID form.
Get the current global synchronized time.
Perform a ping to the Blecon infrastructure.
Cancel a ping to the Blecon infrastructure.
Get latency information from the last ping.
Start a peer scanning session.
Stop the current peer scanning session.
Get the data from the last peer scan.
Submit a request for processing.
Get a request processor.
Initialise a request.
Retrieve a request's parameters.
Get the status of a request.
Send data for a request.
Get the user data associated with a send data operation.
Start a receiving operation.
Get the user data associated with a receive data operation.
Clean-up a request.
Macros
Enumerations
Data Structures
struct blecon_callbacks_t
Callbacks structure to populate by user.
Members
void(*)(struct blecon_t *blecon)on_connection
Called when a blecon connection is open.
void(*)(struct blecon_t *blecon)on_disconnection
Called when a blecon connection is closed.
void(*)(struct blecon_t *blecon)on_time_update
Called when time is updated from the Blecon infrastructure.
void(*)(struct blecon_t *blecon)on_ping_result
Called when a ping is completed.
void(*)(struct blecon_t *blecon)on_scan_report
Called when a scan report is available.
void(*)(struct blecon_t *blecon)on_scan_complete
Called when a scan completed.
struct blecon_request_callbacks_t
Callbacks structure to populate by user for requests.
Members
void(*)(struct blecon_request_t *request)on_closed
Called when a request has completed and all data has been sent and received by the modem, or when the request terminated with an error.
void(*)(struct blecon_request_send_data_op_t *send_data_op, bool data_sent)on_data_sent
Called when the data set in blecon_request_send_data() has been sent.
uint8_t *(*)(struct blecon_request_receive_data_op_t *receive_data_op, size_t sz)alloc_incoming_data_buffer
Allocate memory for incoming data.
void(*)(struct blecon_request_receive_data_op_t *receive_data_op, bool data_received, const uint8_t *data, size_t sz, bool finished)on_data_received
Called when new data is received for a request.
struct blecon_request_parameters_t
A structure used to build a request based on its attributes.
Members
booloneway
If true, the request is one-way (no response expected)
const char *method
< The namespace of this request's event type (maximum BLECON_NAMESPACE_MAX_SZ characters, including null terminator) or NULL
const char *request_content_type
The content type of the request (e.g. application/cbor, maximum BLECON_CONTENT_TYPE_MAX_SZ characters, including null terminator) or NULL.
const char *response_content_type
The expected content type of the response (e.g. application/cbor, maximum BLECON_CONTENT_TYPE_MAX_SZ characters, including null terminator) or NULL.
size_tresponse_mtu
The maximum size of a response data frame (for a single data operation, maximum BLECON_MTU)
const struct blecon_request_callbacks_t *callbacks
The callbacks to use for this request.
void *user_data
User data to pass to the callbacks.
Functions
blecon_int_modem_create()
struct blecon_modem_t * blecon_int_modem_create(struct blecon_event_loop_t * event_loop, struct blecon_timer_t * timer, struct blecon_bluetooth_t * bluetooth, struct blecon_crypto_t * crypto, struct blecon_nvm_t * nvm, struct blecon_nfc_t * nfc, size_t scan_buffer_size, void *(*)(size_t) allocator)Create new internal modem instance.
Parameters
event_loop
a platform-specific event loop instance
timer
a platform-specific timer instance
bluetooth
a platform-specific bluetooth instance
crypto
a platform-specific crypto instance
nvm
a platform-specific nvm instance
nfc
a platform-specific nfc instance
scan_buffer_size
the size of the scan buffer
allocator
a function to allocate memory
Returns
a pointer to a struct blecon_modem_t instance
blecon_int_modem_destroy()
void blecon_int_modem_destroy(struct blecon_modem_t * modem, void(*)(void *) deallocator)Destroy internal modem instance.
Parameters
modem
a pointer to a struct blecon_modem_t instance created by blecon_int_modem_create()
deallocator
a function to deallocate memory or NULL
blecon_ext_modem_create()
struct blecon_modem_t * blecon_ext_modem_create(struct blecon_event_loop_t * event_loop, struct blecon_ext_modem_transport_t * transport, void *(*)(size_t) allocator)Create new external modem instance.
Parameters
event_loop
a platform-specific event loop instance
transport
a platform-specific transport instance
allocator
a function to allocate memory
Returns
a pointer to a struct blecon_modem_t instance
blecon_ext_modem_destroy()
void blecon_ext_modem_destroy(struct blecon_modem_t * modem, void(*)(void *) deallocator)Destroy external modem instance.
Parameters
modem
a pointer to a struct blecon_modem_t instance created by blecon_ext_modem_create()
deallocator
a function to deallocate memory or NULL
blecon_init()
void blecon_init(struct blecon_t * blecon, struct blecon_modem_t * modem)Initialise Blecon.
Parameters
blecon
the blecon instance to initialise
modem
the modem instance to use
blecon_setup()
bool blecon_setup(struct blecon_t * blecon)Set-up Blecon.
Parameters
blecon
the blecon instance to set-up
Returns
true on success, or false on failure
blecon_set_callbacks()
void blecon_set_callbacks(struct blecon_t * blecon, const struct blecon_callbacks_t * callbacks, void * user_data)Set callbacks.
Parameters
blecon
the blecon instance
callbacks
a struct blecon_modem_callbacks_t structure containing the user's callbacks
user_data
user data to pass to the callbacks
blecon_get_info()
void blecon_get_info(struct blecon_t * blecon, struct blecon_modem_info_t * info)Get information about the modem.
Parameters
blecon
the blecon instance
info
a pointer to a struct blecon_modem_info_t structure which is populated on success
blecon_set_application_data()
bool blecon_set_application_data(struct blecon_t * blecon, const uint8_t * application_model_id, uint32_t application_schema_version)Set application-related data.
Parameters
blecon
the blecon instance
application_model_id
the device's specific model id encoded as a UUID (16 bytes long)
application_schema_version
the device's schema version
Returns
true on success, or false on failure
blecon_announce()
bool blecon_announce(struct blecon_t * blecon)Announce the device ID to surrounding hotspots.
Parameters
blecon
the blecon instance
Returns
true on success, or false on failure
blecon_connection_initiate()
bool blecon_connection_initiate(struct blecon_t * blecon)Initiate a connection to the Blecon infrastructure.
Parameters
blecon
the blecon instance
Returns
true on success, or false on failure
blecon_connection_terminate()
bool blecon_connection_terminate(struct blecon_t * blecon)Terminate the current connection, or cancel the connection attempt.
Parameters
blecon
the blecon instance
Returns
true on success, or false on failure
blecon_is_connected()
bool blecon_is_connected(struct blecon_t * blecon)Check if a connection is established.
Parameters
blecon
the blecon instance
Returns
true if connected, or false if not
blecon_get_url()
bool blecon_get_url(struct blecon_t * blecon, char * url, size_t max_sz)Get the device's ID in URL form.
Parameters
blecon
the blecon instance
url
a char array where to store the url (0-terminated)
max_sz
the maximum size of the array (including space for 0 terminator)
Returns
true on success, or false on failure
blecon_get_identity()
bool blecon_get_identity(struct blecon_t * blecon, uint8_t * uuid)Get the device's ID in UUID form.
Parameters
blecon
the blecon instance
uuid
a 16-byte array where to store the uuid
Returns
true on success, or false on failure
blecon_get_time()
bool blecon_get_time(struct blecon_t * blecon, bool * time_valid, uint64_t * utc_time_ms_now, uint64_t * utc_time_ms_last_updated)Get the current global synchronized time.
Parameters
blecon
the blecon instance
time_valid
a pointer to a bool which is set to true if the time is valid
utc_time_ms_now
a pointer to a uint64_t where the current time is stored
utc_time_ms_last_updated
a pointer to a uint64_t where the time of last update is stored
Returns
true on success, or false on failure
blecon_ping_perform()
bool blecon_ping_perform(struct blecon_t * blecon, uint32_t timeout_ms)Perform a ping to the Blecon infrastructure.
Parameters
blecon
the blecon instance
timeout_ms
the timeout in milliseconds
Returns
true on success, or false on failure
blecon_ping_cancel()
bool blecon_ping_cancel(struct blecon_t * blecon)Cancel a ping to the Blecon infrastructure.
Parameters
blecon
the blecon instance
Returns
true on success, or false on failure
blecon_ping_get_latency()
bool blecon_ping_get_latency(struct blecon_t * blecon, bool * latency_available, uint32_t * connection_latency_ms, uint32_t * round_trip_latency_ms)Get latency information from the last ping.
Parameters
blecon
the blecon instance
latency_available
a pointer to a bool which is set to true if the latency is available
connection_latency_ms
a pointer to a uint32_t where the connection latency is stored (milliseconds)
round_trip_latency_ms
a pointer to a uint32_t where the round trip latency is stored (milliseconds)
Returns
true on success, or false on failure
blecon_scan_start()
bool blecon_scan_start(struct blecon_t * blecon, bool peer_scan, bool raw_scan, uint32_t duration_ms)Start a peer scanning session.
Parameters
blecon
the blecon instance
peer_scan
true to report peer devices
raw_scan
true to report raw advertising data
duration_ms
the duration of the scan in milliseconds
Returns
true on success, or false on failure
blecon_scan_stop()
bool blecon_scan_stop(struct blecon_t * blecon)Stop the current peer scanning session.
Parameters
blecon
the blecon instance
Returns
true on success, or false on failure
blecon_scan_get_data()
bool blecon_scan_get_data(struct blecon_t * blecon, void(*)(const struct blecon_modem_peer_scan_report_t *report, void *user_data) peer_scan_report_iterator, void(*)(const struct blecon_modem_raw_scan_report_t *report, void *user_data) raw_scan_report_iterator, bool * overflow, void * user_data)Get the data from the last peer scan.
Parameters
blecon
the blecon instance
peer_scan_report_iterator
a function to call for each peer device report; if NULL, no peer device reports are returned
raw_scan_report_iterator
a function to call for each raw advertising data report; if NULL, no raw advertising data reports are returned
overflow
a pointer to a bool which is set to true if the scan data buffer overflowed
user_data
user data to pass to the report iterator callbacks
Returns
true on success, or false on failure
blecon_submit_request()
void blecon_submit_request(struct blecon_t * blecon, struct blecon_request_t * request)Submit a request for processing.
Parameters
blecon
the blecon instance
request
the request to submit
blecon_get_request_processor()
struct blecon_request_processor_t * blecon_get_request_processor(struct blecon_t * blecon)Get a request processor.
Parameters
blecon
the blecon instance
Returns
a pointer to a struct blecon_request_processor_t instance
blecon_request_init()
void blecon_request_init(struct blecon_request_t * request, const struct blecon_request_parameters_t * parameters)Initialise a request.
Parameters
request
the request instance to initialise
parameters
a struct blecon_request_parameters_t structure containing the request's parameters
blecon_request_get_parameters()
const struct blecon_request_parameters_t * blecon_request_get_parameters(struct blecon_request_t * request)Retrieve a request's parameters.
Parameters
request
the request instance
Returns
a pointer to the request's parameters
blecon_request_get_status()
enum blecon_request_status_code_t blecon_request_get_status(struct blecon_request_t * request)Get the status of a request.
Parameters
request
the request instance
Returns
the status code of the request
blecon_request_send_data()
bool blecon_request_send_data(struct blecon_request_send_data_op_t * op, struct blecon_request_t * request, const uint8_t * data, size_t sz, bool finished, void * user_data)Send data for a request.
Parameters
op
a pointer to a struct blecon_request_send_data_op_t structure which is populated on success
request
a pointer to the relevant request structure
data
the data to send
sz
the size of the data buffer (maximum BLECON_MTU)
finished
a flag indicating if this is the end of the data
user_data
a pointer to user-defined data which will be associated with the operation
Returns
true if the operation was queued successfully, or false on failure
blecon_request_send_data_op_get_user_data()
void * blecon_request_send_data_op_get_user_data(struct blecon_request_send_data_op_t * op)Get the user data associated with a send data operation.
Parameters
op
the send data operation instance
Returns
a pointer to the user data
blecon_request_receive_data()
bool blecon_request_receive_data(struct blecon_request_receive_data_op_t * op, struct blecon_request_t * request, void * user_data)Start a receiving operation.
Parameters
op
a pointer to a struct blecon_request_receive_data_op_t structure which is populated on success
request
a pointer to the relevant request structure
user_data
a pointer to user-defined data which will be associated with the operation
Returns
true if the operation was queued successfully, or false on failure
blecon_request_receive_data_op_get_user_data()
void * blecon_request_receive_data_op_get_user_data(struct blecon_request_receive_data_op_t * op)Get the user data associated with a receive data operation.
Parameters
op
the receive data operation instance
Returns
a pointer to the user data
blecon_request_cleanup()
void blecon_request_cleanup(struct blecon_request_t * request)Clean-up a request.
Parameters
request
the request to clean-up
Last updated