# 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**:
   ```bash
   git clone https://github.com/AFASystems/presence.git
   cd presence
   ```

2. **Start the system**:
   ```bash
   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:

```bash
# 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:

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

### Battery Monitoring

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

### Button Detection

```yaml
# 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
```go
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
```go
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
```go
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**:
   ```bash
   go mod download
   ```

2. **Run individual services**:
   ```bash
   # 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**:
   ```bash
   go test ./...
   ```

### Building Docker Images

```bash
# 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

```bash
# 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](LICENSE) file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/AFASystems/presence/issues)
- **Documentation**: [Project Wiki](https://github.com/AFASystems/presence/wiki)
- **Discussions**: [GitHub Discussions](https://github.com/AFASystems/presence/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.