max_ble_hci.ble_hci

Contains full HCI implementation.

class BleHci(port_id: str, baud: int = 115200, id_tag: str = 'DUT', log_level: str | int = 'INFO', logger_name: str = 'BLE-HCI', retries: int = 0, timeout: float = 1.0, async_callback: Callable[[AsyncPacket], Any] | None = None, evt_callback: Callable[[EventPacket], Any] | None = None)[source]

Bases: BleStandardCmds, VendorSpecificCmds

Host-controller interface.

The BleHci object defines a host-controller interface for BLE testing on any BLE-compatible microchip. Controller provides implementations for both BLE standard HCI command and ADI vendor specific commands. Support is also provided for the creation and use of custom vendor-specific commands.

Parameters:

port_id (str) – ID string for the port on which a connection should be established.
baud (int) – Port baud rate.
id_tag (str) – Connection ID string to use when logging.
log_level (Union[str, int]) – Logging level.
logger_name (str) – Name that should be used to reference HCI logger.
retries (int) – Number of times a port read should be retried before and error is thrown.
timeout (float) – Port timeout.
async_callback (Callable[[AsyncPacket], Any], optional) – Function pointer defining the process that should be taken when an async packet is received. If not defined, the async packet will be thrown out.
evt_callback (Callable[[EventPacket], Any], optional) – Function pointer defining the process that should be taken when an unexpected event packet is received. If not defined, the event packet will be thrown out.

port_id

Id string for the port on which a connection has been established

Type:: str

port

Serial port interfacing object connected to the DUT.

Type:: SerialUartTransport

id_tag

Connection ID string used by the logger.

Type:: str

logger

HCI logging object reference by the logger_name argument.

Type:: logging.Logger

retries

Number of times a port read should be retried before an error is thrown.

Type:: int

timeout

Port timeout.

Type:: float

bb_disable() → StatusCode

Disable the baseband radio

Return type:: StatusCode

bb_enable() → StatusCode: Enable the baseband radio NOTE: Must be done before using RSSI :rtype: StatusCode

create_connection(conn_params: ~max_ble_hci.data_params.ConnParams = peer_addr: 0 scan_interval: 256 scan_window: 256 init_filter_policy: 0 peer_addr_type: AddrType.PUBLIC own_addr_type: AddrType.PUBLIC conn_interval_min: 6 conn_interval_max: 6 max_latency: 0 sup_timeout: 100 min_ce_length: 3856 max_ce_length: 3856) → StatusCode

Command board to connect with a peer device.

Sends a command to the DUT, telling it to create a connection to a peer device based on the given connection parameters.

Parameters:: conn_params (ConnParams, optional) – Dataclass object containing the desired connection parameters.
Returns:: The return packet status code.
Return type:: StatusCode

disconnect(handle: int = 0, reason: int = 22) → StatusCode

Disconnect from an existing connection.

Sends a command to the DUT, telling it to disconnect from the indicated connection for the given reason.

Parameters:

handle (int, optional) – The handle to the desired connection.
reason (int, optional) – The reason for the disconnection.

Returns:

The return packet status code.

Return type:

StatusCode

enable_acl_sink(enable: bool) → StatusCode

Enable/disable ACL sink.

Sends a vendor-specific command to the DUT, telling it to enable or disable asynchronous connection-less packet sink.

Parameters:: enable (bool) – Enable ACL sink?
Returns:: The return packet status code.
Return type:: StatusCode

enable_adv(enable: bool) → StatusCode

Command board to start/stop advertising.

Sends a command to the DUT, telling it to either start or stop advertising based on the the enable argument.

Parameters:: enable (bool) – Enable advertising?
Returns:: The return packet status code.
Return type:: StatusCode

enable_autogen_iso_packets(packet_len: int) → StatusCode

Enable/disable automatic generation of ISO packets.

Sends a vendor-specific command to the DUT, telling it to enable or disable the automatic generation of ISO packets in accordance with the values provided.

Parameters:: packet_len (int) – Desired ISO packet length. Set to 0 to disable automatic generation.
Returns:: The return packet status code.
Return type:: StatusCode
Raises:: ValueError – If packet_len is larger than 32 bits (4 bytes) in size.

enable_autogenerate_acl(enable: bool) → StatusCode

Enable/disable automatic generation of ACL packets.

Sends a vendor-specific command to the DUT, telling it to enable or disable automatic generation of asynchronous connection-less packets.

Parameters:: enable (bool) – Enable automatic ACL packet generation?
Returns:: The return packet status code.
Return type:: StatusCode

enable_iso_packet_sink(enable: bool) → StatusCode

Enable/disable ISO packet sink.

Sends a vendor-specific command to the DUT, telling it to enable or disable ISO packet sink in accordance with the value provided.

Parameters:: enable (bool) – Enable ISO packet sink?
Returns:: The return packet status code.
Return type:: StatusCode

enable_scanning(enable: bool, filter_duplicates: bool = False) → StatusCode

Command board to start/stop scanning.

Sends a command to the DUT, telling it to either start or stop scanning based on the enable argument.

Parameters:

enable (bool) – Enable scanning?
filter_duplicates (bool, optional) – Filter duplicates?

Returns:

The return packet status code.

Return type:

StatusCode

enable_sniffer_packet_forwarding(enable: bool) → StatusCode

Enable/disable sniffer packet forwarding.

Sends a vendor-specific command to the DUT, telling it to enable or disable sniffer packet forwarding in accordance with the value provided.

Parameters:: enable (bool) – Enable sniffer packet forwarding?
Returns:: The return packet status code.
Return type:: StatusCode

end_test() → Tuple[int, StatusCode]

End the current test.

Sends a command to the DUT, telling it to end the current DTM test.

Returns:

StatusCode – The return packet status code.
int – The number of packets received correctly during the test. If ending a TX test, this value will be 0.

exit() → None[source]

Close the HCI connection.

Used to safely close the connection between the HCI and the test board.

generate_acl(handle: int, packet_len: int, num_packets: int) → StatusCode

Command board to generate ACL data.

Sends a vendor-specific command to the DUT telling it to generate/send ACL data in accordance with the provided packet length and number of packets. A test end function must be called to end this process on the board.

Parameters:

handle (int) – Connection handle.
packet_len (int) – Desired packet length.
num_packets (int) – Desired number of packets to send.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If handle is larger than 2 bytes.
ValueError – If packet_len is greater than 65535.
ValueError – If num_packets is greater than 255.

generate_iso_packets(handle: int, packet_len: int, num_packets: int) → StatusCode

Generate ISO packets.

Sends a vendor-specific command to the DUT, telling it to generate ISO packets on the indicated connection in accordance with the parameters provided.

Parameters:

handle (int) – Handle to the desired connection.
packet_len (int) – Desired packet length.
num_packets (int) – Number of ISO packets to send.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If handle is larger than 2 bytes in size.
ValueError – If packet_len is larger than 2 bytes in size.

get_acl_test_report() → Tuple[TestReport, StatusCode]

Get ACL test report.

Sends a vendor-specific command to the DUT, telling it to retrieve the current ACL test report.

Returns:

TestReport – The ACL test report returned by the DUT.
StatusCode – The return packet status code.

get_adv_stats() → Tuple[AdvPktStats, StatusCode]

Get the accumulated advertising stats.

Sends a vendor-specific command to the DUT, telling it to retrieve the current accumulated advertising statistics.

Returns:

AdvPktStats – Advertising statistics report retrieved by the DUT.
StatusCode – The return packet status code.

get_aux_adv_stats() → Tuple[AdvPktStats, StatusCode]

Get the accumulated auxiliary advertising stats.

Sends a vendor-specific command to the DUT, telling it to retrieve the current accumulated auxiliary advertising statistics.

Returns:

AdvPktStats – The auxiliary advertising statistics report retrieved by the DUT.
StatusCode – The return packet status code.

get_aux_scan_stats() → Tuple[ScanPktStats, StatusCode]

Get the accumulated auxiliary scan stats.

Sends a vendor-specific command to the DUT, telling it to retrieve the current accumulated auxiliary scan statistics.

Returns:

ScanPktStats – The auxiliary scan statistics report retrieved by the DUT.
StatusCode – The return packet status code.

get_channel_map_periodic_scan_adv(handle: int, is_advertising: bool) → Tuple[int, StatusCode]

Get the channel map used for periodic scanning/advertising.

Sends a vendor-specific command to the DUT, telling it to retrieve the channel map used for either periodic scanning or periodic advertising in accordance with the given values.

Parameters:

handle (int) – The handle to the desired periodic scanner/advertiser.
is_advertising (bool) – Does the handle point to a periodic advertiser?

Returns:

int – The channel map returned by the DUT.
StatusCode – The return packet status code.

Raises:

ValueError – If handle is larger than 2 bytes in size.

get_conn_stats() → Tuple[DataPktStats, StatusCode]

Get the stats captured during a connection.

Sends a vendor-specific command to the DUT, telling it to retrieve the statistics captured during a connection.

Returns:

DataPktStats – Connection statistics report retrieved by the DUT.
StatusCode – The return packet status code.

get_iso_connection_stats() → Tuple[DataPktStats, StatusCode]

Get the stats captured during an ISO connection.

Sends a vendor-specific command to the DUT, telling it to retrieve the statistics captured during an ISO connection.

Returns:

DataPktStats – The ISO connection statistics report retrieved by the DUT.
StatusCode – The return packet status code.

get_iso_test_report() → Tuple[TestReport, StatusCode]

Get the stats collected during an ISO test.

Sends a vendor-specific command to the DUT, telling it to retrieves the statistics collected during an ISO test.

Returns:

TestReport – The ISO test statistics report retrieved by the DUT.
StatusCode – The return packet status code.

get_log_level() → str[source]

Retrieve the current log level.

Retrieved the current logging level in string format.

Returns:: The current logging level.
Return type:: str

get_memory_stats() → Tuple[MemPktStats, StatusCode]

Get memory and system stats.

Sends a vendor-specific command to the DUT, telling it to retrieve the current memory and system statistics.

Returns:

MemPktStats – Memory and system statistics report retrieved by the DUT.
StatusCode – The return packet status code.

get_pdu_filter_stats() → Tuple[PduPktStats, StatusCode]

Get the accumulated PDU filter stats.

Sends a vendor-specific command to the DUT, telling it to retrieves the current accumulated PDU filter statistics.

Returns:

PduPktStats – PDU filter statistics report returned by the DUT.
StatusCode – The return packet status code.

get_peer_min_num_channels_used(handle: int) → Tuple[Dict[PhyOption, int], StatusCode]

Get the minimum number of channels used by a peer.

Sends a vendor-specific command to the DUT, telling it to retrieve the minimum number of channels used by a peer device as indicated by the given value.

Parameters:

handle (int) – Handle to the desired peer connection.

Returns:

Dict[PhyOption, int] – Peer minimum number of used channels by PHY type.
StatusCode – The return packet status code.

Raises:

ValueError – If handle is larger than 2 bytes in size.

get_periodic_scanning_stats() → Tuple[ScanPktStats, StatusCode]

Get the accumulated periodic scanning stats.

Sends a vendor-specific command to the DUT, telling it to retrieve the current accumulated periodic scanning statistics.

Returns:

ScanPktStats – The periodic scanning statistics report retrieved by the DUT.
StatusCode – The return packet status code.

get_pool_stats() → Tuple[List[PoolStats], StatusCode]

Get the memory pool stats captured during runtime.

Sends a vendor-specific command to the DUT, telling it to retrieve the memory pool statistics captured during runtime.

Returns:

List[PoolStats] – Memory pool statistics reports retrieved by the DUT.
StatusCode – The return packet status code.

get_rand_address() → Tuple[int, StatusCode]

Get a random device address.

Sends a vendor-specific command to the DUT, telling it to retrieve a random device address.

Returns:

int – Random device address retrieved by the DUT.
StatusCode – The return packet status code.

get_rssi_vs(channel: int = 0) → Tuple[int, StatusCode]

Get the RSSI values.

Sends a vendor-specific command to the DUT, telling it to retrieve the RSSI value for the indicated channel.

Parameters:

channel (int, optional) – Channel for which value should be retrieved.

Returns:

int – RSSI value for the indicated channel.
StatusCode – The return packet status code.

Raises:

ValueError – If channel is greater than 39 or less than 0.

get_scan_stats() → Tuple[ScanPktStats, StatusCode]

Get Scan stats

Returns:: Accumulated scanning stats and status code
Return type:: Tuple[ScanPktStats, StatusCode]

get_test_stats() → Tuple[DataPktStats, StatusCode]

Get the stats captured during test mode.

Sends a vendor-specific command to the DUT, telling it to retrieve the statistics captured during DTM.

Returns:

DataPktStats – Test mode statistics report retrieved by the DUT.
StatusCode – The return packet status code.

init_connection(addr: int | None = None, interval: int = 6, sup_timeout: int = 100, conn_params: ConnParams | None = None) → StatusCode[source]

Initialize a connection.

Convenience function which sends a sequence of commands to the DUT, telling it to initialize a connection. PHYs preferences cannot be set when using this function, but connection parameters can be using the optional conn_params parameter. If a value is provided for conn_params, the values of the addr, interval, and sup_timeout parameters are ignored. If no value is provided, all connection parameters except min/max interval and supervision timeout are defaulted. In addition, a value for addr must be provided.

Parameters:

addr (int) – Peer device BD address.
interval (int, optional) – Connection inverval.
sup_timeout (int, optional) – Supervision timeout.

Returns:

The return status of the create connection command.

Return type:

StatusCode

Raises:

ValueError – If both addr and conn_params are None.
ValueError – If addr is more than 6 bytes in size.

read_event(timeout: float | None = None) → EventPacket[source]

Read an event from controller.

Parameters:: timeout (Optional[float], optional) – Timeout for read operation. Can be used to temporarily override this object’s timeout attribute.
Returns:: Packet retrieved from the controller.
Return type:: EventPacket
Raises:: TimeoutError – If a timeout occurs and there are no retries remaining.

read_register(addr: int, length: int, print_data: bool = False) → Tuple[List[int], StatusCode]

Read a number of bytes from a register.

Sends a vendor-specific command to the DUT, telling it to read bytes from a register in accordance with the given length and register address values.

Parameters:

addr (int) – The address at which the read should begin.
length (int) – The number of bytes to read.
print_data (bool, optional) – Print read data to the console?

Returns:

List[int] – The read data.
StatusCode – The return packet status code.

reset() → StatusCode

Reset board controller/link layer.

Sends a command to the DUT, telling it that the controller and the link layer should be reset. On-board implementation may vary, meaning this command does not necessarily perform a full hardware reset.

Returns:: The return packet status code.
Return type:: StatusCode

reset_connection_stats() → StatusCode

Reset accumulated connection stats.

Sends a vendor-specific command to the DUT, telling it to reset all accumulated connection statisitics.

Returns:: The return packet status code.
Return type:: StatusCode

reset_test_stats() → StatusCode

Reset accumulated test stats.

Sends a vendor-specific command to the DUT, telling it to reset all accumulated test statistics.

Returns:: The return packet status code.
Return type:: StatusCode

rx_test(channel: int = 0, phy: PhyOption | int = PhyOption.PHY_1M, modulation_idx: int = 0) → StatusCode

Start a receiver test.

Sends a command to the DUT, telling it to start a DTM receiver test in accordance with the given parameters.

Parameters:

channel (int, optional) – The channel on which the receiver should listen for packets.
phy (Union[PhyOption,int], optional) – The PHY that should be used by the receiver.
modulation_idx (float, optional) – The expected modulation index of the transmitter. Indicates whether the modulation index is standard (0) or stable (1).

Returns:

The return packet status code.

Return type:

StatusCode

rx_test_vs(channel: int = 0, phy: PhyOption | int = PhyOption.PHY_1M, num_packets: int = 0, modulation_idx: int = 0) → StatusCode

Start a vendor-specific receiver test.

Sends a vendor-specific command to the DUT, telling it to start a DTM receiver test in accordance with the given parameters.

Parameters:

channel (int) – The channel on which the receiver should listen for packets.
phy (Union[PhyOption, int]) – The PHY that should be used by the receiver.
num_packets (int) – The number of packets that the receiver is expected to receive, i.e. the number of packets the transmitter is sending.
modulation_idx (int) – The expected modulation index of the transmitter. Indicates whether the modulation index is standard (0) or stable (1).

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If channel is greater than 39 or less than 0.
ValueError – if num_packets is greater than 65535.

send_controller_command(ocf: OCF, params: List[int] | None = None, return_evt: bool = False) → StatusCode | EventPacket

Send a Controller command to the test board.

Sends a command from the OGF Controller subgroup to the DUT.

Parameters:

ocf (OCF) – Opcode command field value for the desired HCI command.
params (List[int], optional) – Command parameters as single-byte values.
return_evt (bool, optional) – If true, function returns full EventPacket object. If false, function returns only the status code.

Returns:

If return_evt argument is true, the full return packet from the DUT. If return_evt argument is false, the return packet status code.

Return type:

Union[StatusCode, EventPacket]

send_le_controller_command(ocf: OCF, params: List[int] | None = None, return_evt: bool = False) → StatusCode | EventPacket

Send an LE Controller command to the test board.

Sends a command from the OGF LE Controller subgroup to the DUT.

Parameters:

ocf (OCF) – Opcode command field value for the desired HCI command.
params (List[int], optional) – Command parameters as single-byte values.
return_evt (bool, optional) – If true, function returns full EventPacket object. If false, function returns only the status code.

Returns:

If return_evt argument is true, the full return packet from the DUT. If return_evt argument is false, the return packet status code.

Return type:

Union[StatusCode, EventPacket]

send_link_control_command(ocf: OCF, params: List[int] | None = None, return_evt: bool = False) → StatusCode | EventPacket

Send a Link Control command to the test board.

Sends a command from the OGF Link Control subgroup to the DUT.

Parameters:

ocf (OCF) – Opcode command field value for the desired HCI command.
params (List[int], optional) – Command parameters as single-byte values.
return_evt (bool, optional) – If true, function returns full EventPacket object. If false, function returns only the status code.

Returns:

If return_evt argument is true, the full return packet from the DUT. If return_evt argument is false, the return packet status code.

Return type:

Union[StatusCode, EventPacket]

send_vs_command(ocf: OCF, params: List[int] | None = None, return_evt: bool = False) → EventPacket | StatusCode

Send a vendor-specific command to the test board.

Sends a command from the OGF Vendor Specific subgroup to the DUT.

Parameters:

ocf (OCF) – Opcode command field value for the desired HCI command.
params (List[int], optional) – Command parameters as single-byte values.
return_evt (bool, optional) – If true, function returns full EventPacket object. If false, function returns only the status code.

Returns:

If return_evt argument is true, the full return packet from the DUT. If return_evt argument is false, the return packet status code.

Return type:

Union[StatusCode, EventPacket]

set_256_priv_key(priv_key: List[int]) → StatusCode

Set/clear the P-256 private key.

Sends a vendor-specific command to the DUT, telling it to set or clear the P-256 private key used to generate key pairs and Diffie-hellman keys in accordance with the given value.

Parameters:: priv_key (list) – Desired P-256 private key. Setting to 0 will clear the key.
Returns:: The return packet status code.
Return type:: StatusCode
Raises:: ValueError – If priv_key is larger than 32 bytes in size.

set_additional_aux_ptr_offset(delay: int, handle: int) → StatusCode

Set auxiliary packet offset delay.

Sends a vendor-specific command to the DUT, telling it to set the auxiliary packet offset delay in accordance with the given values.

Parameters:

delay (int) – Desired delay. Set to 0 to disable.
handle (int) – Handle to the desired connection.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If delay is larger than 4 bytes in size.

set_address(addr: int) → StatusCode

Sets the BD address.

Function sets the chip BD address. Address can be given as either a bytearray or as a list of integer values.

Parameters:: addr (List[int]) – Desired BD address.
Returns:: The return packet status code.
Return type:: StatusCode

set_adv_params(adv_params: ~max_ble_hci.data_params.AdvParams = interval_min: 96 interval_max: 96 adv_type: 3 own_addr_type: AddrType.PUBLIC peer_addr_type: AddrType.PUBLIC peer_addr: 0 channel_map: 7 filter_policy: 0) → StatusCode

Set test board advertising parameters.

Sends a command to the DUT, telling it to set the advertising parameters to the given values.

Parameters:: adv_params (AdvParams, optional) – Dataclass object containing the desired advertising parameters.
Returns:: The return packet status code.
Return type:: StatusCode

set_adv_tx_power(tx_power: int) → StatusCode

Set the advertising TX power.

Sends a vendor-specific command to the DUT, telling it to set the advertising TX power in accordance with the given value.

Parameters:: tx_power (int) – Desired advertising TX power.
Returns:: The return packet status code.
Return type:: StatusCode
Raises:: ValueError – If tx_power is greater than 127 or less than -127.

set_channel_map(channels: List[int] | int | None = None, handle: int = 0) → StatusCode

Set the channel map for an existing connection.

Sends a vendor-specific command to the DUT, telling it to set the channel map for the indicated connection in accordance with the mask generated from the given channel values.

Parameters:

channels (Union[List[int], int], optional) – The channel(s) that should be included in the connection channel map.
handle (int, optional) – The handle to the desired connection.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If handle is more than 2 bytes in size.

set_conn_tx_power(tx_power: int, handle: int = 0) → StatusCode

Set the connection TX power.

Sends a vendor-specific command to the DUT, telling it to set the TX power on the indicated connection in accordance with the given value.

Parameters:

tx_power (int) – Desired connection TX power.
handle (int, optional) – The handle to the desired connection.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If handle is more than 2 bytes in size.
ValueError – If tx_power is greater than 127 or less than -127.

set_connection_op_flags(handle: int, flags: int, enable: bool) → StatusCode

Set connection operational flags.

Sends a vendor-specific command to the DUT, telling it to enable/disable the connection operational flags for the indicated connection in accordance with the values provided.

Parameters:

handle (int) – The handle to the desired connection.
flags (int) – Mask indicating the desired connection operational flags that should be enabled/disabled. Flags are indicated when their corresponding bit is set to 1.
enable (bool) – If true, enables the indicated flags. If false, disables them.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If handle is larger than 2 bytes in size.
ValueError – If flags is larger than 4 bytes in size.

set_connection_phy_tx_power(handle: int, power: int, phy: PhyOption) → StatusCode

Set the connection TX power level for a specific PHY.

Sends a vendor-specific command to the DUT, telling it to set the connection TX power level for the indicated connection and PHY in accordance with the value provided.

Parameters:

handle (int) – Handle to the desired connection.
power (int) – Desired TX power.
phy (PhyOption) – PHY on which the TX power should be set.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If handle is larger than 2 bytes in size.

set_data_len(handle: int = 0, tx_octets: int = 64256, tx_time: int = 36930) → StatusCode

Set the maximum TX payload size and transmit time.

Sends a command to the DUT, telling it to set the maximum TX payload size and transmit time to the given values.

Parameters:

handle (int, optional) – Connection handle.
tx_octets (int, optional) – Desired maximum number of payload octets.
tx_time (int, optional) – Desired maximum TX time.

Returns:

The return packet status code.

Return type:

StatusCode

set_default_phy(all_phys: int = 0, tx_phys: int = 7, rx_phys: int = 7) → StatusCode

Set defaults for ALL, TX, and RX PHYs.

Sends a command to the DUT, telling it to set the default behavior for ALL, TX, and RX PHYs in accordance with the given values.

Parameters:

all_phys (int, optional) – Value describing desired behavior of all PHYs.
tx_phys (int, optional) – Value describing desired behavior of TX PHYs.
rx_phys (int, optional) – Value describing desired behavior of RX PHYs.

Returns:

The return packet status code.

Return type:

StatusCode

set_diagnostic_mode(enable: bool) → StatusCode

Enable/disable diagnostic mode.

Sends a vendor-specific command to the DUT, telling it to enable or disable the PAL system assert trap in accordance with the provided value.

Parameters:: enable (bool) – Enable diagnostic mode?
Returns:: The return packet status code.
Return type:: StatusCode

set_encryption_mode(handle: int, enable: bool, nonce_mode: bool) → StatusCode

Set the encryption mode of an existing connection.

Sends a vendor-specific command to the DUT, telling it to set the encryption mode of the indicated connection in accordance with the values provided.

Parameters:

handle (int) – Handle to the desired connection.
enable (bool) – Enable authentication?
nonce_mode (bool) – Enable nonce mode?

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If handle is larger than 2 bytes in size.

set_event_mask(mask: int, mask_pg2: int | None = None) → StatusCode | Tuple[StatusCode, StatusCode]

Enable/disable events the board can generate.

Sends a command to the DUT, telling it to enable/disable events that can be generated and returned to the host in accordance with the given mask. If a page2 mask if provided, then the command which sets the page2 masks will also be sent.

Parameters:

mask (int) – Mask indicating the desired events. Setting a bit to 1 enables the corresponding event. Setting the bit to 0 disables it.
mask_pg2 (Optional[int], optional) – Mask indicating the desired events for the second event mask page. Setting a bit to 1 enables the corresponding event. Setting the bit to 0 disables it.

Returns:

The return packet status codes(s). If both page1 and page2 were set, the first return is the status code for the page1 command and the second is the status code for the page2 command.

Return type:

Union[StatusCode, Tuple[StatusCode, StatusCode]]

set_event_mask_le(mask: int) → StatusCode

Enable/disable LE events the board can generate.

Sends a command to the DUT, telling it to enable/disable LE events that can be generated and returned to the host in accordance with the given mask.

Parameters:: mask (int) – Mask indicating the desired LE events. Setting a bit to 1 enables the corresponding event. Setting the bit to 0 disables it.
Returns:: The return packet status code.
Return type:: StatusCode

set_event_mask_vs(mask: int, enable: bool) → StatusCode

Enable/disable vendor specific events the board can generate.

Sends a vendor-specific command to the DUT, telling it to enable/disable vendor-specific events that can be generated and returned to the host in accordance with the given mask.

Parameters:

mask (int) – Mask indicating the vendor-specific events that should be enabled/disabled. Events are indicated when their corresponding bit is set to 1.
enable (bool) – If true, enables the indicated events. If false, disables them.

Returns:

The return packet status code.

Return type:

StatusCode

set_ext_adv_data_fragmentation(handle: int, frag_length: int) → StatusCode

Set the extended advertising fragmentation length.

Sends a vendor-specific command to the DUT, telling it to set the extended advertising fragmentation length in accordance with the values provided.

Parameters:

handle (int) – Desired advertising handle.
frag_length (int) – Desired fragmentation length.

Returns:

The return packet status code.

Return type:

StatusCode

set_extended_advertising_default_phy_opts(phy_opts: int) → StatusCode

Set the extended advertising default TX PHY options.

Sends a vendor-specific command to the DUT, telling it to set the default TX PHY options for the extended advertising slave primary and secondary channels in accordance with the value provided.

Parameters:: phy_opts (int) – Desired PHY options.
Returns:: The return packet status code.
Return type:: StatusCode

set_extended_advertising_phy_opts(handle: int, primary: int, secondary: int) → StatusCode

Set extended advertising PHY options.

Sends a vendor-specific command to the DUT, telling it to set the extended advertising PHY options in accordance with the values provided.

Parameters:

handle (int) – Desired advertising handle.
primary (int) – Desired primary advertising channel PHY options.
secondary (int) – Desired secondary advertising channel PHY options.

Returns:

The return packet status code.

Return type:

StatusCode

set_local_feature(features: int) → StatusCode

Set local supported features.

Sends a vendor-specific command to the DUT, telling it to set the local supported features in accordance with the given value.

Parameters:: features (int) – Mask indicating the local supported features. Setting a bit to 1 will enable the indicated feature. Setting a bit to 0 will disable it.
Returns:: The return packet status code.
Return type:: StatusCode
Raises:: ValueError – If features is larger than 64 bits (8 bytes) in size.

set_local_num_min_used_channels(phy: PhyOption, pwr_thresh: int, min_used: int) → StatusCode

Set local minimum number of used channels.

Sends a vendor-specific command to the DUT, telling it to set the local minimum number of used channels in accordance with the given PHY, power threshold, and minimum values.

Parameters:

phy (PhyOption) – PHY on which the process should take place.
pwr_thresh (int) – Power threshold for the selected PHY.
min_used (int) – Minimum number of used channels.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If pwr_thresh is greater than 127 or less than -127.
ValueError – if min_used is greater than 37 or less than 1.

set_log_level(level: str | int) → None[source]

Sets log level.

Provides intermediary control over the logging level of the host-controller interface module logger. If necessary, desired log level is automatically converted from a string to an integer. As such, both strings and integers are valid inputs to the level parameter.

Parameters:: level (Union[int, str]) – Desired log level.

set_operational_flags(flags: int, enable: bool) → StatusCode

Enable/disable operational flags.

Sends a vendor-specific command to the DUT, telling it to enable or disable operational flags in accordance with the values provided.

Parameters:

flags (int) – Mask indicating the desired operational flags that should be enabled/disabled. Flags are indicated when their corresponding bit is set to 1.
enable (bool) – If true, enables the indicated flags. If false, disabled them.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If flags is larger than 32 bits (4 bytes) in size.

set_phy(handle: int = 0, all_phys: int = 0, tx_phys: int = 7, rx_phys: int = 7, phy_opts: int = 0) → StatusCode

Set the PHY preferences for a connection.

Sends a command to the DUT, telling it to set the PHY preferences for the indicated connection in accordance with the given values.

Parameters:

handle (int, optional) – The handle to the desired connection.
all_phys (int, optional) – Behavior settings for all PHYs. Indicates if a PHY preference exists for both RX and TX PHYs.
tx_phys (PhyOption, optional) – PHY preference for TX PHYs.
rx_phys (PhyOption, optional) – PHY preference for RX PHYs.

Returns:

The return packet status code.

Return type:

StatusCode

set_scan_channel_map(channel_map: int) → StatusCode

Set the channel map used for scanning.

Sends a vendor-specific command to the DUT, telling it to set the channel map used for scanning in accordance with the given value.

Parameters:: channel_map (int) – Desired channel map to use for scanning.
Returns:: The return packet status code.
Return type:: StatusCode

set_scan_params(scan_params: ~max_ble_hci.data_params.ScanParams = scan_type: 1 scan_interval: 256 scan_window: 256 addr_type: AddrType.PUBLIC filter_policy: 0) → StatusCode

Set test board scanning parameters.

Sends a command to the DUT, telling it to set the scanning parameters to the given values.

Parameters:: scan_params (ScanParams, optional) – Dataclass object containing the desired scanning parameters.
Returns:: The return packet status code.
Return type:: StatusCode

set_tx_test_err_pattern(pattern: int) → StatusCode

Set the TX test mode error pattern.

Sends a vendor-specific command to the DUT, telling it to set the pattern of errors for the TX test mode in accordance with the given value.

Parameters:: pattern (int) – Desired error pattern.
Returns:: The return packet status code.
Return type:: StatusCode
Raises:: ValueError – If pattern is larger than 32 bits (4 bytes) in size.

set_validate_pub_key_mode(mode: PubKeyValidateMode) → StatusCode

Set the mode used to validate the public key.

Sends a vendor-specific command to the DUT, telling it to set the mode used to validate the public key in accordance with the given value.

Parameters:: mode (PubKeyValidateMode) – Desired public key validation mode.
Returns:: The return packet status code.
Return type:: StatusCode

start_advertising(connect: bool = True, adv_params: AdvParams | None = None) → StatusCode[source]

Start advertising.

Convenience function which sends a sequence of commands to the DUT, telling it to begin advertising. PHYs preferences cannot be set when using this function, but advertising parameters can be using the optional adv_params parameter. If a value is provided for adv_params, the value of the connect parameter is ignored. If no value is provided, all advertising parameters are defaulted and connect is used to determine the advertising type.

Parameters:

connect (bool, optional) – Make connectable? If true, advertising type is set to 0x0 (ADV_IND). If false, advertising type is set to 0x3 (ADV_NONCONN_IND). Ignored if adv_params is not None.
adv_params (AdvParams, optional.) – Advertising parameters.

Returns:

The return status of the enable advertising command.

Return type:

StatusCode

tx_test(channel: int = 0, phy: PhyOption | int = PhyOption.PHY_1M, payload: PayloadOption | int = PayloadOption.PLD_PRBS9, packet_len: int = 0) → StatusCode

Start a transmitter test.

Sends a command to the DUT, telling it to start a DTM transmitter test in accordance with the given parameters.

Parameters:

channel (int, optional) – The channel on which transmission should take place.
phy (Union[PhyOption,int], optional) – The PHY that should be used by the transmitter.
payload (PayloadOption, optional) – The packet payload type that should be used.
packet_len (int, optional) – The desired length of the transmitted packets.

Returns:

The return packet status code.

Return type:

StatusCode

tx_test_vs(channel: int = 0, phy: PhyOption | int = PhyOption.PHY_1M, payload: PayloadOption | int = PayloadOption.PLD_PRBS15, packet_len: int = 0, num_packets: int = 0) → StatusCode

Start a vendor-specific transmitter test.

Sends a vendor-specific command to the DUT, telling it to start a DTM transmitter test in accordance with the given parameters.

Parameters:

channel (int) – The channel on which transmission should take place.
phy (Union[PhyOption, int]) – The PHY that should be used by the transmitter.
payload (Union[PayloadOption, int]) – The packet payload type that should be transmitted.
packet_len (int) – The desired length of the transmitted packets.
num_packets (int) – The number of packets to transmit. Set to 0 to enable continuous transmission.

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

ValueError – If channel is greater than 39 or less than 0.
ValueError – If packet_len is greater than 255.
ValueError – If num_packets is greater than 65535.

write_command(command: CommandPacket, timeout: float | None = None) → EventPacket[source]

Send a command and retrieve the return packet.

Parameters:

command (Union[str, int]) – Command to send. Must be an instance of the CommandPacket class.
timeout (int) – Timeout for read portion of the read/write. Can be used to temporarily override this object’s timeout attribute.

Returns:

The command return packet.

Return type:

EventPacket

write_command_raw(raw_command: bytearray, timeout: float | None = None) → EventPacket[source]

Write raw command to device

Parameters:

raw_command (bytearray) – Command as bytearray
timeout (int) – Timeout for read portion of the read/write. Can be used to temporarily override this object’s timeout attribute.

Return type:

EventPacket