From f54c0a0f35581b8047d61620f8ba737aacecc018 Mon Sep 17 00:00:00 2001
From: Fredrik Wahlberg <fredrik@wahlberg.se>
Date: Sat, 27 Dec 2025 13:42:51 +0100
Subject: [PATCH] Add Raspberry Pi setup and testing guide

Created SETUP_ON_PI.md with comprehensive instructions for:
- Pulling latest changes on the Pi
- Installing system dependencies (Bluetooth, Python)
- Setting up virtual environment
- Configuring Bluetooth permissions
- Setting up configuration files
- Running test
- Troubleshooting common issues
- Environment variable reference

Enables seamless development workflow between machines.
---
 SETUP_ON_PI.md | 176 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 176 insertions(+)
 create mode 100644 SETUP_ON_PI.md

diff --git a/SETUP_ON_PI.md b/SETUP_ON_PI.md
new file mode 100644
index 0000000..d9120fe
--- /dev/null
+++ b/SETUP_ON_PI.md
@@ -0,0 +1,176 @@
+# Setup on Raspberry Pi - Testing Guide
+
+## Prerequisites
+- Raspberry Pi with Bluetooth support
+- Raspberry Pi OS (Debian-based)
+- Git repository access
+- MQTT broker accessible from the Pi
+
+## Quick Setup Steps
+
+### 1. Pull Latest Changes
+```bash
+cd ~/sensorpajen  # or wherever your repo is
+git pull origin master
+```
+
+### 2. Install System Dependencies
+```bash
+# Install Bluetooth and build tools
+sudo apt update
+sudo apt install -y bluetooth bluez libbluetooth-dev python3-dev python3-pip python3-venv
+
+# Verify Bluetooth is working
+sudo systemctl status bluetooth
+```
+
+### 3. Create Virtual Environment
+```bash
+cd ~/sensorpajen
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### 4. Install Python Dependencies
+```bash
+pip install --upgrade pip
+pip install bluepy paho-mqtt
+
+# Or install the package in development mode
+pip install -e .
+```
+
+### 5. Set Bluetooth Capabilities
+This allows Python to access Bluetooth without sudo:
+```bash
+# Set capabilities on the Python interpreter in the venv
+sudo setcap 'cap_net_raw,cap_net_admin+eip' .venv/bin/python3
+```
+
+### 6. Configure the Application
+```bash
+# Copy configuration templates
+cp config/sensorpajen.env.example config/sensorpajen.env
+cp config/sensors.json.example config/sensors.json
+
+# Edit MQTT settings
+nano config/sensorpajen.env
+# Update MQTT_HOST, MQTT_USER, MQTT_PASSWORD
+
+# Verify/edit sensor list
+nano config/sensors.json
+# Should already have your 8 sensors from legacy config
+```
+
+### 7. Test Run
+```bash
+# Make sure virtual environment is activated
+source .venv/bin/activate
+
+# Load environment variables
+export $(cat config/sensorpajen.env | grep -v '^#' | xargs)
+
+# Run the application
+python -m sensorpajen.main
+```
+
+You should see:
+- Configuration being loaded
+- MQTT connection established
+- BLE scanning started
+- Sensor readings as they come in
+
+Press Ctrl+C to stop.
+
+## Troubleshooting
+
+### Bluetooth Permission Issues
+If you get permission errors:
+```bash
+# Check if capabilities are set
+getcap .venv/bin/python3
+
+# If not set, run:
+sudo setcap 'cap_net_raw,cap_net_admin+eip' .venv/bin/python3
+
+# Verify Bluetooth device is up
+hciconfig hci0 up
+```
+
+### MQTT Connection Issues
+```bash
+# Test MQTT connection
+mosquitto_sub -h 10.0.0.114 -u hasse -P casablanca -t "MiTemperature2/#" -v
+
+# Check if broker is accessible
+ping 192.168.0.114  # or your MQTT broker IP
+```
+
+### No Sensor Data
+```bash
+# Check if sensors are in range and broadcasting
+sudo hcitool lescan
+
+# Check logs for specific errors
+python -m sensorpajen.main 2>&1 | tee test.log
+```
+
+### BluePy Installation Issues
+If bluepy fails to install:
+```bash
+sudo apt install -y libglib2.0-dev
+pip install --no-cache-dir bluepy
+```
+
+## Environment Variables Reference
+
+Copy from `config/sensorpajen.env.example` and modify:
+
+```bash
+# Required
+MQTT_HOST=192.168.0.114          # Your MQTT broker IP
+MQTT_USER=hasse                   # MQTT username
+MQTT_PASSWORD=casablanca          # MQTT password
+
+# Optional
+MQTT_PORT=1883                    # Default MQTT port
+MQTT_CLIENT_ID=mibridge          # Client identifier
+MQTT_TOPIC_PREFIX=MiTemperature2 # MQTT topic prefix
+
+# Application settings
+SENSOR_CONFIG_FILE=config/sensors.json  # Sensor config file
+WATCHDOG_TIMEOUT=5                # BLE watchdog timeout (seconds)
+ENABLE_BATTERY=true               # Include battery data
+LOG_LEVEL=INFO                    # DEBUG, INFO, WARNING, ERROR
+```
+
+## Viewing Logs
+```bash
+# While running in terminal, logs go to stdout
+python -m sensorpajen.main
+
+# To save logs to file
+python -m sensorpajen.main 2>&1 | tee sensorpajen.log
+```
+
+## Next Steps
+
+Once testing is successful:
+1. Continue to Phase 4-6 in ROADMAP.md to set up systemd service
+2. Service will run automatically on boot
+3. Logs will be available via `journalctl --user -u sensorpajen`
+
+## Returning to Development Machine
+
+All changes can be committed on the Pi and pushed back:
+```bash
+# On Raspberry Pi
+git add -A
+git commit -m "Your changes"
+git push origin master
+
+# On development machine
+git pull origin master
+```
+
+The development workflow works seamlessly from either machine!