From e3bec0d16ef3c32b65a4dc348614ad423a59030b Mon Sep 17 00:00:00 2001 From: Fredrik Wahlberg Date: Sat, 27 Dec 2025 14:30:21 +0100 Subject: [PATCH] Update README with current system architecture - Modernized documentation to reflect systemd service - Added installation and configuration instructions - Kept thermometer flashing instructions - Added troubleshooting section - Added project structure overview - Removed outdated DHT11 and cron references --- readme.md | 260 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 234 insertions(+), 26 deletions(-) diff --git a/readme.md b/readme.md index 2d8355d..1865eba 100644 --- a/readme.md +++ b/readme.md @@ -1,33 +1,241 @@ # Sensorpajen -Raspberry Pi Zero W som läser av diverse mätere och rapporterar data till MQTT. -Använder Xiaomi Mijia thermometer 2 samt inbyggd DHT11 sensor -## Bluetooth termometrarna - - LYWSD03MMC.py - script för att läsa av Mi Mijia Thermometer 2 - - sensorer.ini - config till LYWSD03MMC - - sendToMQTT.sh - stödscript till LYWSD03MMC - - bluetooth_utils.py - stödscript till LYWSD03MMC +Raspberry Pi service that monitors Xiaomi Mijia LYWSD03MMC Bluetooth temperature sensors and publishes data to MQTT. -## Sensorer i pajen - - temperatur_koksfonstret.py - Läser av DHT 11 sensor kopplad till Pi, används av cron - - sensorer.sh - script för att starta tmux vid boot, används av cron - -## Cronjobb -``` -@reboot /home/pi/sensorer.sh -*/1 * * * * /home/pi/temperatur_koksfonstret.py 11 4 +## Features + +- 🌡️ Monitors 8 Xiaomi Mijia thermometers via Bluetooth (ATC firmware) +- 📡 Publishes temperature, humidity, and battery data to MQTT +- 🔄 Automatic restart on failure +- 📊 Systemd service with journald logging +- 🔧 Modern Python package with virtual environment +- ⚙️ Configuration via environment variables and JSON + +## Requirements + +- Raspberry Pi (tested on Raspberry Pi Zero W and newer) +- Raspberry Pi OS (Debian-based) +- Python 3.9+ +- Bluetooth adapter +- MQTT broker +- Xiaomi Mijia LYWSD03MMC sensors with ATC firmware + +## Installation + +See [SETUP_ON_PI.md](SETUP_ON_PI.md) for complete installation instructions. + +### Quick Start + +```bash +# Clone repository +git clone ~/sensorpajen +cd ~/sensorpajen + +# Create and activate virtual environment +python3 -m venv .venv +source .venv/bin/activate + +# Install dependencies +pip install -e . + +# Configure +cp config/sensorpajen.env.example config/sensorpajen.env +cp config/sensors.json.example config/sensors.json +nano config/sensorpajen.env # Edit MQTT settings +nano config/sensors.json # Edit 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 + +# Start service +systemctl --user enable sensorpajen +systemctl --user start sensorpajen + +# Check status +systemctl --user status sensorpajen +journalctl --user -u sensorpajen -f ``` -## Flasha nya termometrar +## Configuration - - Öppna och flasha bara en termometer i taget!! - - Ha en permanent marker tillgänglig - - Flashning måste göras från en mobil +### MQTT Settings - 1. Ta reda på termometerns mac-adress med någon bra app för Bluetooth BLE . Den heter något i stil med LYWSD03MMC (Om du bara startat en termometer så är det lätt att hitta) - 2. Ladda ned senaste releasen av firmware här: https://github.com/atc1441/ATC_MiThermometer - 3. Öppna den här webbsidan: https://atc1441.github.io/TelinkFlasher.html - 4. Tryck på Connect och sök upp den aktiva termometern. Den heter något i stil med LYWSD03MMC - 5. Gör Do Activation och när den hittat Select Firmarware Start Flashing - 6. Anteckna mac-adressen från (1) och sätt ett id på termometern. Det ska senare in i filen sensorer.ini - 7. Verifiera i din BLE läsare att termometern nu heter något i stil med ATC_XXXXXX. Om du missade att anteckna mac-adressen så är första delen alltid A4:C1:38 och XXXXXX i namnet är de sista tre delarna \ No newline at end of file +Edit `config/sensorpajen.env`: + +```bash +MQTT_HOST=192.168.1.10 +MQTT_PORT=1883 +MQTT_USERNAME=username +MQTT_PASSWORD=password +MQTT_CLIENT_ID=sensorpajen +MQTT_TOPIC_PREFIX=MiTemperature2 +``` + +### Sensors + +Edit `config/sensors.json`: + +```json +[ + { + "mac": "A4:C1:38:12:34:56", + "name": "Living Room" + }, + { + "mac": "A4:C1:38:AB:CD:EF", + "name": "Bedroom" + } +] +``` + +## Service Management + +See [systemd/README.md](systemd/README.md) for detailed service management instructions. + +```bash +# Start/stop service +systemctl --user start sensorpajen +systemctl --user stop sensorpajen + +# Enable/disable autostart +systemctl --user enable sensorpajen +systemctl --user disable sensorpajen + +# View status +systemctl --user status sensorpajen + +# View logs +journalctl --user -u sensorpajen -f +journalctl --user -u sensorpajen -n 100 +``` + +## Flashing New Thermometers + +**Important**: Flash only one thermometer at a time! + +1. **Find MAC address**: Use a Bluetooth BLE app to find the thermometer's MAC address. It will appear as `LYWSD03MMC`. + +2. **Download firmware**: Get the latest ATC firmware from https://github.com/atc1441/ATC_MiThermometer + +3. **Flash firmware**: + - Open https://atc1441.github.io/TelinkFlasher.html on your phone + - Click "Connect" and select your thermometer (LYWSD03MMC) + - Click "Do Activation" + - When found, select firmware and click "Start Flashing" + +4. **Record MAC address**: Note the MAC address (from step 1) and label the thermometer physically with a permanent marker. + +5. **Add to configuration**: Add the MAC address and name to `config/sensors.json` + +6. **Verify**: The thermometer should now appear as `ATC_XXXXXX` where XXXXXX are the last 3 bytes of the MAC address. MAC addresses always start with `A4:C1:38`. + +## Project Structure + +``` +sensorpajen/ +├── src/sensorpajen/ # Python package +│ ├── main.py # Application entry point +│ ├── config.py # Configuration management +│ ├── mqtt_publisher.py # MQTT client wrapper +│ ├── sensor_reader.py # Bluetooth sensor reader +│ └── utils.py # Bluetooth utilities +├── config/ # Configuration files +│ ├── sensorpajen.env.example +│ └── sensors.json.example +├── systemd/ # Systemd service files +│ ├── sensorpajen.service +│ └── README.md +├── legacy/ # Old scripts (deprecated) +├── pyproject.toml # Python package configuration +└── README.md # This file +``` + +## Troubleshooting + +### Permission Denied Errors + +If you see `PermissionError: [Errno 1] Operation not permitted`: + +```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 + +```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) +``` + +### MQTT Connection Issues + +```bash +# Test MQTT connection +mosquitto_sub -h -u -P -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 + +```bash +# Clone and setup +git clone ~/sensorpajen +cd ~/sensorpajen +python3 -m venv .venv +source .venv/bin/activate +pip install -e . + +# Run directly (without systemd) +python -m sensorpajen.main + +# Run tests (when available) +pytest +``` + +## Migration from Legacy System + +See [ROADMAP.md](ROADMAP.md) for the complete migration plan from the old cron/tmux-based system to the modern systemd service. + +## License + +See license headers in individual source files. + +## Credits + +- Bluetooth utilities based on work by Colin GUYON (MIT License) +- ATC firmware by atc1441: https://github.com/atc1441/ATC_MiThermometer \ No newline at end of file