# XX230v Diagnostic Gaps & Oktopus Test Plan ## The Problem When a customer reports WiFi issues, the tech currently has almost no data to diagnose whether the problem is: - **The XX230v ONT** (GPON side failing, internal routing broken) - **The Deco mesh** (WiFi radio issue, coverage gap) - **The fibre itself** (signal degradation, dirty connector) - **The customer's device** (driver issue, band-steering problem) The current GenieACS provision (`xx230v_inform`) only reads: - GPON serial, MAC, uptime - WiFi SSID list (names only, no signal/client data) - Connected hosts (cleared every inform! → useless for diagnosis) **We're blind.** The XX230v exposes a rich TR-181 data model that we're not reading. --- ## What TR-181 Parameters the XX230v Actually Has The XX230v (TP-Link Deco XE75 ONT variant) supports the full TR-181:2 data model. Here's what we SHOULD be reading but currently aren't: ### 1. Optical Signal (fibre health) ``` Device.Optical.Interface.1.Status → Up/Down Device.Optical.Interface.1.Stats.SignalRxPower → dBm (target: -8 to -25) Device.Optical.Interface.1.Stats.SignalTxPower → dBm Device.Optical.Interface.1.Stats.BytesSent Device.Optical.Interface.1.Stats.BytesReceived Device.Optical.Interface.1.Stats.ErrorsSent Device.Optical.Interface.1.Stats.ErrorsReceived Device.Optical.Interface.1.Stats.DiscardPacketsSent Device.Optical.Interface.1.Stats.DiscardPacketsReceived Device.Optical.Interface.1.LowerLayers → underlying interface ``` **Diagnosis power:** If RxPower < -25 dBm → fibre problem (dirty connector, bend, break). If errors high → OLT port issue or fibre degradation. No need to swap the ONT. ### 2. WiFi Radios (per-band stats) ``` Device.WiFi.Radio.1.Status → Up/Down (2.4GHz) Device.WiFi.Radio.1.Channel Device.WiFi.Radio.1.OperatingFrequencyBand → 2.4GHz / 5GHz / 6GHz Device.WiFi.Radio.1.CurrentOperatingChannelBandwidth → 20MHz/40MHz/80MHz/160MHz Device.WiFi.Radio.1.Stats.Noise → dBm (background noise) Device.WiFi.Radio.1.Stats.BytesSent Device.WiFi.Radio.1.Stats.BytesReceived Device.WiFi.Radio.1.Stats.ErrorsSent Device.WiFi.Radio.1.Stats.ErrorsReceived Device.WiFi.Radio.1.Stats.PacketsSent Device.WiFi.Radio.1.Stats.PacketsReceived Device.WiFi.Radio.2.* → 5GHz band Device.WiFi.Radio.3.* → 6GHz band (XE75 has WiFi 6E) ``` **Diagnosis power:** High noise + errors on a specific band → channel congestion (not a hardware fault). Channel 1/6/11 comparison shows interference. ### 3. WiFi Access Points & Connected Clients ``` Device.WiFi.AccessPoint.1.AssociatedDevice.{i}. MACAddress → client MAC SignalStrength → dBm (how well client hears the AP) Noise → dBm (noise floor at client) Retransmissions → high = poor signal quality Active → currently connected? LastDataDownlinkRate → actual PHY rate to client (Mbps) LastDataUplinkRate → actual PHY rate from client (Mbps) OperatingStandard → ax/ac/n/g (WiFi generation) Device.WiFi.AccessPoint.1. AssociatedDeviceNumberOfEntries → client count Status → Enabled/Disabled SSIDAdvertisementEnabled → SSID visible? ``` **Diagnosis power:** If client SignalStrength > -65 dBm but Retransmissions high → interference. If LastDataDownlinkRate < 50 Mbps on WiFi 6 → something wrong with negotiation. If 0 clients on 5GHz → band steering issue. ### 4. Deco Mesh Topology (MultiAP / EasyMesh) ``` Device.WiFi.MultiAP.APDevice.{i}. MACAddress → mesh node MAC Manufacturer SerialNumber Radio.{j}. Noise Utilization → % channel busy AP.{k}. SSID UnicastBytesSent AssociatedDevice.{l}. MACAddress SignalStrength LastDataDownlinkRate Device.WiFi.DataElements.Network.Device.{i}. ID → mesh node ID MultiAPCapabilities Radio.{j}. CurrentOperatingClassProfile UnassociatedSTA.{k}. → devices seen but not connected ``` **Diagnosis power:** Shows which Deco node each client is connected to, signal quality per-node, backhaul utilization. If satellite Deco has poor backhaul → move it closer or add wired backhaul. ### 5. IP Diagnostics (built-in speed/ping test) ``` Device.IP.Diagnostics.IPPing. Host → target to ping NumberOfRepetitions Timeout DataBlockSize DiagnosticsState → set to "Requested" to trigger → Results: SuccessCount, FailureCount AverageResponseTime MinimumResponseTime MaximumResponseTime Device.IP.Diagnostics.DownloadDiagnostics. DownloadURL → URL to download from DiagnosticsState → "Requested" to trigger → Results: ROMTime, BOMTime, EOMTime TestBytesReceived TotalBytesReceived → Calculate: speed = TestBytesReceived / (EOMTime - BOMTime) Device.IP.Diagnostics.UploadDiagnostics. UploadURL → URL to upload to DiagnosticsState → "Requested" to trigger → Results: same pattern as download ``` **Diagnosis power:** Remote speed test FROM the ONT itself. Eliminates WiFi as a variable. If ONT→server speed is good but client speed is bad → WiFi issue. If ONT→server speed is bad → fibre/OLT issue. ### 6. Ethernet Ports ``` Device.Ethernet.Interface.{i}. Status → Up/Down MACAddress MaxBitRate → negotiated link speed (100/1000/2500) DuplexMode → Full/Half Stats.BytesSent/Received Stats.ErrorsSent/Received Stats.PacketsSent/Received ``` **Diagnosis power:** If Ethernet negotiated at 100Mbps instead of 1Gbps → bad cable or port. If errors high → physical layer issue. ### 7. DNS & Routing ``` Device.DNS.Client.Server.{i}. DNSServer → configured DNS Status Type → DHCPv4 / Static Device.Routing.Router.1.IPv4Forwarding.{i}. DestIPAddress GatewayIPAddress Interface Status ``` --- ## What to Add to GenieACS Inform (Immediate) Update the `xx230v_inform` provision to read diagnostic data on every inform: ```javascript // === DIAGNOSTIC DATA (add to xx230v_inform) === // Optical signal — THE most important diagnostic declare("Device.Optical.Interface.1.Status", {value: now}); declare("Device.Optical.Interface.1.Stats.SignalRxPower", {value: now}); declare("Device.Optical.Interface.1.Stats.SignalTxPower", {value: now}); declare("Device.Optical.Interface.1.Stats.ErrorsSent", {value: now}); declare("Device.Optical.Interface.1.Stats.ErrorsReceived", {value: now}); // WiFi radio stats (per band) declare("Device.WiFi.Radio.1.Status", {value: now}); declare("Device.WiFi.Radio.1.Channel", {value: now}); declare("Device.WiFi.Radio.1.CurrentOperatingChannelBandwidth", {value: now}); declare("Device.WiFi.Radio.1.Stats.Noise", {value: now}); declare("Device.WiFi.Radio.1.Stats.ErrorsSent", {value: now}); declare("Device.WiFi.Radio.2.Status", {value: now}); declare("Device.WiFi.Radio.2.Channel", {value: now}); declare("Device.WiFi.Radio.2.CurrentOperatingChannelBandwidth", {value: now}); declare("Device.WiFi.Radio.2.Stats.Noise", {value: now}); declare("Device.WiFi.Radio.3.Status", {value: now}); // 6GHz if supported declare("Device.WiFi.Radio.3.Channel", {value: now}); // Connected clients count per AP declare("Device.WiFi.AccessPoint.1.AssociatedDeviceNumberOfEntries", {value: now}); declare("Device.WiFi.AccessPoint.2.AssociatedDeviceNumberOfEntries", {value: now}); declare("Device.WiFi.AccessPoint.3.AssociatedDeviceNumberOfEntries", {value: now}); // WAN IP (already partially read) declare("Device.IP.Interface.1.IPv4Address.1.IPAddress", {value: now}); // Ethernet port status declare("Device.Ethernet.Interface.1.Status", {value: now}); declare("Device.Ethernet.Interface.1.MaxBitRate", {value: now}); declare("Device.Ethernet.Interface.2.Status", {value: now}); declare("Device.Ethernet.Interface.2.MaxBitRate", {value: now}); ``` --- ## Equipment Swap Status — Fix the "Not Sure It's Defective" Problem Instead of immediately marking as "Défectueux", the swap flow should support **diagnostic swap**: ### Updated Status Flow ``` Normal equipment statuses: En inventaire → Actif → [issue reported] → Option A: "En diagnostic" ← tech swaps to test, original goes back to warehouse Option B: "Défectueux" ← confirmed dead Option C: "Retourné" ← returned to stock after test (was fine) Swap types: 1. "Remplacement définitif" → old = Défectueux, new = Actif 2. "Swap diagnostic" → old = En diagnostic, new = Actif (temporary) 3. "Retour de diagnostic" → old = Actif (put back), temp = Retourné ``` ### Updated Wizard Step 2 (Reason) ``` Step 2: "Type de remplacement" [select-cards] 🔴 Remplacement définitif — L'équipement est mort 🟡 Swap diagnostic — Tester si le problème vient de l'équipement 🔵 Mise à niveau — Remplacer par un modèle supérieur ``` If "Swap diagnostic" is chosen: - Old equipment → status "En diagnostic" (not Défectueux) - A follow-up task is auto-created: "Diagnostic result for {serial}" - Due in 7 days - Options: "Confirmed defective" → mark Défectueux | "Works fine" → mark Retourné --- ## Oktopus Test Plan — What to Verify ### Step 1: Deploy Oktopus with TR-069 Adapter Oktopus is already at `oss.gigafibre.ca` with 8 containers. We need to: 1. **Verify it's running**: `curl https://oss.gigafibre.ca/api/health` 2. **Check the TR-069 adapter port**: Oktopus listens for CWMP connections (typically 7547) 3. **Check the admin UI**: Oktopus CE has a web dashboard ### Step 2: Point ONE Test XX230v to Oktopus On GenieACS, push a parameter change to a single test device: ``` Device.ManagementServer.URL = "https://acs-new.gigafibre.ca:7547" ``` Or physically: configure the ACS URL in the XX230v admin panel. ### Step 3: What to Check on Oktopus Once the XX230v connects to Oktopus: | Check | What to Look For | Why It Matters | |-------|-----------------|----------------| | Device appears | Does Oktopus see the TR-069 inform? | Basic connectivity | | Data model | Does it show the full TR-181 tree? | TR-181 paths are the same | | Parameter read | Can we read `Device.Optical.Interface.1.Stats.SignalRxPower`? | Real-time diagnostics | | Parameter set | Can we push WiFi SSID/password? | Provisioning works | | Reboot | Can we trigger a remote reboot? | Basic management | | Firmware | Can we push a firmware update? | Fleet management | | Tasks | Can we queue tasks for next inform? | Offline task queue | | Webhooks | Does Oktopus fire webhooks on events? | n8n integration | | Multiple devices | Can it handle the full fleet? | Scalability | ### Step 4: TR-369 (USP) Check If the XX230v firmware supports USP (check TP-Link release notes for your version): ``` Device.LocalAgent.Controller.{i}. EndpointID Protocol → MQTT / WebSocket MTP.{j}. Enable Protocol MQTT.Topic ``` If USP is available → configure Oktopus as USP controller → real-time bidirectional management (no more polling!). ### Step 5: Compare GenieACS vs Oktopus Data Run the same device through both ACS simultaneously (different inform intervals) and compare: | Aspect | GenieACS | Oktopus | Notes | |--------|----------|---------|-------| | Inform data | _lastInform, basic params | ? | Same TR-181 paths | | WiFi clients | Cleared by provision (broken!) | ? | Don't clear in Oktopus | | Optical power | Only via summarizeDevice() | ? | Should be real-time | | Remote diagnostics | Via NBI task push | Via USP Operate | USP is synchronous | | Webhook events | None (we poll) | Built-in | Major improvement | | Firmware mgmt | GridFS upload + provision | Native firmware repo | Cleaner | | Bulk operations | JS provisions | Device groups + policies | More scalable | --- ## Immediate Actions ### 1. Update xx230v_inform provision (15 min) Add the diagnostic parameters listed above. Deploys instantly to all XX230v fleet via GenieACS. ### 2. Update summarizeDevice() in targo-hub (15 min) Add optical signal, WiFi radio stats, client counts, Ethernet link speed to the device summary. ### 3. Update Ops app device detail view (30 min) Show the new diagnostic data in the device panel (Optical power, WiFi channels, client count per band). ### 4. SSH to Oktopus server, verify it's running (10 min) Check `docker compose ps` at `/opt/oktopus/`, verify API responds, check admin UI. ### 5. Point one test XX230v to Oktopus (10 min) Via GenieACS: set `Device.ManagementServer.URL` on a single device. ### 6. Add "En diagnostic" status to Service Equipment (5 min) Add the new status option + update swap flow logic.