- Bump version to 3.0.0 and update docs
- Fix Debian payload to include TUI and install /usr/bin/sensorpajen-tui wrapper
- Make systemd unit upgrades safer and ignore deb build artifacts
Version bump:
- Update VERSION to 2.0.0 (from 2.0.0-dev)
- Update pyproject.toml to 2.0.0
- Change development status to Production/Stable
Documentation updates:
- Add Debian package installation instructions (system-wide)
- Add sensor discovery and approval workflow documentation
- Update configuration section with approval workflow
- Update service management for system installation
- Update troubleshooting for system installation
- Update MQTT settings documentation
- Add links to download Debian packages from releases
The application is now production-ready with:
- Systemd integration for automatic service management
- Automatic startup and restart on failure
- Configuration via /etc/sensorpajen/
- Runtime state in /var/lib/sensorpajen/
- Interactive sensor approval workflow
- Automatic configuration reload
- Comprehensive logging via journalctl
Remove stale .pyc files and __pycache__ directories before installing
the sensorpajen package to ensure Python rebuilds bytecode fresh.
This should prevent cached bytecode issues from old syntax errors.
Changes:
- approve_sensor: Add explicit logging that sensor was marked as approved
- ignore_sensor: Add explicit logging that sensor was marked in discovered_sensors.json
- Both now clearly indicate the sensor status is updated, not just added/ignored
This makes it clear to users that approved sensors will no longer appear as
pending in future runs, since their status in discovered_sensors.json is
changed from 'pending' to 'approved' or 'ignored'.
The service was failing with 'Read-only file system' when trying to create
discovered_sensors.json in the /etc/sensorpajen config directory.
Changes:
- config.py: Add STATE_DIR for runtime state
- System mode: /var/lib/sensorpajen (writable at runtime)
- Dev mode: config/ (same as config directory)
- config.py: Use STATE_DIR for discovered_sensors.json path
- debian/postinst: Create and own /var/lib/sensorpajen
- debian/sensorpajen.service: Add /var/lib/sensorpajen to ReadWritePaths
- debian/postinst: Remove discovered_sensors.json.example copy (created at runtime)
This separates:
- Config: /etc/sensorpajen (static, not updated by service)
- State: /var/lib/sensorpajen (dynamic, updated by service at runtime)
The venv had dependencies installed but not the sensorpajen package itself,
causing 'No module named sensorpajen' errors when running.
Changes:
- After installing dependencies from requirements.txt
- Now also runs 'pip install --no-deps .' to install sensorpajen
- Uses --no-deps to avoid re-installing already-installed dependencies
- Installed in /opt/sensorpajen where pyproject.toml exists
Fixes: ModuleNotFoundError: No module named 'sensorpajen'
- config.SensorConfig.load() now warns instead of raising FileNotFoundError
if sensors.json doesn't exist
- main.py no longer exits if len(sensors) == 0
- Instead, warns user and suggests using 'sensorpajen approve-sensors'
- Application will now start in discovery-only mode
- This allows users to use the discovery workflow to add sensors
Changes:
- config.py: Handle missing sensors.json gracefully
- main.py: Log warning instead of error when no sensors configured
and continue running (allows discovery to work)
Fixes: Unable to start application for initial sensor discovery
- Add comments explaining absolute vs relative paths
- Clarify usage for system vs development installations
- Make it clear that SENSOR_CONFIG_FILE/DISCOVERED_SENSORS_FILE
should use /etc/sensorpajen paths in system installations
- Remove misleading comment about 'relative to project root'
The code imports 'bluetooth._bluetooth' which requires the PyBluez package
(not bluepy). PyBluez provides Classic Bluetooth support needed by utils.py
and sensor_reader.py.
- Add pybluez>=0.31 to both requirements.txt and pyproject.toml
- Keep bluepy and paho-mqtt as they are also needed
- bluez system package also needed (already in debian/control)
Fixes: ModuleNotFoundError: No module named 'bluetooth'
- Move chown -R before setcap to preserve Bluetooth capabilities
- setcap must be applied after ownership is set, not before
- Ensures Python executable has proper Bluetooth permissions for venv
- Add requirements.txt to debian/install
- Update postinst to use requirements.txt for pip install
- Install from requirements.txt instead of -e . (editable install)
- Ensures bluepy and paho-mqtt are installed in venv
- Fixes 'ModuleNotFoundError: No module named bluetooth' on startup
- Add override_dh_builddeb with -Zgzip flag
- Ensures package uses gzip instead of zstd compression
- Provides better compatibility with older dpkg versions
- Package now installs successfully on all systems
- Remove debian/compat file (conflicts with Build-Depends)
- Fix debian/install to use correct readme.md filename
- Update verify-deb.sh to mark debian/compat as optional
- Add -Zgzip flag to dpkg-buildpackage for compatibility
(uses gzip instead of zstd for better compatibility)
- Update verify-deb.sh to check optional vs required files
Package now builds and installs successfully on systems
without zstd support.
- Create debian/ directory structure with all required files:
- control: Package metadata and dependencies
- compat: Debhelper compatibility level
- changelog: Version history
- rules: Build instructions
- install: File installation mappings
- postinst: Post-installation setup (user, venv, setcap)
- prerm: Pre-removal script (stop service)
- postrm: Post-removal script (cleanup, preserve config)
- sensorpajen.service: System-wide systemd unit
- Update config.py to support dual-mode operation:
- Auto-detects system installation (/opt/sensorpajen)
- Uses /etc/sensorpajen for config in system mode
- Falls back to PROJECT_ROOT/config for development
- Update scripts/approve-sensors.sh for system paths:
- Detects system vs development installation
- Uses correct venv and config paths
- Create scripts/verify-deb.sh: Automated build and verification
- Create debian/README.md: Comprehensive packaging documentation
Package features:
- System-wide installation to /opt/sensorpajen/
- Configuration in /etc/sensorpajen/ (preserved on upgrade/remove)
- Dedicated sensorpajen system user
- Automatic venv creation with dependencies
- Bluetooth capabilities set automatically
- Service auto-enabled but waits for config before starting
- Dual-mode code supports both system and development installations
Completed:
- Created INSTALL.md with concise sysadmin-focused guide
- Updated README.md troubleshooting to reference INSTALL.md
- Marked ROADMAP Phase 9 complete
Documentation Philosophy:
- Compact and practical
- Assumes sysadmin familiarity
- Focus on actual usage, not theory
All 9 phases of migration now complete!
Changes:
- Added 'reviewed' field to DiscoveredSensor dataclass
- By default, only show new (unreviewed) pending sensors
- Mark sensors as reviewed when shown in approval CLI
- Add --all flag to show all pending sensors (including reviewed)
- Add --ignored flag to show ignored sensors
- Prevent repeatedly asking for approval of same sensor
Usage:
approve-sensors # Only new sensors
approve-sensors --all # All pending sensors
approve-sensors --ignored # Ignored sensors
approve-sensors --all --ignored # Everything
Clarifications added:
- Storage: config/discovered_sensors.json with extended metadata
- ntfy: Optional notifications via curl with token auth
- CLI: sensorpajen approve-sensors (interactive only)
- Config reload: Every 15 minutes, no service restart needed
- Metadata: MAC, name, RSSI, timestamps, sample readings
- Ignored sensors: Stored with timestamp and optional reason
- Pre-filled comments with metadata for user to edit
Key discoveries during systemd service implementation:
- AmbientCapabilities doesn't work in user services
- NoNewPrivileges prevents file capabilities
- Must use setcap with readlink -f on actual binary
NoNewPrivileges=true prevents file capabilities from working.
Since we need CAP_NET_RAW/CAP_NET_ADMIN for Bluetooth, we must
disable this security feature.
- Created systemd/sensorpajen.service user service unit
- Uses %h for portability across systems
- Loads environment from EnvironmentFile
- Auto-restart with bluetooth capabilities
- Comprehensive security settings
- Created systemd/README.md
- Installation instructions
- Service management commands
- Troubleshooting guide
- Log viewing examples
- Updated ROADMAP.md to mark Phase 6 complete
Handle both paho-mqtt v1.x and v2.x in MQTTPublisher:
- Try v2.x format with callback_api_version first
- Fall back to v1.x format if needed
- Ensures compatibility across different paho-mqtt versions
Fixes: ValueError when using paho-mqtt 2.0+
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.
Core modules created:
- config.py: Environment-based configuration management
- Loads MQTT settings from environment variables
- SensorConfig class for JSON sensor mapping
- Relative path resolution (PROJECT_ROOT)
- Configuration validation with fail-fast
- mqtt_publisher.py: MQTT client wrapper
- MQTTPublisher class with connection management
- Replaces sendToMQTT.sh shell script
- Direct Python MQTT publishing
- Automatic reconnection support
- Optional battery data publishing
- sensor_reader.py: Bluetooth BLE sensor reader
- SensorReader class for passive BLE scanning
- ATC firmware packet parsing
- Duplicate packet filtering via advertisement counter
- Watchdog thread for BLE recovery
- Measurement dataclass for type safety
- utils.py: Bluetooth utilities
- Ported from bluetooth_utils.py (MIT, Colin GUYON)
- BLE scanning and advertisement parsing functions
- Linux HCI socket operations
- main.py: Application entry point
- Sensorpajen main application class
- Signal handling (SIGTERM/SIGINT) for graceful shutdown
- Logging to stdout for journald integration
- Coordinates all components
Architecture:
- Direct Python integration (no shell scripts)
- Clean separation of concerns
- Type hints and dataclasses
- Comprehensive logging
- Graceful shutdown handling
Updated ROADMAP.md to mark Phase 2 as complete.
Next: Phase 3 - Configuration Migration (mostly done in Phase 1)
Directory structure:
- Created src/sensorpajen/ for new Python package
- Created config/ for configuration templates
- Created legacy/ for old scripts
- Created systemd/ and debian/ for future phases
Package setup:
- Added pyproject.toml with modern Python packaging
- Created package __init__.py
- Defined dependencies: bluepy, paho-mqtt
Configuration:
- Created config/sensors.json.example (converted from INI)
- Created config/sensorpajen.env.example for environment variables
- All 8 Xiaomi sensors migrated to JSON format
Cleanup:
- Removed temperatur_koksfonstret.py (DHT11 functionality)
- Moved all legacy scripts to legacy/ folder:
- LYWSD03MMC.py
- bluetooth_utils.py
- sendToMQTT.sh
- sensorer.sh
- startup.sh
- sensorer.ini
Updated ROADMAP.md to mark Phase 1 as complete.
Next: Phase 2 - Python Package Structure
Starting modernization phase:
- Transition to systemd service
- Modern Python package structure
- Relative configuration paths
- APT package support
See ROADMAP.md for complete implementation plan.
- AGENTS.md: Guidelines for AI agents working on this project
- ROADMAP.md: Complete migration plan from tmux/cron to systemd
- Configuration strategy using relative paths
- APT package creation plan (Phase 8)
- Progress tracking instructions
