sensorpajen/systemd/README.md

# Systemd Service Installation

## Installing Sensorpajen as a User Service

This allows sensorpajen to run automatically on boot as your user (no sudo required for management).

### Installation Steps

#### 1. Install the Service File

```bash
cd ~/sensorpajen

# Create user systemd directory if it doesn't exist
mkdir -p ~/.config/systemd/user/

# Copy service file
cp systemd/sensorpajen.service ~/.config/systemd/user/

# Reload systemd to recognize the new service
systemctl --user daemon-reload
```

#### 2. Enable Lingering (Run Without Login)

This allows your user services to run even when you're not logged in:

```bash
# Enable lingering for your user
sudo loginctl enable-linger $USER

# Verify it's enabled
loginctl show-user $USER | grep Linger
# Should show: Linger=yes
```

#### 3. Start and Enable the Service

```bash
# Start the service now
systemctl --user start sensorpajen

# Enable it to start on boot
systemctl --user enable sensorpajen

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

### Service Management Commands

```bash
# Start the service
systemctl --user start sensorpajen

# Stop the service
systemctl --user stop sensorpajen

# Restart the service
systemctl --user restart sensorpajen

# Check status
systemctl --user status sensorpajen

# View logs (all)
journalctl --user -u sensorpajen

# View logs (follow/tail)
journalctl --user -u sensorpajen -f

# View logs (last 100 lines)
journalctl --user -u sensorpajen -n 100

# View logs (since specific time)
journalctl --user -u sensorpajen --since "1 hour ago"
journalctl --user -u sensorpajen --since "2025-12-27 10:00"

# Enable service (start on boot)
systemctl --user enable sensorpajen

# Disable service (don't start on boot)
systemctl --user disable sensorpajen
```

### Viewing Logs

The service logs to systemd journal. View them with:

```bash
# Live view (like tail -f)
journalctl --user -u sensorpajen -f

# With timestamps
journalctl --user -u sensorpajen -f -o short-iso

# Just today's logs
journalctl --user -u sensorpajen --since today
```

### Updating the Service

After making changes to the code:

```bash
# Pull latest changes
cd ~/sensorpajen
git pull origin master

# Restart the service to apply changes
systemctl --user restart sensorpajen

# Check it started correctly
systemctl --user status sensorpajen
```

After editing `sensorpajen.service`:

```bash
# Copy updated service file
cp systemd/sensorpajen.service ~/.config/systemd/user/

# Reload systemd configuration
systemctl --user daemon-reload

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

After editing configuration files:

```bash
# Edit config
nano ~/sensorpajen/config/sensorpajen.env
# or
nano ~/sensorpajen/config/sensors.json

# Restart service to reload config
systemctl --user restart sensorpajen
```

### Troubleshooting
### Permission Denied Errors

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

```bash
# Verify Bluetooth capabilities are set on Python binary
getcap ~/.local/share/virtualenvs/*/bin/python3.*

# If not set, apply capabilities (adjust path to your venv):
sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f ~/sensorpajen/.venv/bin/python3)

# Verify it was set:
getcap $(readlink -f ~/sensorpajen/.venv/bin/python3)
# Should show: cap_net_admin,cap_net_raw+eip

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

**Important**: Capabilities must be set on the **actual Python binary**, not symlinks. Use `readlink -f` to resolve the real path.
#### Service Won't Start

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

# Check logs for errors
journalctl --user -u sensorpajen -n 50

# Test the command manually
cd ~/sensorpajen
source .venv/bin/activate
export $(cat config/sensorpajen.env | grep -v '^#' | xargs)
python -m sensorpajen.main
```

#### Bluetooth Permission Errors

Make sure capabilities are set on the Python binary:

```bash
getcap $(readlink -f ~/.venv/bin/python3)
# Should show: cap_net_raw,cap_net_admin+eip

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

#### Service Doesn't Start on Boot

```bash
# Check if service is enabled
systemctl --user is-enabled sensorpajen
# Should show: enabled

# Check if lingering is enabled
loginctl show-user $USER | grep Linger
# Should show: Linger=yes

# If not enabled:
systemctl --user enable sensorpajen
sudo loginctl enable-linger $USER
```

#### Environment Variables Not Loading

```bash
# Verify environment file exists and is readable
cat ~/sensorpajen/config/sensorpajen.env

# Check file permissions
ls -la ~/sensorpajen/config/sensorpajen.env

# Test loading manually
export $(cat ~/sensorpajen/config/sensorpajen.env | grep -v '^#' | xargs)
env | grep MQTT
```

### Verifying Everything Works

After installation:

```bash
# 1. Check service is running
systemctl --user status sensorpajen

# 2. Check logs show sensor data
journalctl --user -u sensorpajen -f

# 3. Check MQTT messages are being published
mosquitto_sub -h 192.168.0.114 -u hasse -P casablanca -t "MiTemperature2/#" -v

# 4. Reboot and verify it starts automatically
sudo reboot
# After reboot:
systemctl --user status sensorpajen
```

### Uninstalling the Service

If you need to remove the service:

```bash
# Stop and disable
systemctl --user stop sensorpajen
systemctl --user disable sensorpajen

# Remove service file
rm ~/.config/systemd/user/sensorpajen.service

# Reload systemd
systemctl --user daemon-reload

# Optionally disable lingering
sudo loginctl disable-linger $USER
```

## Notes

- **User Service**: Runs as your user, not root - more secure and easier to manage
- **Lingering**: Required for services to run when not logged in
- **Logs**: All output goes to systemd journal (journalctl)
- **Auto-restart**: Service restarts automatically on crashes
- **Environment**: Config loaded from `config/sensorpajen.env`
- **Working Directory**: Service runs from `~/sensorpajen`

## Next Steps

Once the service is working:
1. Monitor for a few days to ensure stability
2. Check logs occasionally: `journalctl --user -u sensorpajen --since yesterday`
3. Service will survive reboots and automatically restart on failures