Skip to content

docs: add aparcar lab #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aparcar wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add aparcar lab #136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d053cff
wip: add lab docs
aparcar Jul 17, 2025
800e2fd
docs: add aparcar and format leinelab
aparcar Jul 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 58 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,21 @@ real. Using [`labgrid`](https://labgrid.readthedocs.io/en/latest/) to control
the devices, the framework offers a simple way to write tests and run them on
different hardware.

## Requirements
## Testing

This section provides information on how to run tests using OpenWrt Testing,
either on real or emulated devices. If you want to deploy real devices for
testing, please see the *Lab Setup* section..

### Requirements

There are multiple ways to run tests, on real or emulated devices.

- An OpenWrt firmware image
- Python and [`uv`](https://docs.astral.sh/uv/)
- QEMU
- QEMU (for emulated devices)


## Setup
### Setup

For maximum convenience, clone the repository inside the `openwrt.git`
repository as `tests/`:
Expand Down Expand Up @@ -51,8 +58,6 @@ You can run tests via the Makefile or directly using `pytest`.

You can start runtime and shell tests via the Makefile.

#### Runtime tests

```shell
cd /path/to/openwrt.git
make tests/x86-64 V=s
Expand Down Expand Up @@ -145,3 +150,50 @@ Lastly, unlock your device when you're done:
```shell
uv run labgrid-client unlock
```

## Lab Setup

Setting up a new lab involves several steps and is a fun and curious process,
however some precise and forward thinking is required to ensure a successful
setup. This section describes a low-cost setup usable for network communities
and individuals. Larger setups will be added in the future.

### Concept

The general idea is to have independent labs (i.e. coordinator and exporter) and
connect them over a global coordinator, which has access to all labs. Developers
and CI can access individual labs over the global coordinator, the graphic below
gives an idea.

![](docs/img/labnet_overview.png)

This decentralized approach allows labs to function even if the global
coordinator is down. Also access management can be individually controlled, i.e.
which developer may access which lab or at what time automated CIs run tests.

### Requirements

* Coordinator/Exporter (i.e **RaspberryPi 5**)
* PoE switch (i.e. **Zyxel GS1900-8HP**)
* PoE Splitter (12v, 5v, etc.)
* Devices-Under-Test (DUTs)
* Some cables
* A guest wifi
Comment on lines +174 to +181
Copy link

@francoriba francoriba Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This assumes that all labs use PoE for power control, right?. Maybe it would be nice to have a "Power Control Options" subsection that mentions more approaches. I'm thinking something like this:

Suggested change
### Requirements
* Coordinator/Exporter (i.e **RaspberryPi 5**)
* PoE switch (i.e. **Zyxel GS1900-8HP**)
* PoE Splitter (12v, 5v, etc.)
* Devices-Under-Test (DUTs)
* Some cables
* A guest wifi
### Requirements
#### Core Components (All Labs)
- Coordinator/Exporter host (e.g., Raspberry Pi 5, ThinkPad, etc.)
- Internet access for coordinator (wired or via guest WiFi network)
- Network switch (managed recommended)
- USB-to-serial adapters (one per DUT)
- Devices-Under-Test (DUTs)
- Ethernet cables
#### Power Control Options (multiple approaches depending on your preferences)
**Option A: PoE-based (Recommended for simplicity)**
- PoE-capable managed switch (e.g., Zyxel GS1900-8HP)
- PoE splitters matching DUT voltage requirements (5V, 12V, etc.)
- Labgrid will use `NetworkPowerPort` resource
**Option B: Relay-based (Lower cost, more flexible)**
- Arduino or similar microcontroller (software interface required)
- Relay module (one channel per DUT)
- USB cable (controller to coordinator)
- PDUDaemon software
- Labgrid will use `PDUDaemonPort` resource
**Option C: GPIO-based (Raspberry Pi only)**
- GPIO-controlled relay board
- Labgrid will use GPIO drivers


### Setup

For a minimal setup, a single device runs the coordinator and exporter at the
same time, from now on called controller. The controller is connected to a PoE
switch, managing network and power. A serial to USB-to-serial converter is
needed for each *Device Under Test* (DUT) as well as a PoE splitter.

> [!NOTE]
> Larger setups may run multiple exporters, each connected to a separate PoE
> switch.

![](docs/img/labnet_setup.png)

### Conroller
Copy link

@francoriba francoriba Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Conroller
### Controller


The controller should be setup via Ansible, which install `labgrid` as well as
Copy link

@francoriba francoriba Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The controller should be setup via Ansible, which install `labgrid` as well as
The controller should be setup via Ansible, which installs `labgrid` as well as

all required tools.
Binary file added docs/img/labnet_overview.png
View file
Open in desktop
Copy link

@francoriba francoriba Dec 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @aparcar ! I have a question that came to mind while looking at tihis diagram. Each lab has a "Lab Coordinator." How are these coordinators different from the Global Coordinator / what are they needed for? My guess is that the green lab coordinators are only involved in local testing of each lab. Otherwise, the interaction is directly between the global coordinator and each lab's exporter.. is this right?

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/labnet_setup.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
57 changes: 57 additions & 0 deletions docs/labs/aparcar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Devices in LeineLab Testlab
Copy link

@francoriba francoriba Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this should be Aparcar lab, right?

Copy link

@francoriba francoriba Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Devices in LeineLab Testlab
# Devices in Aparcar Lab


## Coordinator/Exporter

### Raspberry Pi 5

- Ethernet (eth0): Connection to Switch
- Hardware serial: Not connected
- GPIO: Not connected
- USB: Connected to USB Serial converters and a USB hub

## Switch

### Zyxel GS1900-10HP Switch

- Ethernet Ports:
- Port 1 (eth): Connected to managed switch untagged VLAN 101
- Port 2 (eth): Connected to managed switch untagged VLAN 102
- Port 3 (eth): Connected to managed switch untagged VLAN 103
- Port 4 (eth): Connected to managed switch untagged VLAN 104
- Port 5 (eth): Connected to managed switch untagged VLAN 105
- Port 6 (eth): Connected to managed switch untagged VLAN 106
- Port 7 (eth): Connected to managed switch untagged VLAN 107
- Port 8 (eth): Connected to managed switch untagged VLAN 108
- Port 9 (sfp): Connected to unmanaged switch untagged VLAN 200
- Port 10 (sfp): Connected to Raspberry Pi 5

## DUT

### genexis_pulse-ex400

- WAN Port: Connected to unmanaged switch
- LAN-Port 1: Connected to managed switch VLAN 101

### tplink_tl-wdr3600-v1

- WAN Port: Connected to unmanaged switch
- LAN-Port 1: Connected to managed switch VLAN 102

### openwrt_one

- WAN Port: Connected to managed switch VLAN 103
- LAN-Port 1: Connected to managed switch VLAN 104

### bananapi_bpi-r4

- WAN Port: Connected to unmanaged switch
- LAN-Port 1: Connected to managed switch VLAN 105

### glinet_gl-mt6000

- WAN Port: Connected to unmanaged switch
- LAN-Port 1: Connected to managed switch VLAN 107

### rpi-4

- LAN-Port 1: Connected to managed switch VLAN 108
26 changes: 14 additions & 12 deletions docs/labs/leinelab.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,24 @@
# Devices in LeineLab Testlab

## Coordinator/Exporter

- Raspberry Pi 3
- Ethernet (eth0): Uplink
- USB NIC (eth1): Connected to LAN iface of TPLink 1043
- Hardware serial: Connected to hardware serial of TPLink 1043
- GPIO: Control power and reset-pin of TPLink 1043 via Relays
- Ethernet (eth0): Uplink
- USB NIC (eth1): Connected to LAN iface of TPLink 1043
- Hardware serial: Connected to hardware serial of TPLink 1043
- GPIO: Control power and reset-pin of TPLink 1043 via Relays

## DUT

- TPLink 1043
- WAN-Port: Uplink
- LAN-Port 1: Connected to USB NIC of Raspberry Pi
- LAN-Port 2: n/c
- LAN-Port 3: n/c
- LAN-Port 4: n/c
- Serial: Connected to hardware serial of TPLink 1043
- Power: Controlled by relais via GPIO
- Reset-Pin: Controlled by relais via GPIO
- WAN-Port: Uplink
- LAN-Port 1: Connected to USB NIC of Raspberry Pi
- LAN-Port 2: n/c
- LAN-Port 3: n/c
- LAN-Port 4: n/c
- Serial: Connected to hardware serial of TPLink 1043
- Power: Controlled by relais via GPIO
- Reset-Pin: Controlled by relais via GPIO

## Misc Hardware

Expand Down
Loading