sensorpajen/readme.md

# 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

See [SETUP_ON_PI.md](SETUP_ON_PI.md) for complete installation instructions.

### Quick Start

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

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

# Install dependencies
pip install -e .

# 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

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

## Configuration

### MQTT Settings

Edit `config/sensorpajen.env`:

```bash
MQTT_HOST=192.168.1.10
MQTT_PORT=1883
MQTT_USERNAME=username
MQTT_PASSWORD=password
MQTT_CLIENT_ID=sensorpajen
MQTT_TOPIC_PREFIX=MiTemperature2
```

### Sensors

Edit `config/sensors.json`:

```json
[
  {
    "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.

```bash
# Start/stop service
systemctl --user start sensorpajen
systemctl --user stop sensorpajen

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

# View status
systemctl --user status sensorpajen

# View logs
journalctl --user -u sensorpajen -f
journalctl --user -u sensorpajen -n 100
```

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

### Permission Denied Errors

If you see `PermissionError: [Errno 1] Operation not permitted`:

```bash
# Verify capabilities are set
getcap $(readlink -f ~/sensorpajen/.venv/bin/python3)

# Should show: cap_net_admin,cap_net_raw+eip
# If not, set them:
sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f ~/sensorpajen/.venv/bin/python3)

# Restart service
systemctl --user restart sensorpajen
```

### Service Won't Start

```bash
# Check service status
systemctl --user status sensorpajen

# View logs
journalctl --user -u sensorpajen -n 50

# Common issues:
# - Missing config files (check config/ directory)
# - Wrong MQTT credentials (check config/sensorpajen.env)
# - Bluetooth not enabled (sudo systemctl start bluetooth)
```

### MQTT Connection Issues

```bash
# Test MQTT connection
mosquitto_sub -h <MQTT_HOST> -u <USERNAME> -P <PASSWORD> -t "MiTemperature2/#" -v

# Check logs for connection errors
journalctl --user -u sensorpajen | grep -i mqtt
```

### No Sensor Data

```bash
# Check if sensors are visible
sudo hcitool lescan

# Verify sensor MAC addresses in config/sensors.json
# Make sure sensors have ATC firmware flashed
# Check battery level (low battery can cause connection issues)
```

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