sensorpajen/debian

Debian Package Build Guide

This directory contains the Debian packaging files for sensorpajen, a Bluetooth temperature sensor monitor for Raspberry Pi.

Overview

The Debian package installs sensorpajen as a system-wide service with:

• Installation to /opt/sensorpajen/
• Configuration in /etc/sensorpajen/
• Dedicated sensorpajen system user
• Systemd service integration
• Automatic Python virtual environment setup
• Bluetooth capability configuration

Prerequisites

Required Packages

sudo apt install \
    debhelper \
    dpkg-dev \
    python3 \
    python3-venv \
    python3-pip

Optional (for verification)

sudo apt install lintian

Quick Start

Automated Build and Verification

# From project root
./scripts/verify-deb.sh

This script will:

1. Check for required tools
2. Build the package
3. Show package contents
4. Run lintian checks
5. Display installation instructions

Manual Build

# From project root
dpkg-buildpackage -us -uc -b

The .deb file will be created in the parent directory:

ls -lh ../sensorpajen_*.deb

Build Output

../sensorpajen_2.0.0-dev_all.deb     # Installable package
../sensorpajen_2.0.0-dev_armhf.build      # Build log
../sensorpajen_2.0.0-dev_armhf.buildinfo  # Build metadata
../sensorpajen_2.0.0-dev_armhf.changes    # Changes file

Package Verification

Check Package Contents

dpkg-deb -c ../sensorpajen_*.deb

Check Package Metadata

dpkg-deb -I ../sensorpajen_*.deb

Run Lintian

lintian ../sensorpajen_*.deb

Note: Warnings are acceptable. Focus on fixing errors.

Installation

On Raspberry Pi

# Copy package to Pi
scp ../sensorpajen_*.deb pi@raspberrypi:~/

# SSH to Pi and install
ssh pi@raspberrypi
sudo apt install ./sensorpajen_*.deb

Local Testing (Not Recommended)

Installing on your development machine will modify /opt and /etc:

sudo apt install ../sensorpajen_*.deb

Warning: This will create system directories and a system user on your dev machine.

Post-Installation Configuration

After installing the package:

# 1. Edit MQTT credentials
sudo nano /etc/sensorpajen/sensorpajen.env

# 2. Configure sensors
sudo nano /etc/sensorpajen/sensors.json

# 3. Start the service
sudo systemctl start sensorpajen

# 4. Check status
sudo systemctl status sensorpajen

# 5. View logs
sudo journalctl -u sensorpajen -f

Package Structure

Installed Files

Source	Destination
src/sensorpajen/*.py	/opt/sensorpajen/src/sensorpajen/
scripts/approve-sensors.sh	/opt/sensorpajen/scripts/
pyproject.toml	/opt/sensorpajen/
README.md, INSTALL.md, ROADMAP.md	/usr/share/doc/sensorpajen/
config/*.example	/usr/share/doc/sensorpajen/examples/
debian/sensorpajen.service	/etc/systemd/system/
(created in postinst)	/opt/sensorpajen/venv/
(created in postinst)	/etc/sensorpajen/

Configuration Files

• Active Config: /etc/sensorpajen/sensorpajen.env (credentials)
• Active Config: /etc/sensorpajen/sensors.json (sensor list)
• Discovery Data: /etc/sensorpajen/discovered_sensors.json
• Examples: /usr/share/doc/sensorpajen/examples/*.example

Maintainer Scripts

postinst (Post-Installation)

Runs after package installation:

1. Creates sensorpajen system user (if doesn't exist)
2. Creates /etc/sensorpajen/ directory
3. Copies example configs to /etc/sensorpajen/ (if missing)
4. Creates Python virtual environment in /opt/sensorpajen/venv/
5. Installs Python dependencies via pip
6. Sets Bluetooth capabilities on Python executable
7. Installs systemd service file
8. Enables service (but doesn't start until configured)

prerm (Pre-Removal)

Runs before package removal:

1. Stops the sensorpajen service
2. Disables the service (on remove, not upgrade)

postrm (Post-Removal)

Runs after package removal:

1. Removes systemd service file
2. Reloads systemd daemon
3. Preserves configuration in /etc/sensorpajen/
4. Preserves sensorpajen user

Note: Configuration and user are intentionally preserved to prevent data loss.

Upgrade Behavior

When upgrading to a new version:

sudo apt install ./sensorpajen_2.1.0_all.deb

• ✅ Service is stopped during upgrade
• ✅ Old files are replaced
• ✅ Configuration in /etc/sensorpajen/ is preserved
• ✅ Python dependencies are updated
• ✅ Service is restarted after upgrade
• ✅ Example files in /usr/share/doc/ are updated

Removal Behavior

Remove (Keep Config)

sudo apt remove sensorpajen

• Service stopped and disabled
• Application files removed from /opt/sensorpajen/
• Configuration preserved in /etc/sensorpajen/
• User preserved

Purge (Still Keeps Config)

sudo apt purge sensorpajen

• Same as remove
• Configuration still preserved (by design, for safety)
• User still preserved

Complete Removal

To completely remove everything:

sudo apt purge sensorpajen
sudo rm -rf /etc/sensorpajen
sudo userdel sensorpajen

Troubleshooting

Build Fails: "debhelper: command not found"

sudo apt install debhelper

Build Fails: "dh_python3: command not found"

sudo apt install dh-python

Lintian Warnings About Permissions

The postinst script runs as root and sets file permissions. This is expected and safe.

Package Won't Install: Dependency Issues

# Fix missing dependencies
sudo apt install -f

Service Won't Start After Install

Check if configuration has been edited:

sudo journalctl -u sensorpajen -n 50

Common issues:

• MQTT_HOST still has example value
• sensors.json is empty
• Bluetooth adapter not available

Bluetooth Capability Not Set

# Manually set capability
sudo setcap cap_net_raw,cap_net_admin+eip $(readlink -f /opt/sensorpajen/venv/bin/python3)

# Verify
getcap $(readlink -f /opt/sensorpajen/venv/bin/python3)

Development Workflow

Making Changes

1. Edit source code in src/sensorpajen/
2. Update version in pyproject.toml
3. Update debian/changelog with new entry
4. Rebuild package: ./scripts/verify-deb.sh
5. Test on Raspberry Pi

Version Numbering

• Development: 2.0.0-dev
• Release: 2.0.0
• Patch: 2.0.1

Update in both:

• pyproject.toml (line 6: version = "...")
• debian/changelog (first line)

Testing on Pi

# Build
./scripts/verify-deb.sh

# Copy to Pi
scp ../sensorpajen_*.deb pi@raspberrypi:~/

# Install on Pi
ssh pi@raspberrypi
sudo systemctl stop sensorpajen  # If upgrading
sudo apt install ./sensorpajen_*.deb
sudo systemctl status sensorpajen

Package Metadata

Package Name: sensorpajen
Section: misc
Priority: optional
Architecture: all (pure Python)
Maintainer: Fredrik fredrik@wahlberg.se
Depends: python3 (>= 3.9), python3-venv, python3-pip, bluetooth, bluez, libcap2-bin
Recommends: mosquitto-clients

Additional Resources

• TASKS.md: Detailed implementation notes
• ROADMAP.md: Phase 8 section for APT package creation
• INSTALL.md: User installation guide
• systemd/README.md: Service management guide

Support

For issues or questions:

1. Check sudo journalctl -u sensorpajen -n 100
2. Verify configuration files in /etc/sensorpajen/
3. Check Bluetooth adapter: hciconfig
4. Test MQTT connection: mosquitto_pub -h <host> -t test -m "test"

---

Last Updated: December 27, 2025
Package Version: 2.0.0-dev