diff --git a/docs/guide/FirmwareUpgrade.md b/docs/guide/FirmwareUpgrade.md index 88dde1c..8189755 100644 --- a/docs/guide/FirmwareUpgrade.md +++ b/docs/guide/FirmwareUpgrade.md @@ -29,47 +29,52 @@ The iopsys firmware upgrade system provides a robust, dual-bank firmware managem ### System Components ``` -┌─────────────────────────────────────────────────────────────────────┐ -│ Upgrade Interfaces │ -├──────────┬──────────────────┬──────────────────┬────────────────────┤ -│ TR-069 │ USP/TR-369 │ DHCP │ CLI │ -│ (CWMP) │ │ Onboarding │ (fwbank) │ -│ Agent │ ┌──────────┐ │ │ │ -│ icwmp │ │ Sulu │ │ udhcpc hooks │ Shell script │ -│ │ │ GUI │◄───┤ WebSocket │ invocation │ -│ │ └────┬─────┘ │ │ │ -│ │ │ │ │ │ -│ │ ┌────▼─────┐ │ │ │ -│ │ │ OB-USPa │ │ │ │ -│ │ │ Agent │ │ │ │ -└────┬─────┴──────┬───────────┴────┬─────────────┴──────┬─────────────┘ - │ │ │ │ - ├────────────┴────────────────┤ │ - │ BBF Datamodel (sysmngr) │ │ - │ Device.DeviceInfo. │ │ - │ FirmwareImage.{i}. │ │ - │ Download() / Activate() │ │ - └──────────────┬──────────────┘ │ - │ │ - └───────────────┬───────────────────┘ - │ - ┌───────▼────────┐ - │ fwbank │ (UBUS: fwbank.upgrade) - │ (Core logic) │ - └───────┬────────┘ - │ - ┌────────────────┼────────────────┐ - │ │ │ - ┌─────▼─────┐ ┌──────▼──────┐ ┌─────▼─────┐ - │ opconf │ │ sysupgrade │ │ ubus │ - │ (config) │ │ (OpenWrt) │ │ (events) │ - └───────────┘ └─────────────┘ └───────────┘ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ Upgrade Interfaces │ +├──────────┬──────────────────────────┬──────────────────┬────────────────────┤ +│ TR-069 │ USP/TR-369 │ DHCP │ fwbank CLI │ +│ (CWMP) │ │ Onboarding │ │ +│ │ │ │ │ +│ icwmp │ ┌─────────┬─────────┐ │ udhcpc hooks │ /etc/sysmngr/ │ +│ Agent │ │ Sulu │ dmcli │ │ │ fwbank │ +│ │ │ GUI │ CLI │ │ │ │ +│ │ └────┬────┴────┬────┘ │ │ │ +│ │ │ │ │ │ │ +│ │ └────┬────┘ │ │ │ +│ │ │ │ │ │ +│ │ ┌─────▼──────┐ │ │ │ +│ │ │ OB-USPa │ │ │ │ +│ │ │ Agent │ │ │ │ +└────┬─────┴──────┴────┬───────┴──────┴────┬─────────────┴──────┬─────────────┘ + │ │ │ │ + ├─────────────────┤ │ │ + │ BBF Datamodel │ │ │ + │ (sysmngr) │ │ │ + │ Device.DeviceInfo │ │ + │ .FirmwareImage.{i} │ │ + │ Download()/Activate() │ │ + └──────────┬──────┘ │ │ + │ │ │ + └────────────┬──────────────┴────────────────────┘ + │ + ┌───────▼────────┐ + │ fwbank │ (UBUS: fwbank.upgrade) + │ (Core logic) │ + └───────┬────────┘ + │ + ┌────────────────┼────────────────┐ + │ │ │ + ┌─────▼─────┐ ┌──────▼──────┐ ┌─────▼─────┐ + │ opconf │ │ sysupgrade │ │ ubus │ + │ (config) │ │ (OpenWrt) │ │ (events) │ + └───────────┘ └─────────────┘ └───────────┘ ``` **Protocol Paths:** - **TR-069/USP:** Use BBF datamodel → sysmngr → fwbank UBUS -- **DHCP/CLI:** Call fwbank UBUS directly (bypass BBF datamodel) -- **Sulu:** Web GUI using USP/TR-369 protocol via OB-USPa agent +- **DHCP/fwbank CLI:** Call fwbank UBUS directly (bypass BBF datamodel) +- **Sulu:** Web GUI using USP/TR-369 protocol via OB-USPa agent (WebSocket) +- **dmcli:** CLI using BBF datamodel via local UBUS or remote USP (MQTT/WebSocket) --- @@ -358,8 +363,10 @@ The firmware upgrade system supports **four upgrade methods**: 4. **CLI** - Direct command-line access → Direct UBUS to fwbank > **Important Notes:** -> - **Sulu** is a web GUI that uses **USP/TR-369 protocol** to communicate with the device. It is not a separate upgrade method but rather a user-friendly client for USP operations. -> - **DHCP and CLI** bypass the BBF datamodel layer and call fwbank UBUS methods directly, providing lower-level access but with limited protocol features (no async operations, no transfer complete events). +> - **Sulu and dmcli** are clients that use **USP/TR-369 protocol** to access the BBF datamodel. They are not separate upgrade methods but rather different interfaces for USP operations. +> - **Sulu:** Browser-based GUI with WebSocket to local OB-USPa agent +> - **dmcli:** Command-line interface that can connect locally (UBUS) or remotely (USP) +> - **DHCP and fwbank CLI** bypass the BBF datamodel layer and call fwbank UBUS methods directly, providing lower-level access but with limited protocol features (no async operations, no transfer complete events). ### Method 1: USP/TR-369 (Recommended) @@ -369,6 +376,7 @@ The firmware upgrade system supports **four upgrade methods**: **Clients:** - **Sulu Web GUI** - Browser-based interface (WebSocket connection to OB-USPa) +- **dmcli** - Command-line interface for BBF datamodel (local UBUS or remote USP) - **External USP Controller** - Remote management platform (STOMP/MQTT/WebSocket) **Configuration:** Per-operation parameters (highest flexibility) @@ -440,6 +448,89 @@ await downloadToDevice({ **Result:** Operator config reset, user WiFi/network settings preserved +#### USP Client 3: dmcli (Data Model CLI) + +**Interface:** Interactive command-line interface for BBF data models + +**Modes:** +- **Local Mode:** Run directly on device via SSH/console (uses local UBUS to sysmngr) +- **Remote Mode:** Run from computer and connect via USP (MQTT/WebSocket to OB-USPa) + +**Configuration:** Full control via operation parameters + +**Installation:** +```bash +# On device (pre-installed) +ssh operator@192.168.1.1 +dmcli + +# On host computer (requires NodeJS) +npm install -g @gnx/dmcli@latest +``` + +**Remote Connection Setup:** +```bash +# Configure USP connection profile +dmcli +# set Settings.USP.ActiveConnectionProfile iowrt-gnx-operator +# do Settings.USP.Connect() +``` + +##### Example: Firmware Upgrade via dmcli + +**Interactive Mode:** +```bash +# Start dmcli +dmcli + +# Navigate to firmware object +# cd Device.DeviceInfo.FirmwareImage.2 + +# Check current status +# get Status Version Name + +# Download firmware +# do Download() URL=https://firmware.isp.com/v5.15.0.itb AutoActivate=1 X_IOWRT_EU_KeepConfig=1 X_IOWRT_EU_KeepOpConf=0 X_IOWRT_EU_ConfigScope=UserOnly + +# For async operations, use -n flag to not wait +# do -n Download() URL=https://firmware.isp.com/v5.15.0.itb AutoActivate=1 +``` + +**Non-Interactive Mode:** +```bash +# Single command execution +dmcli do Device.DeviceInfo.FirmwareImage.2.Download() \ + URL=https://firmware.isp.com/v5.15.0.itb \ + AutoActivate=1 \ + X_IOWRT_EU_KeepConfig=1 \ + X_IOWRT_EU_KeepOpConf=0 \ + X_IOWRT_EU_ConfigScope=UserOnly + +# Activate previously downloaded firmware +dmcli do Device.DeviceInfo.FirmwareImage.2.Activate() \ + X_IOWRT_EU_KeepConfig=1 \ + X_IOWRT_EU_KeepOpConf=1 \ + X_IOWRT_EU_ConfigScope=All +``` + +**Configuration Control:** + +| Feature | dmcli Support | +|---------|---------------| +| KeepConfig | ✅ Full control via parameter | +| KeepOpConf | ✅ Full control via parameter | +| ConfigScope | ✅ Full control via parameter | +| Authentication | ✅ HTTP auth in URL parameter | +| Progress Tracking | ✅ Async mode with `-n` flag | +| Auto-completion | ✅ Tab completion for paths and parameters | + +**Advantages:** +- Full access to BBF datamodel with tab completion +- Can be scripted for automation +- Supports both local and remote operation +- Comprehensive parameter control +- Interactive exploration of data model + #### Example: Scheduled Activation ```json @@ -1545,6 +1636,37 @@ reboot: 0 (manual) ### Common Commands +#### Using dmcli (BBF Datamodel - Recommended) + +```bash +# Check firmware status +dmcli get Device.DeviceInfo.FirmwareImage. + +# Upgrade with full config preservation +dmcli do Device.DeviceInfo.FirmwareImage.2.Download() \ + URL=https://fw.example.com/firmware.itb \ + AutoActivate=1 \ + X_IOWRT_EU_KeepConfig=1 \ + X_IOWRT_EU_KeepOpConf=1 \ + X_IOWRT_EU_ConfigScope=All + +# Upgrade with operator reset, keep user settings +dmcli do Device.DeviceInfo.FirmwareImage.2.Download() \ + URL=https://fw.example.com/firmware.itb \ + AutoActivate=1 \ + X_IOWRT_EU_KeepConfig=1 \ + X_IOWRT_EU_KeepOpConf=0 \ + X_IOWRT_EU_ConfigScope=UserOnly + +# Factory reset upgrade +dmcli do Device.DeviceInfo.FirmwareImage.2.Download() \ + URL=https://fw.example.com/firmware.itb \ + AutoActivate=1 \ + X_IOWRT_EU_KeepConfig=0 +``` + +#### Using fwbank UBUS (Direct Access) + ```bash # Check current status ubus call fwbank dump @@ -1571,7 +1693,12 @@ Are you upgrading via... │ ├─ Sulu Web GUI │ │ └─ Toggle: "Keep Settings" checkbox in File Upload mode │ │ Basic control, KeepConfig only (URL download uses defaults) -│ │ Can be enhanced to expose KeepOpConf and ConfigScope +│ │ +│ ├─ dmcli (Data Model CLI) +│ │ └─ Use: X_IOWRT_EU_KeepConfig, X_IOWRT_EU_KeepOpConf, X_IOWRT_EU_ConfigScope +│ │ Full control via operation parameters +│ │ Works locally (UBUS) or remotely (USP) +│ │ Example: dmcli do Device.DeviceInfo.FirmwareImage.2.Download() URL=... AutoActivate=1 X_IOWRT_EU_KeepConfig=1 │ │ │ └─ External USP Controller │ └─ Use: X_IOWRT_EU_KeepConfig, X_IOWRT_EU_KeepOpConf, X_IOWRT_EU_ConfigScope