# genieACS 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