NexusBus

NexusBus: A robust FastAPI-based middleware for Modbus TCP/RTU, offering a database-driven gateway for seamless data integration. It provides dynamic device management via REST API, automated polling with in-memory caching, real-time MQTT publishing, and hot-reload capabilities for configurations.

📚 Documentation Navigation

| Quick Start | Device Management | Polling | MQTT | Monitoring | Migrations | | ------------------------------------- | ----------------------------------------------- | ------------------------------------------------- | ---------------------------------------- | ------------------------------------------------- | ----------------------------------------- | | Database Setup | Device API Guide | Polling Config | MQTT Guide | Metrics & Monitoring | Migration Guide |

✅ Database-Driven Configuration - Store and manage Modbus devices in PostgreSQL
✅ Dynamic Device Management - Add/update/remove devices via REST API without restart
✅ Automatic Polling - Configure registers to poll automatically from database
✅ Parallel Polling - Poll multiple devices concurrently for improved performance
✅ Hot-Reload - Apply configuration changes without server restart
✅ Connection Pooling - Efficiently manage Modbus TCP connections & shared gateways
✅ Circuit Breaker - Automatic failure detection with fast-fail and auto-recovery
✅ Request Timeout Handling - Automatic timeout and connection reset
✅ REST API - Complete API for device interaction and management
✅ Async Support - Full async/await with asyncpg for optimal performance
✅ Smart Caching - Register value caching with TTL and automatic eviction
✅ MQTT Integration - Real-time data publishing to MQTT brokers
✅ Soft Delete - Deactivate devices/polling without losing configuration
✅ Structured Logging - JSON-formatted logs for easy parsing and monitoring
✅ Metrics Collection - Built-in metrics for performance monitoring
✅ Enhanced Health Checks - Comprehensive health monitoring for all services
✅ Input Validation - Robust validation for all API inputs

🚀 Quick Start

1. Installation

# Clone repository
git clone https://github.com/Jonathan0823/nexusbus.git
cd nexusbus

# Create virtual environment
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows PowerShell
# source venv/bin/activate    # Linux/Mac

# Install dependencies
pip install -r requirements.txt

2. Database Setup

Configure Environment:

cp .env.example .env
# Edit .env with your PostgreSQL credentials

Run Migrations:

python migrate.py

This creates:

✅ modbus_devices table with sample devices
✅ polling_targets table with sample polling configs

Full Migration Guide →

3. Start Application

uvicorn main:app --reload

Access:

API: http://localhost:8000
Interactive Docs: http://localhost:8000/docs
Health Check: http://localhost:8000/health
Metrics: http://localhost:8000/api/metrics

4. Run with Docker (Recommended) 🐳

For easier setup and deployment, you can use Docker Compose to run the application and its PostgreSQL database.

docker-compose up -d

This command will:

Build the nexusbus_app Docker image and start the container.
Create and start a PostgreSQL database container (nexusbus_db).
Automatically run database migrations.
Expose the application on port 8000.

Access:

API: http://localhost:8000
Interactive Docs: http://localhost:8000/docs
Health Check: http://localhost:8000/health

To stop the services:

docker-compose down

📖 API Quick Reference

Device Operations

| Endpoint | Method | Description | Docs | | ----------------------------------- | ------ | -------------- | ------------------------------------------------- | | /api/devices | GET | List devices | → | | /api/devices/{id}/registers | GET | Read registers | → | | /api/devices/{id}/registers/write | POST | Write register | → | | /api/devices/gateways | GET | Gateway status | → |

Admin - Device Management

| Endpoint | Method | Description | Docs | | --------------------------- | ------ | ---------------------- | ------------------------------------------------------------- | | /api/admin/devices | GET | List all devices | → | | /api/admin/devices | POST | Create device | → | | /api/admin/devices/{id} | PUT | Update device | → | | /api/admin/devices/{id} | DELETE | Soft delete | → | | /api/admin/devices/reload | POST | Hot-reload configs | → |

Admin - Polling Management

| Endpoint | Method | Description | Docs | | ------------------------- | ------ | --------------------- | ---------------------------------------------------------------------- | | /api/admin/polling | GET | List polling targets | → | | /api/admin/polling | POST | Create polling target | → | | /api/admin/polling/{id} | PUT | Update target | → | | /api/admin/polling/{id} | DELETE | Soft delete | → |

Admin - Cache Management

| Endpoint | Method | Description | Docs | | ------------------------------ | ------ | -------------------- | ---- | | /api/admin/cache | GET | Inspect all cache | - | | /api/admin/cache/stats | GET | Cache statistics | - | | /api/admin/cache/device/{id} | GET | Inspect device cache | - | | /api/admin/cache | DELETE | Clear all cache | - |

Metrics & Monitoring

| Endpoint | Method | Description | Docs | | ------------------ | ------ | ------------------------ | ---- | | /api/metrics | GET | Get all application metrics | - | | /api/metrics/reset | POST | Reset metrics (testing) | - | | /health | GET | Comprehensive health check | - |

Complete API Documentation →

📦 Configuration

Environment Variables

This application uses a .env file for configuration. Copy .env.example to .env to start.

Database Configuration

MQTT Configuration (Optional)

Application Settings

**Log

Nexusbus

Install / Use

README