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
|
||||
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 <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!!
|
||||
- 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
|
||||
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 <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