Main Menu

Latest

Unique (most likely human) visitors
274
(since October 2026)

Your first Homylon house on Linux

Homylon runs fine on a small Linux computer: an old PC, a mini PC or a Raspberry Pi. This page takes you from nothing to a working house in one go: the engine, the agents for Hue, CoAP and MQTT, a simple monitor to watch it all happen, and a remote on your phone.

Every step is a command you type in a terminal. Copy them as they are.

What you need

  • A Linux computer on your home network: a PC or mini PC (64-bit), or a Raspberry Pi 2, 3, 4 or 5.
  • One or more of these: a Philips Hue bridge, a CoAP gateway (the kind with a security code on the bottom), or Zigbee or Z-Wave devices through MQTT.
  • A phone or tablet for the remote.

Step 1 - Which download do you need

Every program comes in three versions, one for each kind of machine. Ask your machine:

uname -m
It says Your machine Take the downloads ending in
x86_64 a PC or mini PC linux-intel64
aarch64 a Raspberry Pi 3, 4 or 5 (64-bit) linux-arm64
armv7l a Raspberry Pi 2, or a 32-bit Pi linux-arm32

Not sure? Take one. The install command checks the machine and tells you if it is the wrong one.

Step 2 - Download everything into one folder

Make a folder and go into it:

mkdir ~/homylon
cd ~/homylon

From the Downloads page, put these files in that folder. Always take the newest version; the file names below show it as *. Shown here for a PC (intel64):

  • the engine: homylon-*-linux-intel64.tar.gz
  • the Hue agent: homylonhue-*-linux-intel64.tar.gz
  • the CoAP agent: homyloncoap-*-linux-intel64.tar.gz
  • the MQTT agent: homylonmqtt-*-linux-intel64.tar.gz
  • the simple monitor: first_monitor.py
  • the checksums: SHA256SUMS.txt

You only need the agents for the equipment you have.

Want to be sure nothing went wrong on the way? Check them:

sha256sum -c --ignore-missing SHA256SUMS.txt

Every file should say OK.

Then unpack them all at once:

for f in *.tar.gz; do tar xzf "$f"; done

You now have one folder for every program. Each holds four files: the command you use, the program itself, its settings and a README.

Step 3 - Install the engine

cd ~/homylon/homylon-*-linux-intel64
./homylon install

It asks for your password once. When it offers avahi-utils, say yes: that is how your agents and apps find the engine by themselves.

From now on the command homylon works from any folder.

Step 4 - Your first scene

A fresh engine has no scene yet. Make one in your home folder:

nano ~/FirstHouse.scene

and type (or paste) this:

// FirstHouse - a first Homylon scene
// The lamps and sensors come from your agents (Hue, CoAP, MQTT). They announce
// themselves, so this scene does not need to define them: just use their names.

define home firsthouse latitude 52.09 longitude 5.12

log @"FirstHouse has started"

// Use the name of a motion sensor and a lamp from your Hue app
when motion on "Hallway sensor" then
    light "Hallway lamp" on duration 60
end

Change latitude and longitude to where you live (the engine uses them for sunrise and sunset), and "Hallway sensor" and "Hallway lamp" to names from your own Hue app. Save with ctrl-O, leave with ctrl-X.

Start the engine with it:

homylon start ~/FirstHouse.scene
homylon status

The engine copies your scene into its own scenes folder and starts. Changed your scene? Start it the same way again; the engine asks whether to replace its copy: answer y.

Step 5 - The agents

Each agent is installed the same way: go into its folder and type install. The first time it asks one question about your equipment.

The Hue agent

cd ~/homylon/homylonhue-*-linux-intel64
./homylonhue install

It offers to pair with your Hue bridge: press the round button on top of the bridge, then Enter. Missed it? Type homylonhue pair later.

homylonhue start
homylonhue status

The CoAP agent

cd ~/homylon/homyloncoap-*-linux-intel64
./homyloncoap install

It asks for the 16-character security code printed underneath your gateway. If it does not find the gateway by itself it asks for its address too (your router shows it).

homyloncoap start
homyloncoap status

The MQTT agent

cd ~/homylon/homylonmqtt-*-linux-intel64
./homylonmqtt install

It asks where your MQTT broker is. If the broker runs on this same machine the answer is localhost.

homylonmqtt start
homylonmqtt status

No MQTT broker yet?

The MQTT agent does not talk to Zigbee or Z-Wave devices itself. Two other programs do that, and the agent listens to them:

  • Mosquitto, the broker. On the same machine: sudo apt install mosquitto. The broker is then "localhost", port 1883.
  • Zigbee2MQTT for Zigbee devices, with a Zigbee USB stick (for example a Sonoff Zigbee 3.0 dongle), or Z-Wave JS UI for Z-Wave devices with a Z-Wave USB stick. Both have clear installation guides on their own websites: zigbee2mqtt.io and zwave-js.github.io/zwave-js-ui. Pair your devices there and give them good names: those are the names you use in your scenes.

Every status shows "Engine: found on the network" once the agent has found the engine. Within a second the agent tells the engine what it has: lights, sensors, rooms.

Step 6 - Watch the engine think

The simple monitor shows everything the engine does: every lamp that changes, every sensor, every rule that fires.

cd ~/homylon
python3 first_monitor.py

Switch a lamp in the Hue app or walk past your motion sensor and watch the lines appear. Stop it with ctrl-C.

Step 7 - Start everything when the machine starts

homylon boot on
homylonhue boot on
homyloncoap boot on
homylonmqtt boot on

Only for the agents you installed.

Step 8 - A remote on your phone

Android

On the Remotes page, tap the Android button of Lights and blinds on your phone and open the download. Android asks whether you allow apps from this source: allow it for this one install.

Android cannot find the engine by itself. Open Settings in the app and type the address of your Linux machine. Don't know it? On the Linux machine type hostname -I and take the first address.

iPhone and iPad

The iPhone and iPad remotes come as source code: you build them yourself with Xcode on a Mac and put them on your own iPhone or iPad. Download the iOS sources of Lights and blinds from the Remotes page, unzip them, open the project in Xcode, choose your own Apple ID under Signing and press Run with your device connected. The README in the zip walks you through it.

At home Lights and blinds finds the engine by itself. The pocket remote needs the engine's address in its settings, like Android.

Open the remote: your lamps, rooms and curtains are there. Switch one.

Try it at home first

Do your first test at home, with the phone and the Linux machine on the same home network. That is where everything finds everything by itself.

Finding by itself only works inside one home network. It does not work:

  • from outside, over a VPN
  • when the Linux machine sits on a network of its own (a guest network, a VLAN)

In those cases type the engine's address in the remote's settings (hostname -I on the Linux machine, the first address). The remote keeps it and uses it whenever it cannot find the engine by itself.

The commands in short

Every program has the same commands. For the engine:

homylon start SCENE      start with a scene
homylon status           is it running, with which scene
homylon stop             stop it
homylon restart          stop and start again
homylon log              what it has been doing
homylon settings edit    change its settings (then: homylon restart)
homylon boot on          start it when the machine starts

The agents have the same ones: homylonhue status, homyloncoap log, homylonmqtt restart, and so on.