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 ~/homylonFrom 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.txtEvery file should say OK.
Then unpack them all at once:
for f in *.tar.gz; do tar xzf "$f"; doneYou 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 installIt 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.sceneand 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
endChange 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 statusThe 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 installIt 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 statusThe CoAP agent
cd ~/homylon/homyloncoap-*-linux-intel64
./homyloncoap installIt 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 statusThe MQTT agent
cd ~/homylon/homylonmqtt-*-linux-intel64
./homylonmqtt installIt asks where your MQTT broker is. If the broker runs on this same machine the answer is localhost.
homylonmqtt start
homylonmqtt statusNo 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.pySwitch 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 onOnly 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 startsThe agents have the same ones: homylonhue status, homyloncoap log, homylonmqtt restart, and so on.
Sunrise and sunset move by more than four hours through the year. A clock time for the curtains is wrong most of the year, and changing it every few weeks is the kind of chore a house should do itself. The Engine calculates sunrise and sunset every day from the latitude and longitude of the home, so this scene never needs a clock time changed.
A sun time can be moved by minutes: sunset - 30 is half an hour before sunset, sunrise + 30 half an hour after sunrise. The lamps come from the Hue agent and the curtains from the Matter agent, and both announce themselves. The holiday variable is the same one the front door example uses, switched from Emma's phone.
Mark cannot hear the doorbell, Sophie can. Sometimes they are both at home, sometimes one of them is out, and sometimes the whole family is on holiday. A doorbell that does the same thing every time is no good to anybody here. This scene lets the house decide, every time somebody comes to the front door, who needs to know and how.
It knows who is home because Mark and Sophie each have a switch "athome" on the remote on their phone, and Emma has the holiday switch. The motion sensor by the door and the lamps come from the Hue agent, the sound from the Sound agent; both announce themselves, so the scene does not have to define them.
Suppose you have a P1 interface connected to your Smart Power Meter in your home and you have written a simple Python script to read it and send messages to the Engine when the average consumption changed in the last minute. You also have a HUE bulb and light strip you use as signal for various event in your home like motion at the front door, time to take your medicine and power consumption of your home.
This script stored in your system folder of your myhome.homylon package could set the tresholds you want to be noticed about.