From 0a49cbe5161cb4ef163f688c105b4a445e58d676 Mon Sep 17 00:00:00 2001 From: scott Date: Tue, 17 Mar 2026 17:53:36 -0400 Subject: [PATCH] Update CLAUDE.md to reflect current multi-file architecture Document the new file structure, both connection methods (serial/network), both workflows (serial config and firmware update), key design notes (auth credentials, firmware bug workaround, API paths), and the planned network-based config workflow. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9770ef5 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,76 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Running the Tool + +```bash +python3 es24n_conf.py +``` + +The script requires root or appropriate serial device permissions. If the serial device is inaccessible, re-run with `sudo`. + +## What This Is + +An interactive CLI tool for configuring and updating TrueNAS ES24N expansion shelf IOM (I/O Module) controllers via the Redfish API. It supports two connection methods: + +- **Serial (loopback):** Connects via USB serial cable to the IOM1 console port, then reaches the Redfish API at `https://127.0.0.1` using `root` credentials. Used for initial network configuration when the IOM has no IP address yet. +- **Network:** Connects directly to the IOM's management IP address using `Admin` credentials. Used for firmware updates and (planned) network reconfiguration once the IOM is reachable on the network. + +No external dependencies — Python 3 standard library only. Compatible with TrueNAS (FreeBSD) and Linux. + +## File Structure + +``` +es24n_conf.py ← Entry point and main menu (run this) +es24n/ + ui.py ← ANSI colours, display helpers, input prompts + serial_port.py ← SerialPort class (termios/fcntl/select, no pyserial) + models.py ← IOMConfig and ShelfConfig dataclasses + redfish.py ← Redfish API client (shared by all workflows) + workflow_serial.py ← Serial-based IOM network configuration workflow + workflow_firmware.py ← IOM and Fabric Card firmware update workflow +``` + +`es24n_conf.py` adds `es24n/` to `sys.path` at startup so all inter-module imports work without a package structure. + +## Workflows + +### 1 — Serial Network Configuration (`workflow_serial.py`) +5-step workflow using the USB serial cable: +1. Detect USB serial device (`/dev/ttyUSB*`, `/dev/ttyACM*`, `/dev/ttyU*`) +2. Open 115200-baud 8N1 connection and wake the IOM console +3. Query current network settings via Redfish (`GET` over `127.0.0.1`) +4. Collect new settings from user (Static IP or DHCP) +5. Apply via Redfish `PATCH` over `127.0.0.1` + +### 2 — Firmware Update (`workflow_firmware.py`) +Updates IOM firmware and/or Fabric Card firmware over the network: +- Prompts for which IOM(s) to update (IOM1, IOM2, or both) +- Uploads firmware via `POST` to `/redfish/v1/UpdateService` (multipart form) +- Triggers update via Redfish `SimpleUpdate` action +- Polls `/redfish/v1/TaskService/Tasks/` until completion +- Restarts the IOM (and fabric card if applicable) after each update +- The firmware file must be re-uploaded between the IOM and Fabric Card steps — it does not persist after the first update (firmware quirk, documented in `_update_fabric_fw()`) +- Scans the current working directory for firmware files (`.bin`, `.img`, `.fw`, `.hex`, `.zip`, `.tar`, `.tgz`, `.gz`) and presents them as a numbered list before falling back to manual path entry + +## Key Design Notes + +**Static IP firmware bug workaround:** Setting a static IP requires two sequential PATCH requests: +- Pass 1: set `IPv4StaticAddresses` (while DHCP is still enabled) +- Pass 2: disable `DHCPv4` (after the address is committed) + +A single PATCH combining both fields fails due to a known ES24N firmware bug. Documented in `_apply_iom()` in `workflow_serial.py`. + +**Authentication:** +- Serial loopback (`127.0.0.1`): username `root` +- Network IP: username `Admin` + +**Redfish API paths:** +- Network config: `/redfish/v1/Managers/{IOM1|IOM2}/EthernetInterfaces/1` +- Firmware update: `/redfish/v1/UpdateService` +- Fabric card: `/redfish/v1/Chassis/{IOM1|IOM2}/NetworkAdapters/1` + +## Planned Features + +- Network-based IOM network configuration (`workflow_network.py`) — same config workflow as serial but connecting via the IOM's existing IP address using `Admin` credentials, for cases where the IOM is already reachable on the network