AFA Systems Presence Detection

A comprehensive Bluetooth Low Energy (BLE) presence detection system that tracks beacon devices in real-time, calculates locations based on signal strength, and integrates with popular IoT platforms like Home Assistant and Node-RED.

🏗️ System Architecture

The system follows a microservices architecture with Apache Kafka as the central message bus:

┌─────────────┐    MQTT     ┌─────────────┐   Kafka    ┌─────────────┐
│   MQTT      │ ────────► │   Bridge    │ ────────► │  Decoder    │
│   Gateway   │           │   Service   │           │  Service    │
└─────────────┘           └─────────────┘           └─────────────┘
                                                          │
                                                          ▼
┌─────────────┐   WebSocket  ┌─────────────┐   Kafka    ┌─────────────┐
│   Web UI    │ ◄────────── │   Server    │ ◄───────── │  Location   │
│  Dashboard  │             │   Service   │           │  Algorithm  │
└─────────────┘             └─────────────┘           └─────────────┘

Core Components

🔌 Bridge Service (cmd/bridge/)

• Purpose: MQTT to Kafka message gateway
• Function: Subscribes to publish_out/# MQTT topics and forwards messages to Kafka rawbeacons topic
• Features: Configurable MQTT connection, automatic reconnection, error handling

🔍 Decoder Service (cmd/decoder/)

• Purpose: Processes raw BLE beacon advertisements
• Supported Formats: Ingics, Eddystone, Minew B7
• Functions:
  • Battery level monitoring
  • Fall detection events
  • Button press detection
  • Device telemetry extraction
• Output: Processed events to alertbeacons Kafka topic

📍 Location Algorithm (cmd/location/)

• Purpose: Calculates device locations based on RSSI and proximity
• Features:
  • Weighted location calculation using RSSI values
  • Confidence scoring system
  • Location change notifications
  • Configurable thresholds and parameters
• Output: Location events to locevents Kafka topic

🌐 Server Service (cmd/server/)

• Purpose: HTTP API and WebSocket server
• Features:
  • RESTful API for beacon management (CRUD operations)
  • Real-time WebSocket communication
  • Settings management interface
  • CORS-enabled web interface
  • Home Assistant integration endpoints

📊 Supporting Services

• Kafka 3.9.0: Central message bus with automatic topic creation
• Kafdrop: Web-based Kafka monitoring and management UI
• Node-RED: IoT workflow automation with pre-configured flows
• Redis: Real-time data caching and WebSocket session management
• BoltDB: Embedded database for persistent storage

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Go 1.24+ (for local development)
• MQTT broker (compatible with BLE gateways)

Installation

1. Clone the repository:

   git clone https://github.com/AFASystems/presence.git
   cd presence
   

2. Start the system:

   cd build
   docker-compose up -d
   

3. Verify services:

   • Web Interface: http://localhost:8080
   • Kafdrop (Kafka UI): http://localhost:9000
   • Node-RED: http://localhost:1880

Configuration

Set the following environment variables:

# Web Server
HTTP_HOST_PATH=":8080"
HTTP_WS_HOST_PATH=":8081"

# MQTT Configuration
MQTT_HOST="tcp://mqtt-broker:1883"
MQTT_USERNAME="your_username"
MQTT_PASSWORD="your_password"

# Kafka Configuration
KAFKA_URL="kafka:29092"

# Database
DB_PATH="./volumes/presence.db"

📡 Supported Beacon Types

Ingics Beacons

• Battery level monitoring
• Event detection (fall detection, button presses)
• Signal strength tracking

Eddystone Beacons

• Eddystone-UID protocol support
• Battery telemetry (Eddystone-TLM)
• Proximity detection

Minew B7 Beacons

• Vendor-specific format decoding
• Button counter tracking
• Battery status monitoring
• Multiple button modes

🔧 Configuration Options

System Settings (SettingsVal)

Parameter	Type	Default	Description
location_confidence	int64	80	Minimum confidence level for location changes
last_seen_threshold	int64	300	Time (seconds) before beacon considered offline
beacon_metrics_size	int	10	Number of RSSI measurements to keep for averaging
ha_send_interval	int64	60	Home Assistant update interval (seconds)
ha_send_changes_only	bool	true	Send updates only on location changes
rssi_min_threshold	int64	-90	Minimum RSSI value for beacon detection
enforce_rssi_threshold	bool	true	Filter out weak signals

API Endpoints

Beacon Management

• GET /api/beacons - List all registered beacons
• POST /api/beacons - Register a new beacon
• PUT /api/beacons/{id} - Update beacon information
• DELETE /api/beacons/{id} - Remove a beacon

Settings

• GET /api/settings - Get current system settings
• POST /api/settings - Update system settings

WebSocket

• /ws/broadcast - Real-time beacon updates and notifications

🏠 Home Assistant Integration

MQTT Auto-Discovery

The system automatically generates MQTT messages for Home Assistant:

# Example device tracker configuration
device_tracker:
  - platform: mqtt
    devices:
      beacon_001: "Presence/Beacons/beacon_001"

Battery Monitoring

# Battery level sensor
sensor:
  - platform: mqtt
    name: "Beacon Battery"
    state_topic: "Presence/Beacons/beacon_001/battery"
    unit_of_measurement: "%"
    device_class: battery

Button Detection

# Button press sensor
binary_sensor:
  - platform: mqtt
    name: "Beacon Button"
    state_topic: "Presence/Beacons/beacon_001/button"
    device_class: "button"

📊 Data Models

Core Entities

Beacon

type Beacon struct {
    Name                      string              `json:"name"`
    ID                        string              `json:"beacon_id"`
    BeaconType                string              `json:"beacon_type"`
    BeaconLocation            string              `json:"beacon_location"`
    LastSeen                  int64               `json:"last_seen"`
    Distance                  float64             `json:"distance"`
    LocationConfidence        int64               `json:"location_confidence"`
    HSButtonCounter           int64               `json:"hs_button_counter"`
    HSBattery                 int64               `json:"hs_button_battery"`
    // ... additional fields
}

BeaconAdvertisement

type BeaconAdvertisement struct {
    Hostname        string `json:"hostname"`
    MAC             string `json:"mac"`
    RSSI            int64  `json:"rssi"`
    Data            string `json:"data"`
    BeaconType      string `json:"beacon_type"`
    UUID            string `json:"uuid"`
    Major           string `json:"major"`
    Minor           string `json:"minor"`
    // ... additional fields
}

LocationChange

type LocationChange struct {
    Method           string `json:"method"`
    BeaconRef        Beacon `json:"beacon_info"`
    Name             string `json:"name"`
    PreviousLocation string `json:"previous_location"`
    NewLocation      string `json:"new_location"`
    Timestamp        int64  `json:"timestamp"`
}

🐳 Docker Services

Available Services

Service	Image	Ports	Description
kafka	apache/kafka:3.9.0	9092, 9093	Apache Kafka message broker
kafdrop	obsidiandynamics/kafdrop	9000	Kafka monitoring UI
presence-bridge	local/build	-	MQTT to Kafka bridge
presence-decoder	local/build	-	BLE beacon decoder
presence-location	local/build	-	Location calculation service
presence-server	local/build	8080, 8081	HTTP API and WebSocket server

Volumes

• ./volumes/presence.db - BoltDB database file
• ./volumes/node-red/ - Node-RED configuration and flows
• ./volumes/kafka-data/ - Kafka persistent data

🔧 Development

Local Development Setup

1. Install dependencies:

   go mod download
   

2. Run individual services:

   # Run bridge service
   go run cmd/bridge/main.go
   
   # Run decoder service
   go run cmd/decoder/main.go
   
   # Run location algorithm
   go run cmd/location/main.go
   
   # Run API server
   go run cmd/server/main.go
   

3. Run tests:

   go test ./...
   

Building Docker Images

# Build all services
docker build -t presence-system .

# Build individual service
docker build -f build/package/Dockerfile.bridge -t presence-bridge .

Project Structure

/
├── cmd/                    # Main application entry points
│   ├── server/            # HTTP API & WebSocket server
│   ├── bridge/            # MQTT to Kafka bridge
│   ├── decoder/           # BLE beacon decoder
│   ├── location/          # Location calculation algorithm
│   └── testbench/         # Testing/development utilities
├── internal/              # Private application code
│   ├── app/               # Application components
│   └── pkg/               # Shared internal packages
│       ├── model/         # Data structures and types
│       ├── kafkaclient/   # Kafka producer/consumer
│       ├── config/        # Configuration management
│       ├── persistence/   # BoltDB operations
│       ├── redis/         # Redis client
│       └── bridge/        # MQTT bridge logic
├── build/                 # Build artifacts and Docker configs
│   ├── package/           # Dockerfile for each component
│   └── docker-compose.yaml # Complete system deployment
├── web/                   # Web interface files
├── volumes/               # Persistent data and configurations
├── scripts/               # Utility scripts
└── docs/                  # Documentation

📈 Monitoring and Debugging

Kafka Topics

• rawbeacons - Raw BLE beacon advertisements
• alertbeacons - Processed beacon events (battery, buttons)
• locevents - Location change notifications

Health Checks

• Kafka: Topic creation and broker connectivity
• Services: Automatic restart on failure
• Database: BoltDB integrity checks

Logs

# View service logs
docker-compose logs -f [service-name]

# View all logs
docker-compose logs -f

🔌 Integrations

Node-RED Flows

Pre-configured Node-RED flows are available in /volumes/node-red/:

• Beacon monitoring dashboards
• Location-based automations
• Battery level alerts
• Notification systems

MQTT Topics

System publishes to the following MQTT topics:

• Presence/Beacons/{beacon_id}/location - Current beacon location
• Presence/Beacons/{beacon_id}/battery - Battery level
• Presence/Beacons/{beacon_id}/button - Button press events
• Presence/Beacons/{beacon_id}/distance - Distance from nearest gateway

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow Go conventions and best practices
• Write comprehensive tests for new features
• Update documentation for API changes
• Use meaningful commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: Project Wiki
• Discussions: GitHub Discussions

🔮 Roadmap

Upcoming Features

• Enhanced location algorithms with machine learning
• Support for additional beacon types (iBeacon, AltBeacon)
• Mobile application for beacon management
• Advanced analytics and reporting dashboard
• Multi-tenant architecture
• Cloud deployment templates

Current Development Status

• ✅ Bridge Service: Complete and stable
• ✅ Decoder Service: Core functionality implemented
• ✅ Location Algorithm: Basic algorithm functional
• ✅ Server Service: API and WebSocket implementation
• 🚧 Web Interface: Basic UI, enhancements in progress
• 🚧 Documentation: Comprehensive documentation being created
• 📋 Testing: Automated tests being expanded

---

AFA Systems Presence Detection - Real-time BLE beacon tracking and location intelligence for modern IoT environments.