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, flowcontrol=False, recover_on_power_loss=False)[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

disable_all_events() → StatusCode[source]

Enable all available event masks for Controller (including page 2) and LE Events

Returns:: The return status of the set event mask or set event mask le commands
Return type:: StatusCode

enable_all_events() → StatusCode[source]

Enable all available event masks for Controller (including page 2) and LE Events

Returns:: The return status of the set event mask or set event mask le commands
Return type:: StatusCode

exit() → None[source]

Close the HCI connection.

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

firmware_update(name: str) → StatusCode[source]

Upload the firmware to second flash memory bank

Parameters:: name (str) – The name of firmware binary file
Returns:: The return status of the firmware update command.
Return type:: StatusCode

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

init_connection(addr: str | int | None = None, interval: int = 6, sup_timeout: int = 100, conn_params: EstablishConnParams | None = None, event_mask: EventMaskLE | 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.

set_local_adv_name(adv_name: str, complete=True) → StatusCode[source]

_summary_

Parameters:

adv_name (str) – Namem of device to advertise
complete (bool, optional) – Use complete local name or shortened local name as defined by the BLE Spec, by default True

Returns:

Status

Return type:

StatusCode

Raises:

ValueError – If advertising name is empty

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.

start_advertising(connect: bool = True, adv_params: AdvParams | None = None, adv_name='') → 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

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 | str, 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