Domoticz: a home automation hub that treats Lua scripts and 150 device types as first class

One binary, five operating systems, and a frontend that adapts

Domoticz is described as a free open source home automation system for Linux, Windows, macOS and Raspberry Pi, and the claim that matters most in that sentence is the last platform. A Raspberry Pi is an ARM board with limited memory and no display, which is not where a browser-based interface normally starts. Domoticz's answer is that the user interface is a scalable HTML5 web frontend, automatically adapted for desktop and mobile devices and compatible with all modern browsers. The server renders nothing itself. You point a phone or a laptop at it and the same code serves both.

That single design decision explains most of the repository's shape. Because the interface is web-based, every protocol client is a background concern that reports state upward rather than a window with its own controls. It also means the process is a long-running daemon with a port open, which is where the security material comes in later.

The stated feature list is long but specific enough to be useful. 150+ supported hardware types, naming Z-Wave, Zigbee, MQTT, RFXCOM, P1 Smart Meter, YouLess Meter, Pulse Counters, 1-Wire and Philips Hue. Event scripting with dzVents in Lua and Python plugins. Extended logging. Push notifications for iPhone, Android and desktop. Auto learning for sensors and switches, plus manual creation of switch codes for hardware that cannot report its own identity. Sharing and using external devices is listed too, which is the feature that turns a single-house controller into something usable across a property.

The sensor list in the opening paragraph is broader than lighting. Temperature, rain, wind, UV, energy, gas and water are all named as monitorable, and the repository topics back that up with `energy-monitoring`, `sensors`, `iot` and `smart-home` alongside the protocol names. This is a controller that treats a water meter as a first-class citizen, which is a different emphasis from the voice-assistant-first systems it gets compared with.

The directory listing is the architecture

There is no package manifest, no Python project file and no vendored dependency lockfile at the root. What there is instead is a set of directories that read as a map of the server's responsibilities:

main/
hardware/
dzVents/
plugins/
www/
alexa/
mcpserver/
notifications/
push/
mdns/
iamserver/
httpclient/
smtpclient/
tcpserver/
extern/

`hardware/` is the one that carries the 150+ claim. `main/` is the server itself. `dzVents/` is the event engine, and it has its own top-level documentation file because it is a language surface rather than an implementation detail. `plugins/` is the Python extension point. `www/` is the frontend that the browser loads.

The next group is where the design gets interesting, because each of these is a protocol or a channel that the server speaks outward. `alexa/` suggests voice assistant integration and has a matching `ALEXA.md` at the root. `mcpserver/` is more recent in vocabulary and points at the Model Context Protocol. `notifications/` and `push/` split local alerting from phone push. `mdns/` is multicast DNS discovery, which is how a device on the LAN announces itself without a static address. `iamserver/`, `httpclient/`, `smtpclient/` and `tcpserver/` are the outbound clients and the identity layer.

`extern/` for vendored third-party code and `tinyxpath/` for an XPath engine both suggest a codebase that predates the current Go module ecosystem and has been kept buildable ever since. `CMakeLists.txt`, `build.sh`, `getgit.cmake` and `msbuild/` at the root tell you the same thing from the build side: a CMake project with a shell build path and a Visual Studio path, which is what it takes to ship one codebase to both a Pi and a Windows desktop.

The remaining root entries are operational rather than architectural: `History.txt`, `domoticz.logrotate`, `server_cert.pem`, `ttnmqtt_aliasses.json`, and the three update scripts `updatebeta`, `updatedomo` and `updaterelease`. A checked-in certificate and a logrotate config are a project telling you it expects to run unattended on a small box for years.

dzVents and Python plugins are two different ways to add behaviour

Domoticz offers two scripting paths and the distinction between them is the single most useful thing to understand before configuring an installation, because they run at different layers and fail in different ways.

dzVents is the built-in event engine, written in Lua and shipped inside the repository as a top-level directory. The README lists it as event scripting with dzVents, and it also has its own repository topic. The reason it exists in the main tree rather than as an external package is that it needs a fast path into the server's live device state: a trigger fires, the script reads current values of other devices, and it acts. That kind of thing has to be cheap, because the alternative is polling the database or the HTTP API from an external process and waking on a timer. Lua was a sensible choice for a scripting language embedded in a C++ binary with a small footprint.

Python plugins are the other layer. `plugins/` sits beside `dzVents/` in the tree, and the README names Python plugins alongside dzVents rather than as an extension of it. In practice this is the path for things that need real libraries: talking to an external service, doing arithmetic across many devices, or integrating with something that has a Python client. The cost is a separate runtime and an IPC boundary.

The difference matters when something misbehaves. A dzVents script runs inside the server process and sees device state directly. A Python plugin runs outside it, talks over a socket, and can be restarted without touching the server. Neither is better; they answer different questions, and the README's job is to name both rather than rank them.

Between them they cover the automation cases that a hardware controller cannot do alone, which is why `dzvents` and `scripting` both appear among the repository topics alongside the language names `lua` and `python`.

First run, the setup wizard, and how to provision an account without clicking

On first run Domoticz presents a setup wizard to create the admin account. That is the correct default for a Raspberry Pi with a keyboard and screen, and it is the awkward path for a Docker deployment or an unattended box, which is why the README documents an environment-variable route for it. For Docker deployments you can set `DOMOTICZ_ADMIN_PASSWORD` and optionally `DOMOTICZ_ADMIN_USERNAME` to provision the admin account automatically.

DOMOTICZ_ADMIN_PASSWORD
DOMOTICZ_ADMIN_USERNAME

Two variables, one required and one optional, and the asymmetry is the useful detail. A password with no username means the wizard's account is created under a default name, which is fine for a single-admin home installation and probably wrong for anything shared.

The README's next line points at `SECURITY_SETUP.md` for more information on securing a Domoticz setup, and there is a separate `SECURITY.md` at the root for reporting security issues. That is an unusual and welcome amount of security documentation for a self-hosted project with a web interface, and it signals that the maintainers treat the open web interface as the main risk rather than an afterthought. The checked-in `server_cert.pem` in the tree is the other half of that story: HTTPS is a supported configuration rather than something bolted on by a front-end proxy.

The wizard is also the reason `DOMOTICZ_ADMIN_PASSWORD` appears in the README at all, which is a reminder that these projects accumulate configuration surface from real operational experience rather than from a design document. Anything you deploy behind a reverse proxy should still read `SECURITY_SETUP.md` first, because the environment variables provision the account, they do not configure the exposure of the port.

Where support happens, and where it explicitly does not

The README draws a line in the support section that more self-hosted projects would benefit from copying. The first place for support is the Domoticz Forum, and then it says the GitHub issue tracker is not for end-user support.

That sentence exists because of what the issue tracker is used for instead. Open issues number 26 against roughly 3,800 stars and 1,150 forks, which is a low number for a project this size, and it is low because hardware questions get redirected to the forum while the tracker holds things that reproduce: crashes, protocol client bugs, build failures, documentation errors. The fork count is comparatively high, a ratio that usually means people deploy it and modify it, which fits a product that people run on their own hardware.

The forum, wiki and website are three separate destinations listed at the end of the README: the site at domoticz.com, the forum at forum.domoticz.com, and the wiki at wiki.domoticz.com. Build instructions are on the wiki rather than in the repository, under a page titled Build Domoticz from source. For a CMake project of this size that is sensible, since the build recipe changes more often than the source does, but it does mean the repository alone does not tell you how to build it.

What the repository does contain for developers is a small set of standalone documents: `INSTALL.md`, `ALEXA.md`, `SECURITY.md`, `SECURITY_SETUP.md` and `History.txt`. The donations section sits between the security note and the links, with a PayPal button and a line saying donations will buy hardware, devices, sensors, hosting and coffee. For a project whose maintainers have to buy the sensors its users ask questions about, that is an unusually direct statement of where the money goes.

Build coverage, the development branch, and a release cadence you can plan around

The build status table in the README covers three jobs: a GitHub Actions workflow named `development.yml` for Linux x86_64, a second workflow for Windows x86, and an Appveyor job for Windows. Two build systems for the Windows side and one for Linux, which tracks with the presence of both `CMakeLists.txt` and `msbuild/` in the tree.

development.yml
windows-development-build.yml

The absence of a macOS or ARM build job in that table is worth noting against the claim that the software runs on macOS and Raspberry Pi. It does not mean those targets are unsupported, since the same source builds everywhere and plenty of users deploy on a Pi. It does mean the continuous integration does not prove it on every push, so a Pi-specific regression would reach users before CI noticed.

The default branch is `development`, not `master`, and the workflow filenames agree with that. This is a project where the integration branch is the working branch, so reading the source at the default revision means reading unreleased work. Releases are cut from it on a schedule that is easy to predict from the tag list: `2026.1` on 2026-03-25, `2026.2` on 2026-05-31, and `2026.3` on 2026-08-02. Roughly every two to three months, with the calendar year as the version, and no patch suffix anywhere in the recent history to suggest a hotfix culture.

The project is GPL-3.0 licensed, written in C++, and not archived. There are 20 repository topics, which is the broadest set in this batch and reads like a feature index: `cpp`, `domoticz`, `dzvents`, `energy-monitoring`, `home-automation`, `html5`, `iot`, `linux`, `lua`, `mqtt`, `open-source`, `python`, `raspberry-pi`, `scripting`, `sensors`, `smart-home`, `web-interface`, `windows`, `z-wave` and `zigbee`. The last push was on 2026-09-23, so the branch that becomes the next release is moving.

Editorial conclusion

The directory listing is the honest summary of this project: `hardware/` for device drivers, `dzVents/` for the event engine, `plugins/` for the Python extension point, and `www/` for the interface that sits on top of all of it. Pick the two directories that match the hardware you already own and read those first, because the 150+ device claim lives or dies in `hardware/` rather than in the feature list. The README routes end users to the forum and explicitly rules the GitHub issue tracker out for support, so expect questions to be answered elsewhere than the tracker. Builds are covered for Linux x86_64 and Windows x86 on CI, with a Windows Appveyor job as well. Version 2026.3 is the current release, the default branch is `development` rather than `master`, and the last push was on 2026-09-23.

Frequently asked questions

Official sources

1. domoticz/domoticz on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases