From 61eb695c41768f8ebb77ad446f3fcbb87cb54aa5 Mon Sep 17 00:00:00 2001
From: Nic D <n_drolet@hotmail.ca>
Date: Wed, 20 May 2026 10:41:54 -0400
Subject: [PATCH] docs(readme): let Claude have a go at making a fancy README
 to describe the repo so far

---
 README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 75 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1355135..d77afc2 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,76 @@
-# genieACS-projects
+# genieACS Projects
 
-Collection of genieACS or TR069/TR369-related projects
\ No newline at end of file
+> A collection of extensions and provisioning scripts for [genieACS](https://genieacs.com/) — an open-source TR-069/TR-369 ACS (Auto Configuration Server) for managing CPE devices at scale.
+
+---
+
+## Overview
+
+This repository contains scripts that automate device configuration through the genieACS platform, targeting TP-Link ONU (Optical Network Unit) hardware. The scripts are structured around the two main genieACS script types: **extensions** (server-side helper functions) and **provisions** (device-lifecycle automation).
+
+---
+
+## Repository Structure
+
+```
+genieACS-projects/
+├── extensions/
+│   └── TPLink-ONU-VOIP-mapping.js      # API helper: resolves VOIP VLAN name by device ID
+└── provisions/
+    └── TPLink-ONU-VOIP-binding-fix.js  # Provision: binds VOIP VLAN interface on TP-Link ONUs
+```
+
+---
+
+## Scripts
+
+### `extensions/TPLink-ONU-VOIP-mapping.js`
+
+A genieACS **extension** that exposes a helper callable from any provision script.
+
+**What it does:**
+- Queries the genieACS NBI (Northbound Interface) REST API for a given device ID
+- Retrieves all `Device.Ethernet.VLANTermination.*` instances from the device's parameter tree
+- Finds the VLAN termination entry where `VLANID = 20` (the designated VOIP VLAN)
+- Returns the `Name` of that termination (e.g. `"veip0.20"`) for use downstream
+
+**Key config:**
+
+| Variable | Default | Description |
+|---|---|---|
+| `GENIEACS_URL` | `http://10.5.2.111:7557` | Base URL of the genieACS NBI |
+
+---
+
+### `provisions/TPLink-ONU-VOIP-binding-fix.js`
+
+A genieACS **provision** script that runs during the inform cycle of TP-Link XX230v ONU devices.
+
+**What it does:**
+1. Declares and caches the device's VLAN termination data (`VLANID` + `Name` properties)
+2. Calls the `TPLink-ONU-VOIP-mapping` extension to resolve the correct VOIP interface name
+3. Writes the resolved name to both VOIP binding parameters on the device:
+   - `Device.Services.VoiceService.1.X_TP_BoundIfName`
+   - `Device.X_TP_Services.X_TP_VoiceService.1.BoundIfName`
+
+This ensures VOIP traffic is always bound to the correct VLAN interface, even after resets or re-provisioning.
+
+---
+
+## Protocol Background
+
+| Term | Meaning |
+|---|---|
+| **TR-069** | Broadband Forum standard for CPE remote management over CWMP |
+| **genieACS** | Open-source ACS implementing TR-069; manages device parameters via provisions and extensions |
+| **ONU** | Optical Network Unit — the customer-side fiber termination device |
+| **VLAN** | Virtual LAN; used here to segment VOIP traffic onto a dedicated logical interface |
+| **NBI** | genieACS Northbound Interface — the REST API used by extensions to query device data |
+
+---
+
+## Requirements
+
+- A running [genieACS](https://github.com/genieacs/genieacs) instance
+- Axios available in the genieACS extension environment
+- TP-Link XX230v ONU devices managed by the ACS