max_ble_hci.vendor_spec_cmds

Module contains definitions for ADI vendor-specific HCI commands.

class VendorSpecificCmds(port: SerialUartTransport, logger_name: str)[source]

Bases: object

Definitions for ADI vendor-specific HCI commands.

Class contains functions used to implement Analog Devices vendor-specific HCI commands. Used as a parent for the full Analog Devices BLE HCI class.

Parameters:

port (SerialUartTransport) – Serial port interfacing object.
logger_name (str) – Name used to reference the HCI logger.

port

Serial port interfacing object.

Type:: SerialUartTransport

logger

HCI logging object referenced by the name argument.

Type:: logging.Logger

enable_acl_sink(enable: bool) → StatusCode[source]

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_autogen_iso_packets(packet_len: int) → StatusCode[source]

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[source]

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[source]

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_sniffer_packet_forwarding(enable: bool) → StatusCode[source]

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

erase_memory() → StatusCode[source]

Erase the flash memory.

Erase the flash memory with one page starting at addr.

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

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

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[source]

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][source]

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][source]

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][source]

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][source]

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][source]

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][source]

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][source]

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][source]

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_memory_stats() → Tuple[MemPktStats, StatusCode][source]

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][source]

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][source]

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][source]

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][source]

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][source]

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][source]

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][source]

Get Scan stats

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

get_test_stats() → Tuple[DataPktStats, StatusCode][source]

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.

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

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_adv_stats() → StatusCode[source]

Reset accumulated advertising stats

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

reset_connection_stats() → StatusCode[source]

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_device() → StatusCode[source]

Reset the device.

Reset the device, which has the same functionality as pressing the reset button on dev board.

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

reset_scan_stats() → StatusCode[source]

Reset accumulated scanning stats

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

reset_test_stats() → StatusCode[source]

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_vs(channel: int = 0, phy: PhyOption | int = PhyOption.PHY_1M, num_packets: int = 0, modulation_idx: int = 0) → StatusCode[source]

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_vs_command(ocf: OCF, params: List[int] | None = None, return_evt: bool = False) → EventPacket | StatusCode[source]

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[source]

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[source]

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 | str) → StatusCode[source]

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 (Union[int, str]) – Desired BD address. If str, format expected xx:xx:xx:xx:xx
Returns:: The return packet status code.
Return type:: StatusCode

set_adv_tx_power(tx_power: int) → StatusCode[source]

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[source]

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[source]

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[source]

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[source]

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_diagnostic_mode(enable: bool) → StatusCode[source]

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[source]

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_vs(mask: int, enable: bool) → StatusCode[source]

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[source]

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[source]

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[source]

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_flash_addr(addr: int | str) → StatusCode[source]

Set the flash write address.

Set the starting address of flash memory to be written

Parameters:: addr (Union[int, str]) – Desired flash memory address. If str, format expected xx:xx:xx:xx
Returns:: The return packet status code.
Return type:: StatusCode

set_local_feature(features: int) → StatusCode[source]

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[source]

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_operational_flags(flags: int, enable: bool) → StatusCode[source]

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_scan_channel_map(channel_map: int) → StatusCode[source]

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_tx_test_err_pattern(pattern: int) → StatusCode[source]

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[source]

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

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[source]

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_flash(chunk: List[int]) → StatusCode[source]

Write data to the flash memory.

Write 128 bits of data chunk to the flash memory

Parameters:: chunk (List[int]) – 128bit data chunk of new firmware
Returns:: The return packet status code.
Return type:: StatusCode