269 lines
6.9 KiB
Markdown
269 lines
6.9 KiB
Markdown
# Sensorpajen
|
|
|
|
Raspberry Pi service that monitors Xiaomi Mijia LYWSD03MMC Bluetooth temperature sensors and publishes data to MQTT.
|
|
|
|
## 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
|
|
|
|
### System Installation (Debian Package - Recommended for Raspberry Pi)
|
|
|
|
The easiest way to install on Raspberry Pi OS is using the pre-built Debian package:
|
|
|
|
```bash
|
|
# Download the latest release
|
|
wget https://gitea.wahlberg.se/api/v1/repos/fredrik/sensorpajen/releases/download/v3.0.1/sensorpajen_3.0.1_all.deb
|
|
|
|
# Install
|
|
sudo dpkg -i sensorpajen_3.0.1_all.deb
|
|
|
|
# Configure
|
|
sudo nano /etc/sensorpajen/sensorpajen.env # Edit MQTT settings
|
|
sudo systemctl restart sensorpajen
|
|
|
|
# View logs
|
|
sudo journalctl -u sensorpajen -f
|
|
```
|
|
|
|
The system package installs:
|
|
- Application in `/opt/sensorpajen/`
|
|
- Configuration in `/etc/sensorpajen/`
|
|
- Runtime state in `/var/lib/sensorpajen/`
|
|
- Systemd service (runs automatically)
|
|
|
|
### Development Installation
|
|
|
|
See [INSTALL.md](INSTALL.md) for complete development setup.
|
|
|
|
## Configuration
|
|
|
|
### Quick Setup
|
|
|
|
After installation, configure your MQTT broker and sensors:
|
|
|
|
```bash
|
|
# Edit MQTT settings
|
|
sudo nano /etc/sensorpajen/sensorpajen.env
|
|
|
|
# Restart service to apply changes
|
|
sudo systemctl restart sensorpajen
|
|
```
|
|
|
|
### Sensor Management (TUI)
|
|
|
|
The service automatically discovers nearby Bluetooth sensors. You can manage them using the built-in Text UI:
|
|
|
|
```bash
|
|
# Launch the management TUI
|
|
sudo sensorpajen-tui
|
|
```
|
|
|
|
The TUI allows you to:
|
|
- **Discovery**: View newly discovered sensors and **Approve** (add to monitoring) or **Ignore** them.
|
|
- **Configured**: View currently monitored sensors, **Edit** their names, or **Remove** them.
|
|
- **Ignored**: View ignored sensors and **Unignore** them if you change your mind.
|
|
|
|
**Keybindings:**
|
|
- `a`: Approve selected sensor
|
|
- `i`: Ignore selected sensor
|
|
- `e`: Edit sensor name and comment
|
|
- `v`: View details (MAC/name/comment)
|
|
- `u`: Unignore sensor
|
|
- `Delete`: Remove sensor from monitoring
|
|
- `r`: Refresh data
|
|
- `q`: Quit
|
|
|
|
When you approve a sensor, it's added to your configuration and the service automatically starts monitoring it.
|
|
|
|
### Legacy CLI Approval (Deprecated)
|
|
|
|
The recommended workflow is the TUI (`sensorpajen-tui`). A legacy CLI tool still exists:
|
|
|
|
```bash
|
|
sudo sensorpajen-approve-sensors
|
|
```
|
|
|
|
### MQTT Settings
|
|
|
|
Edit `/etc/sensorpajen/sensorpajen.env`:
|
|
|
|
```bash
|
|
MQTT_HOST=192.168.1.10
|
|
MQTT_PORT=1883
|
|
MQTT_USER=username
|
|
MQTT_PASSWORD=password
|
|
MQTT_CLIENT_ID=sensorpajen
|
|
MQTT_TOPIC_PREFIX=MiTemperature2
|
|
```
|
|
|
|
### Sensors
|
|
|
|
Sensors are automatically managed via the approval workflow. You can also manually edit `/etc/sensorpajen/sensors.json`:
|
|
|
|
```json
|
|
{
|
|
"sensors": [
|
|
{
|
|
"mac": "A4:C1:38:12:34:56",
|
|
"name": "Living Room"
|
|
},
|
|
{
|
|
"mac": "A4:C1:38:AB:CD:EF",
|
|
"name": "Bedroom"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Service Management
|
|
|
|
### System Installation (Debian Package)
|
|
|
|
```bash
|
|
# Start/stop service
|
|
sudo systemctl start sensorpajen
|
|
sudo systemctl stop sensorpajen
|
|
|
|
# Enable/disable autostart
|
|
sudo systemctl enable sensorpajen
|
|
sudo systemctl disable sensorpajen
|
|
|
|
# View status
|
|
sudo systemctl status sensorpajen
|
|
|
|
# View logs (live)
|
|
sudo journalctl -u sensorpajen -f
|
|
|
|
# View last 50 log lines
|
|
sudo journalctl -u sensorpajen -n 50
|
|
|
|
# Uninstall
|
|
sudo dpkg -r sensorpajen
|
|
# Note: Configuration is preserved in /etc/sensorpajen/
|
|
# To remove config: sudo rm -rf /etc/sensorpajen/
|
|
```
|
|
|
|
### Development Installation
|
|
|
|
## 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
|
|
|
|
### System Installation (Debian Package)
|
|
|
|
**Service won't start:**
|
|
```bash
|
|
# Check what's wrong
|
|
sudo journalctl -u sensorpajen -n 50
|
|
|
|
# Check configuration is valid
|
|
sudo cat /etc/sensorpajen/sensorpajen.env
|
|
|
|
# Manually test the application
|
|
sudo /opt/sensorpajen/venv/bin/python -m sensorpajen.main
|
|
```
|
|
|
|
**MQTT connection issues:**
|
|
```bash
|
|
# Verify MQTT settings in the log
|
|
sudo journalctl -u sensorpajen | grep MQTT
|
|
|
|
# Test MQTT connection manually
|
|
mosquitto_sub -h <MQTT_HOST> -u <USER> -P <PASSWORD> -t "MiTemperature2/#" -v
|
|
```
|
|
|
|
**Sensor not found:**
|
|
```bash
|
|
# Run the TUI to view/approve newly discovered sensors
|
|
sudo sensorpajen-tui
|
|
|
|
# Check recent logs
|
|
sudo journalctl -u sensorpajen -n 100
|
|
```
|
|
|
|
### Development Installation
|
|
|
|
## 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 |