Nordic BLE Interfaces
This collection of BLE interfaces can be used with almost any Nordic processor running an application built with the nRF Connect SDK and running Zephyr RTOS.
NUS Service
The BLENUSService provides read and write functions for communicating over the Nordic UART Service (NUS).
This service mimics a traditional UART interface over BLE.
BLENUSService
Provies an interface to read and write data via the Nordic UART Service (NUS).
__init__(client)
Construct a new BLENUSService object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
BLEClient
|
BLEClient object to use for communication |
required |
set_nus_received_cb(received_cb)
async
Set the callback that is called when data is received.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
received_cb
|
Callable[[str, bytearray], None]
|
Callback that will receive the UUID and received data when a notification arrives |
required |
Returns:
| Type | Description |
|---|---|
None
|
None |
write_nus(data)
async
Write data to the NUS characteristic.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
bytearray
|
Data to send over NUS |
required |
Returns:
| Type | Description |
|---|---|
None
|
None |
SMP Service
Nordic devices running the Zephyr RTOS support the Simple Management Protocol, or SMP. This message protocol allows access to various operating system resources such as images, file systems, and OS usage statistics. In order for this service to work, SMP and the various command groups must be enabled in your project configuration.
BLESMPService
Provides an interface to send and receive SMP messages over Nordic's SMP Transport.
__init__(client)
Construct a new BLESMPService object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
BLEClient
|
BLEClient object to use for communication |
required |
_get_smp_header(operation, data_length, group, sequence, command)
staticmethod
Internal function to return an SMP header buffer specifically for image management
:meta private:
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
operation
|
Type of SMP operation to execute |
required | |
data_length
|
int
|
Length of SMP payload data |
required |
group
|
int
|
Group number |
required |
sequence
|
int
|
Sequence number (usually 0) |
required |
command
|
int
|
Command number |
required |
_parse_smp_header(header_bytes)
staticmethod
Internal function to return an SMP header buffer specifically for image management
:meta private:
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
header_bytes
|
bytearray
|
Header bytes to decode |
required |
_smp_rx_cb(char_uuid, data)
Internal function that acts as an SMP received callback. Sets an event to notify the class that new data has been received, and sets the global response object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
char_uuid
|
str
|
Characteristic over which the data was received |
required |
data
|
bytearray
|
Received data |
required |
write_smp_and_response(data, timeout=10)
async
Write SMP data and wait for a response based on a timeout
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
bytearray
|
Byte data to write to SMP characteristic |
required |
timeout
|
Timeout of operation (in seconds) |
10
|
Returns:
| Type | Description |
|---|---|
|
Response object as a dictionary |
DFU Service
Device Firmware Update (DFU) is accomplished via the image management commands of SMP. This service builds off of
BLESMPService to allow image management. Typically, the DFU process contains the following steps:
- Call
get_state_of_imagesto get the current image state - Call
image_uploadto upload the binary to the device - Call
get_state_of_imagesto ensure the image was uploaded, and retrieve the image's hash - Call
set_state_of_imageto either set the image for test, or permanent swap
Further information about the image management process can be found here.
BLEDFUService
Bases: BLESMPService
A service for performing device image management over SMP.
__init__(client)
Construct a new BLEDFUService object.
_build_image_upload_payload(image_num, image_path, offset, image_total_size, hash_str)
Internal function to build an SMP payload for the image upload
erase_image(slot)
async
Erase an image by slot and return the response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
slot
|
int
|
Slot of image to erase (usually 1, the DFU slot) |
required |
Returns:
| Type | Description |
|---|---|
|
Response object as dictionary |
get_image_version(image_path)
staticmethod
Return the version of an MCU boot update binary.
Returns:
| Type | Description |
|---|---|
tuple[int, int, int, int] | None
|
Version as a tuple of (major, minor, revision, build num), None if parsing failed or image doesn't exist |
get_state_of_images(verbose=True)
async
Performs a request over SMP to get the state of images. The format of the response can be found
here <https://docs.zephyrproject.org/latest/services/device_mgmt/smp_groups/smp_group_1.html#get-state-of-images-response>
Returns:
| Type | Description |
|---|---|
|
Response object as dictionary |
image_upload(image_path, on_update=None)
async
Upload an image to the second image slot of the device. This method will upload the entire image which could take several minutes depending on the size of the image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image_path
|
str
|
Absolute path to the image binary file (relative paths may not work correctly) |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Status of operation (True on success, False on error) |
print_state_of_images(rsp)
staticmethod
Prints the status of of the image partitions
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rsp
|
Image management retrieved from the SMP header buffer |
required |
set_state_of_image(hash_str, confirm, verbose=True)
async
Performs a request over SMP to set the state of an image.
More information: https://docs.zephyrproject.org/latest/services/device_mgmt/smp_groups/smp_group_1.html#set-state-of-image-request
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hash_str
|
str
|
Hash of image to set the state of |
required |
confirm
|
bool
|
If “confirm” is false or not provided, an image with the “hash” will be set for test, which means that it will not be marked as permanent and upon hard reset the previous application will be restored to the primary slot. In case when “confirm” is true, the “hash” is optional as the currently running application will be assumed as target for confirmation. |
required |
Returns:
| Type | Description |
|---|---|
|
Response object as dictionary |
BLESMPService
Provides an interface to send and receive SMP messages over Nordic's SMP Transport.
__init__(client)
Construct a new BLESMPService object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
BLEClient
|
BLEClient object to use for communication |
required |
_get_smp_header(operation, data_length, group, sequence, command)
staticmethod
Internal function to return an SMP header buffer specifically for image management
:meta private:
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
operation
|
Type of SMP operation to execute |
required | |
data_length
|
int
|
Length of SMP payload data |
required |
group
|
int
|
Group number |
required |
sequence
|
int
|
Sequence number (usually 0) |
required |
command
|
int
|
Command number |
required |
_parse_smp_header(header_bytes)
staticmethod
Internal function to return an SMP header buffer specifically for image management
:meta private:
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
header_bytes
|
bytearray
|
Header bytes to decode |
required |
_smp_rx_cb(char_uuid, data)
Internal function that acts as an SMP received callback. Sets an event to notify the class that new data has been received, and sets the global response object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
char_uuid
|
str
|
Characteristic over which the data was received |
required |
data
|
bytearray
|
Received data |
required |
write_smp_and_response(data, timeout=10)
async
Write SMP data and wait for a response based on a timeout
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
bytearray
|
Byte data to write to SMP characteristic |
required |
timeout
|
Timeout of operation (in seconds) |
10
|
Returns:
| Type | Description |
|---|---|
|
Response object as a dictionary |
Shell Service
Zephyr's built-in Shell subsystem has several backends, one of which is SMP. This interface class allows sending and receiving of shell commands via SMP over BLE.
BLESMPService
Provides an interface to send and receive SMP messages over Nordic's SMP Transport.
__init__(client)
Construct a new BLESMPService object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
BLEClient
|
BLEClient object to use for communication |
required |
_get_smp_header(operation, data_length, group, sequence, command)
staticmethod
Internal function to return an SMP header buffer specifically for image management
:meta private:
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
operation
|
Type of SMP operation to execute |
required | |
data_length
|
int
|
Length of SMP payload data |
required |
group
|
int
|
Group number |
required |
sequence
|
int
|
Sequence number (usually 0) |
required |
command
|
int
|
Command number |
required |
_parse_smp_header(header_bytes)
staticmethod
Internal function to return an SMP header buffer specifically for image management
:meta private:
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
header_bytes
|
bytearray
|
Header bytes to decode |
required |
_smp_rx_cb(char_uuid, data)
Internal function that acts as an SMP received callback. Sets an event to notify the class that new data has been received, and sets the global response object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
char_uuid
|
str
|
Characteristic over which the data was received |
required |
data
|
bytearray
|
Received data |
required |
write_smp_and_response(data, timeout=10)
async
Write SMP data and wait for a response based on a timeout
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
bytearray
|
Byte data to write to SMP characteristic |
required |
timeout
|
Timeout of operation (in seconds) |
10
|
Returns:
| Type | Description |
|---|---|
|
Response object as a dictionary |
BLEShellService
Bases: BLESMPService
A service for performing shell operations over SMP.
__init__(client)
Construct a new BLEShellService object.
execute_command(command)
async
Performs a shell command over SMP. The format of the response can be found
here <https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/services/device_mgmt/smp_groups/smp_group_9.html#shell-command-line-execute-response>_
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
command
|
list[str]
|
Array of command and arguments (eg, ["command", "arg1", "arg2"]) |
required |
Returns:
| Type | Description |
|---|---|
|
Shell response object as a dictionary |