sensorpajen/INSTALL.md

Installation Guide

Prerequisites

• Raspberry Pi with Raspberry Pi OS (Debian-based)
• Python 3.9+
• Bluetooth adapter
• MQTT broker accessible on network
• Xiaomi Mijia LYWSD03MMC sensors with ATC firmware

Quick Install

# Clone repository
git clone <repo-url> ~/sensorpajen
cd ~/sensorpajen

# Create virtual environment and install
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Configure
cp config/sensorpajen.env.example config/sensorpajen.env
cp config/sensors.json.example config/sensors.json
nano config/sensorpajen.env  # Set MQTT_HOST, credentials
nano config/sensors.json     # Add 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

# Enable and start
systemctl --user enable sensorpajen
systemctl --user start sensorpajen

Verify Installation

# Check service status
systemctl --user status sensorpajen

# View logs
journalctl --user -u sensorpajen -f

# Test MQTT (adjust credentials)
mosquitto_sub -h MQTT_HOST -u USER -P PASSWORD -t "MiTemperature2/#" -v

Configuration Files

MQTT Settings (config/sensorpajen.env)

MQTT_HOST=192.168.1.10          # Required
MQTT_PORT=1883
MQTT_USER=username
MQTT_PASSWORD=password
MQTT_CLIENT_ID=sensorpajen
MQTT_TOPIC_PREFIX=MiTemperature2

# Optional: ntfy notifications
NTFY_ENABLED=false
NTFY_URL=https://ntfy.sh
NTFY_TOPIC=sensorpajen
NTFY_TOKEN=

# Tuning
WATCHDOG_TIMEOUT=5              # BLE scan restart timeout
CONFIG_RELOAD_INTERVAL=900      # Auto-reload sensors (15 min)
LOG_LEVEL=INFO

Sensors (config/sensors.json)

{
  "sensors": [
    {
      "mac": "A4:C1:38:12:34:56",
      "name": "Living Room",
      "comment": "Optional description"
    }
  ]
}

Adding New Sensors

Automatic Discovery (Recommended)

1. Power on new sensor near Raspberry Pi
2. Wait for ntfy notification (if enabled) or check logs
3. Run approval tool:

   ./scripts/approve-sensors.sh
   

4. Approve sensor with custom name
5. Sensor auto-loaded within 15 minutes

Manual Addition

1. Add to config/sensors.json
2. Wait 15 minutes for auto-reload, or restart:

   systemctl --user restart sensorpajen
   

Service Management

# Start/stop
systemctl --user start sensorpajen
systemctl --user stop sensorpajen
systemctl --user restart sensorpajen

# Enable/disable autostart
systemctl --user enable sensorpajen
systemctl --user disable sensorpajen

# Status and logs
systemctl --user status sensorpajen
journalctl --user -u sensorpajen -f              # Follow
journalctl --user -u sensorpajen -n 100          # Last 100 lines
journalctl --user -u sensorpajen --since today   # Today's logs

Troubleshooting

Permission Denied on Bluetooth

# Verify capabilities
getcap $(readlink -f ~/sensorpajen/.venv/bin/python3)
# Should show: cap_net_admin,cap_net_raw+eip

# If missing, set them
sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f ~/sensorpajen/.venv/bin/python3)
systemctl --user restart sensorpajen

MQTT Connection Failed

# Test MQTT manually
mosquitto_sub -h MQTT_HOST -u USER -P PASSWORD -t "test" -v

# Check credentials in config/sensorpajen.env
# Check firewall on MQTT broker

No Sensor Data

# Verify sensors visible
sudo hcitool lescan

# Check sensor has ATC firmware (should show as ATC_XXXXXX)
# Verify MAC addresses in sensors.json match actual sensors
# Check battery level (low battery = intermittent connection)

Service Won't Start

# Check logs for errors
journalctl --user -u sensorpajen -n 50

# Common issues:
# - MQTT_HOST not set in config/sensorpajen.env
# - sensors.json syntax error
# - Bluetooth service not running: sudo systemctl start bluetooth

Updates

cd ~/sensorpajen
git pull
source .venv/bin/activate
pip install -e .

# Reinstall service if systemd file changed
cp systemd/sensorpajen.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user restart sensorpajen

Uninstall

# Stop and disable service
systemctl --user stop sensorpajen
systemctl --user disable sensorpajen

# Remove service file
rm ~/.config/systemd/user/sensorpajen.service
systemctl --user daemon-reload

# Remove capabilities
sudo setcap -r $(readlink -f ~/sensorpajen/.venv/bin/python3)

# Delete repository
rm -rf ~/sensorpajen