This chapter describes how Calaos works internally, component by component. It is aimed at developers, contributors and advanced users who want to understand how the pieces fit together, write a client, or port Calaos to new hardware.
Nothing in this chapter is needed to use Calaos. To install and configure your system, see Getting started and Calaos OS.
The whole installation revolves around a single process, calaos_server. It talks to the hardware, applies the rules and exposes an API. Every other component — graphical interfaces, wall screens, mobile applications — is a client of that API, with no direct access to the hardware.
This architecture has one practical consequence: writing a new client requires touching nothing else. The API is the same for everyone, documented by the calaos_server code, and the existing clients are so many examples of it.
| Component | Role | Technology | Repository |
|---|---|---|---|
| Calaos Server | Core of the system: hardware, rules, API | C++ / libuv | calaos_base |
| Calaos Home | Local touchscreen interface | Qt / QML | calaos_mobile |
| Calaos Mobile | iOS and Android applications | Qt / QML | calaos_mobile |
| Remote UI | Standalone wall screens | ESP32-P4 | calaos_remote_ui |
| Calaos WebApp | Browser interface | JavaScript | calaos-web-app |
| Calaos DDNS | Remote access and certificates | Go | calaos_ddns |
| Configuration files | Format and location of the configuration | XML | calaos_base |
On top of these come the components that run the system itself: calaos-container, the daemon managing the containerised services, and calaos-os, the administration tool. They are described in Under the hood and The calaos-os tool.
| Port | Protocol | Use |
|---|---|---|
| 5454 | TCP | JSON API, over HTTP and WebSocket |
| 4545 | UDP | Server discovery on the local network |
| 4646 | UDP | Listening for Wago PLCs |
| 8000 | TCP | calaos-container administration API, on the loopback interface only |
The API port can be changed with the port_api setting.
The API on port 8000 is the one Calaos Home uses to install the system, configure the network and confirm a rollback — see Calaos Home.
Calaos is free software, released under GPL v3 for most of its components. Contributions are welcome: every repository accepts pull requests, and discussions happen on the forum and in GitHub issues.
The core of the system: hardware drivers, rules engine and JSON API.
The local touchscreen interface, and how it drives the system.
The iOS and Android applications, and the base they share with Calaos Home.
The wall screen firmware, and how to port it to new boards.
The interface reachable from a browser.
The dynamic DNS client, certificates and HAProxy routing.
The configuration files: format, location and life cycle.