ACS - Auto Configuration Server

Carrier-grade TR-069 (CWMP) and TR-369 (USP) device management system built with Laravel 11

🚀 Features

Multi-Protocol Support

✅ TR-069 (CWMP) - Legacy device management protocol
✅ TR-369 (USP) - Next-generation User Services Platform
✅ Dual Protocol - Devices can operate with both protocols

TR-369 USP Transport Layers (MTP)

🔌 MQTT - Broker-based pub/sub communication
🌐 WebSocket - Direct device connections (RFC 6455 compliant)
📡 HTTP - Polling-based for restricted networks

Core Capabilities

📊 100,000+ Device Management - Scalable architecture
⚡ Zero-Touch Provisioning - Automated device configuration
🔄 Firmware Management - Upload, version, and deploy firmware
📈 Real-time Monitoring - Dashboard with metrics and charts
🔔 Subscribe/Notify - Event-based device notifications
🧪 Remote Diagnostics - Ping, traceroute, speed tests (TR-143)
🔐 API Security - Key-based authentication
📡 Queue Processing - Laravel Horizon for async tasks

📋 Quick Start

Prerequisites

PHP 8.3+
PostgreSQL 16+ (or SQLite for development)
Redis (for queue processing)
Composer
MQTT Broker (optional, test.mosquitto.org available)

Installation

1. Clone & Install Dependencies

git clone https://github.com/dexter939/EvoAcs.git
cd EvoAcs
composer install

2. Environment Setup (Automated)

# Run interactive setup wizard
./scripts/setup-env.sh

Or Manual Setup:

cp .env.example .env
php artisan key:generate

# Edit .env with your configuration
nano .env

See Environment Setup Guide for detailed configuration.

3. Database Migration

# Run database migrations
php artisan migrate

# Optional: Seed sample data
php artisan db:seed

4. Start Services

Development Server:

php artisan serve --host=0.0.0.0 --port=5000

Background Services (Optional):

# Terminal 1: MQTT Subscriber (for MQTT transport)
php artisan usp:mqtt-subscribe

# Terminal 2: WebSocket Server (for WebSocket transport)
php artisan usp:websocket-server

# Terminal 3: Queue Worker (for async tasks)
php artisan horizon

5. Access Dashboard

http://localhost:5000/acs/dashboard

🔧 Configuration

Essential Environment Variables

# Application
APP_KEY=                          # Auto-generated

# Database
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_DATABASE=acs_database
DB_USERNAME=acs_user
DB_PASSWORD=your_password

# ACS API Key (REQUIRED)
ACS_API_KEY=your-secret-api-key

# TR-369 USP
USP_CONTROLLER_ENDPOINT_ID=proto::acs-controller
USP_WEBSOCKET_PORT=9000

# MQTT Broker
MQTT_HOST=test.mosquitto.org
MQTT_PORT=1883

# Redis (for queues & WebSocket)
REDIS_HOST=127.0.0.1
QUEUE_CONNECTION=redis

📖 Complete Reference: Environment Variables Documentation

📡 Protocol Endpoints

TR-069 (CWMP)

POST /tr069

SOAP-based endpoint for TR-069 device communication.

TR-369 (USP)

POST /usp

Binary protobuf endpoint for USP Records (HTTP MTP).

RESTful API

POST /api/v1/usp/devices/{device}/get-params
POST /api/v1/usp/devices/{device}/set-params
POST /api/v1/usp/devices/{device}/operate
POST /api/v1/usp/devices/{device}/add-object
DELETE /api/v1/usp/devices/{device}/delete-object
POST /api/v1/usp/devices/{device}/reboot
POST /api/v1/usp/devices/{device}/subscribe
DELETE /api/v1/usp/devices/{device}/subscriptions/{id}

Authentication: API Key required in X-API-Key header.

📖 Complete API Docs: USP API Documentation

🏗️ Architecture

System Components

┌─────────────────────────────────────────────────────┐
│                   ACS Controller                    │
│                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │  TR-069 SOAP │  │  TR-369 USP  │  │  RESTful  │ │
│  │   Endpoint   │  │   Endpoint   │  │    API    │ │
│  └──────────────┘  └──────────────┘  └───────────┘ │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │         Transport Layer (MTP)                │  │
│  │  ┌──────┐  ┌──────────┐  ┌────────────────┐ │  │
│  │  │ MQTT │  │ WebSocket│  │  HTTP Polling  │ │  │
│  │  └──────┘  └──────────┘  └────────────────┘ │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │         Queue System (Laravel Horizon)       │  │
│  │         Database (PostgreSQL)                │  │
│  │         Cache & Session (Redis)              │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
                         ↕
┌─────────────────────────────────────────────────────┐
│                CPE Devices (100K+)                  │
│   TR-069 CWMP Devices  │  TR-369 USP Devices       │
└─────────────────────────────────────────────────────┘

Key Technologies

Backend: Laravel 11, PHP 8.3
Database: PostgreSQL 16 (optimized for 100K+ devices)
Queue: Redis + Laravel Horizon
Protocols: Protocol Buffers (TR-369), SOAP (TR-069)
Transport: MQTT (php-mqtt/laravel-client), WebSocket (native PHP), HTTP
Frontend: Soft UI Dashboard, Chart.js
Icons: FontAwesome 6

🧪 Testing

Manual Testing Scripts

# Test USP API endpoints
./tests/test_usp_api.sh

# Test Subscribe/Notify pattern
./tests/test_subscribe_notify.sh

USP Protocol Testing

# Test message encoding/decoding
php artisan usp:test-message

# Test MQTT communication
php artisan usp:test-mqtt

# Test controller functionality
php artisan usp:test-controller

📊 Dashboard Features

Statistics Cards (12 total)

Legacy Metrics: Devices Online, Tasks Pending, Firmware Deploys, Tests, etc.
TR-069 Metrics: CWMP device count
TR-369 Metrics: USP device count, MQTT/HTTP transport statistics

Charts (4 interactive)

Device Status (Doughnut Chart)
Provisioning Tasks (Bar Chart)
Diagnostics (Polar Area Chart)
Firmware Deployments (Line Chart)

Device Management

Protocol filtering (TR-069 / TR-369)
MTP transport filtering (MQTT / WebSocket / HTTP)
Status badges and icons
Real-time auto-refresh (30s)

📖 Documentation

Environment Setup Guide - Detailed configuration
Environment Variables - Complete variable reference
USP API Documentation - RESTful API guide
Postman Collection - API testing

🔐 Security

Production Checklist

Change ACS_API_KEY to strong random value (32+ chars)
Set APP_ENV=production and APP_DEBUG=false
Enable SSL/TLS for MQTT (port 8883)
Enable WebSocket SSL (USP_WEBSOCKET_SSL=true)
Configure trusted proxies for load balancer
Implement multi-tenant authentication (roadmap)
Enable rate limiting
Configure monitoring (Sentry, metrics)

API Authentication

All /api/v1/* endpoints require API key:

curl -H "X-API-Key: your-api-key" \
  http://localhost:5000/api/v1/usp/devices

🚀 Production Deployment

Background Services (Required)

Use a process manager (systemd, supervisor, or PM2):

# /etc/systemd/system/acs-mqtt.service
[Unit]
Description=ACS MQTT Subscriber
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/acs
ExecStart=/usr/bin/php artisan usp:mqtt-subscribe
Restart=always

[Install]
WantedBy=multi-user.target

Repeat for:

acs-websocket.service → php artisan usp:websocket-server
acs-horizon.service → php artisan horizon

Performance Optimization

# Cache configuration
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Optimize autoloader
composer install --optimize-autoloader --no-dev

🛠️ Troubleshooting

Common Issues

1. WebSocket connection failed

# Check if port is configured
grep USP_WEBSOCKET_PORT .env

# Start WebSocket server
php artisan usp:websocket-server

2. MQTT connection failed

# Test MQTT connection
php artisan usp:test-mqtt

# Check broker settings
grep MQTT_ .env

3. Queue not processing

# Check queue configuration
grep QUEUE_CONNECTION .env

# Start Horizon
php artisan horizon

4. API authentication failed

# Verify API key is set
grep ACS_API_KEY .env

# Use in request
curl -H "X-API-Key: your-key" http://localhost:5000/api/v1/...

🗺️ Roadmap

Current Version (v1.0)

✅ TR-069 CWMP support
✅ TR-369 USP support
✅ MQTT/WebSocket/HTTP transport
✅ Subscribe/Notify pattern
✅ RESTful API
✅ Web dashboard

Future Enhancements

Multi-tenant authentication system
Bulk device operations
Device grouping and tagging
Scheduled provisioning (cron-based)
Advanced analytics and reporting
Prometheus metrics export
High-availability clustering
Rate limiting and throttling

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

Broadband Forum - TR-069 and TR-369 specifications
Laravel - PHP framework
Soft UI Dashboard - Admin template
Chart.js - Charting library

📞 Support

For issues and questions:

Open an issue on GitHub
Check Documentation
Review Troubleshooting Guide

Built with ❤️ for telecom operators managing large-scale CPE deployments

Name		Name	Last commit message	Last commit date
app		app
attached_assets		attached_assets
bootstrap		bootstrap
config		config
data		data
database		database
deploy		deploy
docker		docker
docs		docs
k8s		k8s
mobile-app		mobile-app
monitoring		monitoring
public		public
resources		resources
routes		routes
scripts		scripts
storage		storage
tests		tests
wiki		wiki
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.env.testing		.env.testing
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.replit		.replit
CREATE_ADMIN_USER.md		CREATE_ADMIN_USER.md
DEPLOYMENT.md		DEPLOYMENT.md
DEPLOYMENT_FIX_INSTRUCTIONS.md		DEPLOYMENT_FIX_INSTRUCTIONS.md
Dockerfile		Dockerfile
GITHUB_RELEASE_UPDATE_SYSTEM.md		GITHUB_RELEASE_UPDATE_SYSTEM.md
KUBERNETES.md		KUBERNETES.md
MONITORING.md		MONITORING.md
Makefile		Makefile
PRODUCTION-NOTES.md		PRODUCTION-NOTES.md
Procfile		Procfile
QUICK-INSTALL.md		QUICK-INSTALL.md
README-INSTALLATION.md		README-INSTALLATION.md
README.md		README.md
SECURITY.md		SECURITY.md
STAGING_DEPLOYMENT_CHECKLIST.md		STAGING_DEPLOYMENT_CHECKLIST.md
TELEMETRY_MONITORING_GUIDE.md		TELEMETRY_MONITORING_GUIDE.md
TEST_RESULTS_TR_PROTOCOLS.md		TEST_RESULTS_TR_PROTOCOLS.md
artisan		artisan
backup.sh		backup.sh
composer.json		composer.json
composer.lock		composer.lock
deploy.sh		deploy.sh
docker-compose.monitoring.yml		docker-compose.monitoring.yml
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
phpunit.xml		phpunit.xml
prosody.cfg.lua		prosody.cfg.lua
reinstall.sh		reinstall.sh
replit.md		replit.md
restore.sh		restore.sh
run-tests.sh		run-tests.sh
supervisord.conf		supervisord.conf
test_xmpp_mikrotik.php		test_xmpp_mikrotik.php
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation