fredrik/sensorpajen
1
0
Fork 0
Code Issues Pull Requests Projects Releases 2 Wiki Activity
Files
54d55cf0f60616c01c5c8d1bdc050f834a2a7f77
sensorpajen/readme.md

6.8 KiB
Raw Blame History

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:

# 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

# Install
sudo dpkg -i sensorpajen_2.0.0_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 for complete development setup.

Configuration

Quick Setup

After installation, configure your MQTT broker and sensors:

# 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:

# 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
  • 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

If you prefer the command line, you can still use:

sudo sensorpajen approve-sensors

MQTT Settings

Edit config/sensorpajen.env:

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:

{
  "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:

  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:

# 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:

# 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:

# Run sensor discovery
sudo sensorpajen approve-sensors

# Check discovered sensors
sudo cat /var/lib/sensorpajen/discovered_sensors.json | jq '.'

Development Installation

Development

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

Reference in New Issue View Git Blame Copy Permalink