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
This commit is contained in:
260
readme.md
260
readme.md
@@ -1,33 +1,241 @@
|
|||||||
# Sensorpajen
|
# 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
|
Raspberry Pi service that monitors Xiaomi Mijia LYWSD03MMC Bluetooth temperature sensors and publishes data to MQTT.
|
||||||
- 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
|
|
||||||
|
|
||||||
## Sensorer i pajen
|
## Features
|
||||||
- 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
|
- 🌡️ Monitors 8 Xiaomi Mijia thermometers via Bluetooth (ATC firmware)
|
||||||
|
- 📡 Publishes temperature, humidity, and battery data to MQTT
|
||||||
## Cronjobb
|
- 🔄 Automatic restart on failure
|
||||||
```
|
- 📊 Systemd service with journald logging
|
||||||
@reboot /home/pi/sensorer.sh
|
- 🔧 Modern Python package with virtual environment
|
||||||
*/1 * * * * /home/pi/temperatur_koksfonstret.py 11 4
|
- ⚙️ 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 <repo-url> ~/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!!
|
### MQTT Settings
|
||||||
- Ha en permanent marker tillgänglig
|
|
||||||
- Flashning måste göras från en mobil
|
|
||||||
|
|
||||||
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)
|
Edit `config/sensorpajen.env`:
|
||||||
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
|
```bash
|
||||||
4. Tryck på Connect och sök upp den aktiva termometern. Den heter något i stil med LYWSD03MMC
|
MQTT_HOST=192.168.1.10
|
||||||
5. Gör Do Activation och när den hittat Select Firmarware Start Flashing
|
MQTT_PORT=1883
|
||||||
6. Anteckna mac-adressen från (1) och sätt ett id på termometern. Det ska senare in i filen sensorer.ini
|
MQTT_USERNAME=username
|
||||||
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
|
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 <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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Clone and setup
|
||||||
|
git clone <repo-url> ~/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
|
||||||
Reference in New Issue
Block a user