Modem API Reference
The Blecon Device SDK provides a developer interface to the Blecon modem.
The Blecon SDK is available on GitHub. This document refers to SDK Version 2.0.1.
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 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
on_connection
Called when a blecon connection is open.
on_disconnection
Called when a blecon connection is closed.
on_time_update
Called when time is updated from the Blecon infrastructure.
on_ping_result
Called when a ping is completed.
on_scan_report
Called when a scan report is available.
on_scan_complete
Called when a scan completed.
struct blecon_request_callbacks_t
Callbacks structure to populate by user for requests.
Members
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.
on_data_sent
alloc_incoming_data_buffer
Allocate memory for incoming data.
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
oneway
If true, the request is one-way (no response expected)
method
< The namespace of this request's event type (maximum BLECON_NAMESPACE_MAX_SZ characters, including null terminator) or NULL
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.
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.
response_mtu
The maximum size of a response data frame (for a single data operation, maximum BLECON_MTU)
callbacks
The callbacks to use for this request.
user_data
User data to pass to the callbacks.
Functions
blecon_int_modem_create()
Create new internal modem instance.
Parameters
event_loop
a platform-specific event loop 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()
Destroy internal modem instance.
Parameters
modem
deallocator
a function to deallocate memory or NULL
blecon_ext_modem_create()
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()
Destroy external modem instance.
Parameters
modem
deallocator
a function to deallocate memory or NULL
blecon_init()
Initialise Blecon.
Parameters
blecon
the blecon instance to initialise
modem
the modem instance to use
blecon_setup()
Set-up Blecon.
Parameters
blecon
the blecon instance to set-up
Returns
true on success, or false on failure
blecon_set_callbacks()
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()
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()
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()
Announce the device ID to surrounding hotspots.
Parameters
blecon
the blecon instance
Returns
true on success, or false on failure
blecon_connection_initiate()
Initiate a connection to the Blecon infrastructure.
Parameters
blecon
the blecon instance
Returns
true on success, or false on failure
blecon_connection_terminate()
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()
Check if a connection is established.
Parameters
blecon
the blecon instance
Returns
true if connected, or false if not
blecon_get_url()
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()
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()
Get the current 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()
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()
Cancel a ping to the Blecon infrastructure.
Parameters
blecon
the blecon instance
Returns
true on success, or false on failure
blecon_ping_get_latency()
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()
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()
Stop the current peer scanning session.
Parameters
blecon
the blecon instance
Returns
true on success, or false on failure
blecon_scan_get_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()
Submit a request for processing.
Parameters
blecon
the blecon instance
request
the request to submit
blecon_get_request_processor()
Get a request processor.
Parameters
blecon
the blecon instance
Returns
a pointer to a struct blecon_request_processor_t instance
blecon_request_init()
Initialise a request.
Parameters
request
the request instance to initialise
parameters
blecon_request_get_parameters()
Retrieve a request's parameters.
Parameters
request
the request instance
Returns
a pointer to the request's parameters
blecon_request_get_status()
Get the status of a request.
Parameters
request
the request instance
Returns
the status code of the request
blecon_request_send_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()
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()
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()
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()
Clean-up a request.
Parameters
request
the request to clean-up
Last updated