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.
This commit is contained in:
176
SETUP_ON_PI.md
Normal file
176
SETUP_ON_PI.md
Normal file
@@ -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!
|
||||
Reference in New Issue
Block a user