# Gigafibre FSM — CPE Hardware Management

> Managing the customer-premises equipment fleet (ONTs, routers, mesh
> nodes). Covers TR-069 (GenieACS), the modem-bridge for deep TP-Link
> diagnostics, and the diagnostic-swap workflow.

---

## 1. Protocol & Tooling Stack

The current ACS is **GenieACS** (TR-069 / CWMP — HTTP/SOAP polling).
It's external to the prod box (separate VM managed by the network
team). The hub talks to it via the GenieACS NBI (Northbound Interface)
on the internal network.

**About TR-369 / USP** — we ran a parallel Oktopus CE deployment for
USP (TR-369 over MQTT/WebSocket) but **decommissioned it in May 2026**
after the broker filled the disk with debug spam. The integration
modules in the hub (`lib/oktopus.js`, `lib/oktopus-mqtt.js`) remain
in the tree gated behind `OKTOPUS_DISABLED=1` so we can re-enable them
later if we settle on a different USP controller. For now, all CPE
management goes through TR-069 + GenieACS.

**Polling cadence** — GenieACS receives an Inform from each ONT every
~5 minutes (configurable in the device firmware). For real-time deep
dives that can't wait for the next Inform window, the hub falls back
to:
- **modem-bridge** (`services/modem-bridge/`) — Playwright-driven HTTP
  client that scrapes encrypted TR-181 parameters from the modem's
  native admin UI. Specifically targets the TP-Link XX230v / Deco mesh.
- **OLT SNMP** — direct SNMPv2 walk against the OLT for ONT optical
  status, when even the modem itself is unreachable.

---

## 2. TP-Link XX230v (Deco XE75) Deep Diagnostics

The XX230v exposes a rich TR-181 data model. When customers report
"WiFi issues", CSRs and techs should not blindly swap the hardware.
Poll these endpoints first to find the actual root cause.

### A. Optical Signal (Is it the Fibre?)

```text
Device.Optical.Interface.1.Stats.SignalRxPower   → target: -8 to -25 dBm
Device.Optical.Interface.1.Stats.ErrorsSent
```

**Diagnosis** — RxPower < -25 dBm = dirty connector or fibre break.
**Not** an ONT hardware fault. Don't swap; dispatch a fibre tech.

### B. WiFi Radio & Topology (Is it Interference?)

```text
Device.WiFi.Radio.1.Stats.Noise                          → 2.4 GHz interference
Device.WiFi.Radio.2.Stats.Noise                          → 5 GHz interference
Device.WiFi.MultiAP.APDevice.{i}.Radio.{j}.Utilization   → mesh backhaul load
```

**Diagnosis** — high noise/errors on a band = environmental channel
congestion (neighbours, microwave, baby monitor). High backhaul
utilization on a satellite Deco = customer needs to move it closer
to the main unit.

### C. Live Speed Test (Is it the Client Device?)

```text
Device.IP.Diagnostics.DownloadDiagnostics.DiagnosticsState = "Requested"
```

**Diagnosis** — kicks off a server-to-ONT speed test, which eliminates
WiFi-side latency variables. ONT speed test fast + customer's iPhone
slow → the iPhone or the WiFi link is the bottleneck, not the line.

---

## 3. The "Diagnostic Swap" Workflow

A common gap occurs when techs swap equipment simply because they
aren't sure what is defective. This creates inventory chaos.

We use a **3-way diagnostic status** instead of a binary `Défectueux`:

1. **Remplacement définitif** — the equipment is dead.
   *(Old → Défectueux, New → Actif)*
2. **Swap diagnostic** — swapping to test if the problem resolves.
   *(Old → En diagnostic, New → Actif (temporary))*
3. **Retour de diagnostic** — the old unit was actually fine.
   *(Old → Actif (returned to use), Test unit → Retourné)*

If a tech chooses **Swap diagnostic**, an ERPNext Task is automatically
generated scheduling a follow-through test on the removed hardware
within 7 days. If the unit tests fine at the warehouse, it goes back
to `En inventaire` instead of being trashed.

---

## 4. Hub Endpoints (`/devices/*`)

The ops "Diagnostiquer" button on a customer or equipment row hits the
hub, which orchestrates GenieACS / OLT / modem-bridge in the right
order:

1. `/devices/lookup?serial=X` — finds the ONT by serial in GenieACS.
2. The hub returns the latest Inform snapshot (interface, mesh, wifi,
   opticalStatus). If older than 60s, it kicks an immediate
   `Refresh` task to GenieACS.
3. For TP-Link models specifically, deeper params (encrypted TR-181)
   are fetched via modem-bridge if needed.
4. Final response is a consolidated JSON consumed by
   `apps/ops/src/components/equipment/EquipmentDiagnostic.vue`.

See [module-interactions.md](../architecture/module-interactions.md)
for the full call graph.

---

## 5. Cross-references

- [../architecture/module-interactions.md](../architecture/module-interactions.md) — hub call graph for device flows.
- [vision-ocr.md](vision-ocr.md) — barcode scan during install (ONT
  serial, MAC) feeds back into Service Equipment.
- [dispatch.md](dispatch.md) §5.6 — equipment install/swap from the
  tech mobile page.