From 2f054c28152da43276db37e2befdd72e7ea622c1 Mon Sep 17 00:00:00 2001 From: Tarun Date: Thu, 27 Aug 2026 11:33:09 +0000 Subject: [PATCH] py-scripts/README.md: Add public toolbox CLI documentation for test_l3 and lf_test_generic Signed-off-by: Tarun --- py-scripts/README.md | 5 +- py-scripts/docs/lf_test_generic_toolbox.md | 117 ++++++++++++++++++++ py-scripts/docs/test_l3_toolbox.md | 121 +++++++++++++++++++++ 3 files changed, 241 insertions(+), 2 deletions(-) create mode 100644 py-scripts/docs/lf_test_generic_toolbox.md create mode 100644 py-scripts/docs/test_l3_toolbox.md diff --git a/py-scripts/README.md b/py-scripts/README.md index 8fbe55a1b..c6eec5ed8 100644 --- a/py-scripts/README.md +++ b/py-scripts/README.md @@ -6,8 +6,9 @@ To learn more about automating Chamber View tests like TR-398, WiFi Capacity Tes for more information. We also support Toolbox mode (--toolbox), enabling modular, standalone operations such as creating stations, managing cross-connections, and toggling port administrative states on supported scripts: -- [`test_l3.py`](./test_l3.py) — Layer-3 traffic generation (see [Toolbox Documentation](https://candelatech.atlassian.net/wiki/spaces/LANFORGE/pages/2854715395/test_l3.py+Toolbox+Mode+CLI+Reference+Usage+Guide)) -- [`lf_test_generic.py`](./lf_test_generic.py) — Generic endpoints and cross-connections (see [Toolbox Documentation](https://candelatech.atlassian.net/wiki/spaces/LANFORGE/pages/2859859969/lf_test_generic.py+Toolbox+Mode+CLI+Reference+Usage+Guide)) + +- [`test_l3.py`](./test_l3.py) — Layer-3 traffic generation (see [Toolbox CLI Reference Guide](./docs/test_l3_toolbox.md)) +- [`lf_test_generic.py`](./lf_test_generic.py) — Generic endpoints and cross-connections (see [Toolbox CLI Reference Guide](./docs/lf_test_generic_toolbox.md)) For more information, see [these documentation links](../README.md#documentation-links) or email [`support@candelatech.com`](mailto:support@candelatech.com) with questions. diff --git a/py-scripts/docs/lf_test_generic_toolbox.md b/py-scripts/docs/lf_test_generic_toolbox.md new file mode 100644 index 000000000..0d0e78a10 --- /dev/null +++ b/py-scripts/docs/lf_test_generic_toolbox.md @@ -0,0 +1,117 @@ +# LANforge `lf_test_generic.py` Toolbox Mode — CLI Reference & Usage Guide + +## 1. Overview +The `--toolbox` mode in [`lf_test_generic.py`](../lf_test_generic.py) provides standalone building-block operations for generic endpoints (ping, iperf3, curl, speedtest) and cross-connections without running full test suites. + +### Key Characteristics +- **Modular Lifecycle**: Build, start, stop, and delete generic endpoints/CXs independently. +- **Custom Naming**: Name endpoints and cross-connections via `--endp_names`. +- **Existing Ports**: Attach generic endpoints to existing stations or ethernet ports (`--use_existing_eid`). +- **Scoped `all`**: Actions using `all` apply only to Generic tab items and never affect other test types. + +--- + +## 2. CLI Reference + +| Flag / Option | Arguments | Description | +| :--- | :--- | :--- | +| `--toolbox` / `--tool_box` | *None* | Enables toolbox mode and exits immediately after completing requested action(s). | +| `--build` | *None* | Builds stations (if configured), generic endpoints, and cross-connections. | +| `--endp_names` / `--cx_names` | `` | Custom name(s) for the generic endpoint(s) and cross-connection(s). | +| `--test_type` | `ping`, `iperf3`, `iperf3-client`, `iperf3-server`, `lfcurl`, `speedtest` | Test type to configure for generic endpoints during build. | +| `--target` | `` | Target destination for ping, iperf3, or curl. | +| `--interval` | `` | Interval between transmissions (e.g. `0.2`, `0.01`). | +| `--cmd` | `""` | Custom shell command for generic endpoint execution. | +| `--use_existing_eid` | `` | Attach endpoints to existing ports (e.g. `1.1.sta0000`, `1.1.eth1`). | +| `--radio`, `--num_stations`, `--ssid`, `--passwd`, `--security` | Radio/Wi-Fi parameters | Parameters to auto-create Wi-Fi stations during build. | +| `--port_wait_time` | `` | Max timeout in seconds to wait for port actions (appear, up, ip). Default: `60`. | +| `--start_gen_cx` | `` or `all` | Starts specified generic CX(s) or `all` generic CXs on the manager into `RUNNING` state. | +| `--stop_gen_cx` | `` or `all` | Stops specified generic CX(s) or `all` generic CXs on the manager (`STOPPED` state). | +| `--del_gen_cx` | `` or `all` | Deletes specified generic CX(s) & endpoints or `all` generic CXs & endpoints on the manager. | + +--- + +## 3. Usage Guide & Examples + +### 1. Build (Create Endpoints & CXs without running traffic) + +- **Create new Wi-Fi stations + Ping generic endpoints**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --build \ + --test_type ping --target www.google.com \ + --radio wiphy1 --num_stations 2 --ssid TestSSID --passwd 12345678 --security wpa2 \ + --endp_names ping_sta0,ping_sta1 + ``` + +- **Build on an already-existing station (e.g., sub-second roaming ping)**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --build \ + --test_type ping --target 8.8.8.8 --use_existing_eid 1.1.sta0000 \ + --interval 0.01 --endp_names roam_ping_sta0 + ``` + +- **Build iPerf3 client endpoint**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --build \ + --test_type iperf3-client --target 192.168.1.100 --client_port 5201 \ + --use_existing_eid 1.1.sta0000 --endp_names iperf_client0 + ``` + +--- + +### 2. Start Generic Cross-Connections (`--start_gen_cx`) + +- **Start specific CX**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --start_gen_cx ping_sta0 + ``` + +- **Start multiple CXs**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --start_gen_cx ping_sta0,ping_sta1 + ``` + +- **Start all generic CXs**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --start_gen_cx all + ``` + +--- + +### 3. Stop Generic Cross-Connections (`--stop_gen_cx`) + +- **Stop specific CX**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --stop_gen_cx ping_sta0 + ``` + +- **Stop all generic CXs**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --stop_gen_cx all + ``` + +--- + +### 4. Delete Generic Cross-Connections & Endpoints (`--del_gen_cx`) + +- **Delete specific CX and its endpoint**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --del_gen_cx ping_sta0 + ``` + +- **Delete all generic CXs and generic endpoints**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --del_gen_cx all + ``` + +--- + +### 5. Chained Workflow (Build and Start in one line) + +- **Build stations/endpoints and start traffic immediately**: + ```bash + python3 py-scripts/lf_test_generic.py --mgr 192.168.244.45 --toolbox --build \ + --test_type ping --target www.google.com \ + --radio wiphy1 --num_stations 2 --ssid TestSSID --passwd 12345678 --security wpa2 \ + --endp_names ping_sta0,ping_sta1 --start_gen_cx all + ``` diff --git a/py-scripts/docs/test_l3_toolbox.md b/py-scripts/docs/test_l3_toolbox.md new file mode 100644 index 000000000..547b4cc03 --- /dev/null +++ b/py-scripts/docs/test_l3_toolbox.md @@ -0,0 +1,121 @@ +# LANforge `test_l3.py` Toolbox Mode — CLI Reference & Usage Guide + +## 1. Overview +The `--toolbox` mode in [`test_l3.py`](../test_l3.py) provides standalone building-block operations for station management, Layer-3 cross-connections, and port administration without running full test loops. + +### Key Characteristics +- **Modular Actions**: Create stations, build cross-connections, toggle port states, and clean up. +- **Custom CX Naming**: Assign custom names to cross-connections via `--cx_names`. +- **Admin State Control**: Set ports Admin UP or DOWN (`--ports_up`, `--ports_down`). +- **Collision Avoidance**: Auto-detects existing stations and adjusts offsets to avoid conflicts. +- **Selective / Bulk Control**: Target specific items by name or apply across `all`. +- **Automation Ready**: Returns `0` on success and `1` on error. + +--- + +## 2. Command Line Arguments Reference + +| Flag / Option | Arguments | Description | +| :--- | :--- | :--- | +| `--toolbox` / `--tool_box` | *None* | Enables standalone toolbox mode and exits upon action completion. | +| `--create_station` | *None* | Action: Creates Wi-Fi stations using specified `--radio` configuration. | +| `--radio` | `"radio== stations== ssid== ..."` | Configuration key-value string for station creation (e.g. `radio==wiphy0 stations==2 ssid==TestAP security==wpa2`). | +| `--ports` / `--downstream_ports` | `` | Specifies target/downstream port EIDs or aliases (e.g. `1.1.eth2`, `sta0000`). | +| `--upstream_port` | `` | Specifies the upstream port EID for cross-connection building (e.g. `1.1.eth1`). | +| `--cx_names` / `--cx_name` | `` | Custom cross-connection name or prefix (e.g. `wlan0`, `toolbox`). | +| `--build_cxs` / `--build_cx` | *None* | Action: Builds Layer-3 cross-connections between `--upstream_port` and `--ports`. | +| `--start_cx` | `` or `all` | Action: Starts specified cross-connection(s) or `all` existing cross-connections. | +| `--stop_cx` | `` or `all` | Action: Stops specified cross-connection(s) or `all` existing cross-connections. | +| `--del_cx` | `` or `all` | Action: Deletes specified cross-connection(s) or `all` existing cross-connections. | +| `--del_stations` | `` or `all` | Action: Deletes specified station ports (e.g. `sta5000`) or `all` station ports. | +| `--ports_up` | `` or `all` | Action: Sets specified ports or `all` station ports Admin UP. | +| `--ports_down` | `` or `all` | Action: Sets specified ports or `all` station ports Admin DOWN. | + +--- + +## 3. Usage Guide & CLI Examples + +### 1. Create Wi-Fi Stations +Creates 2 stations on radio `wiphy0` with WPA2 security: +```bash +python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox \ + --create_station --radio "radio==wiphy0 stations==2 ssid==TestAP ssid_pw==12345678 security==wpa2" +``` + +### 2. Build Layer-3 Cross-Connections +- **Build with Default Names** (between upstream `1.1.eth1` and station ports `1.1.sta5000,1.1.sta5001`): + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox \ + --build_cxs --upstream_port 1.1.eth1 --ports 1.1.sta5000,1.1.sta5001 + ``` + +- **Build with Custom CX Name (`--cx_names`)**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox \ + --build_cxs --upstream_port 1.1.eth1 --ports 1.1.sta0000 --cx_names toolbox + ``` + +- **Build Ethernet/VLAN Cross-Connections (`--downstream_ports`)**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox \ + --build_cxs --upstream_port 1.1.eth1 --downstream_ports 1.1.eth2 --cx_names eth_link + ``` + +### 3. Start Cross-Connections (`--start_cx`) +- **Start specific CX by name**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --start_cx toolbox + ``` +- **Start all CXs**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --start_cx all + ``` + +### 4. Stop Cross-Connections (`--stop_cx`) +- **Stop specific CX by name**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --stop_cx toolbox + ``` +- **Stop all CXs**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --stop_cx all + ``` + +### 5. Set Port Admin State (`--ports_down` & `--ports_up`) +- **Set Admin DOWN**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --ports_down 1.1.sta5000,1.1.eth2 + ``` +- **Set Admin UP**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --ports_up 1.1.sta5000,1.1.eth2 + ``` + +### 6. Delete Cross-Connections & Stations +- **Delete specific CX by name**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --del_cx toolbox + ``` +- **Delete all CXs**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --del_cx all + ``` +- **Delete specific stations**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --del_stations sta5000,sta5001 + ``` +- **Delete all station ports**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox --del_stations all + ``` + +--- + +### 7. Chained Workflows + +- **Create Stations + Build CXs in Single Execution**: + ```bash + python3 py-scripts/test_l3.py --lfmgr 192.168.244.45 --toolbox \ + --create_station --radio "radio==wiphy0 stations==2 ssid==TestAP ssid_pw==12345678 security==wpa2" \ + --build_cxs --upstream_port 1.1.eth1 --cx_names test_flow + ```