Getting started - Optional steps

This guide covers advanced setup procedures, such as running HomeGenie as a system service and granting it access to specific hardware.

Running as a system service

For unattended operation, it is highly recommended to install HomeGenie as a system service. This ensures it starts automatically on boot and runs reliably in the background.

Linux (systemd)

These instructions are for modern Linux distributions that use systemd, such as Raspberry Pi OS, Debian, and Ubuntu.

Creating a dedicated user

Running the service under a dedicated, non-root user is a security best practice.

# Create a new system user named 'homegenie' with its home directory
sudo useradd -r -m -s /bin/false homegenie

# Copy the application files into the new home directory
# Assumes you are in the directory where you extracted the zip
sudo cp -ar ./homegenie/* /home/homegenie/

# Ensure the ownership of all files is correct
sudo chown -R homegenie:homegenie /home/homegenie

Creating the systemd service file

Create a new service definition file at /etc/systemd/system/homegenie.service with the following content:

[Unit]
Description=HomeGenie Automation Server
After=network.target

[Service]
Type=notify
User=homegenie
Group=homegenie
WorkingDirectory=/home/homegenie/
ExecStart=/home/homegenie/HomeGenie
Restart=on-failure
RestartSec=15s

[Install]
WantedBy=multi-user.target

Managing the service

After creating the file, you can manage the service with systemctl:

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

# Enable the service to start automatically on boot
sudo systemctl enable homegenie.service

# Start the service now
sudo systemctl start homegenie.service

Other useful commands include status, stop, and restart.

Windows service

HomeGenie can be installed as a native Windows Service.

Opening a terminal as administrator

You must use a PowerShell or Command Prompt with administrative privileges.

Installing and starting the service

Navigate to the homegenie application directory and run the following commands:

# Install the service
.\HomeGenie.exe --service install

# Start the service
.\HomeGenie.exe --service start

The service will now be listed in the Windows "Services" application and will start automatically on boot. You can manage it from there or using the following commands:

.\HomeGenie.exe --service stop (to stop it)
.\HomeGenie.exe --service uninstall (to remove it)

Hardware access configuration (Linux)

For HomeGenie to interact with physical hardware, you may need to grant the homegenie user the necessary permissions.

Serial port and GPIO access

Add the homegenie user to the dialout and gpio groups. These groups typically control access to serial devices (like Z-Wave/ZigBee dongles) and GPIO pins.

sudo usermod -a -G dialout,gpio homegenie

A system reboot might be required for these group changes to take full effect.

X10 (CM15/CM19) USB controller

Install libusb: This library is required for communication with the device.
```
sudo apt update && sudo apt install libusb-1.0-0
```

Create a udev rule: This rule grants the dialout group permission to access the X10 controller when it's plugged in. Create a new file at /etc/udev/rules.d/98-homegenie.rules with this content:

# Grant access to CM15 and CM19 X10 USB controllers
SUBSYSTEM=="usb", ATTRS{idVendor}=="0bc7", ATTRS{idProduct}=="0001", GROUP="dialout", MODE="0660"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0bc7", ATTRS{idProduct}=="0002", GROUP="dialout", MODE="0660"

Apply the new rules: Reload the udev rules and re-plug your device for the changes to apply.
```
sudo udevadm control --reload-rules && sudo udevadm trigger
```

Audio and voice synthesis

Install the necessary utilities for audio playback and text-to-speech.

sudo apt update
# For audio playback (e.g., playing MP3s)
sudo apt install alsa-utils lame
# For the Pico text-to-speech engine
sudo apt install libttspico-utils

Back to Getting started or continue to Setup page.

forum Q & A discussion forum