ATCMI Scanner

A distributed Bluetooth Low Energy (BLE) scanner system for Xiaomi thermometers with custom ATC firmware. The system has been architected into 4 distinct applications for better separation of concerns and scalability.

Architecture Overview

The ATCMI Scanner consists of 4 applications:

┌─────────┐    HTTP POST   ┌───────────┐    SQLite   ┌────────────┐
│  agent  │ ─────────────► │ db-server │ ──────────► │  Database  │
└─────────┘                └───────────┘             └────────────┘
                                 ▲
                                 │ HTTP GET
                                 │
                          ┌────────────┐
                          │ web-server │
                          └────────────┘

1. agent/ - BLE Scanner

• Purpose: Scans for Bluetooth Low Energy devices and sends data to db-server
• Port: N/A (uses host networking for Bluetooth)
• Features: CLI dashboard, multi-agent support, configurable polling
• Dependencies: Requires Bluetooth hardware

2. db-server/ - Database API Server

• Purpose: Minimal SvelteKit app providing REST API for database operations
• Port: 3001
• Database: SQLite for sensor readings storage
• Features: Health checks, device management, historical data queries

3. web-server/ - Dashboard UI

• Purpose: SvelteKit web application serving the sensor monitoring dashboard
• Port: 3000
• Features: Real-time charts, device cards, historical data visualization
• Dependencies: Fetches data from db-server API

4. agent/shared/ - Common Utilities

• Purpose: Shared configuration and utilities used by the agent
• Exports: BLE config, API config, data types, helper functions

Quick Start

Using Docker Compose (Recommended)

1. Start all services:

docker compose up -d

2. Access the dashboard:

   • Web Dashboard: http://localhost:3000
   • Database API: http://localhost:3001

3. View logs:

docker compose logs --follow
docker compose logs agent --follow  # Agent logs only

4. Stop services:

docker compose down

Building Docker Images

To rebuild containers after code changes:

# Rebuild all services
docker compose build

# Rebuild specific service
docker compose build db-server
docker compose build web-server
docker compose build agent

# Rebuild and restart
docker compose up -d --build

Multi-Agent Deployment

Deploy agents on multiple machines for distributed scanning:

1. On the server machine:

# Start db-server and web-server only
docker compose up db-server web-server -d

2. On each agent machine:

# Update SERVER_URL in environment
export SERVER_URL=http://your-db-server-ip:3001

# Start remote agent
docker compose --profile remote up agent-remote -d

Manual Development Setup

Database Server

cd db-server
npm install
npm run dev        # Development server on port 3001
npm run build      # Build for production
npm start          # Start production server

Web Server

cd web-server
npm install
npm run dev        # Development server on port 3000
npm run build      # Build for production
npm start          # Start production server

Agent

cd agent
npm install
node main.js --server http://localhost:3001     # Connect to db-server
node main.js --dashboard                        # Run with CLI dashboard
node main.js --poll 30s                        # Custom polling interval

Configuration

Environment Variables

db-server

• NODE_ENV: Environment (development/production)
• PORT: Server port (default: 3001)
• DB_PATH: Database file path (default: /app/data/sensor_data.db)

web-server

• NODE_ENV: Environment (development/production)
• PORT: Server port (default: 3000)
• VITE_DB_SERVER_URL: Database server URL (default: http://localhost:3001)

agent

• SERVER_URL: Database server URL (default: http://localhost:3001)
• AGENT_ID: Unique identifier for the agent (auto-generated)
• BLE_ADDRESS_PREFIX: MAC address prefix to filter (default: a4:c1:38)
• POLL_INTERVAL: Scan interval (default: 30s)

Docker Compose Configuration

The docker-compose.yml file includes:

• Service Dependencies: web-server waits for db-server health check
• Networking: Internal network for service communication
• Volumes: Persistent storage for SQLite database
• Health Checks: Automatic service health monitoring

API Endpoints (db-server:3001)

Core Endpoints

• POST /api/sensor-data - Accept sensor readings from agents
• GET /api/health - Server health check
• GET /api/devices - List all discovered devices
• GET /api/all-data - Get all sensor data
• GET /api/historical-data - Get historical data with filters
• GET /api/stream - Server-sent events for real-time updates

Device Management

• GET /api/devices/{address}/history - Historical data for specific device

Testing

All Tests

npm test                    # Run all tests (root level)
npm run test:watch          # Run tests in watch mode
npm run test:coverage       # Generate coverage report

Service-Specific Tests

# Agent tests
cd agent && npm test
cd agent && npm run test:unit         # Data parsing unit tests
cd agent && npm run test:ble          # BLE connection tests (mocked)
cd agent && npm run test:hardware     # Hardware integration tests

# Database server tests
cd db-server && npm test

# Web server tests  
cd web-server && npm test
cd web-server && npm run format       # Format code with Prettier
cd web-server && npm run lint         # Check code formatting

Bluetooth Setup (Linux)

npm run setup:bluetooth      # Setup Bluetooth permissions (Linux)

Hardware Requirements

Agent Requirements

• Linux machine with Bluetooth LE support
• Noble.js compatible Bluetooth adapter
• Node.js 18+
• Docker (for containerized deployment)

Supported Devices

• Xiaomi thermometers with custom ATC firmware
• Default MAC prefix: a4:c1:38:
• Service UUID: 181a for sensor data

Device Data Format

The application expects Xiaomi thermometers flashed with ATC custom firmware:

• Temperature: 16-bit signed integer (÷10 for actual value)
• Humidity: 8-bit unsigned integer (percentage)
• Battery: 8-bit unsigned integer (percentage)
• Battery Voltage: 16-bit unsigned integer (÷1000 for volts)

Deployment Options

1. Single Machine: All services on one machine
2. Distributed: Multiple agents connecting to central servers
3. Development: Local services for testing
4. Containerized: Docker Compose for production

Troubleshooting

Common Issues

1. Bluetooth permissions: Run npm run setup:bluetooth
2. Agent connection: Check SERVER_URL environment variable
3. Database issues: Verify DB_PATH and volume mounts
4. Port conflicts: Ensure ports 3000 and 3001 are available

Logs

docker compose logs agent --follow     # Agent logs
docker compose logs db-server --follow # Database server logs
docker compose logs web-server --follow # Web server logs

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

License

[Add your license here]