Nicolas/genieACS-projects
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): let Claude have a go at making a fancy README to describe the repo so far

Browse Source
This commit is contained in:
Nic D 2026-05-20 10:41:54 -04:00
parent 83785f463f
commit 61eb695c41
1 changed files with 75 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
README.md
View File

@ -1,3 +1,76 @@
# genieACS-projects
# genieACS Projects
Collection of genieACS or TR069/TR369-related projects
> 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