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!

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
+```

ROADMAP.md

@@ -460,29 +460,36 @@ When installed via .deb package:
 
 ---
 
-### Phase 9: Cleanup & Documentation ✓ TODO
+### Phase 9: Cleanup & Documentation ✅ DONE (2025-12-27)
 **Goal**: Remove legacy code and finalize documentation
 
+**Notes**:
+- Legacy cron/tmux scripts removed
+- Documentation focused on practical usage
+- INSTALL.md created for sysadmins
+
 #### Tasks:
-1. Once new service is stable (run for 1-2 weeks):
+- ✅ Deleted legacy/ folder (old cron/tmux scripts)
-   - Delete legacy/ folder
+- ✅ Created INSTALL.md with concise installation guide
-   - Remove cron jobs completely
+- ✅ Updated README.md troubleshooting section
-   - Remove tmux session references
+- ✅ Documentation assumes sysadmin familiarity
 
-2. Update README.md:
+---
-   - Installation instructions
-   - Configuration guide
-   - Service management commands
-   - Troubleshooting section
-   - Remove DHT11 references
-   - Remove pirate_audio references
 
-3. Create INSTALL.md:
+## Migration Complete! 🎉
-   - Fresh installation steps
-   - Configuration examples
-   - First-time setup guide
 
-4. Document in README:
+All phases completed. The system has been successfully migrated from a legacy cron/tmux-based system to a modern systemd service with:
+
+- ✅ Python package structure
+- ✅ Environment-based configuration (no .ini files)
+- ✅ Systemd user service with auto-restart
+- ✅ Automatic sensor discovery with approval workflow
+- ✅ Configuration auto-reload (no restart needed)
+- ✅ ntfy notifications for new sensors
+- ✅ Comprehensive documentation
+
+**Version**: 2.0.0-dev  
+**Status**: Production-ready
    ```markdown
    ## Installation
    

readme.md

@@ -22,7 +22,7 @@ Raspberry Pi service that monitors Xiaomi Mijia LYWSD03MMC Bluetooth temperature
 
 ## Installation
 
-See [SETUP_ON_PI.md](SETUP_ON_PI.md) for complete installation instructions.
+See [INSTALL.md](INSTALL.md) for complete installation instructions.
 
 ### Quick Start
 
@@ -158,56 +158,25 @@ sensorpajen/
 
 ## Troubleshooting
 
-### Permission Denied Errors
+See [INSTALL.md](INSTALL.md#troubleshooting) for detailed troubleshooting steps.
 
-If you see `PermissionError: [Errno 1] Operation not permitted`:
+### Quick Checks
 
+**Permission errors:**
 ```bash
-# Verify capabilities are set
-getcap $(readlink -f ~/sensorpajen/.venv/bin/python3)
-
-# Should show: cap_net_admin,cap_net_raw+eip
-# If not, set them:
 sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f ~/sensorpajen/.venv/bin/python3)
-
-# Restart service
 systemctl --user restart sensorpajen
 ```
 
-### Service Won't Start
+**Service status:**
-
 ```bash
-# Check service status
 systemctl --user status sensorpajen
-
+journalctl --user -u sensorpajen -f
-# View logs
-journalctl --user -u sensorpajen -n 50
-
-# Common issues:
-# - Missing config files (check config/ directory)
-# - Wrong MQTT credentials (check config/sensorpajen.env)
-# - Bluetooth not enabled (sudo systemctl start bluetooth)
 ```
 
-### MQTT Connection Issues
+**MQTT test:**
-
 ```bash
-# Test MQTT connection
+mosquitto_sub -h <MQTT_HOST> -u <USER> -P <PASSWORD> -t "MiTemperature2/#" -v
-mosquitto_sub -h <MQTT_HOST> -u <USERNAME> -P <PASSWORD> -t "MiTemperature2/#" -v
-
-# Check logs for connection errors
-journalctl --user -u sensorpajen | grep -i mqtt
-```
-
-### No Sensor Data
-
-```bash
-# Check if sensors are visible
-sudo hcitool lescan
-
-# Verify sensor MAC addresses in config/sensors.json
-# Make sure sensors have ATC firmware flashed
-# Check battery level (low battery can cause connection issues)
 ```
 
 ## Development