Release v2.0.0 - Production ready
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:
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|||||||
|
|
||||||
[project]
|
[project]
|
||||||
name = "sensorpajen"
|
name = "sensorpajen"
|
||||||
version = "2.0.0-dev"
|
version = "2.0.0"
|
||||||
description = "Bluetooth temperature sensor monitor for Xiaomi Mijia LYWSD03MMC"
|
description = "Bluetooth temperature sensor monitor for Xiaomi Mijia LYWSD03MMC"
|
||||||
readme = "README.md"
|
readme = "README.md"
|
||||||
requires-python = ">=3.9"
|
requires-python = ">=3.9"
|
||||||
@@ -14,7 +14,7 @@ authors = [
|
|||||||
]
|
]
|
||||||
keywords = ["bluetooth", "temperature", "sensor", "mqtt", "raspberry-pi"]
|
keywords = ["bluetooth", "temperature", "sensor", "mqtt", "raspberry-pi"]
|
||||||
classifiers = [
|
classifiers = [
|
||||||
"Development Status :: 4 - Beta",
|
"Development Status :: 5 - Production/Stable",
|
||||||
"Intended Audience :: Developers",
|
"Intended Audience :: Developers",
|
||||||
"License :: OSI Approved :: MIT License",
|
"License :: OSI Approved :: MIT License",
|
||||||
"Programming Language :: Python :: 3",
|
"Programming Language :: Python :: 3",
|
||||||
|
|||||||
161
readme.md
161
readme.md
@@ -22,48 +22,72 @@ Raspberry Pi service that monitors Xiaomi Mijia LYWSD03MMC Bluetooth temperature
|
|||||||
|
|
||||||
## Installation
|
## 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
|
```bash
|
||||||
# Clone repository
|
# Download the latest release
|
||||||
git clone <repo-url> ~/sensorpajen
|
wget https://gitea.wahlberg.se/api/v1/repos/fredrik/sensorpajen/releases/download/v2.0.0/sensorpajen_2.0.0_all.deb
|
||||||
cd ~/sensorpajen
|
|
||||||
|
|
||||||
# Create and activate virtual environment
|
# Install
|
||||||
python3 -m venv .venv
|
sudo dpkg -i sensorpajen_2.0.0_all.deb
|
||||||
source .venv/bin/activate
|
|
||||||
|
|
||||||
# Install dependencies
|
|
||||||
pip install -e .
|
|
||||||
|
|
||||||
# Configure
|
# Configure
|
||||||
cp config/sensorpajen.env.example config/sensorpajen.env
|
sudo nano /etc/sensorpajen/sensorpajen.env # Edit MQTT settings
|
||||||
cp config/sensors.json.example config/sensors.json
|
sudo systemctl restart sensorpajen
|
||||||
nano config/sensorpajen.env # Edit MQTT settings
|
|
||||||
nano config/sensors.json # Edit sensor MAC addresses
|
|
||||||
|
|
||||||
# Set Bluetooth capabilities
|
# View logs
|
||||||
sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f .venv/bin/python3)
|
sudo journalctl -u sensorpajen -f
|
||||||
|
|
||||||
# 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
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
|
## 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
|
### MQTT Settings
|
||||||
|
|
||||||
Edit `config/sensorpajen.env`:
|
Edit `config/sensorpajen.env`:
|
||||||
@@ -71,7 +95,7 @@ Edit `config/sensorpajen.env`:
|
|||||||
```bash
|
```bash
|
||||||
MQTT_HOST=192.168.1.10
|
MQTT_HOST=192.168.1.10
|
||||||
MQTT_PORT=1883
|
MQTT_PORT=1883
|
||||||
MQTT_USERNAME=username
|
MQTT_USER=username
|
||||||
MQTT_PASSWORD=password
|
MQTT_PASSWORD=password
|
||||||
MQTT_CLIENT_ID=sensorpajen
|
MQTT_CLIENT_ID=sensorpajen
|
||||||
MQTT_TOPIC_PREFIX=MiTemperature2
|
MQTT_TOPIC_PREFIX=MiTemperature2
|
||||||
@@ -79,10 +103,11 @@ MQTT_TOPIC_PREFIX=MiTemperature2
|
|||||||
|
|
||||||
### Sensors
|
### Sensors
|
||||||
|
|
||||||
Edit `config/sensors.json`:
|
Sensors are automatically managed via the approval workflow. You can also manually edit `/etc/sensorpajen/sensors.json`:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
{
|
||||||
|
"sensors": [
|
||||||
{
|
{
|
||||||
"mac": "A4:C1:38:12:34:56",
|
"mac": "A4:C1:38:12:34:56",
|
||||||
"name": "Living Room"
|
"name": "Living Room"
|
||||||
@@ -91,30 +116,39 @@ Edit `config/sensors.json`:
|
|||||||
"mac": "A4:C1:38:AB:CD:EF",
|
"mac": "A4:C1:38:AB:CD:EF",
|
||||||
"name": "Bedroom"
|
"name": "Bedroom"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
```
|
}
|
||||||
|
|
||||||
## Service Management
|
## Service Management
|
||||||
|
|
||||||
See [systemd/README.md](systemd/README.md) for detailed service management instructions.
|
### System Installation (Debian Package)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Start/stop service
|
# Start/stop service
|
||||||
systemctl --user start sensorpajen
|
sudo systemctl start sensorpajen
|
||||||
systemctl --user stop sensorpajen
|
sudo systemctl stop sensorpajen
|
||||||
|
|
||||||
# Enable/disable autostart
|
# Enable/disable autostart
|
||||||
systemctl --user enable sensorpajen
|
sudo systemctl enable sensorpajen
|
||||||
systemctl --user disable sensorpajen
|
sudo systemctl disable sensorpajen
|
||||||
|
|
||||||
# View status
|
# View status
|
||||||
systemctl --user status sensorpajen
|
sudo systemctl status sensorpajen
|
||||||
|
|
||||||
# View logs
|
# View logs (live)
|
||||||
journalctl --user -u sensorpajen -f
|
sudo journalctl -u sensorpajen -f
|
||||||
journalctl --user -u sensorpajen -n 100
|
|
||||||
|
# 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
|
## Flashing New Thermometers
|
||||||
|
|
||||||
**Important**: Flash only one thermometer at a time!
|
**Important**: Flash only one thermometer at a time!
|
||||||
@@ -158,27 +192,40 @@ sensorpajen/
|
|||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
See [INSTALL.md](INSTALL.md#troubleshooting) for detailed troubleshooting steps.
|
### System Installation (Debian Package)
|
||||||
|
|
||||||
### Quick Checks
|
**Service won't start:**
|
||||||
|
|
||||||
**Permission errors:**
|
|
||||||
```bash
|
```bash
|
||||||
sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f ~/sensorpajen/.venv/bin/python3)
|
# Check what's wrong
|
||||||
systemctl --user restart sensorpajen
|
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
|
```bash
|
||||||
systemctl --user status sensorpajen
|
# Verify MQTT settings in the log
|
||||||
journalctl --user -u sensorpajen -f
|
sudo journalctl -u sensorpajen | grep MQTT
|
||||||
```
|
|
||||||
|
|
||||||
**MQTT test:**
|
# Test MQTT connection manually
|
||||||
```bash
|
|
||||||
mosquitto_sub -h <MQTT_HOST> -u <USER> -P <PASSWORD> -t "MiTemperature2/#" -v
|
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
|
## Development
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
Reference in New Issue
Block a user