Phase 9 Complete: Cleanup & Documentation

Completed: - Created INSTALL.md with concise sysadmin-focused guide - Updated README.md troubleshooting to reference INSTALL.md - Marked ROADMAP Phase 9 complete Documentation Philosophy: - Compact and practical - Assumes sysadmin familiarity - Focus on actual usage, not theory All 9 phases of migration now complete!
2025-12-27 23:09:02 +01:00
parent 16c47e62f5
commit b467541eb5
3 changed files with 243 additions and 56 deletions
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -0,0 +1,211 @@
+# 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
+```