LAA manager (laam) - Python3

The LAA Manager is a python application that allows to interact with the LAA REST API.

This is the documentation to use laam in a python script.

Installation

laam is available from PyPI:

python3 -m venv venv
source venv/bin/activate
python3 -m pip install --upgrade laam
laam --help
laam --version

The version is also exposed to python as laam.__version__.

Configuration

You can create identities via console

The identities can then be used in this way:

import laam
LAA_1 = laam.LAA("identity-1");

Local Commands

“local” commands are not defined for python.

LAA class

class laam.LAA

Main Abstraction class to interact with a Linaro Automation Appliance.

This class provides the core object model and methods required to remotely interact with an LAA from the host machine using LAAM. It abstracts the underlying communication protocols (e.g., REST, WebSockets) necessary to control the Appliance’s primary functions to control the Device Under Test mounted on the LAA itself. The functions include power cycling, logs, usb control, serial interaction, etc…

__init__(self, laa_identity='default')

Initializes the interface object for the target LAA.

This method prepares the interface object using the provided identity. The identity is critical for addressing and authenticating a specific LAA

** Authentication Note ** To authenticate and enable control, you must:

  1. Create an API token on the LAA

  2. Manually configure the LAAM environment to use the token

Parameters:

  • laa_identity (str): A required unique string identifier the target LAA

Properties, Classes, and Methods

identities

There is no identitiesproperty. identities commands are supposed to be configured manually via the console interface, not through automated Python scripts.

dut

There is no dut property. Device configuration files are supposed to be configured manually via the console interface, not through automated Python scripts.

files

Manage files in /var/lib/lava/dispatcher/tmp on the LAA.

property laam.LAA.files

Interface for remote file management on the LAA. Based on the class Files.

help(laam.LAA.Files) for more info.

class laam.LAA.Files

Class for file management and transfer on the LAA.

NOTE: This class should NOT be instantiated directly by the user. Access to these functions is available only via the main LAA object.

decompress(self, local_path: str, compression: laam.models.Compression, tar: bool = False)

Decompress a file in the LAA the working folder.

Args:

  • local_path (str): Path of the file to decompress.

  • compression (laam.models.Compression): Compression algorithm of the file. Possible values: “xz”, “gz”, “bz2”, “zip”, “zstd”.

  • tar (bool): Indicates if the internal file is a tar.

Raises:

  • LAAError: If the LAA is offline or the request fails.

list(self, local_path: str | None = None) → list

Lists files and directories.

Args:

  • local_path (str | None): The local path of the directory to investigate. Defaults to None, which is the working folder.

Returns:

  • A list of elements.

Raises:

  • LAAError: If the LAA is offline or the request fails.

mkdir(self, local_path: str, parents: bool = False, exist_ok: bool = False)

Creates a directory

Args:

  • local_path (str): The local path of the directory to create.

  • parents (bool): Indicates if the parents should be created as well. Defaults to False

  • exist_ok (bool): Indicates if an error should be returned if the directory already exists. Defaults to False

Raises:

  • LAAError: If the LAA is offline or the request fails.

pull(self, local_path: str, file: pathlib.Path, force: bool = False)

Downloads a file from the LAA the working folder to the local machine.

Args:

  • local_path (str): The local path of the file on the LAA.

  • file (pathlib.Path): The path to which the file downloaded from the LAA will be saved.

  • force (bool): Overwrite the local file if it already exists. Defaults to False, raising an error if the file exists.

Raises:

  • LAAError: If the LAA is offline or the request fails.

push(self, local_path: str, file)

Uploads a file from the local machine to the LAA the working folder.

Args:

  • local_path (str): The local path on the LAA to save the file.

  • file (str, pathlib.Path, os.PathLike, io.BufferedReader): The file on the local machine to be uploaded. It can be a path to the object file itself.

Raises:

  • LAAError: If the LAA is offline or the request fails.

remove(self, local_path: str)

Removes a file in the LAA the working folder.

Args:

  • local_path (str): Local path of the file to be removed.

Raises:

  • LAAError: If the LAA is offline or the request fails.

rmdir(self, local_path: str, recursive: bool = False)

Removes a directory or sub-directory on the LAA

Args:

  • local_path (str): The local path of the directory to be removed.

  • recursive (bool): Remove the directory even if it has elements inside. Defaults to False

Raises:

  • LAAError: If the LAA is offline or the request fails.

laacli

Execute laacli commands on the LAA.

property laam.LAA.laacli

Interface for executing laacli commands. Based on the class LAACli.

help(laam.LAA.LAACli) for more info.

class laam.LAA.LAACli

Class for executing laacli commands on the LAA.

NOTE: This class should NOT be instantiated directly by the user. Access to these functions is available only via the main LAA object.

button(self, button: laam.models.Button, state: laam.models.ButtonState) → laam.models.CommandResponse

Controls the virtual buttons on the LAA.

Args:

  • button (laam.models.Button): The virtual button to control. Available choices are: “1”, “2”, “power”, “reset”.

  • state (laam.models.ButtonState): State to set on the button. Available choices are: “on”, “off”, “status”.

Returns:

  • laam.models.CommandResponse: Returned command execution object.

Raises:

  • LAAError: If the LAA is offline or the request fails.

history(self, since: str = '1h') → laam.models.History

Returns the recorded sensor history from the LAA. It covers the DUT power rails (voltage, current, power) and the board temperatures.

Args:

  • since (str): How far back to fetch, e.g. “90s”, “5m”, “2h”, “1d”. Defaults to “1h”.

Returns:

  • laam.models.History: Sensor history samples.

Raises:

  • LAAError: If the LAA is offline or the request fails.

led(self, state: laam.models.LedState) → laam.models.CommandResponse

Controls the status LED on the LAA.

Args:

  • state (laam.models.LedState): The state of the LED. Available choices are: “on”, “off”.

Returns:

  • laam.models.CommandResponse: Returned command execution object

Raises:

  • LAAError: If the LAA is offline or the request fails.

power(self, vbus: laam.models.VBus, state: laam.models.PowerState) → laam.models.CommandResponse

Controls the power rails on the LAA.

Args:

  • vbus (laam.models.VBus): Power rail to control. Available choices are: “1v8”, “3v3”, “5v”, “12v”.

  • state (laam.models.PowerState): State to set the rail. Available choices are: “on”, “off”, “reset”, “status”.

Returns:

  • laam.models.CommandResponse: Returned command execution object.

Raises:

  • LAAError: If the LAA is offline or the request fails.

rev(self) → laam.models.Rev

Returns the hardware revision of the LAA.

Returns:

  • laam.models.Rev: Returned revision object.

Raises:

  • LAAError: If the LAA is offline or the request fails.

screenshot(self, filename) → laam.models.Screenshot

Screenshots the current OLED and downloads it as a file on the local machine.

Args:

  • filename (str, os.PathLike, pathlib.Path, io.BufferedWriter): It can be the file path to save the file downloaded from the LAA, or the opened file object itself.

Returns:

  • laam.models.Screenshot: Returned command execution object.

Raises:

  • LAAError: If the LAA is offline or the request fails.

temp(self, probe: laam.models.TempProbe) → laam.models.Temp

Returns temperature information from the LAA.

Args:

  • probe (laam.models.TempProbe): Temperature probe to check. Available choices are: “amb”, “dut”, “sys”.

Returns:

  • laam.models.Temp: Temperature information.

Raises:

  • LAAError: If the LAA is offline or the request fails.

usb(self, port: laam.models.UsbPort, state: laam.models.UsbState) → laam.models.CommandResponse

Controls the four USB ports on the LAA (the ones pointing upwards).

Args:

  • port (laam.models.UsbPort): USB port to control. Available choices are: 0, 1, 2, 3, 4. Where 0 is the USB Hub controlling USB ports 1, 2, 3, 4.

  • state (laam.models.UsbState): State to set the port or just check the status. Available choices are: “on”, “off”, “reset”, “start”, “status”, “vbus”. “reset” and “start” only apply to port 0 (the hub), while “on”, “off”, “status” and “vbus” only apply to ports 1 to 4.

Returns:

  • laam.models.CommandResponse: Returned command execution object.

Raises:

  • LAAError: If the LAA is offline or the request fails.

usbg_ms(self, state: laam.models.UsbgMsState, filename: str = '') → laam.models.CommandResponse

Controls the USBG-MS port on the LAA (the ones at the front marked as USB-OTG).

Args:

  • state (laam.models.UsbgMsState): State to set the port or just check the status. Available choices are: “on”, “off”, “status”.

  • filename (str): File name of the image to be used, It is assumed to be located in the working LAA folder. Parameter needed only if the status is set to “on”.

Returns:

  • laam.models.CommandResponse: Returned command execution object.

Raises:

  • LAAError: If the LAA is offline or the request fails.

watt(self, vbus: laam.models.VBus) → laam.models.Watt

Returns power usage information from the LAA.

Args:

  • vbus (laam.models.VBus): Power rail to check. Available choices are: “1v8”, “3v3”, “5v”, “12v”.

Returns:

  • laam.models.Watt: Power usage information.

Raises:

  • LAAError: If the LAA is offline or the request fails.

network

Manage LAA network configuration

property laam.LAA.network

Interface for monitoring the LAA’s network interfaces. Based on the class Network.

help(laam.LAA.Network) for more info.

class laam.LAA.Network

Class for monitoring the LAA’s network interfaces.

NOTE: This class should NOT be instantiated directly by the user. Access to these functions is available only via the main LAA object.

addresses(self) → laam.models.NetworkAddresses

Returns the addresses of the LAA.

Returns:

  • laam.models.NetworkAddresses: Addresses information.

Raises:

  • LAAError: If the LAA is offline or the request fails.

hostname(self) → laam.models.NetworkHostname

Returns the hostname of the LAA.

Returns:

  • laam.models.NetworkHostname: Returns the hostname.

Raises:

  • LAAError: If the LAA is offline or the request fails.

interfaces(self) → list[laam.models.NetworkInterface]

Returns the interfaces of the LAA.

Returns:

  • list[laam.models.NetworkInterface]: Returns the interfaces.

Raises:

  • LAAError: If the LAA is offline or the request fails.

routes(self) → laam.models.NetworkRoutes

Returns the network routes of the LAA.

Returns:

  • laam.models.NetworkRoutes: Returns the routes.

Raises:

  • LAAError: If the LAA is offline or the request fails.

settings(self) → str

Returns the network settings of the LAA.

Returns:

  • str: Returns the settings.

Raises:

  • LAAError: If the LAA is offline or the request fails.

serials

List and interact with the different serial consoles provided by the LAA.

property laam.LAA.serials

Interface for managing and interacting with the LAA’s serial consoles. Based on the class Serials.

help(laam.LAA.Serials) for more info.

class laam.LAA.Serials

Class for managing and interacting with the LAA’s serial consoles with the DUT.

NOTE: This class should NOT be instantiated directly by the user. Access to these functions is available only via the main LAA object.

list(self, ser_filter=None, speed: laam.models.SerialSpeed | None = None, legacy=True) → list[laam.models.Serial]

Lists all the serials accessible via the LAA.

Args:

  • ser_filter: Glob matched against the serial device path, e.g. “/dev/ttyUSB*”.

  • speed (laam.models.SerialSpeed | None): Only list serials for a given speed. Available choices are: “9600”, “115200”, “1.5M”, “3M”. Defaults to None (all speeds).

  • legacy (bool): Include legacy serials. Defaults to True.

Returns:

  • list[laam.models.Serial]: Returns a list of serials.

Raises:

  • LAAError: If the LAA is offline or the request fails.

get(self, name: str) → laam.models.Serial

Returns the details of a specific serial console.

Args:

  • name (str): Name of the serial console, example “ttyUSB0”.

Returns:

  • laam.models.Serial: Returns serial information.

Raises:

  • LAAError: If the LAA is offline or the request fails.

connect_async_fun(self, name: str, readonly: bool = False, istream: io.TextIOBase = sys.stdin, ostream: io.TextIOBase = sys.stdout, force_str: bool | None = None) → int

Connects to a serial console with the DUT in an async function.

Args:

  • name (str): Name of the serial console, example “ttyUSB0”.

  • readonly (bool): True to start a readonly serial connection. (Default) False for an interactive connection

  • istream (io.TextIOBase): Input stream used to send data to the DUT on the LAA. Defaults to sys.stdin.

  • ostream (io.TextIOBase): Output stream used to receive data from the DUT on the LAA. Defaults to sys.stdout.

  • force_str (bool | None): True to exchange data as string. False to exchange data as bytes. (Default) None to automatically use the best option. Exposed mostly for testing purposes.

Returns:

  • int: 0 if the serial connection completed by itself without errors. 1 if it failed or got interrupted.

Raises:

  • LAAError: If the LAA is offline or the request fails.

connect_async(self, name: str, readonly: bool = False, istream: io.TextIOBase = sys.stdin, ostream: io.TextIOBase = sys.stdout, force_str: bool | None = None) → asyncio.Task

Connects to a serial console with the DUT in an async task. Basically a wrapper for connect_async_fun that returns the task.

Args:

  • name (str): Name of the serial console, example “ttyUSB0”.

  • readonly (bool): True to start a readonly serial connection. (Default) False for an interactive connection

  • istream (io.TextIOBase): Input stream used to send data to the DUT on the LAA. Defaults to sys.stdin.

  • ostream (io.TextIOBase): Output stream used to receive data from the DUT on the LAA. Defaults to sys.stdout.

  • force_str (bool | None): True to exchange data as string. False to exchange data as bytes. (Default) None to automatically use the best option. Exposed mostly for testing purposes.

Returns:

  • asyncio.Task: Returns an async tasks that can be easily managed.

Raises:

  • LAAError: If the LAA is offline or the request fails.

connect_pexpect(self, name: str, readonly: bool = False) → laam.utils.ConnectPexpect

Connects to a serial console with the DUT in an Pexpect object.

Args:

  • name (str): Name of the serial console, example “ttyUSB0”.

  • readonly (bool): True to start a readonly serial connection. (Default) False for an interactive connection.

Returns:

  • laam.utils.ConnectPexpect: Custom Pexpect object.

Raises:

  • LAAError: If the LAA is offline or the request fails.

services

Monitor systemd services running on the LAA.

property laam.LAA.services

Interface for monitoring system services on the LAA. Based on the class Services.

help(laam.LAA.Services) for more info.

class laam.LAA.Services

Class for monitoring system services on the LAA.

NOTE: This class should NOT be instantiated directly by the user. Access to these functions is available only via the main LAA object.

list(self) → list[laam.models.Service]

Lists all the services on the LAA.

Returns:

  • list[laam.models.Service]: Returns a list of services.

Raises:

  • LAAError: If the LAA is offline or the request fails.

logs(self, name: str) → list

Returns the logs of a specific service.

Args:

  • name (str): Name of the service.

Returns:

  • list: Returns logs information.

Raises:

  • LAAError: If the LAA is offline or the request fails.

ssh

Manage the ssh keys used to ssh to the LAA.

property laam.LAA.ssh

Interface for monitoring ssh keys on the LAA. Based on the class Ssh.

help(laam.LAA.Ssh) for more info.

class laam.LAA.Ssh

Class for SSH key management.

NOTE: This class should NOT be instantiated directly by the user. Access to these functions is available only via the main LAA object.

list(self) → list

Lists all available ssh pub keys on the LAA.

Returns:

  • list: List of ssh keys. Empty list if the LAA has none.

Raises:

  • LAAError: If the LAA is offline or the request fails.

add(self, file)

Adds an ssh pub key to the LAA.

Args:

  • file (str, pathlib.Path, os.PathLike, io.BufferedReader): The file on the local machine to be uploaded. It can be a path to the object file itself.

Raises:

  • LAAError: If the LAA is offline or the request fails.

get(self, checksum: str) → dict

Prints details of one ssh pub key from the LAA.

Args:

  • checksum (str): ssh key fingerprint.

Returns:

  • dict: ssh pub key details.

Raises:

  • LAAError: If the LAA is offline or the request fails.

delete(self, checksum: str)

Removes an ssh pub key from the LAA.

Args:

  • checksum (str): ssh key fingerprint.

Raises:

  • LAAError: If the LAA is offline or the request fails.

system

Display LAA system information.

property laam.LAA.system

Interface for general system-level monitoring. Based on the class System.

help(laam.LAA.System) for more info.

class laam.LAA.System

Class for general system-level monitoring.

NOTE: This class should NOT be instantiated directly by the user. Access to these functions is available only via the main LAA object.

version(self) → str

Returns the OS software version on the LAA.

Returns:

  • str: Returns the version.

Raises:

  • LAAError: If the LAA is offline or the request fails.

fleet(self) → laam.models.SystemFleet

Returns information of the fleet that the LAA is registered with.

Returns:

  • laam.models.SystemFleet: Returns fleet information.

Raises:

  • LAAError: If the LAA is offline or the request fails.

logs(self) → list

Returns system logs from the LAA.

Returns:

  • list: Returns logs.

Raises:

  • LAAError: If the LAA is offline or the request fails.

usbs

Display usb devices.

property laam.LAA.usbs

Interface for monitoring the LAA’s USB sub-system. Based on the class USBs.

help(laam.LAA.USBs) for more info.

class laam.LAA.USBs

Class for monitoring the LAA’s USB sub-system.

NOTE: This class should NOT be instantiated directly by the user. Access to these functions is available only via the main LAA object.

list(self) → list[laam.models.USB]

Lists all the active usb connections seen by the operating system.

Returns:

  • list[laam.models.USB]: Returns a list of active usb connections with bus and device details.

Raises:

  • LAAError: If the LAA is offline or the request fails.

get(self, bus: str, device: str) → str

Get details of a USB device on a particular bus.

Args:

  • bus (str): Name of the bus to look into.

  • device (str): Name of the device to get details of.

Returns:

  • str: Returns the details of the device.

Raises:

  • LAAError: If the LAA is offline or the request fails.

workers

Manage LAVA workers running on the LAA.

property laam.LAA.workers

Interface for monitoring workers on the LAA. Based on the class Workers.

help(laam.LAA.Workers) for more info.

class laam.LAA.Workers

Class for monitoring workers on the LAA.

NOTE: This class should NOT be instantiated directly by the user. Access to these functions is available only via the main LAA object.

dockerfile(self, worker_id: int) → str

Returns the dockerfile of the specified worker.

Args:

  • worker_id (int): identifier of the worker.

Returns:

  • str: Returns a dockerfile content.

Raises:

  • LAAError: If the LAA is offline or the request fails.

list(self) → list[laam.models.Worker]

Lists all the workers active on the LAA.

Returns:

  • list[laam.models.Worker]: Returns a list of workers with main information.

Raises:

  • LAAError: If the LAA is offline or the request fails.

logs(self, worker_id: int) → list

Returns the logs of the specified worker.

Args:

  • worker_id (int): identifier of the worker.

Returns:

  • list: Returns logs.

Raises:

  • LAAError: If the LAA is offline or the request fails.

get(self, worker_id: int) → laam.models.WorkerDetails

Returns details of the specified worker.

Args:

  • worker_id (int): identifier of the worker.

Returns:

  • laam.models.WorkerDetails: Returns worker details.

Raises:

  • LAAError: If the LAA is offline or the request fails.

test(self, worker_id: int) → laam.models.WorkerConnection

Returns the connection status of the worker with its LAVA instance.

Args:

  • worker_id (int): identifier of the worker.

Returns:

  • laam.models.WorkerConnection: Returns connection status.

Raises:

  • LAAError: If the LAA is offline or the request fails.

Data models

Several methods return pydantic models defined in laam.models. They behave like regular objects (attribute access) and can be serialized back to JSON with their model_dump_json() method.

Argument choices

The methods that only accept a fixed set of values type their arguments with an enumeration from laam.models. All of them (except UsbPort, which is an IntEnum) are StrEnum, so plain strings are accepted as well: both laa.laacli.power(laam.models.VBus.V5V, "on") and laa.laacli.power("5v", "on") work. An invalid value raises LAAError before any request is sent.

Enumeration

Values

Used by

laam.models.Button

“1,” “2,” “power,” “reset”

laacli.button()

laam.models.ButtonState

“on,” “off,” “status”

laacli.button()

laam.models.LedState

“on,” “off”

laacli.led()

laam.models.VBus

“1v8,” “3v3,” “5v,” “12v”

laacli.power(), laacli.watt()

laam.models.PowerState

“on,” “off,” “reset,” “status”

laacli.power()

laam.models.TempProbe

“amb,” “dut,” “sys”

laacli.temp()

laam.models.UsbPort

0, 1, 2, 3, 4

laacli.usb()

laam.models.UsbState

“on,” “off,” “reset,” “start,” “status,” “vbus”

laacli.usb()

laam.models.UsbgMsState

“on,” “off,” “status”

laacli.usbg_ms()

laam.models.Compression

“xz,” “gz,” “bz2,” “zip,” “zstd”

files.decompress()

laam.models.SerialSpeed

“9600,” “115200,” “1.5M,” “3M”

serials.list()

laam.models.SerialReadStatus

“matched,” “timeout,” “eof”

SerialReadResult.status

Command responses

class laam.models.CommandResponse

Base model returned by the laacli commands.

Attributes:

  • cmd (list[str]): The command that was executed on the LAA.

  • code (int): Return code of the command (0 on success).

  • stdout (str): Standard output of the command.

  • stderr (str): Standard error of the command.

class laam.models.HistoryRow

A single sensor history sample.

Attributes:

  • t (int): Sample timestamp (epoch seconds).

  • v (list[float | None]): Sampled values aligned with History.ds (None for gaps).

class laam.models.History

Returned by laacli.history(). Inherits from CommandResponse.

Attributes:

  • start (int): Start of the returned window (epoch seconds).

  • end (int): End of the returned window (epoch seconds).

  • step (int): Sampling step in seconds.

  • ds (list[str]): Names of the data sources, in column order.

  • rows (list[laam.models.HistoryRow]): The history samples.

class laam.models.Rev

Returned by laacli.rev(). Inherits from CommandResponse.

Attributes:

  • revision (float | None): The hardware revision of the LAA.

class laam.models.Screenshot

Returned by laacli.screenshot(). Inherits from CommandResponse.

Attributes:

  • screenshot (str | None): The base64 encoded OLED screenshot.

class laam.models.Temp

Returned by laacli.temp(). Inherits from CommandResponse.

Attributes:

  • temperature (float | None): The temperature in °C.

class laam.models.Watt

Returned by laacli.watt(). Inherits from CommandResponse.

Attributes:

  • V (float | None): Voltage.

  • A (float | None): Current.

  • W (float | None): Power consumption.

Network

class laam.models.NetworkAddress

A single network address.

Attributes:

  • ip (str): The IP address.

  • prefix (int): The network prefix length.

  • flags (str): The address flags.

laam.models.NetworkAddresses

Alias for dict[str, list[laam.models.NetworkAddress]], keyed by interface name. Returned by network.addresses().

class laam.models.NetworkHostname

Returned by network.hostname().

Attributes:

  • hostname (str): The hostname of the LAA.

class laam.models.NetworkInterface

A network interface. network.interfaces() returns a list of these.

Attributes:

  • name (str): The interface name.

  • type (str): The interface type.

  • status (str): The interface status.

  • mac (str): The interface MAC address.

laam.models.NetworkInterfaces

Alias for list[laam.models.NetworkInterface]. Returned by network.interfaces().

class laam.models.NetworkRoute

A single network route.

Attributes:

  • src (str): The source address.

  • dst (str): The destination address.

  • via (str): The gateway address.

  • type (str): The route type.

  • protocol (str): The route protocol.

  • dst_prefix (int): The destination prefix length.

laam.models.NetworkRoutes

Alias for dict[str, list[laam.models.NetworkRoute]], keyed by interface name. Returned by network.routes().

Serials and services

class laam.models.Serial

A serial console. Returned by serials.get().

Attributes:

  • name (str): The serial name.

  • port (int): The ser2net port.

  • path (str): The device path.

  • speed (str): The serial speed (e.g. “115200n81”).

laam.models.SerialList

Alias for list[laam.models.Serial]. Returned by serials.list().

class laam.models.SerialReadResult

Returned by ConnectPexpect.read_until().

Attributes:

  • status (laam.models.SerialReadStatus): “matched”, “timeout” or “eof”.

  • pattern (str): The pattern that was waited for.

  • timeout (float): The timeout that was used.

  • output (str): All output captured before the match (or before timeout/EOF).

  • matched (str | None): The matched text, or None on timeout/EOF.

class laam.models.Service

A systemd service. Returned within services.list().

Attributes:

  • name (str): The service name.

  • status (str): The service status.

laam.models.ServiceList

Alias for list[laam.models.Service]. Returned by services.list().

System

class laam.models.SystemFleet

Returned by system.fleet().

Attributes:

  • token (str | None): The fleet token.

  • online (bool | None): Whether the LAA is online.

  • serial (str | None): The LAA serial number.

  • organization (str | None): The organization the LAA belongs to.

USB

class laam.models.USB

A single USB device. Returned within usbs.list().

Attributes:

  • bus (str): The USB bus.

  • device (str): The USB device.

  • id (str): The USB device id.

  • tag (str): The USB device description.

laam.models.USBList

Alias for list[laam.models.USB]. Returned by usbs.list().

Workers

class laam.models.Worker

A worker. Returned within workers.list().

Attributes:

  • id (int): The worker id.

  • name (str): The worker name.

  • server_url (str): The LAVA server URL.

laam.models.WorkerList

Alias for list[laam.models.Worker]. Returned by workers.list().

class laam.models.WorkerDetails

Returned by workers.get().

Attributes:

  • id (int): The worker id.

  • name (str): The worker name.

  • server_url (str): The LAVA server URL.

  • token (str | None): The worker token.

  • running (bool): Whether the worker is running.

class laam.models.WorkerConnection

Returned by workers.test().

Attributes:

  • connected (bool): Whether the worker is connected to its LAVA server.

  • error (str): The connection error, if any.

  • status_code (int | None): The HTTP status code of the connection test.

Exceptions

The following are the main exceptions that can be thrown by using an LAA object. They’re defined in laam.exceptions.

exception LAAError(Exception)

Base exception class for all LAA application errors.

Attributes:

  • message (str): The detailed error message describing the issue.

exception LAAConnectionError(LAAError)

Exception class for connection errors with the LAA (like wrong IP address or device offline).

Attributes:

  • message (str): The detailed error message describing the issue.

exception LAAApiError(LAAError)

Exception class for all HTTP API errors from the LAA.

Attributes:

  • message (str): The detailed error message describing the issue.

  • http_code (int): The relevant HTTP status code (e.g., 400, 500).

exception LAACliError(LAAError)

Exception class for all errors when running commands of the LAA itself.

Attributes:

  • message (str): The detailed error message describing the issue.

  • ret_json (dict): The error object returned from the LAA with ‘stdout’,’sterr’, and ‘code’

ConnectPexpect class

The laam.utils.ConnectPexpect is based on Pexpect.spawn class

The logfile member variable collects incoming data only.

class ConnectPexpect(pexpect.spawn)

In addition to the pexpect.spawn API, the following helper is available:

read_until(self, pattern, timeout: float = 30.0) → laam.models.SerialReadResult

Waits for a pattern on the serial console and returns all output up to it. Useful to detect known states: U-Boot prompt, kernel login, panic messages.

Args:

  • pattern: pexpect-style regex pattern to wait for (e.g. “U-Boot>”, “login:”).

  • timeout (float): Maximum seconds to wait. Defaults to 30.

Returns:

  • laam.models.SerialReadResult: The read status (“matched”, “timeout” or “eof”), the captured output and the matched text.

Examples

Here a few examples on how to use the LAA object in a script.

Example 1

List Files in my LAA

from laam import LAA
my_laa = LAA("my_laa_id")
print(my_laa.files.list())

=> ["file1", "file2", "file2"]

Example 2

Connect to a Serial in my LAA

from laam import LAA
import time
my_laa = LAA("my_laa_id")

# Assuming the DUT on the LAA uses `ttymxc3`
pexp_connection = my_laa.serials.connect_pexpect(name="ttymxc3")

# Logging the DUT console on a file
pexp_connection.logfile = open("serial.log", "w")

time.sleep(1)
pexp_connection.expect("Connected to port 2001", timeout=2)
pexp_connection.sendline("")

 # Waiting for uBoot on the DUT on my LAA
pexp_connection.expect("=>", timeout=40)
pexp_connection.send(b"usb start; usb info\n")
pexp_connection.expect("LAA USB Mass Storage Gadget", timeout=1)
pexp_connection.logfile.close()

Issues

In case you of problems open a work item

Backward Compatibility Policy

laam interfaces directly with LAA OS API endpoints. To ensure stability for automation and CI/CD pipelines, we follow these rules:

  • Version Baseline: Full backward compatibility is guaranteed starting with laam 0.9.0 and LAA OS 1.7.0.

  • Backward-Compatible API: LAA OS API endpoints are never removed. Existing endpoints can be changed in backward-compatible ways only. This means any laam version works with any LAA OS version >= 1.7.0.

  • Automation-First: laam must remain a reliable component for any third-party automation tools using an LAA.