greearb · saurabhkakade21 · Aug 27, 2026 · Aug 27, 2026
diff --git 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
@@ -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` | `<name1,name2...>` | 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` | `<hostname/IP/EID>` | Target destination for ping, iperf3, or curl. |
+| `--interval` | `<seconds>` | Interval between transmissions (e.g. `0.2`, `0.01`). |
+| `--cmd` | `"<custom command>"` | Custom shell command for generic endpoint execution. |
+| `--use_existing_eid` | `<eid1,eid2...>` | 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` | `<seconds>` | Max timeout in seconds to wait for port actions (appear, up, ip). Default: `60`. |
+| `--start_gen_cx` | `<name(s)>` or `all` | Starts specified generic CX(s) or `all` generic CXs on the manager into `RUNNING` state. |
+| `--stop_gen_cx` | `<name(s)>` or `all` | Stops specified generic CX(s) or `all` generic CXs on the manager (`STOPPED` state). |
+| `--del_gen_cx` | `<name(s)>` 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
@@ -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==<r> stations==<n> ssid==<s> ..."` | Configuration key-value string for station creation (e.g. `radio==wiphy0 stations==2 ssid==TestAP security==wpa2`). |
+| `--ports` / `--downstream_ports` | `<eid1,eid2...>` | Specifies target/downstream port EIDs or aliases (e.g. `1.1.eth2`, `sta0000`). |
+| `--upstream_port` | `<eid>` | Specifies the upstream port EID for cross-connection building (e.g. `1.1.eth1`). |
+| `--cx_names` / `--cx_name` | `<name1,name2...>` | 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` | `<name>` or `all` | Action: Starts specified cross-connection(s) or `all` existing cross-connections. |
+| `--stop_cx` | `<name>` or `all` | Action: Stops specified cross-connection(s) or `all` existing cross-connections. |
+| `--del_cx` | `<name>` or `all` | Action: Deletes specified cross-connection(s) or `all` existing cross-connections. |
+| `--del_stations` | `<name>` or `all` | Action: Deletes specified station ports (e.g. `sta5000`) or `all` station ports. |
+| `--ports_up` | `<name>` or `all` | Action: Sets specified ports or `all` station ports Admin UP. |
+| `--ports_down` | `<name>` 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
+  ```