sensorpajen/INSTALL.md

# Installation Guide

## Prerequisites

- Raspberry Pi with Raspberry Pi OS (Debian-based)
- Python 3.9+
- Bluetooth adapter
- MQTT broker accessible on network
- Xiaomi Mijia LYWSD03MMC sensors with ATC firmware

## Quick Install

```bash
# Clone repository
git clone <repo-url> ~/sensorpajen
cd ~/sensorpajen

# Create virtual environment and install
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Configure
cp config/sensorpajen.env.example config/sensorpajen.env
cp config/sensors.json.example config/sensors.json
nano config/sensorpajen.env  # Set MQTT_HOST, credentials
nano config/sensors.json     # Add sensor MAC addresses

# Set Bluetooth capabilities
sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f .venv/bin/python3)

# Install systemd service
mkdir -p ~/.config/systemd/user/
cp systemd/sensorpajen.service ~/.config/systemd/user/
systemctl --user daemon-reload
sudo loginctl enable-linger $USER

# Enable and start
systemctl --user enable sensorpajen
systemctl --user start sensorpajen
```

## Verify Installation

```bash
# Check service status
systemctl --user status sensorpajen

# View logs
journalctl --user -u sensorpajen -f

# Test MQTT (adjust credentials)
mosquitto_sub -h MQTT_HOST -u USER -P PASSWORD -t "MiTemperature2/#" -v
```

## Configuration Files

### MQTT Settings (`config/sensorpajen.env`)

```bash
MQTT_HOST=192.168.1.10          # Required
MQTT_PORT=1883
MQTT_USER=username
MQTT_PASSWORD=password
MQTT_CLIENT_ID=sensorpajen
MQTT_TOPIC_PREFIX=MiTemperature2

# Optional: ntfy notifications
NTFY_ENABLED=false
NTFY_URL=https://ntfy.sh
NTFY_TOPIC=sensorpajen
NTFY_TOKEN=

# Tuning
WATCHDOG_TIMEOUT=5              # BLE scan restart timeout
CONFIG_RELOAD_INTERVAL=900      # Auto-reload sensors (15 min)
LOG_LEVEL=INFO
```

### Sensors (`config/sensors.json`)

```json
{
  "sensors": [
    {
      "mac": "A4:C1:38:12:34:56",
      "name": "Living Room",
      "comment": "Optional description"
    }
  ]
}
```

## Adding New Sensors

### Automatic Discovery (Recommended)

1. Power on new sensor near Raspberry Pi
2. Wait for ntfy notification (if enabled) or check logs
3. Run approval tool:
   ```bash
   ./scripts/approve-sensors.sh
   ```
4. Approve sensor with custom name
5. Sensor auto-loaded within 15 minutes

### Manual Addition

1. Add to `config/sensors.json`
2. Wait 15 minutes for auto-reload, or restart:
   ```bash
   systemctl --user restart sensorpajen
   ```

## Service Management

```bash
# Start/stop
systemctl --user start sensorpajen
systemctl --user stop sensorpajen
systemctl --user restart sensorpajen

# Enable/disable autostart
systemctl --user enable sensorpajen
systemctl --user disable sensorpajen

# Status and logs
systemctl --user status sensorpajen
journalctl --user -u sensorpajen -f              # Follow
journalctl --user -u sensorpajen -n 100          # Last 100 lines
journalctl --user -u sensorpajen --since today   # Today's logs
```

## Troubleshooting

### Permission Denied on Bluetooth

```bash
# Verify capabilities
getcap $(readlink -f ~/sensorpajen/.venv/bin/python3)
# Should show: cap_net_admin,cap_net_raw+eip

# If missing, set them
sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f ~/sensorpajen/.venv/bin/python3)
systemctl --user restart sensorpajen
```

### MQTT Connection Failed

```bash
# Test MQTT manually
mosquitto_sub -h MQTT_HOST -u USER -P PASSWORD -t "test" -v

# Check credentials in config/sensorpajen.env
# Check firewall on MQTT broker
```

### No Sensor Data

```bash
# Verify sensors visible
sudo hcitool lescan

# Check sensor has ATC firmware (should show as ATC_XXXXXX)
# Verify MAC addresses in sensors.json match actual sensors
# Check battery level (low battery = intermittent connection)
```

### Service Won't Start

```bash
# Check logs for errors
journalctl --user -u sensorpajen -n 50

# Common issues:
# - MQTT_HOST not set in config/sensorpajen.env
# - sensors.json syntax error
# - Bluetooth service not running: sudo systemctl start bluetooth
```

## Updates

```bash
cd ~/sensorpajen
git pull
source .venv/bin/activate
pip install -e .

# Reinstall service if systemd file changed
cp systemd/sensorpajen.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user restart sensorpajen
```

## Uninstall

```bash
# Stop and disable service
systemctl --user stop sensorpajen
systemctl --user disable sensorpajen

# Remove service file
rm ~/.config/systemd/user/sensorpajen.service
systemctl --user daemon-reload

# Remove capabilities
sudo setcap -r $(readlink -f ~/sensorpajen/.venv/bin/python3)

# Delete repository
rm -rf ~/sensorpajen
```