fredrik/sensorpajen
1
0
Fork 0
Code Issues Pull Requests Projects Releases 2 Wiki Activity

Release v2.0.0 - Production ready

Browse Source 
Version bump:
- Update VERSION to 2.0.0 (from 2.0.0-dev)
- Update pyproject.toml to 2.0.0
- Change development status to Production/Stable

Documentation updates:
- Add Debian package installation instructions (system-wide)
- Add sensor discovery and approval workflow documentation
- Update configuration section with approval workflow
- Update service management for system installation
- Update troubleshooting for system installation
- Update MQTT settings documentation
- Add links to download Debian packages from releases

The application is now production-ready with:
- Systemd integration for automatic service management
- Automatic startup and restart on failure
- Configuration via /etc/sensorpajen/
- Runtime state in /var/lib/sensorpajen/
- Interactive sensor approval workflow
- Automatic configuration reload
- Comprehensive logging via journalctl
This commit is contained in:
fredrik
2025-12-28 10:54:57 +01:00
parent a55d065c38
commit e9b8d56f6d
3 changed files with 115 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
readme.md
View File

@@ -22,48 +22,72 @@ Raspberry Pi service that monitors Xiaomi Mijia LYWSD03MMC Bluetooth temperature
## Installation
See [INSTALL.md](INSTALL.md) for complete installation instructions.
### System Installation (Debian Package - Recommended for Raspberry Pi)
### Quick Start
The easiest way to install on Raspberry Pi OS is using the pre-built Debian package:
```bash
# Clone repository
git clone <repo-url> ~/sensorpajen
cd ~/sensorpajen
# Download the latest release
wget https://gitea.wahlberg.se/api/v1/repos/fredrik/sensorpajen/releases/download/v2.0.0/sensorpajen_2.0.0_all.deb
# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -e .
# Install
sudo dpkg -i sensorpajen_2.0.0_all.deb
# 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
sudo nano /etc/sensorpajen/sensorpajen.env # Edit MQTT settings
sudo systemctl restart sensorpajen
# 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
# 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
```
### Approving Sensors (Discovery Workflow)
The service automatically discovers nearby Bluetooth sensors and stores them in a pending list. You approve which ones to monitor:
```bash
# Start sensor discovery (if not already running)
sudo systemctl start sensorpajen
# Let it scan for a minute or two to discover sensors
sleep 120
# View discovered sensors and approve them
sudo sensorpajen approve-sensors
```
The approval CLI will:
1. Show newly discovered sensors with their current readings
2. Ask you to approve, ignore, or skip each sensor
3. Save approved sensors to `/etc/sensorpajen/sensors.json`
4. Mark their status in `/var/lib/sensorpajen/discovered_sensors.json`
When you approve a sensor, it's added to your configuration and the service automatically starts monitoring it.
### MQTT Settings
Edit `config/sensorpajen.env`:
@@ -71,7 +95,7 @@ Edit `config/sensorpajen.env`:
```bash
MQTT_HOST=192.168.1.10
MQTT_PORT=1883
MQTT_USERNAME=username
MQTT_USER=username
MQTT_PASSWORD=password
MQTT_CLIENT_ID=sensorpajen
MQTT_TOPIC_PREFIX=MiTemperature2
@@ -79,42 +103,52 @@ MQTT_TOPIC_PREFIX=MiTemperature2
### Sensors
Edit `config/sensors.json`:
Sensors are automatically managed via the approval workflow. You can also manually edit `/etc/sensorpajen/sensors.json`:
```json
[
{
"mac": "A4:C1:38:12:34:56",
"name": "Living Room"
},
{
"mac": "A4:C1:38:AB:CD:EF",
"name": "Bedroom"
}
]
```
{
"sensors": [
{
"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.
### System Installation (Debian Package)
```bash
# Start/stop service
systemctl --user start sensorpajen
systemctl --user stop sensorpajen
sudo systemctl start sensorpajen
sudo systemctl stop sensorpajen
# Enable/disable autostart
systemctl --user enable sensorpajen
systemctl --user disable sensorpajen
sudo systemctl enable sensorpajen
sudo systemctl disable sensorpajen
# View status
systemctl --user status sensorpajen
sudo systemctl status sensorpajen
# View logs
journalctl --user -u sensorpajen -f
journalctl --user -u sensorpajen -n 100
# 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!
@@ -158,27 +192,40 @@ sensorpajen/
## Troubleshooting
See [INSTALL.md](INSTALL.md#troubleshooting) for detailed troubleshooting steps.
### System Installation (Debian Package)
### Quick Checks
**Permission errors:**
**Service won't start:**
```bash
sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f ~/sensorpajen/.venv/bin/python3)
systemctl --user restart sensorpajen
# 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
```
**Service status:**
**MQTT connection issues:**
```bash
systemctl --user status sensorpajen
journalctl --user -u sensorpajen -f
```
# Verify MQTT settings in the log
sudo journalctl -u sensorpajen | grep MQTT
**MQTT test:**
```bash
# Test MQTT connection manually
mosquitto_sub -h <MQTT_HOST> -u <USER> -P <PASSWORD> -t "MiTemperature2/#" -v
```
**Sensor not found:**
```bash
# Run sensor discovery
sudo sensorpajen approve-sensors
# Check discovered sensors
sudo cat /var/lib/sensorpajen/discovered_sensors.json | jq '.'
```
### Development Installation
## Development
```bash