How labgrid-project/labgrid works
Purpose and Entry Points
Labgrid is a Python library and command-line ecosystem for controlling embedded boards in development, automation, and pytest-driven testing. Its principal execution surfaces are local environment-based use, the pytest plugin, and remote client/coordinator/exporter services. Key paths: labgrid/environment.py, labgrid/pytestplugin/__init__.py, labgrid/remote/client.py.
Target, Resource, and Binding Model
A Target represents a board/test system assembled from declarative configuration. Resources model available hardware/connectivity (serial ports, USB, power, network); drivers bind to compatible resources and expose operations. This is the core abstraction boundary: callers use driver protocols rather than hardware-specific implementations. Key paths: labgrid/target.py, labgrid/resource/base.py, labgrid/binding.py.
Configuration and Object Construction
Environment and YAML configuration define targets, resources, drivers, and remote references. The factory resolves configured class names and instantiates the object graph, separating board inventory/configuration from automation code. Key paths: labgrid/config.py, labgrid/environment.py, labgrid/factory.py.
Protocols, Drivers, and Hardware Adapters
Protocols define capability contracts—console, command, power, reset, filesystem, video—while drivers implement them for concrete transports and devices. Driver families span serial/SSH shells and bootloaders, USB flashing/muxing, network services, measurement equipment, power switches, Docker, and QEMU. Key paths: labgrid/protocol/commandprotocol.py, labgrid/driver/serialdriver.py, labgrid/driver/powerdriver.py.
Strategies and Execution Observability
Strategies compose driver-level operations into stateful board workflows such as shell, U-Boot, Barebox, Docker, and graph-based transitions. The step subsystem captures nested operational steps and reporting/logging boundaries around hardware actions. Key paths: labgrid/strategy/graphstrategy.py, labgrid/strategy/bareboxstrategy.py, labgrid/step.py.
Remote Lab Control Plane
The remote layer distributes boards across hosts. Exporters expose local resources; a coordinator maintains places/reservations and scheduling; clients acquire remote places and operate exported resources. The boundary is gRPC/protobuf, with generated stubs derived from the coordinator schema. Key paths: labgrid/remote/exporter.py, labgrid/remote/coordinator.py, labgrid/remote/proto/labgrid-coordinator.proto.
Test and Automation Integration
The pytest plugin supplies fixtures and hooks that load a Labgrid environment and make targets/drivers available to tests; it is intentionally an integration layer rather than the test framework itself. Autoinstall provides automated deployment-oriented execution. Key paths: labgrid/pytestplugin/fixtures.py, labgrid/pytestplugin/hooks.py, labgrid/autoinstall/main.py.
Runtime and Infrastructure Boundaries
The primary runtime is Python. External control surfaces include serial devices, SSH, USB/udev, network power controllers, HTTP/REST, MQTT, Modbus, SNMP, Docker, QEMU, and instrument APIs. Remote deployments can run as systemd services or Dockerized coordinator/exporter stacks. Key paths: contrib/systemd/labgrid-coordinator.service, dockerfiles/Dockerfile, dockerfiles/staging/docker-compose.yml.
Main entry points: coordinator.py Coordinator · serialdriver.py Drivers · factory.py Factory · environment.py Environment
Components 20
Local automation
- Environment · Loads configuration and owns configured targets.
labgrid/environment.py - Pytest plugin
labgrid/pytestplugin/__init__.py - Fixtures & hooks · Exposes environments, targets, and drivers to tests.
labgrid/pytestplugin/fixtures.py - Autoinstall
labgrid/autoinstall/main.py
Core model
- YAML configuration · Declares targets, resources, drivers, and remote references.
labgrid/config.py - Factory · Resolves configured classes into the runtime object graph.
labgrid/factory.py - Target · Board or test system assembled from bindings.
labgrid/target.py - Bindings · Connects drivers to compatible resources.
labgrid/binding.py - Resources · Represents serial, USB, power, network, and other available hardware.
labgrid/resource/base.py - Driver protocols · Stable caller-facing console, command, power, reset, and filesystem interfaces.
labgrid/protocol/commandprotocol.py - Drivers · Implements protocols for concrete transports and devices.
labgrid/driver/serialdriver.py - Power drivers · Controls concrete power-switch hardware.
labgrid/driver/powerdriver.py - Graph strategies · Composes driver actions into state transitions.
labgrid/strategy/graphstrategy.py - Step subsystem · Captures nested hardware operations for reporting and logging.
labgrid/step.py
Remote control plane
- Remote client · Acquires places and operates remote resources.
labgrid/remote/client.py - Coordinator · Maintains places, reservations, and scheduling.
labgrid/remote/coordinator.py - Exporter · Exposes host-local resources to the remote lab.
labgrid/remote/exporter.py - Coordinator protocol · Defines the coordinator API and generated stubs.
labgrid/remote/proto/labgrid-coordinator.proto
Deployment
- Systemd service
contrib/systemd/labgrid-coordinator.service - Docker deployment · Packages coordinator and exporter deployments.
dockerfiles/staging/docker-compose.yml
Connections 23
- Pytest plugin → Fixtures & hooks: loads
- Fixtures & hooks → Environment: creates
- Autoinstall → Environment: uses
- Environment → YAML configuration: loads
- Environment → Factory: constructs through
- Factory → Target: instantiates
- Factory → Resources: instantiates
- Factory → Drivers: instantiates
- Target → Bindings: contains
- Bindings → Resources: selects
- Bindings → Drivers: binds
- Drivers → Driver protocols: implements
- Power drivers → Drivers: driver family
- Graph strategies → Drivers: orchestrates
- Graph strategies → Step subsystem: records actions
- Remote client → Coordinator: acquires places via
- Coordinator → Exporter: schedules exported resources
- Remote client → Coordinator protocol: uses
- Coordinator → Coordinator protocol: implements
- Exporter → Resources: exports local
- Systemd service → Coordinator: runs
- Docker deployment → Coordinator: deploys
- Docker deployment → Exporter: deploys