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!
This commit is contained in:
211
INSTALL.md
Normal file
211
INSTALL.md
Normal file
@@ -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
|
||||
```
|
||||
41
ROADMAP.md
41
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):
|
||||
- Delete legacy/ folder
|
||||
- Remove cron jobs completely
|
||||
- Remove tmux session references
|
||||
- ✅ Deleted legacy/ folder (old cron/tmux scripts)
|
||||
- ✅ Created INSTALL.md with concise installation guide
|
||||
- ✅ Updated README.md troubleshooting section
|
||||
- ✅ 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:
|
||||
- Fresh installation steps
|
||||
- Configuration examples
|
||||
- First-time setup guide
|
||||
## Migration Complete! 🎉
|
||||
|
||||
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
|
||||
|
||||
|
||||
47
readme.md
47
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
|
||||
|
||||
# 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)
|
||||
journalctl --user -u sensorpajen -f
|
||||
```
|
||||
|
||||
### MQTT Connection Issues
|
||||
|
||||
**MQTT test:**
|
||||
```bash
|
||||
# Test MQTT connection
|
||||
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)
|
||||
mosquitto_sub -h <MQTT_HOST> -u <USER> -P <PASSWORD> -t "MiTemperature2/#" -v
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
Reference in New Issue
Block a user