Initial commit: firmware pusher app, GenieACS docs, network file

- firmware-pusher/: standalone HTML app for GenieACS firmware pushes - genieacs/: NBI API usage, device IDs, troubleshooting - calix_home_network.txt: live network documentation
2026-05-21 09:38:51 -05:00
commit 983ddd903b
7 changed files with 738 additions and 0 deletions
@@ -0,0 +1,37 @@
+# Calix
+
+Documentation, configuration, and tooling for the Calix home network.
+
+## Contents
+
+### calix_home_network.txt
+Live network documentation — device IPs, credentials, SSIDs, GenieACS server info.
+**Keep this file updated** whenever network changes are made.
+
+### firmware-pusher/
+A standalone HTML app for pushing firmware to GenieSpire satellites via the GenieACS NBI API.
+
+Files:
+- `index.html` — the UI (single file, no build step)
+- `nginx.conf` — nginx config with HTTP Basic Auth
+- `docker-compose.yml` — container deployment
+- `README.md` — setup and usage docs
+
+Access: `https://calix.yoda.ddnsgeek.com`
+Login: `admin` / GenieACS admin password
+
+### genieacs/
+Documentation on GenieACS configuration, quirks, and tips for this setup.
+
+## Device Inventory
+
+| Device | IP | Serial | Software | Notes |
+|--------|----|--------|----------|-------|
+| Main Router (4220E) | 192.168.1.1 | 422208213826 | u6.1 | Mesh controller |
+| Back Hallway Sat (4220E) | 192.168.1.109 | 422208213783 | u6.1 | AP mode |
+| Office Sat (4220E) | 192.168.1.155 | 422208213919 | u6.1 | AP mode |
+| GenieSpire (CXNK010F208F) | 173.21.51.61 | - | 25.2.0.0.44 | Offline/NAT'd |
+| GenieSpire (CXNK010F20EC) | 192.168.1.109 | - | 25.2.0.0.44 | Via GenieACS |
+| GenieSpire (CXNK010F2064) | 192.168.1.155 | - | 25.2.0.0.44 | Via GenieACS |
+
+GenieSpire satellites are TR-069/GenieACS managed — no local web UI.
@@ -0,0 +1,3 @@
+# Password for calix.yoda.ddnsgeek.com: admin / 966QPr@*rCTMrWE9xSGm
+# To regenerate: docker run --rm httpd:alpine htpasswd -nb admin <password>
+admin:$apr1$8f4x.t5E$yHZFFxIxiUyL7wXlfBSav.
@@ -0,0 +1,78 @@
+# GenieACS Firmware Pusher
+
+Standalone HTML app for pushing firmware upgrades to GenieSpire satellites via GenieACS NBI API.
+
+## Access
+
+**URL:** `https://calix.yoda.ddnsgeek.com`
+**Auth:** HTTP Basic Auth — `admin` + GenieACS admin password
+
+## Setup
+
+```bash
+# On VPS (root@161.97.153.158)
+cd /opt/firmware-pusher && docker compose up -d
+```
+
+## Architecture
+
+```
+User browser (HTTPS)
+    ↓
+Traefik (calix.yoda.ddnsgeek.com → firmware-pusher container)
+    ↓
+nginx:alpine (auth + static files)
+    ↓
+firmware-pusher/index.html (the UI)
+
+UI → NBI API: https://nbi.yoda.ddnsgeek.com/devices
+     (NBI also protected by same HTTP Basic Auth)
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `index.html` | The UI — single file, no build |
+| `nginx.conf` | nginx config with auth |
+| `.htpasswd` | HTTP Basic Auth password hash |
+| `docker-compose.yml` | Container definition + Traefik labels |
+
+## How It Works
+
+1. **Device list** — fetches from `GET /devices` (NBI API)
+2. **Firmware files** — fetches from `GET /files` (NBI API)
+3. **Push** — POSTs to `POST /devices/{id}/tasks` with:
+   ```json
+   {
+     "name": "download",
+     "fileType": "1 Firmware Upgrade Image",
+     "fileName": "FullRel_EXOS_SIGNED_E5_R25.2.0.0.img",
+     "productClass": "GigaSpire"
+   }
+   ```
+
+## Changing Password
+
+```bash
+# Generate new htpasswd
+docker run --rm httpd:alpine htpasswd -nb admin NEW_PASSWORD
+
+# Update the .htpasswd file, then:
+docker exec firmware-pusher nginx -s reload
+```
+
+## Firmware Versions Available
+
+| Version | File |
+|---------|------|
+| R23.3.0.5 | FullRel_EXOS_SIGNED_E5_R23.3.0.5.img |
+| R24.1.0.2 | FullRel_EXOS_SIGNED_E5_R24.1.0.2.img |
+| R24.4.0.0 | FullRel_EXOS_SIGNED_E5_R24.4.0.0.img |
+| R25.2.0.0 | FullRel_EXOS_SIGNED_E5_R25.2.0.0.img |
+
+## Troubleshooting
+
+- **blank page / 404**: Check `docker logs firmware-pusher`
+- **auth not working**: Verify `.htpasswd` exists inside container: `docker exec firmware-pusher cat /etc/nginx/.htpasswd`
+- **push fails**: Check GenieACS fault queue at `https://genieacs.yoda.ddnsgeek.com`
@@ -0,0 +1,25 @@
+services:
+  firmware-pusher:
+    image: nginx:alpine
+    container_name: firmware-pusher
+    restart: unless-stopped
+    ports:
+      - '8080:80'
+    volumes:
+      - ./html:/usr/share/nginx/html:ro
+      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
+      - ./nginx/.htpasswd:/etc/nginx/.htpasswd:ro
+    networks:
+      - traefik-network
+    labels:
+      - 'traefik.enable=true'
+      - 'traefik.http.routers.firmware-pusher.rule=Host(`calix.yoda.ddnsgeek.com`)'
+      - 'traefik.http.routers.firmware-pusher.entrypoints=websecure'
+      - 'traefik.http.routers.firmware-pusher.tls=true'
+      - 'traefik.http.routers.firmware-pusher.tls.certResolver=letsencrypt'
+      - 'traefik.http.routers.firmware-pusher.priority=100'
+      - 'traefik.http.services.firmware-pusher.loadbalancer.server.port=80'
+
+networks:
+  traefik-network:
+    external: true
@@ -0,0 +1,476 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>GenieACS Firmware Pusher</title>
+  <style>
+    :root {
+      --bg: #0f1117;
+      --surface: #1a1d27;
+      --border: #2a2d3a;
+      --text: #e4e4e7;
+      --text-dim: #71717a;
+      --accent: #3b82f6;
+      --accent-hover: #2563eb;
+      --success: #22c55e;
+      --error: #ef4444;
+      --warning: #f59e0b;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 1rem;
+    }
+    .card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      padding: 2rem;
+      width: 100%;
+      max-width: 480px;
+    }
+    .logo {
+      font-size: 1.5rem;
+      font-weight: 700;
+      margin-bottom: 0.25rem;
+      color: var(--accent);
+    }
+    .subtitle {
+      color: var(--text-dim);
+      font-size: 0.875rem;
+      margin-bottom: 2rem;
+    }
+    .field {
+      margin-bottom: 1.25rem;
+    }
+    label {
+      display: block;
+      font-size: 0.8rem;
+      font-weight: 600;
+      color: var(--text-dim);
+      margin-bottom: 0.5rem;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+    }
+    select, input {
+      width: 100%;
+      padding: 0.625rem 0.875rem;
+      background: var(--bg);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      color: var(--text);
+      font-size: 0.9rem;
+      transition: border-color 0.15s;
+      appearance: none;
+    }
+    select:focus, input:focus {
+      outline: none;
+      border-color: var(--accent);
+    }
+    select {
+      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath fill='%2371717a' d='M6 8L1 3h10z'/%3E%3C/svg%3E");
+      background-repeat: no-repeat;
+      background-position: right 0.875rem center;
+      padding-right: 2.5rem;
+      cursor: pointer;
+    }
+    .btn {
+      width: 100%;
+      padding: 0.75rem 1rem;
+      background: var(--accent);
+      color: #fff;
+      border: none;
+      border-radius: 8px;
+      font-size: 0.9rem;
+      font-weight: 600;
+      cursor: pointer;
+      transition: background 0.15s, opacity 0.15s;
+    }
+    .btn:hover { background: var(--accent-hover); }
+    .btn:disabled { opacity: 0.5; cursor: not-allowed; }
+    .btn.loading { position: relative; }
+    .btn.loading::after {
+      content: '';
+      display: inline-block;
+      width: 1em; height: 1em;
+      border: 2px solid rgba(255,255,255,0.3);
+      border-top-color: #fff;
+      border-radius: 50%;
+      animation: spin 0.6s linear infinite;
+      margin-left: 0.5em;
+      vertical-align: middle;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    .status {
+      margin-top: 1.25rem;
+      padding: 0.875rem 1rem;
+      border-radius: 8px;
+      font-size: 0.85rem;
+      line-height: 1.5;
+      display: none;
+    }
+    .status.show { display: block; }
+    .status.ok { background: rgba(34,197,94,0.1); border: 1px solid rgba(34,197,94,0.3); color: var(--success); }
+    .status.err { background: rgba(239,68,68,0.1); border: 1px solid rgba(239,68,68,0.3); color: var(--error); }
+    .status.info { background: rgba(59,130,246,0.1); border: 1px solid rgba(59,130,246,0.3); color: var(--accent); }
+    .status .task-id { font-family: monospace; font-size: 0.8em; color: var(--text-dim); }
+    .version-tag {
+      position: fixed;
+      bottom: 0.75rem;
+      right: 1rem;
+      font-size: 0.7rem;
+      color: var(--text-dim);
+    }
+
+    /* Login screen */
+    .login-screen .main-ui { display: none; }
+    .main-ui .login-screen { display: none; }
+    .login-screen {
+      text-align: center;
+    }
+    .login-screen .logo { font-size: 2rem; margin-bottom: 0.5rem; }
+    .login-screen .subtitle { margin-bottom: 2rem; }
+    .login-screen .field { text-align: left; }
+    .lock-icon {
+      font-size: 2.5rem;
+      margin-bottom: 1rem;
+    }
+
+    /* Device / firmware info badges */
+    .badge {
+      display: inline-block;
+      font-size: 0.7rem;
+      padding: 0.15rem 0.4rem;
+      border-radius: 4px;
+      background: rgba(59,130,246,0.15);
+      color: var(--accent);
+      margin-left: 0.5rem;
+      vertical-align: middle;
+      font-family: monospace;
+    }
+    .fw-info { font-size: 0.75rem; color: var(--text-dim); margin-top: 0.25rem; }
+    hr.divider { border: none; border-top: 1px solid var(--border); margin: 1.5rem 0; }
+    .inline-field { display: flex; gap: 0.75rem; }
+    .inline-field .field { flex: 1; }
+  </style>
+</head>
+<body>
+
+<!-- LOGIN SCREEN -->
+<div class="card login-screen" id="loginScreen">
+  <div class="lock-icon">🔐</div>
+  <div class="logo">GenieACS Firmware Pusher</div>
+  <div class="subtitle">Enter your GenieACS credentials to continue</div>
+  <div class="field">
+    <label>Username</label>
+    <input type="text" id="inUser" value="admin" autocomplete="username" spellcheck="false" />
+  </div>
+  <div class="field">
+    <label>Password</label>
+    <input type="password" id="inPass" autocomplete="current-password" spellcheck="false" />
+  </div>
+  <button class="btn" id="btnConnect" onclick="connect()">Connect</button>
+  <div class="status" id="loginStatus"></div>
+</div>
+
+<!-- MAIN UI -->
+<div class="card main-ui" id="mainUI">
+  <div class="logo">GenieACS Firmware Pusher</div>
+  <div class="subtitle">
+    <span id="connectedAs">Connected</span>
+    <button onclick="logout()" style="background:none;border:none;color:var(--text-dim);cursor:pointer;font-size:0.75rem;margin-left:0.5rem;text-decoration:underline;">disconnect</button>
+  </div>
+
+  <hr class="divider">
+
+  <div class="inline-field">
+    <div class="field">
+      <label>Device</label>
+      <select id="selDevice">
+        <option value="">— Loading devices… —</option>
+      </select>
+      <div class="fw-info" id="devInfo"></div>
+    </div>
+  </div>
+
+  <div class="field">
+    <label>
+      Firmware
+      <span class="badge" id="fwCount"></span>
+    </label>
+    <select id="selFw">
+      <option value="">— Loading files… —</option>
+    </select>
+    <div class="fw-info" id="fwInfo"></div>
+  </div>
+
+  <button class="btn" id="btnPush" onclick="pushFirmware()" disabled>
+    Push Firmware
+  </button>
+
+  <div class="status" id="statusBox"></div>
+</div>
+
+<div class="version-tag">GenieACS Firmware Pusher v1.0</div>
+
+<script>
+  const NBI = 'https://nbi.yoda.ddnsgeek.com';
+
+  // ── Auth helpers ───────────────────────────────────────────
+  function getCreds() {
+    return { user: sessionStorage.getItem('nbi_user'), pass: sessionStorage.getItem('nbi_pass') };
+  }
+
+  function b64auth() {
+    const { user, pass } = getCreds();
+    return 'Basic ' + btoa(user + ':' + pass);
+  }
+
+  function logout() {
+    sessionStorage.removeItem('nbi_user');
+    sessionStorage.removeItem('nbi_pass');
+    document.getElementById('mainUI').classList.remove('main-ui');
+    document.getElementById('mainUI').classList.add('login-screen');
+    document.getElementById('loginScreen').classList.add('login-screen');
+    document.getElementById('loginScreen').style.display = '';
+    document.getElementById('inPass').value = '';
+    clearStatus();
+  }
+
+  // ── API helpers ────────────────────────────────────────────
+  async function api(path, method = 'GET', body = null) {
+    const opts = {
+      method,
+      headers: { 'Authorization': b64auth(), 'Content-Type': 'application/json' }
+    };
+    if (body) opts.body = JSON.stringify(body);
+    const r = await fetch(NBI + path, opts);
+    if (r.status === 401) throw new Error('AUTH');
+    if (r.status === 204) return null;
+    return r.json();
+  }
+
+  // ── Login ──────────────────────────────────────────────────
+  async function connect() {
+    const user = document.getElementById('inUser').value.trim();
+    const pass = document.getElementById('inPass').value;
+    if (!user || !pass) { showStatus('loginStatus', 'Please enter username and password.', 'err'); return; }
+
+    const btn = document.getElementById('btnConnect');
+    btn.classList.add('loading'); btn.disabled = true;
+    clearStatus('loginStatus');
+
+    try {
+      // Test auth by fetching devices
+      const test = await fetch(NBI + '/devices?projection=_id', {
+        headers: { 'Authorization': 'Basic ' + btoa(user + ':' + pass) }
+      });
+      if (test.status === 401) throw new Error('Invalid credentials');
+      if (!test.ok) throw new Error('Server error: ' + test.status);
+
+      sessionStorage.setItem('nbi_user', user);
+      sessionStorage.setItem('nbi_pass', pass);
+
+      document.getElementById('loginScreen').style.display = 'none';
+      document.getElementById('mainUI').classList.add('main-ui');
+      document.getElementById('connectedAs').textContent = 'Connected as ' + user;
+
+      await loadDevices();
+      await loadFiles();
+    } catch(e) {
+      if (e.message === 'AUTH' || e.message === 'Invalid credentials') {
+        showStatus('loginStatus', 'Invalid username or password.', 'err');
+      } else {
+        showStatus('loginStatus', 'Cannot reach GenieACS NBI API: ' + e.message, 'err');
+      }
+    } finally {
+      btn.classList.remove('loading'); btn.disabled = false;
+    }
+  }
+
+  // ── Load devices ───────────────────────────────────────────
+  async function loadDevices() {
+    const sel = document.getElementById('selDevice');
+    const info = document.getElementById('devInfo');
+    sel.innerHTML = '<option value="">Loading…</option>';
+    try {
+      const devs = await api('/devices?projection=InternetGatewayDevice.');
+      sel.innerHTML = '';
+      if (!devs || devs.length === 0) {
+        sel.innerHTML = '<option value="">No devices found</option>';
+        return;
+      }
+      // Sort: online first, then by ID
+      devs.sort((a, b) => {
+        const ia = a._id.toLowerCase(), ib = b._id.toLowerCase();
+        return ia.localeCompare(ib);
+      });
+      for (const d of devs) {
+        const serial = d._id.includes('-') ? d._id.split('-').pop() : d._id;
+        const igd = d.InternetGatewayDevice || {};
+        const sw = igd.DeviceInfo?.SoftwareVersion?._value || '—';
+        const url = igd.ManagementServer?.ConnectionRequestURL?._value || '';
+        const online = url && !url.includes('://0.') ? '🟢' : '⚫';
+        const opt = document.createElement('option');
+        opt.value = d._id;
+        opt.textContent = `${online} ${serial} (${sw})`;
+        sel.appendChild(opt);
+      }
+      sel.addEventListener('change', onDevChange);
+      onDevChange();
+    } catch(e) {
+      sel.innerHTML = '<option value="">Error loading devices</option>';
+      info.textContent = e.message;
+    }
+  }
+
+  function onDevChange() {
+    const btn = document.getElementById('btnPush');
+    const sel = document.getElementById('selDevice');
+    const info = document.getElementById('devInfo');
+    const fw = document.getElementById('selFw');
+    info.textContent = '';
+    btn.disabled = !sel.value || !fw.value;
+  }
+
+  // ── Load firmware files ─────────────────────────────────────
+  async function loadFiles() {
+    const sel = document.getElementById('selFw');
+    const count = document.getElementById('fwCount');
+    const info = document.getElementById('fwInfo');
+    sel.innerHTML = '<option value="">Loading…</option>';
+    try {
+      const files = await api('/files');
+      sel.innerHTML = '';
+      if (!files || files.length === 0) {
+        sel.innerHTML = '<option value="">No firmware files uploaded</option>';
+        count.textContent = '0';
+        return;
+      }
+      count.textContent = files.length + ' file' + (files.length !== 1 ? 's' : '');
+      // Sort by version descending
+      files.sort((a, b) => {
+        const va = (a.version || '0').split('.').map(Number);
+        const vb = (b.version || '0').split('.').map(Number);
+        for (let i = 0; i < Math.max(va.length, vb.length); i++) {
+          const na = va[i] || 0, nb = vb[i] || 0;
+          if (na !== nb) return nb - na;
+        }
+        return 0;
+      });
+      for (const f of files) {
+        const opt = document.createElement('option');
+        opt.value = f.fileName;
+        const ver = f.version || f.fileName.match(/R(\d+[\d.]*)/)?.[1] || '—';
+        const sz = f.size ? fmtSize(f.size) : '';
+        opt.textContent = f.version ? `R${f.version}${sz ? '  (' + sz + ')' : ''}` : f.fileName;
+        opt.dataset.version = f.version || '';
+        opt.dataset.size = f.size || '';
+        sel.appendChild(opt);
+      }
+      sel.addEventListener('change', onFwChange);
+      onFwChange();
+    } catch(e) {
+      sel.innerHTML = '<option value="">Error loading files</option>';
+      info.textContent = e.message;
+    }
+  }
+
+  function onFwChange() {
+    const sel = document.getElementById('selFw');
+    const btn = document.getElementById('btnPush');
+    const info = document.getElementById('fwInfo');
+    const opt = sel.options[sel.selectedIndex];
+    if (opt && opt.value) {
+      const sz = opt.dataset.size ? fmtSize(parseInt(opt.dataset.size)) : '';
+      info.textContent = opt.value + (sz ? '  ·  ' + sz : '');
+    } else {
+      info.textContent = '';
+    }
+    btn.disabled = !document.getElementById('selDevice').value || !sel.value;
+  }
+
+  // ── Push firmware ──────────────────────────────────────────
+  async function pushFirmware() {
+    const devId = document.getElementById('selDevice').value;
+    const fileName = document.getElementById('selFw').value;
+    const btn = document.getElementById('btnPush');
+    const status = document.getElementById('statusBox');
+
+    if (!devId || !fileName) return;
+
+    clearStatus();
+    btn.classList.add('loading'); btn.disabled = true;
+
+    try {
+      const task = await api('/devices/' + encodeURIComponent(devId) + '/tasks', 'POST', {
+        name: 'download',
+        fileType: '1 Firmware Upgrade Image',
+        fileName: fileName,
+        productClass: 'GigaSpire'
+      });
+
+      if (task && task.name === 'download') {
+        showStatus('statusBox',
+          `✓ Firmware push queued successfully. Task ID: <span class="task-id">${task.id}</span>`,
+          'ok');
+      } else {
+        showStatus('statusBox', '✓ Task created: ' + JSON.stringify(task).slice(0, 100), 'ok');
+      }
+    } catch(e) {
+      if (e.message === 'AUTH') {
+        showStatus('statusBox', 'Session expired. Please reconnect.', 'err');
+        setTimeout(logout, 1500);
+      } else {
+        showStatus('statusBox', 'Failed to push firmware: ' + e.message, 'err');
+      }
+    } finally {
+      btn.classList.remove('loading'); btn.disabled = false;
+    }
+  }
+
+  // ── UI helpers ─────────────────────────────────────────────
+  function showStatus(id, html, type) {
+    const el = document.getElementById(id);
+    el.innerHTML = html;
+    el.className = 'status show ' + type;
+  }
+  function clearStatus(id = 'statusBox') {
+    const el = document.getElementById(id);
+    if (el) { el.className = 'status'; el.innerHTML = ''; }
+  }
+  function fmtSize(bytes) {
+    if (!bytes) return '';
+    if (bytes >= 1e9) return (bytes/1e9).toFixed(1) + ' GB';
+    if (bytes >= 1e6) return (bytes/1e6).toFixed(0) + ' MB';
+    return (bytes/1e3).toFixed(0) + ' KB';
+  }
+
+  // ── Boot ──────────────────────────────────────────────────
+  (function init() {
+    const { user, pass } = getCreds();
+    if (user && pass) {
+      // Restore session
+      document.getElementById('inUser').value = user;
+      document.getElementById('loginScreen').style.display = 'none';
+      document.getElementById('mainUI').classList.add('main-ui');
+      document.getElementById('connectedAs').textContent = 'Connected as ' + user;
+      loadDevices().then(loadFiles).catch(() => logout());
+    } else {
+      document.getElementById('loginScreen').classList.add('login-screen');
+    }
+    // Enter key on password field
+    document.getElementById('inPass').addEventListener('keydown', e => {
+      if (e.key === 'Enter') connect();
+    });
+  })();
+</script>
+</body>
+</html>
@@ -0,0 +1,21 @@
+server {
+    listen 80;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location = / {
+        auth_basic "GenieACS Firmware Pusher";
+        auth_basic_user_file /etc/nginx/.htpasswd;
+        try_files /index.html =404;
+    }
+
+    location = /index.html {
+        return 404;
+    }
+
+    location / {
+        auth_basic "GenieACS Firmware Pusher";
+        auth_basic_user_file /etc/nginx/.htpasswd;
+        try_files $uri $uri/ /index.html?$query_string =404;
+    }
+}
@@ -0,0 +1,98 @@
+# GenieACS
+
+TR-069 ACS (Auto Configuration Server) for managing Calix GigaSpire satellites.
+
+## Access
+
+| URL | Purpose |
+|-----|---------|
+| `https://genieacs.yoda.ddnsgeek.com` | Admin UI |
+| `https://nbi.yoda.ddnsgeek.com` | NBI API (7557) |
+| `https://acs.yoda.ddnsgeek.com` | CWMP/TR-069 (7547) |
+
+**Admin credentials:** `admin` / `966QPr@*rCTMrWE9xSGm`
+**VPS:** `root@161.97.153.158`
+
+## Version
+
+GenieACS container: `drumsergio/genieacs:latest`
+VPS docker compose: `/var/lib/docker/volumes/portainer_data/_data/compose/58/docker-compose.yml`
+
+## NBI API (port 7557)
+
+All firmware push operations use the NBI API, not the provision framework.
+
+**Base URL:** `http://127.0.0.1:7557` (on VPS) — also proxied via Traefik at `https://nbi.yoda.ddnsgeek.com`
+
+**Auth:** HTTP Basic Auth — `admin` + GenieACS admin password
+
+### Useful NBI Endpoints
+
+```
+GET  /devices                    — list all devices
+GET  /devices/{id}              — device detail
+GET  /devices/{id}/tasks        — task history
+POST /devices/{id}/tasks         — create task (firmware push)
+GET  /files                      — uploaded firmware files
+POST /files                      — upload firmware file
+DELETE /devices/{id}/tasks/{id} — cancel task
+```
+
+### Firmware Push Task
+
+```bash
+curl -X POST http://127.0.0.1:7557/devices/{device_id}/tasks \
+  -u admin:PASSWORD \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "download",
+    "fileType": "1 Firmware Upgrade Image",
+    "fileName": "FullRel_EXOS_SIGNED_E5_R25.2.0.0.img",
+    "productClass": "GigaSpire"
+  }'
+```
+
+Returns a task ID. Poll `/devices/{id}/tasks/{task_id}` to check status.
+
+### Device IDs
+
+```
+b89470-GigaSpire-CXNK010F208F  (Living room — offline/NAT'd)
+b89470-GigaSpire-CXNK010F20EC  (Back hallway sat)
+b89470-GigaSpire-CXNK010F2064  (Office sat)
+```
+
+## Fault Queue
+
+GenieACS 1.2.16 has a known issue where the provision-based `download` task
+throws "Invalid arguments" faults. Use the NBI API instead.
+
+To clear stale faults:
+```bash
+ssh root@161.97.153.158
+docker exec -i genieacs-mongo mongo genieacs --quiet --eval 'db.faults.deleteMany({})'
+```
+
+## GenieACS Doesn't Store
+
+- EXOS web UI passwords (not part of TR-069 data model)
+- WiFi passphrase (only stored in 4220E config, not GenieSpire)
+- WPA keys beyond what GenieSpire devices report via Inform
+
+## Troubleshooting
+
+### Device not connecting to GenieACS
+- Check firewall: port 7547 (CWMP) must be open on VPS
+- Check device has correct ACS URL configured
+- Check device has internet access (TR-069 requires outbound HTTPS)
+
+### Firmware push not working
+1. Verify file exists: `GET /files` — check `fileName` matches exactly
+2. Check fault queue for "Invalid arguments" — means wrong provision path
+3. Use NBI API directly to confirm task was created
+4. Check device Download table: `GET /devices/{id}` → look for `Downloads` parameter
+
+### Devices showing offline
+- GenieACS marks devices offline after ~30 minutes without Inform
+- Device may need to be power-cycled to reconnect
+- Check `LastContact` field on device detail page