max_ble_hci.ble_standard_cmds

Module contains definitions for BLE standard HCI commands.

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

Bases: object

Definitions for BLE standard HCI commands.

Class contains functions used to implement BLE standard 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

convert_fips197(data: int | str) → List[int][source]

Convert data to fips197 format

Parameters:

data (Union[int, str]) – Integer of string

Returns:

fips197 formatted data

Return type:

List[int]

Raises:

  • ValueError – Input is not an int or str

  • ValueError – Data cannot be represented in 16-bytes

create_connection(conn_params: ~max_ble_hci.data_params.EstablishConnParams = peer_addr:  0 scan_interval:  16 scan_window:  16 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[source]

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

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

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_scanning(enable: bool, filter_duplicates: bool = False) → StatusCode[source]

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

encrypt(key: bytes | int | str, plaintext: int | bytes | str) → List[int] | EventPacket[source]

Encrypt data

Parameters:

  • key (Union[bytes, int, str]) – Key to encrypt plaintex with

  • plaintext (Union[int, bytes, str]) – data to encrypt Will pad data with zeros if the block is not 16 bytes

Returns:

Ciphertext if encryption succeeded. Event packet othewise.

Return type:

Union[List[int], EventPacket]

Raises:

  • ValueError – If key is an integer and cannot be represented in 128 bits

  • ValueError – If key is bytes or string an not 16-bytes in length

  • ValueError – If plaintext cannot be represented ins 128 bits

  • ValueError – If plaintext bytes or string and more than 16 bytes

end_test() → Tuple[int, StatusCode][source]

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.

generate_dhk(xcoord: int, ycoord: int, version: int = 1, use_debug_key=False, callback: Callable[[EventPacket], None] | None = None) → StatusCode[source]

Generate Diffie-Hellman Key

Parameters:

  • xcoord (int) – X-Coordinate

  • ycoord (int) – Y-Coordinate

  • version (int, optional) – DHK gen version, by default 1. Options 1 or 2

  • use_debug_key (bool, optional) – Use a debug key instead of in use key, by default False

  • callback (Callable[[EventPacket], None], optional) – Callback to call when complete event is triggered, by default None, by default None

Returns:

The return packet status code.

Return type:

StatusCode

Raises:

  • ValueError – If version not 1 or 2

  • NOTE – Complete event not enabled for you. Please enable event if needed.:

read_local_p256_pub_key(callback: Callable[[EventPacket], None] | None = None) → StatusCode[source]

Read local P256 Key

Parameters:

callback (Callable[[EventPacket], None], optional) – Callback to call when complete event is triggered, by default None

Returns:

  • StatusCode – The return packet status code.

  • NOTE (Event not enabled for you. Please enable event.)

reset() → StatusCode[source]

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

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

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

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

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

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 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]

set_adv_data(data: list) → StatusCode[source]

Set advertising data

Parameters:

data (list) – data to advertise

Returns:

Status

Return type:

StatusCode

Raises:

ValueError – If advertising data cannot be represented in 31 octets or less

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

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_async_callback(callback)[source]

Set callback used for async packet

Parameters:

callback (Callable) – Function to call on async packet

set_data_len(handle: int = 0, tx_octets: int = 64256, tx_time: int = 36930) → StatusCode[source]

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(tx_phys: PhyOption | List[PhyOption] | None = None, rx_phys: PhyOption | List[PhyOption] | None = None) → StatusCode[source]

Set default phy used for TX and RX

Parameters:

  • tx_phys (Union[PhyOption, List[PhyOption]], optional) – Preferred PHY or list of preferred PHYs for TX, by default None meaning no preference

  • rx_phys (Union[PhyOption, List[PhyOption]], optional) – Preferred PHY or list of preferred PHYs for TX, by default None meaning no preference

Returns:

The return packet status code.

Return type:

StatusCode

set_event_callback(callback)[source]

Set callback used for event packet

Parameters:

callback (Callable) – Function to call on event packet

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

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

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_phy(handle: int = 0, tx_phys: PhyOption | List[PhyOption] | None = None, rx_phys: PhyOption | List[PhyOption] | None = None) → StatusCode[source]

Set PHY during connection

Parameters:

  • handle (int, optional) – connection handle, by default 0x0000

  • tx_phys (Union[PhyOption, List[PhyOption]], optional) – PHY or list of PHYS preferred for TX, by default None meaning no preference

  • rx_phys (Union[PhyOption, List[PhyOption]], optional meaning no preference) – PHY or list of PHYs preferred for RX, by default None

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:  16 scan_window:  16 addr_type:  AddrType.PUBLIC filter_policy:  0) → StatusCode[source]

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_scan_resp_data(data: list) → StatusCode[source]

Set advertising data

Parameters:

data (list) – data to respond with on scan requests

Returns:

Status

Return type:

StatusCode

Raises:

ValueError – If scan request data cannot be represented in 31 octets or less

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

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

update_connection_params(handle: int, conn_params: ~max_ble_hci.data_params.ConnParams = conn_interval_min:  0 conn_interval_max:  6 max_latency:  0 sup_timeout:  100 min_ce_length:  3856 max_ce_length:  3856) → StatusCode[source]

Update connection parameters

Parameters:

  • handle (str) – Connection Handle

  • conn_params (ConnParams, optional) – Connection paramters by default ConnParams(0x0)

Returns:

The return packet status code.

Return type:

StatusCode