# labgrid-project/labgrid architecture

> Architecture diagram of the GitHub repository labgrid-project/labgrid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/labgrid-project/labgrid
- Repository: https://github.com/labgrid-project/labgrid

## Overview

#### 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: [`labgrid/remote/coordinator.py`](https://github.com/labgrid-project/labgrid/blob/master/labgrid/remote/coordinator.py) (Coordinator), [`labgrid/driver/serialdriver.py`](https://github.com/labgrid-project/labgrid/blob/master/labgrid/driver/serialdriver.py) (Drivers), [`labgrid/factory.py`](https://github.com/labgrid-project/labgrid/blob/master/labgrid/factory.py) (Factory), [`labgrid/environment.py`](https://github.com/labgrid-project/labgrid/blob/master/labgrid/environment.py) (Environment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local automation"]
  node_environment["Environment<br/>runtime context<br/>[environment.py]"]
  node_pytest["Pytest plugin<br/>test integration<br/>[__init__.py]"]
  node_fixtures["Fixtures &amp; hooks<br/>pytest integration<br/>[fixtures.py]"]
  node_autoinstall["Autoinstall<br/>deployment automation<br/>[main.py]"]
end

subgraph group_core["Core model"]
  node_config["YAML configuration<br/>[config.py]"]
  node_factory["Factory<br/>object construction<br/>[factory.py]"]
  node_target["Target<br/>board model<br/>[target.py]"]
  node_binding["Bindings<br/>compatibility model<br/>[binding.py]"]
  node_resources["Resources<br/>hardware inventory<br/>[base.py]"]
  node_protocols["Driver protocols<br/>capability contracts<br/>[commandprotocol.py]"]
  node_drivers["Drivers<br/>hardware adapters<br/>[serialdriver.py]"]
  node_powerdrivers["Power drivers<br/>hardware adapters<br/>[powerdriver.py]"]
  node_strategies["Graph strategies<br/>board workflow<br/>[graphstrategy.py]"]
  node_steps["Step subsystem<br/>observability<br/>[step.py]"]
end

subgraph group_remote["Remote control plane"]
  node_client["Remote client<br/>remote CLI/client<br/>[client.py]"]
  node_coordinator["Coordinator<br/>scheduler service<br/>[coordinator.py]"]
  node_exporter["Exporter<br/>resource service<br/>[exporter.py]"]
  node_grpc["Coordinator protocol<br/>gRPC/protobuf schema"]
end

subgraph group_deploy["Deployment"]
  node_systemd["Systemd service<br/>service deployment"]
  node_docker["Docker deployment<br/>container deployment<br/>[docker-compose.yml]"]
end

node_pytest -->|"loads"| node_fixtures
node_fixtures -->|"creates"| node_environment
node_autoinstall -->|"uses"| node_environment
node_environment -->|"loads"| node_config
node_environment -->|"constructs through"| node_factory
node_factory -->|"instantiates"| node_target
node_factory -->|"instantiates"| node_resources
node_factory -->|"instantiates"| node_drivers
node_target -->|"contains"| node_binding
node_binding -->|"selects"| node_resources
node_binding -->|"binds"| node_drivers
node_drivers -->|"implements"| node_protocols
node_powerdrivers -.->|"driver family"| node_drivers
node_strategies -->|"orchestrates"| node_drivers
node_strategies -->|"records actions"| node_steps
node_client -->|"acquires places via"| node_coordinator
node_coordinator -->|"schedules exported resources"| node_exporter
node_client -->|"uses"| node_grpc
node_coordinator -->|"implements"| node_grpc
node_exporter -->|"exports local"| node_resources
node_systemd -.->|"runs"| node_coordinator
node_docker -.->|"deploys"| node_coordinator
node_docker -.->|"deploys"| node_exporter

click node_environment "https://github.com/labgrid-project/labgrid/blob/master/labgrid/environment.py"
click node_pytest "https://github.com/labgrid-project/labgrid/blob/master/labgrid/pytestplugin/__init__.py"
click node_fixtures "https://github.com/labgrid-project/labgrid/blob/master/labgrid/pytestplugin/fixtures.py"
click node_autoinstall "https://github.com/labgrid-project/labgrid/blob/master/labgrid/autoinstall/main.py"
click node_config "https://github.com/labgrid-project/labgrid/blob/master/labgrid/config.py"
click node_factory "https://github.com/labgrid-project/labgrid/blob/master/labgrid/factory.py"
click node_target "https://github.com/labgrid-project/labgrid/blob/master/labgrid/target.py"
click node_binding "https://github.com/labgrid-project/labgrid/blob/master/labgrid/binding.py"
click node_resources "https://github.com/labgrid-project/labgrid/blob/master/labgrid/resource/base.py"
click node_protocols "https://github.com/labgrid-project/labgrid/blob/master/labgrid/protocol/commandprotocol.py"
click node_drivers "https://github.com/labgrid-project/labgrid/blob/master/labgrid/driver/serialdriver.py"
click node_powerdrivers "https://github.com/labgrid-project/labgrid/blob/master/labgrid/driver/powerdriver.py"
click node_strategies "https://github.com/labgrid-project/labgrid/blob/master/labgrid/strategy/graphstrategy.py"
click node_steps "https://github.com/labgrid-project/labgrid/blob/master/labgrid/step.py"
click node_client "https://github.com/labgrid-project/labgrid/blob/master/labgrid/remote/client.py"
click node_coordinator "https://github.com/labgrid-project/labgrid/blob/master/labgrid/remote/coordinator.py"
click node_exporter "https://github.com/labgrid-project/labgrid/blob/master/labgrid/remote/exporter.py"
click node_grpc "https://github.com/labgrid-project/labgrid/blob/master/labgrid/remote/proto/labgrid-coordinator.proto"
click node_systemd "https://github.com/labgrid-project/labgrid/blob/master/contrib/systemd/labgrid-coordinator.service"
click node_docker "https://github.com/labgrid-project/labgrid/blob/master/dockerfiles/staging/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_environment,node_pytest,node_fixtures,node_autoinstall toneBlue
class node_config,node_factory,node_target,node_binding,node_resources,node_protocols,node_drivers,node_powerdrivers,node_strategies,node_steps toneAmber
class node_client,node_coordinator,node_exporter,node_grpc toneMint
class node_systemd,node_docker toneRose
```

## Components

### Local automation

- [Environment](https://github.com/labgrid-project/labgrid/blob/master/labgrid/environment.py): runtime context · Loads configuration and owns configured targets. · `labgrid/environment.py`
- [Pytest plugin](https://github.com/labgrid-project/labgrid/blob/master/labgrid/pytestplugin/__init__.py): test integration · `labgrid/pytestplugin/__init__.py`
- [Fixtures & hooks](https://github.com/labgrid-project/labgrid/blob/master/labgrid/pytestplugin/fixtures.py): pytest integration · Exposes environments, targets, and drivers to tests. · `labgrid/pytestplugin/fixtures.py`
- [Autoinstall](https://github.com/labgrid-project/labgrid/blob/master/labgrid/autoinstall/main.py): deployment automation · `labgrid/autoinstall/main.py`

### Core model

- [YAML configuration](https://github.com/labgrid-project/labgrid/blob/master/labgrid/config.py): configuration · Declares targets, resources, drivers, and remote references. · `labgrid/config.py`
- [Factory](https://github.com/labgrid-project/labgrid/blob/master/labgrid/factory.py): object construction · Resolves configured classes into the runtime object graph. · `labgrid/factory.py`
- [Target](https://github.com/labgrid-project/labgrid/blob/master/labgrid/target.py): board model · Board or test system assembled from bindings. · `labgrid/target.py`
- [Bindings](https://github.com/labgrid-project/labgrid/blob/master/labgrid/binding.py): compatibility model · Connects drivers to compatible resources. · `labgrid/binding.py`
- [Resources](https://github.com/labgrid-project/labgrid/blob/master/labgrid/resource/base.py): hardware inventory · Represents serial, USB, power, network, and other available hardware. · `labgrid/resource/base.py`
- [Driver protocols](https://github.com/labgrid-project/labgrid/blob/master/labgrid/protocol/commandprotocol.py): capability contracts · Stable caller-facing console, command, power, reset, and filesystem interfaces. · `labgrid/protocol/commandprotocol.py`
- [Drivers](https://github.com/labgrid-project/labgrid/blob/master/labgrid/driver/serialdriver.py): hardware adapters · Implements protocols for concrete transports and devices. · `labgrid/driver/serialdriver.py`
- [Power drivers](https://github.com/labgrid-project/labgrid/blob/master/labgrid/driver/powerdriver.py): hardware adapters · Controls concrete power-switch hardware. · `labgrid/driver/powerdriver.py`
- [Graph strategies](https://github.com/labgrid-project/labgrid/blob/master/labgrid/strategy/graphstrategy.py): board workflow · Composes driver actions into state transitions. · `labgrid/strategy/graphstrategy.py`
- [Step subsystem](https://github.com/labgrid-project/labgrid/blob/master/labgrid/step.py): observability · Captures nested hardware operations for reporting and logging. · `labgrid/step.py`

### Remote control plane

- [Remote client](https://github.com/labgrid-project/labgrid/blob/master/labgrid/remote/client.py): remote CLI/client · Acquires places and operates remote resources. · `labgrid/remote/client.py`
- [Coordinator](https://github.com/labgrid-project/labgrid/blob/master/labgrid/remote/coordinator.py): scheduler service · Maintains places, reservations, and scheduling. · `labgrid/remote/coordinator.py`
- [Exporter](https://github.com/labgrid-project/labgrid/blob/master/labgrid/remote/exporter.py): resource service · Exposes host-local resources to the remote lab. · `labgrid/remote/exporter.py`
- [Coordinator protocol](https://github.com/labgrid-project/labgrid/blob/master/labgrid/remote/proto/labgrid-coordinator.proto): gRPC/protobuf schema · Defines the coordinator API and generated stubs. · `labgrid/remote/proto/labgrid-coordinator.proto`

### Deployment

- [Systemd service](https://github.com/labgrid-project/labgrid/blob/master/contrib/systemd/labgrid-coordinator.service): service deployment · `contrib/systemd/labgrid-coordinator.service`
- [Docker deployment](https://github.com/labgrid-project/labgrid/blob/master/dockerfiles/staging/docker-compose.yml): container deployment · Packages coordinator and exporter deployments. · `dockerfiles/staging/docker-compose.yml`

## Connections

- 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
