UWB (canvas_uwb)

The modules described in this chapter provide the interface to the UWB stack in the radio module.

class canvas_uwb.UwbDeviceState(state: int)

Helper class to represent the state of the UWB device.

This class should not be created directly. Instead, an instance of the class is returned by get_device_state().

is_active() → bool

Returns:: True if the device has at least one active session. False if the device has no active sessions.

is_error() → bool

Returns:: True if the device is in an error state. False if the device is in a normal state.

is_ready() → bool

Returns:: True if the device is ready to be used. False if the device is not ready to be used.

class canvas_uwb.UwbSession(session_id: int)

Class representing a UWB session. A session is a collection of settings and state related to a UWB ranging session. A session is created by calling session_new(). Following the creation, the session is configured by calling the various set_*() class methods. The session is started by calling the start() method. The session is stopped by calling the stop() method. The session is destroyed by calling the close() method.

In general, the settings of a session must match on both sides of the ranging session. For example, if the initiator sets the ranging interval to 1000ms, then the responder must also set the ranging interval to 1000ms. The UWB radio and stack have no way of exchanging settings between the initiator and responder. Therefore, it is the responsibility of the application to ensure that the settings match on both sides of the session.

Parameters:: session_id – The session ID. This is a unique identifier for the session.

add_multicast(address: int)

Add an address to the multicast list of the session. The UWB stack will attempt to range with all addresses in the multicast list. The session must have been configured as a multicast session by calling the set_app_config() method with the canvas_uwb.CONFIG_MULTI_NODE_MODE configuration ID and a value of canvas_uwb.MODE_MULTICAST. This method is only applicable to the initiator role.

Parameters:: address – The address to add to the multicast list.

close(): Close the session and free any resources associated with the session. Once a session is closed, it cannot be used again.

del_multicast(address: int)

Delete an address from the multicast list of the session.

Parameters:: address – The address to delete from the multicast list.

get_app_config(config_id: int) → any

Get an application configuration value for a session.

Parameters:: config_id – The configuration ID.
Returns:: The configuration value. This is a bytes value of the required length for the configuration ID.

get_session_state() → UwbSessionState

Get the state of the session.

Returns:: The session state as a UwbSessionState object.

set_app_config(config_id: int, value: any)

Set an application configuration value for a session.

Parameters:

config_id – The configuration ID.
value – The configuration value. This is a bytes value of the required length for the configuration ID.

set_callback(cb: any)

Set the callback function for the session. The callback function will be called at approximately the interval specified by the set_ranging_interval() method.

The callback function should expect to take a single list argumnent. Each entry of the list will be a tuple containing the following values:

The address of the peer.
The range value in centimeters. This value will be equal to canas_uwb.RANGE_ERROR if the range is invalid.

Parameters:: cb – The callback function.

set_channel(channel: int)

Set the channel of the session. This is the channel that the UWB stack will use when ranging with the peer(s).

Parameters:: channel (int) – The channel. Only the values 5 and 9 are supported.

set_local_addr(address: int)

Set the local address of the session. This is the address that the UWB stack will use when ranging with the peer(s).

Parameters:: address – The local address.

set_peer_addr(address: int)

Set the peer address of the session. This is the address that the UWB stack will attempt to communicate with when ranging.

Parameters:: address – The peer address.

set_ranging_interval(interval: int)

Set the ranging interval of the session. This is the interval at which the UWB stack will attempt to range with the peer(s). The value should be same on both sides of the ranging session.

Parameters:: interval – The ranging interval in milliseconds.

start() → bool

Start the session. The session must have been configured before calling this method.

Returns:: True if the session was started successfully. False if the session was not started successfully.

stop(): Stop the session.

class canvas_uwb.UwbSessionState(state: int)

Helper class to represent the state of a UWB session.

This class should not be created directly. Instead, an instance of the class is returned by UwbSession.get_session_state().

is_active() → bool

Returns:: True if the session is in the active state. False if the session is not in the active state.

is_deinit() → bool

Returns:: True if the session is in the deinit state. False if the session is not in the deinit state.

is_error() → bool

Returns:: True if the session is not in a normal state. False if the session is in a normal state.

is_idle() → bool

Returns:: True if the session is in the idle state. False if the session is not in the idle state.

is_init() → bool

Returns:: True if the session is in the init state. False if the session is not in the init state.

class canvas_uwb.UwbStackCapabilities(max_multicast: int, max_sessions: int, channel_mask: int, roles: int)

Helper class to represent the capabilities of the UWB stack.

This class should not be created directly. Instead, an instance of the class is returned by get_stack_capability().

get_channel_mask() → int

Returns:: The channel mask of the UWB stack. This is a bit mask where each bit represents a channel. For example, if the channel mask is 0x00000001, then channel 0 is enabled. If the channel mask is 0x00000003, then channels 0 and 1 are enabled.

get_max_multicast() → int

Returns:: The maximum number of multicast addresses that can be added to a session.

get_max_sessions() → int

Returns:: The maximum number of sessions that can be created.

is_initiator_supported() → bool

Returns:: True if the UWB stack supports the initiator role.

is_responder_supported() → bool

Returns:: True if the UWB stack supports the responder role.

canvas_uwb.get_device_info() → any

Get UWB device information.

Returns:: A named tuple containing the following fields: - uci_version: The UCI spec version used by the UWB stack. - mac_version: The version of the MAC spec used by the UWB stack. - phy_version: The version of the PHY spec used by the UWB stack. - uci_test_version: The version of the UCI test spec used by the UWB stack. - device_name: The name of the UWB device. - firmware_version: The version of UWB firmware. - device_version: The version of the UWB device. - serial_number: The serial number of the UWB device. - dsp_version: The version of the DSP used by the UWB stack. - sr040_version: The version of the SR040 used by the UWB stack.

canvas_uwb.get_device_state() → UwbDeviceState

Get the state of the UWB device.

Returns:: The state of the UWB device as a UwbDeviceState object.

canvas_uwb.get_stack_capability() → UwbStackCapabilities

Get the capabilities of the UWB stack.

Returns:: The capabilities of the UWB stack as a UwbStackCapabilities object.

canvas_uwb.init(): Initialize the UWB stack. This method must be called before any other UWB stack methods are called.

canvas_uwb.raw_uci_send(data: any) → bytes

Send a raw UCI command to the UWB stack.

Parameters:: data – The raw UCI command to send to the UWB stack.
Returns:: The raw UCI reply received from the UWB stack.

canvas_uwb.session_from_profile(role: int, local_addr: int, profile: bytes) → UwbSession

Create a new session from a profile.

Parameters:

role – The role of the session. This should be either canvas_uwb.ROLE_RESPONDER or canvas_uwb.ROLE_INITIATOR.
local_addr – The local address to use for the session.
profile – The binary profile data to use for the session as received from the peer.

Returns:

A new session object.

canvas_uwb.session_new(session_id: int, role: int) → UwbSession

Create a new session.

Parameters:

session_id – The session ID. This is a unique identifier for the session.
role – The role of the session. This should be either canvas_uwb.ROLE_RESPONDER or canvas_uwb.ROLE_INITIATOR.

Returns:

A new session object.

canvas_uwb.shutdown(): Shutdown the UWB stack. This method must be called when the UWB stack is no longer needed. To use the UWB stack again, the init() method.

canvas_uwb.CONFIG_DEVICE_ROLE: int

Application configuration for device role

canvas_uwb.CONFIG_DEVICE_TYPE: int

Application configuration for device type

canvas_uwb.CONFIG_LOCAL_ADDRESS: int

Application configuration for local address

canvas_uwb.CONFIG_MAC_ADDRESS_MODE: int

Application configuration for MAC address mode (2 or 8 byte addresses)

canvas_uwb.CONFIG_MAX_RR_RETRY: int

Application configuration for maximum ranging round retries

canvas_uwb.CONFIG_MULTI_NODE_MODE: int

Application configuration for multi-node mode (Unicast or Multicast)

canvas_uwb.CONFIG_NUMBER_OF_CONTROLEES: int

Application configuration for number of controlees in multicast session

canvas_uwb.CONFIG_PEER_ADDRESS: int

Application configuration for peer address

canvas_uwb.CONFIG_PREAMBLE_CODE_INDEX: int

Application configuration for preamble code index

canvas_uwb.CONFIG_RANGING_INTERVAL: int

Application configuration for ranging interval (milliseconds)

canvas_uwb.CONFIG_RANGING_ROUND_USAGE: int

Application configuration for ranging round usage

canvas_uwb.CONFIG_RF_FRAME_CONFIG: int

Application configuration for RF frame configuration

canvas_uwb.CONFIG_SFD_ID: int

Application configuration for SFD identifier

canvas_uwb.CONFIG_SLOTS_PER_RR: int

Application configuration for number of slots per ranging round

canvas_uwb.CONFIG_SLOT_DURATION: int

Application configuration for ranging slot duration

canvas_uwb.MODE_MULTICAST: bytes

Multicast (one-to-many) mode

canvas_uwb.MODE_UNICAST: bytes

Unicast (one-to-one) mode

canvas_uwb.RANGE_ERROR: int

Represents an invalid range value

canvas_uwb.ROLE_INITIATOR: int

Initiator/Controller role

canvas_uwb.ROLE_RESPONDER: int

Responder/Controlee role