Skip to content

Linux

Jump to bottom
MrEditor97 edited this page May 8, 2026 · 4 revisions

This guide covers installing Red Reactor as a persistent background service on Ubuntu or any standard Debian-based Linux distribution running on a Raspberry Pi.

Prerequisites

  • A Raspberry Pi with a Red Reactor board attached
  • Ubuntu 22.04+ (or equivalent Debian-based distro) — Python 3.10 or later required
  • An accessible MQTT broker (e.g. Mosquitto running locally or on your Home Assistant instance)
  • Root / sudo access

Step 1 — Enable I2C

Follow the Enabling I2C guide (Standard Linux section), then return here.

Step 2 — Install Python 3.10+

sudo apt update && sudo apt install -y python3 python3-pip python3-venv
python3 --version   # must be 3.10 or later

Step 3 — Create a Dedicated User and Directories

Running as a dedicated user limits the service's permissions:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin redreactor
sudo mkdir -p /var/lib/redreactor /etc/redreactor
sudo chown redreactor:redreactor /var/lib/redreactor /etc/redreactor

Step 4 — Install Red Reactor into a Virtualenv

sudo -u redreactor python3 -m venv /var/lib/redreactor/.venv
sudo -u redreactor /var/lib/redreactor/.venv/bin/pip install redreactor

Step 5 — Configure Red Reactor

sudo curl -fsSL https://raw.githubusercontent.com/mreditor97/redreactor/master/extras/config.yaml \
  -o /etc/redreactor/config.yaml
sudo chown redreactor:redreactor /etc/redreactor/config.yaml
sudo nano /etc/redreactor/config.yaml

See the Configuration guide for a full reference of every option. At minimum, set your MQTT broker details and hostname:

mqtt:
  broker: 192.168.1.100
  port: 1883
  user: your_mqtt_username
  password: your_mqtt_password

hostname:
  name: redreactor-pi     # Used in MQTT topics — must be unique per device
  pretty: Red Reactor Pi

Step 6 — Allow Shutdown and Restart Commands

The service needs permission to call sudo shutdown when instructed via MQTT:

sudo visudo -f /etc/sudoers.d/redreactor

Add:

redreactor ALL=(ALL) NOPASSWD: /sbin/shutdown

Step 7 — Install the systemd Service

sudo curl -fsSL https://raw.githubusercontent.com/mreditor97/redreactor/master/extras/redreactor.service \
  -o /etc/systemd/system/redreactor.service

sudo systemctl daemon-reload
sudo systemctl enable redreactor
sudo systemctl start redreactor

Step 8 — Verify the Service

sudo systemctl status redreactor

Expected output:

● redreactor.service - Red Reactor Service
     Loaded: loaded (/etc/systemd/system/redreactor.service; enabled)
     Active: active (running)

View live logs:

sudo journalctl -u redreactor -f
# or
tail -f /etc/redreactor/redreactor.log

Updating

sudo -u redreactor /var/lib/redreactor/.venv/bin/pip install --upgrade redreactor
sudo systemctl restart redreactor

Troubleshooting

"Unable to connect to the Red Reactor" on startup

  • Run i2cdetect -y 1 and confirm address 0x40 is listed
  • Ensure the Red Reactor board is firmly seated on the GPIO header
  • Verify I2C is enabled — see Enabling I2C

Service fails to connect to MQTT

  • Test the broker: mosquitto_sub -h <broker_ip> -u <user> -P <pass> -t "#" -v
  • Check credentials in /etc/redreactor/config.yaml
  • If exit_on_fail: true, the service exits on failure — check journalctl -u redreactor

Permission denied on shutdown

  • Verify: sudo -u redreactor sudo shutdown --help should not prompt for a password

If you have problems, create an issue on the GitHub repository.

Clone this wiki locally