ponfw/README.md

PON Fleet Upgrader

An Electron desktop app for operating a Ciena MicroClimate Management System (MCMS) 6.2 PON Manager. Top tabs split it into:

1. Dashboard — read-only network telemetry: ONU/OLT/controller counts, aggregate up/down traffic, health (abnormal Rx, lasers off), and ONU registration-state breakdown (with an opt-in per-ONU Rx/FEC scan). Clicking a state jumps to the ONU tab pre-filtered.
2. ONU — two sub-tabs: an Info / stats page (per-ONU optical/FEC plus the CPE router's DHCPv4/v6 lease status, with a warning when a lease is past its renew point) and Fleet & upgrade (bulk ONU firmware upgrades, below).
3. OLT — bulk OLT NNI-service edits: PON flooding mode (private↔auto) and DHCPv4/v6 filter (pass↔umt) — see "OLT NNI-service edits" below.

ONU firmware upgrades

Filters a fleet of ONUs, previews the planned writes, and stages new firmware to each device's inactive bank so the forced reboot is deferred until the next natural restart window.

Two execution modes:

• Bulk task (Procedure 8, recommended) — creates a single AUTO-TASK-CFG via PUT /v3/tasks/configs/<id>/. MCMS owns the rollout (retries, pacing, scheduled start).
• Per-ONU PUT (Procedure 7) — iterates the selected ONUs, fetches each ONU-CFG, mutates FW Bank {Ptr,Files,Versions}, and PUTs the full document back. Slower, but you see errors live per device.

Prerequisites

• Node.js 18+ and npm
• Network reachability to your MCMS host
• An MCMS user with ONU write + Files write permissions
• A compatible ONU firmware .bin file (already uploaded via this tool or the vendor UI into /files/onu-firmware/)

Install & run

cd pon-fleet-upgrader
npm install
npm start

This launches an Electron window. Use npm run check to syntax-check all source files without launching the app.

Bank strategy

MCMS stores firmware in two slots per ONU (FW Bank Files[0/1], FW Bank Versions[0/1]) with FW Bank Ptr pointing at the active one.

Current FW Bank Ptr	Tool writes to slot	Why
0	1	Don't overwrite active image
1	0	Don't overwrite active image
65535 (unset)	1	Matches Procedure 7 example; slot 0 stays as factory fallback

The tool computes this per ONU and buckets the selection by target slot when submitting a bulk task (MCMS's AUTO-TASK-CFG.Task Details.ONU.FW Bank Ptr accepts a single slot number, so each bucket becomes one task).

Safety notes

• Always validate on one ONU first. Select a single device, run in per-ONU mode, confirm the ONU recovers on slot N before using bulk task on the rest of the fleet.
• Don't blank the active slot. The planner preserves both slots' existing Files/Versions and only writes the target slot.
• Scheduled start is UTC. The datetime-local picker converts from your local timezone to UTC before submitting the AUTO-TASK-CFG.
• Leave the session short. Log out when done — MCMS sessions don't auto-expire and a stale cookie on a shared workstation is an unnecessary exposure.

Filters

The left panel supports:

• Name / address contains — substring match over ONU.Name, ONU.Address, and _id
• PON mode — server-side Mongo filter on ONU.PON Mode
• Active version matches — substring match on the version string in whichever slot FW Bank Ptr points to
• Model / version family — substring match across both slots' version strings, useful for fleet cuts like EV051 (all Everest 5.1x)

The server-side projection is narrow (serial, name/address, PON mode, bank state). The full ONU-CFG is only re-fetched at plan time.

Files

pon-fleet-upgrader/
├── package.json
├── main.js                # Electron main process, IPC handlers
├── preload.js             # contextBridge exposing window.api.*
├── src/
│   ├── mcms-api.js        # HTTPS client with tough-cookie jar + CSRF
│   └── bank-strategy.js   # inactive-bank selection + plan computation
└── renderer/
    ├── index.html         # Login / fleet / campaign views
    ├── app.css
    └── app.js             # UI logic

OLT NNI-service edits

From the fleet view, Open OLT inspector… opens a second workflow for bulk-checking and editing OLT NNI services. Two independent edits can be applied together to every matching service:

Flooding mode — encoded by the presence of a single key on each OLT-CFG["NNI Networks"] entry:

Mode	PON FLOOD ID key	Change
private	present (any value, incl. 0)	→ auto: delete the key
auto	absent	→ private: set the key to 0

DHCP filter mode — values nested under each entry's Filter object (DHCPv4 / DHCPv6), e.g. pass ↔ umt. Only entries that already have the field are touched (the field is never invented); EAPOL/PPPoE/NDP are left alone.

Workflow: enter a TAG MATCH pattern (exact like s0.c76.c0, or a * glob like s0.c76.*), Load OLTs, pick any of the three actions (Flooding / DHCPv4 / DHCPv6), select the OLTs — each matching service shows "→ will change (…)" for the edits that apply — then Execute changes… (two-step confirm). Each OLT is re-fetched, the matching NNI entries are edited in one pass, and the full OLT-CFG is PUT back. A result CSV is auto-saved to ~/Downloads/pon-olt-nni-*.csv.

All directions are supported (e.g. umt → pass), so changes roll back from the same screen. Defaults: s0.c76.c0, flood private → auto, DHCPv4/v6 pass → umt.

Known limitations

• The /v1/onus/<id>/upgrade/status/ path used by the original question isn't part of the dev-guide-documented surface; if your MCMS returns 404 for it, fall back to polling GET /v1/onus/configs/<id>/ and watching FW Bank Versions + FW Bank Ptr change.
• Progress of a bulk task is reported back by MCMS in its own task status collection — the tool currently submits and then leaves monitoring to the PON Manager UI. Follow-up work: poll /v3/tasks/states/<taskId>/.
• No offline mode / cached fleet snapshot. Each Load fleet hits the API.
• PATCH endpoints aren't used — MCMS requires full-document PUTs for ONU-CFG updates (the dev guide is explicit about this).

License

Internal use only.