/serial/`
（或 `.../port/`）地址，而不是 `/dev/ttyUSB*` 路径，因此它们在 tty 重新编号、重启和换端口之后依然有效。
* 线缆被分配之后，它**不再作为通用 UART 设备提供** —— 这条串行线属于那台仪器。
有些廉价的 USB 转串口仿制品共用同一个序列号（或者根本没有）。如果 `assign` 报告匹配到多根线缆，请改用 `--port` 把分配固定到 Box 的某个物理端口。代价是：把线缆换到别的端口之后，分配就失效了。
**移除分配：**
```bash theme={null}
lager nets assign --remove --serial 00000006 --box my-lager-box
```
该线缆会重新作为通用 UART 设备提供。**Net 与它的分配同生共死**：任何绑定到该分配 `serial://` 地址的已保存 Net 都会被自动删除，并在输出中报告。把线缆重新分配给另一台仪器时，以及把它的标识从 `--serial` 改为 `--port` 时，同样会发生这种级联删除。只有仅修改波特率的重新分配才会保留已有的 Net。
**当前可分配的设备：** Rigol DP711（单通道 RS-232 电源）。运行 `lager nets assign --list` 查看您的 Box 支持的目录。
### `delete`
按名称和类型删除某个 Net。
```bash theme={null}
lager nets delete NAME NET_TYPE [OPTIONS]
```
**参数：**
* `NAME` - 要删除的 Net 名称
* `NET_TYPE` - 该 Net 的类型（supply、debug、adc、i2c、spi 等）
**选项：**
* `--box TEXT` - Lager Box 名称或 IP
* `--yes` - 跳过确认提示
**示例：**
```bash theme={null}
# Delete a supply net (with confirmation)
lager nets delete supply1 supply --box my-lager-box
# Delete without confirmation
lager nets delete temp_sensor adc --box my-lager-box --yes
# Delete an I2C net
lager nets delete i2c_bus i2c --box my-lager-box --yes
```
### `delete-all`
删除 Lager Box 上全部已保存的 Net。**这是一个危险操作。**
```bash theme={null}
lager nets delete-all [OPTIONS]
```
**选项：**
* `--box TEXT` - Lager Box 名称或 IP
* `--yes` - 跳过确认提示
**示例：**
```bash theme={null}
# Delete all nets (requires confirmation)
lager nets delete-all --box my-lager-box
# Delete all nets without prompting
lager nets delete-all --box my-lager-box --yes
```
### `rename`
重命名已有的 Net。
```bash theme={null}
lager nets rename NAME NEW_NAME [OPTIONS]
```
**参数：**
* `NAME` - 该 Net 当前的名称
* `NEW_NAME` - 新名称（必须唯一）
**选项：**
* `--box TEXT` - Lager Box 名称或 IP
**示例：**
```bash theme={null}
lager nets rename supply1 main_power --box my-lager-box
```
### `tui`
启动基于终端的交互式界面来管理 Net。TUI 提供查看、创建和删除 Net 的可视化界面。
```bash theme={null}
lager nets tui [OPTIONS]
```
**选项：**
* `--box TEXT` - Lager Box 名称或 IP
**示例：**
```bash theme={null}
lager nets tui --box my-lager-box
```
**TUI 功能：**
* 浏览全部已连接的仪器及其通道
* 在引导式提示下创建新 Net（**+ Add Nets**）
* 阅读 Add 界面上的警告和提示。它们集中显示在同一个区块中，**Dismiss** 按钮可以隐藏该区块。
* 为 LabJack T7 的 `i2c` 或 `spi` Net 选择自定义引脚。该行上的铅笔按钮会打开一个同时编辑 Net 名称和引脚的编辑器。添加该 Net 时也会打开引脚对话框，除非您已经设置过引脚。对话框会显示当前引脚（默认值：I2C SDA=FIO4/SCL=FIO5；SPI CS=FIO0/SCK=FIO1/MOSI=FIO2/MISO=FIO3）。您可以为每个信号选择任意 DIO 引脚，也可以把 CS 设为 none 以使用 3 线 SPI。如果您又选回默认值，该 Net 会恢复默认通道。已被某个已保存 Net 占用的引脚会显示警告
* 用行上的铅笔按钮重命名新建的 Net
* 用 **Assign Device** 把自定义串行设备（RS-232 仪器）分配给它们的 USB 线缆 ——
这是 [`assign`](#assign) 的交互式版本，包含可选的创建 Net 步骤（`--as-net`）
* 选中一个已保存的 Net，对它执行 **Rename**、**Edit Details** 或 **Delete**。**Edit Details** 设置 Purpose、Notes 和 Tags，它只改动这三个字段，Net 记录的其余部分保持不变。
* 用 **Delete All Nets** 删除全部已保存的 Net
* 键盘导航（按 `q` 或 `Ctrl+C` 退出）
引脚编辑器只适用于 LabJack T7。您在 TUI 中添加的 LabJack U3 `i2c` 或 `spi` Net
使用默认引脚（SPI `FIO4-FIO7`，I2C `FIO6-FIO7`）。若要使用 U3 的其他引脚，请用 `lager nets add` 配合引脚选项。
### `set-script`
为已有的调试 Net 附加一个调试脚本 —— JLinkScript 或 OpenOCD 的 `.cfg`/`.tcl`。该文件保存在 Box 上，并在连接、烧录、擦除和复位操作中自动使用。
后端（J-Link 还是 OpenOCD）会根据两个信号自动识别：
1. **探针的 USB VID**，取自该 Net 的 `address` 字段（J-Link → `jlink`；ST-Link、FTDI、CMSIS-DAP 等 → `openocd`）。
2. **文件本身** —— 先看扩展名（`.JLinkScript` → jlink；`.cfg`/`.tcl`/`.ocd` → openocd），对没有扩展名的文件或 stdin，则以内容嗅探作为判定依据。
如果这两个信号互相矛盾，`set-script` 会以明确的错误拒绝执行，并请您用 `--backend` 指定其一。
一个调试 Net 同一时刻只携带**一个**脚本。如果另一个字段已经设置，
`set-script` 会清除它，并在 stderr 上打印一条黄色提示，这样就不会有内容悄悄消失。
```bash theme={null}
lager nets set-script NAME SCRIPT_PATH [OPTIONS]
```
**参数：**
* `NAME` - 调试 Net 的名称
* `SCRIPT_PATH` - 脚本文件的路径，或用 `-` 从 stdin 读取
**选项：**
* `--backend [jlink|openocd]` - 强制使用指定后端而不自动识别（当探针与文件矛盾时必填）
* `--box TEXT` - Lager Box 名称或 IP
**示例：**
```bash theme={null}
# Attach a J-Link script to a J-Link net (auto-detected)
lager nets set-script debug1 ./custom_connect.JLinkScript --box my-lager-box
# Attach an OpenOCD config to an FTDI/ST-Link/CMSIS-DAP net (auto-detected)
lager nets set-script debug1 ./probe.cfg --box my-lager-box
# Read the script from stdin
cat probe.cfg | lager nets set-script debug1 - --box my-lager-box
# Force a specific backend when the file or probe is ambiguous
lager nets set-script debug1 ./generic_script --backend openocd --box my-lager-box
```
### `remove-script`
移除调试 Net 上附加的调试脚本（J-Link 或 OpenOCD）。
```bash theme={null}
lager nets remove-script NAME [OPTIONS]
```
**参数：**
* `NAME` - 调试 Net 的名称
**选项：**
* `--backend [jlink|openocd]` - 只移除指定后端的脚本（默认移除已设置的那一个）
* `--box TEXT` - Lager Box 名称或 IP
**示例：**
```bash theme={null}
# Remove whichever script is attached
lager nets remove-script debug1 --box my-lager-box
# Only remove the J-Link script (leave any OpenOCD config in place)
lager nets remove-script debug1 --backend jlink --box my-lager-box
```
### `show-script`
显示调试 Net 上附加的调试脚本内容。脚本内容写入 stdout，因此 `> out.cfg` 可以正常工作。形如 `# OpenOCD config, 1247 bytes` 的一行摘要写入 stderr，它告诉您看到的是哪个后端的脚本，并且不会污染重定向的结果。
```bash theme={null}
lager nets show-script NAME [OPTIONS]
```
**参数：**
* `NAME` - 调试 Net 的名称
**选项：**
* `--backend [jlink|openocd]` - 只显示指定后端的脚本（默认显示已设置的那一个）
* `--box TEXT` - Lager Box 名称或 IP
**示例：**
```bash theme={null}
# Display the attached script (J-Link or OpenOCD)
lager nets show-script debug1 --box my-lager-box
# Save to a local file (the stderr banner doesn't end up in the file)
lager nets show-script debug1 --box my-lager-box > script.txt
```
### `show`
显示某个已保存 Net 的全部字段，包括用 `describe` 设置的用户元数据（`purpose`、`notes`、`tags`）。
```bash theme={null}
lager nets show NAME [OPTIONS]
```
**参数：**
* `NAME` - Net 名称
**选项：**
* `--json` - 以原始 JSON 输出
* `--box TEXT` - Lager Box 名称或 IP
**示例：**
```bash theme={null}
lager nets show battery1 --box my-lager-box
lager nets show battery1 --json --box my-lager-box
```
### `state`
显示每个已保存 Net 的实时硬件状态。Box 读取每台仪器，并为每个 Net 返回一段简短摘要。输出是 `lager nets` 的分组表格，在 `Channel` 之后多出一个 `State` 列。
```bash theme={null}
lager nets state [OPTIONS]
```
**选项：**
* `--box TEXT` - Lager Box 名称或 IP
* `--json` - 以原始 JSON 输出
**示例：**
```bash theme={null}
lager nets state --box my-lager-box
lager nets state --json --box my-lager-box
```
**输出示例：**
```
Name Net Type Channel State
=============================================================
Acroname 8Port [USB0::0x24FF::0x0013::EBFB0000::INSTR]
├── usb1 usb 0 –
└── usb2 usb 1 –
LabJack T7 [USB0::0x0CD5::0x0007::::INSTR]
├── adc1 adc AIN0 1.2345V
└── gpio1 gpio FIO0 HIGH (1)
Rigol DP811 [USB0::0x1AB1::0x0E11::DP8B123456::INSTR]
└── supply1 power-supply 1 CH1/on/3.30V/0.120A
SiLabs CP210x [USB0::0x10C4::0xEA60::0001::INSTR]
└── uart1 uart /dev/ttyUSB0 –
Nets reporting no state:
usb1, usb2: unreadable:
-> the hub is not on the USB bus at all -- unplugged, or its upstream port is off.
```
**状态值：**
| Net 类型 | 状态 | 示例 |
| ----------------- | ----------------- | ---------------------------------------------------- |
| `power-supply` | 通道、输出、电压、电流 | `CH1/on/3.30V/0.120A` |
| `battery` | 通道、输出、端电压、电流、荷电状态 | `CH1/on/3.70V/0.100A/50%` |
| `usb` | 端口供电 | `enabled`、`disabled` |
| `gpio` | 电平 | `HIGH (1)`、`LOW (0)` |
| `adc`、`dac` | 电压 | `1.2345V` |
| `thermocouple` | 温度 | `25.0°C` |
| `eload` | 模式、输入、电压、电流 | `/on/5.00V/1.000A` |
| `webcam` | 串流 | `stopped`、`streaming ` |
| `watt-meter` | 0.1 秒内的电流、电压、功率 | `0.1200A/3.300V/0.3960W` |
| `energy-analyzer` | 0.5 秒内的平均电流、电压、功率 | `0.1200A/3.300V/0.3960W` |
| `arm` | 位置 | `X0.0/Y250.0/Z0.0` |
| `debug` | GDB 服务器 | `connected/jlink`、`connected/openocd`、`disconnected` |
| `solar` | 辐照度 | `irr:` |
| `router` | 运行时长 | `up/` |
| `i2c` | 总线扫描中有响应的地址 | `0x48,0x76`、`no devices` |
没有探测方式的 Net 类型（例如 `uart`、`spi`、`scope` 和 `logic`）显示 `–`。
**Box 如何读取这些 Net：**
* Box 按仪器把 Net 分组，最多同时读取八台仪器。
* 所有仪器共用 8 秒的总预算。预算用尽时，每个没有响应的 Net 都报告 `deadline`。
* Box 逐个读取 USB 集线器。剩余预算不足 1 秒时它不再读取某个集线器，该集线器的 Net 报告 `hub-skipped`。
* 一次读取会获取与运行中的测试相同的仪器锁，因此该命令可能需要等待某个测试。
* Box 读取 `i2c` Net 时会做一次完整的总线扫描。
* 在 LabJack T7 上，一批操作读取全部 `gpio`、`adc` 和 `dac` Net，并且 `gpio` 读取不会改变引脚方向。
* 在 LabJack U3 上，`gpio` 或 `adc` 读取会把引脚设为数字或模拟模式。U3 的 `dac` Net 在 Box 设置过值之前显示 `–`。
**没有报告状态的 Net：**
在表格下方，命令会解释每一个有原因的 `–`，并按原因把 Net 分组。没有探测方式的 Net 类型属于正常情况，因此脚注不会列出它们。
| 原因 | 含义 |
| ---------------------- | ------------------------------- |
| `deadline` | 共用预算在该仪器响应之前用尽了。仅凭这一点并不说明该仪器慢。 |
| `unreadable: ` | Box 尝试读取该仪器但没有取到值。detail 中给出错误。 |
`usb` Net 还可能带有一个代码。当同一组中所有 Net 的代码相同时，脚注会多加一行补救建议：
| 代码 | 补救建议 |
| --------------------- | ------------------------------------------------- |
| `hub-unreachable` | 集线器在 USB 总线上但不响应。请检查它的供电和上游线缆。重启 Box 服务没有帮助。 |
| `hub-absent` | 集线器不在 USB 总线上。它被拔掉了，或者它的上游端口已断电。 |
| `hub-serial-mismatch` | 总线上有集线器，但没有一个的序列号与该 Net 指定的相符。请检查该 Net 的地址。 |
| `hub-skipped` | Box 没有读取该集线器，因为较慢的仪器先用掉了预算。该集线器可能是正常的，单独读取它就会有响应。 |
| `hub-open-failed` | 没有补救建议。原因中已给出该失败。 |
**JSON 输出：**
`--json` 打印一个数组，每个已保存的 Net 对应一个对象。每个对象包含该 Net 的全部已存字段，外加以下字段：
| 字段 | 说明 |
| ------------------------ | ------------------------------------------------------- |
| `live_state` | 状态字符串，或 `null` |
| `live_state_reason` | 状态为 `null` 的原因，包括 `no probe for role`。只有当 Box 发来原因时才存在。 |
| `live_state_reason_code` | `usb` Net 的代码。只有当 Box 发来代码时才存在。 |
没有这个端点的 Box 会打印一条提示，让您更新它。表格仍然会打印，只是每个 `State`
单元格都是 `–`。
### `describe`
为已保存的 Net 设置元数据，让 AI 智能体（以及人）理解该 Net 在被测设备上的作用。自 **lager 0.24.0** 引入；这些字段通过
[MCP 服务器](/source/zh/reference/mcp/overview)用于智能体辅助测试。
`--purpose`、`--notes` 或 `--tag`（或 `--clear-tags`）中至少要提供一个。
0.46.0 及以上版本的 Lager Box 会通过 HTTP 提供这些字段，因此已接入的控制平面可以同步它们。
```bash theme={null}
lager nets describe NAME [OPTIONS]
```
**参数：**
* `NAME` - Net 名称
**选项：**
* `-p`, `--purpose TEXT` - 一句话：该 Net 在被测设备上做什么
* `-n`, `--notes TEXT` - 可选备注（注意事项、跳线位置、示波器探测点）
* `-t`, `--tag TEXT` - 用于分类/匹配的标签（可重复）
* `--clear-tags` - 在添加新标签之前移除全部已有标签
* `--box TEXT` - Lager Box 名称或 IP
**示例：**
```bash theme={null}
# Describe a net's purpose and add tags
lager nets describe battery1 \
--purpose "Main battery rail powering the MCU" \
--tag power --tag critical \
--box my-lager-box
# Replace the existing tags
lager nets describe battery1 --clear-tags --tag power --box my-lager-box
# View what was set
lager nets show battery1 --box my-lager-box
```
## Net 类型参考
| Net 类型 | 说明 | 典型仪器 |
| --------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `power-supply`（别名 `supply`） | 电源输出 | Rigol DP800、Rigol DP711（通过 [`assign`](#assign)）、Keithley 2200/2280、Keysight E36200 |
| `battery`（别名 `batt`） | 电池模拟器 | Keithley 2281S |
| `solar` | 太阳能模拟器 | EA PSI/EL 系列 |
| `eload` | 电子负载 | Rigol DL3021 |
| `debug` | 调试探针 | J-Link、CMSIS-DAP、ST-Link |
| `adc` | 模拟输入 | LabJack T7、LabJack U3 |
| `dac` | 模拟输出 | LabJack T7、LabJack U3 |
| `gpio` | 数字 I/O | LabJack T7、LabJack U3（`FIO4` 及以上）、MCC USB-202 |
| `i2c` | I2C 总线 | LabJack T7、LabJack U3、Aardvark、FTDI FT232H / FT2232H / FT4232H |
| `spi` | SPI 总线 | LabJack T7、LabJack U3、Aardvark、FTDI FT232H / FT2232H / FT4232H |
| `scope` | 示波器 | Rigol MSO5000、PicoScope |
| `logic` | 逻辑分析仪通道 | Rigol MSO5204 |
| `uart` | 串口 | Prolific USB、SiLabs CP210x |
| `usb` | USB 端口控制 | Acroname 集线器、YKUSH、Plugable 扩展坞 |
| `webcam` | 视频采集 | Logitech BRIO |
| `arm` | 机械臂 | Rotrics Dexarm |
| `watt-meter` | 功率测量 | Yocto Watt |
| `thermocouple` | 温度传感器 | Phidget 热电偶 |
## 调试脚本工作流程
J-Link 和 OpenOCD 调试探针都可以携带一份自定义脚本，用于处理复位序列、时钟初始化、板级信号引脚分配，或其他设备专有行为。
Lager 为每个调试 Net 保存一个脚本 —— 要么是 JLinkScript，要么是 OpenOCD 的
`.cfg`/`.tcl`，绝不会两个都有。它在连接、烧录、擦除和复位操作中自动应用该脚本。
```bash theme={null}
# Attach a J-Link script to a J-Link probe (auto-detected from .JLinkScript extension)
lager nets set-script debug1 ./my_device.JLinkScript --box my-lager-box
# Attach an OpenOCD config to an FTDI / ST-Link / CMSIS-DAP probe (auto-detected)
lager nets set-script debug1 ./probe.cfg --box my-lager-box
# Verify what's attached (stderr says which backend, stdout has the content)
lager nets show-script debug1 --box my-lager-box
# Scripts are used automatically for all debug operations:
lager debug debug1 flash --hex firmware.hex --box my-lager-box
lager debug debug1 gdbserver --box my-lager-box
# Remove the script when no longer needed
lager nets remove-script debug1 --box my-lager-box
```
您也可以在创建 Net 时就附加脚本：
```bash theme={null}
lager nets add debug1 debug STM32F407VG USB::001::002 \
--jlink-script ./my_device.JLinkScript --box my-lager-box
lager nets add debug2 debug d2763 USB::003::004 \
--openocd-config ./probe.cfg --box my-lager-box
```
您还可以在本地 `.lager` 配置文件中按项目配置 J-Link 脚本：
```json theme={null}
{
"DEBUG": {
"debug1": "./scripts/my_device.JLinkScript"
}
}
```
当 Net 级脚本（通过 `set-script`）和项目级脚本（通过 `.lager` 配置）同时存在时，项目级脚本优先。
## 示例
```bash theme={null}
# List all nets
lager nets --box my-lager-box
# Create a new power supply net
lager nets add vdd_main power-supply 1 TCPIP::192.168.1.100::INSTR --box my-lager-box
# Create I2C and SPI bus nets
lager nets add i2c_sensors i2c FIO4-FIO5 USB0::0x0CD5::0x0007::::INSTR --box my-lager-box
lager nets add spi_flash spi SPI0 USB0::0x0403::0xE0D0::2238595116::INSTR --box my-lager-box
# Show the live state of every net
lager nets state --box my-lager-box
# Auto-create all available nets
lager nets add-all --box my-lager-box --yes
# Delete a specific net
lager nets delete old_supply supply --box my-lager-box --yes
# Rename a net
lager nets rename supply1 main_power --box my-lager-box
# Launch interactive manager
lager nets tui --box my-lager-box
# Bulk create from JSON file
lager nets add-batch testbed-nets.json --box my-lager-box
# Manage debug-probe scripts (J-Link or OpenOCD, auto-detected)
lager nets set-script debug1 ./custom_init.JLinkScript --box my-lager-box
lager nets set-script debug2 ./probe.cfg --box my-lager-box
lager nets show-script debug1 --box my-lager-box
lager nets remove-script debug1 --box my-lager-box
```
## 说明
* Net 名称在所有类型中全局唯一
* 用 `lager instruments --box ` 查看可用的仪器和通道
* 第一次配置 Net 时，TUI 是最省事的方式
* 用 `add-all` 可以快速为一台新的 Lager Box 配置合理的默认值
* LabJack T7、LabJack U3、Aardvark，以及 FTDI FT232H、FT2232H 和 FT4232H 适配器都支持 I2C 和 SPI Net
* 调试脚本（J-Link 和 OpenOCD 两者）以 base64 编码保存，并在调试操作期间自动解码
* 一个调试 Net 最多携带一个脚本（`jlink_script` 或 `openocd_config`）；`set-script` 通过在另一个字段已存在时清除它来保证这一点