IoT Bridge

An all-in-one, open-source tool that bundles everything you need for IoT communication into a single package. Includes a built-in MQTT broker (Aedes), SQLite database, REST API server, interactive web dashboard, WSL USB bridging, comprehensive logs management, and an interactive CLI for real-time device interaction. No need for separate installations just install and start bridging your IoT devices!

Table of Contents

• Why IoT Bridge ?
• Features
• Installation
• Quick Start
• Usage
• Configuration
• API Reference
• Web Dashboard
• Security
• Troubleshooting
• Contributing
• License
• Support

Why IoT Bridge ?

IoT Bridge stands out by providing a complete, self-contained IoT communication suite in a single tool. Instead of piecing together multiple services, get everything you need out-of-the-box:

• Built-in MQTT Broker: No external broker needed Aedes MQTT server included.
• Integrated Database: SQLite for logging, no database setup required.
• REST API Server: Ready-to-use API for integrations.
• Web Dashboard: Real-time visualization without additional web servers.
• WSL USB Support: Automatic Windows USB device bridging to WSL.
• Interactive CLI: View logs and send commands simultaneously in the terminal.
• Multiple Instances: Run several instances at once for multi-device management.
• Logs Management: Query, filter, and purge logs with ease.

Perfect for hobbyists, developers, and small teams who want powerful IoT tools without the complexity of managing multiple services.

Features

IoT Bridge offers a comprehensive suite of features in a single, easy-to-use package.

All-in-One Solution

• Built-in MQTT Broker (Aedes): Full MQTT protocol support with client management and topic-based messaging.
• Integrated SQLite Database: Automatic logging with indexing for fast queries no external DB required.
• REST API Server: Comprehensive API for log retrieval, statistics, and device control.
• Interactive Web Dashboard: Real-time charts and command interface using Chart.js and Socket.io.
• WSL USB Bridging: Seamless auto-mounting of Windows USB devices to WSL environments.
• Advanced Logs Management: Query by source, date, or custom filters; secure purge options.
• Interactive CLI: Simultaneous log viewing and command sending in the terminal.
• Multiple Instance Support: Run multiple instances simultaneously for parallel device communication and logging.

Communication Modes

• Serial Port (USB) Mode: Direct USB serial communication with configurable baud rates and device auto-detection.
• MQTT Broker Mode: Wireless IoT communication with standard MQTT support.

Additional Capabilities

• Security Features: JWT authentication, bcrypt password hashing, and secure credential storage.
• Real-Time Updates: WebSocket-based live data streaming to the dashboard.
• System Monitoring: Health checks for database, network, and bridge status.
• Flexible Deployment: Standalone API mode, headless operation, or full interactive experience.

Examples

Serial Communication with Real-Time Logging

$ iot-bridge init
# Select Serial Port (USB), enable logging
✔ LINK ESTABLISHED: /dev/ttyUSB0 @ 9600
YOU > LED ON
Device > LED turned on
# Logs automatically saved to SQLite DB

MQTT Broker with Multiple Clients

$ iot-bridge init
# Select MQTT (Broker)
✔ MQTT Broker Live on PORT: 1883
MQTT SEND > sensors/temp 25.5
[sensors/temp] 25.5
# Multiple clients can connect and logs are unified

Multiple Instances for Multi-Device Setup

# Terminal 1: Serial device
$ iot-bridge init --mode serial --port /dev/ttyUSB0

# Terminal 2: MQTT broker
$ iot-bridge init --mode mqtt --port 1884

# Terminal 3: API server
$ iot-bridge api --port 3001
# All instances share the same database and logs

WSL USB Auto-Bridging

# On WSL, automatic detection and bridging:
Detected USB Devices:
1. ESP32 Dev Board (Bus: 1-2)
? Bridge device: Yes
✔ Device bridged to WSL
# Now accessible as /dev/ttyUSB0

Installation

Prerequisites

• Node.js >= 16.0.0
• npm or yarn
• For Serial mode: USB drivers (usually auto-installed)
• For WSL: usbipd on Windows host

Global Installation

npm install -g @smartiot-stack/iot-bridge

Local Development

git clone https://github.com/smartiot-stack/iot-bridge.git
cd iot-bridge
npm install
npm link

Quick Start

1. Setup Admin Credentials:

   iot-bridge setup
   # Set username and password

2. Start Bridging:

   iot-bridge init
   # Choose Serial or MQTT, enable features

3. Access Dashboard:

   • Open http://localhost:3005
   • Login and start monitoring

4. Send Commands & View Logs:

   • Use the interactive
   • Check logs: iot-bridge logs --query

Usage

Core Commands

iot-bridge setup

First-time admin setup.

iot-bridge setup

iot-bridge init

Interactive bridge configuration.

iot-bridge init
# Guided setup for mode selection

iot-bridge api

Standalone API server.

iot-bridge api --port 8080

iot-bridge logs

Log management.

iot-bridge logs --query --source SERIAL
iot-bridge logs --purge --date 2023-10-01

iot-bridge status

System status check.

iot-bridge status

iot-bridge user

Update admin credentials.

iot-bridge user

Advanced Examples

Running Multiple Instances

# Instance 1: Serial bridge
iot-bridge init --mode serial --port /dev/ttyACM0 --baud 115200 --log --api-port 3001

# Instance 2: MQTT broker on different port
iot-bridge init --mode mqtt --mqtt-port 1884 --log --api-port 3002

# Both save to the same database, accessible via different APIs

Integrating with External Tools

• Grafana: Use /api/stats/:source for metrics
• Node-RED: HTTP request nodes to API endpoints
• Custom Scripts: Direct database queries or API calls

Configuration

Configuration stored in ~/.config/iot-bridge/:

• .config.json: Admin credentials
• iot_bridge.db: SQLite logs

Environment variables:

• IOT_BRIDGE_DB_PATH: Custom DB location
• IOT_BRIDGE_API_PORT: Default API port

API Reference

Authentication

Protected endpoints require JWT:

Authorization: Bearer <token>

Key Endpoints

• POST /api/login: Get JWT token
• GET /api/logs: Recent logs
• GET /api/logs/:source: Filtered logs
• GET /api/history: Date-range logs
• GET /api/stats/:source: Aggregated stats
• GET /api/sources: Unique sources
• DELETE /api/logs/purge: Delete logs
• GET /api/heartbeat: System health

Web Dashboard

Access at http://localhost:3005:

• Live charts with Chart.js
• Send commands to devices
• Browse and filter logs
• Real-time updates via Socket.io

Security

• JWT tokens (1-hour expiry)
• Bcrypt password hashing
• Input sanitization
• Secure credential storage

Troubleshooting

Common Issues

1. Serial Port Access: Check permissions (sudo usermod -a -G dialout $USER)
2. WSL USB: Ensure usbipd is installed and running
3. Port Conflicts: Change default ports if needed
4. Database Issues: Check disk space and permissions

Debugging

• Verbose mode: DEBUG=iot-bridge:* iot-bridge ...
• Check logs: iot-bridge logs --query

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE

Support

• GitHub Issues: Report bugs
• Discussions: Feature requests
• Conatct: web