FHEM

FHEM is a GPL‑licensed, Perl‑based home‑automation server that runs continuously on any 24/7 host—be it a NAS, Raspberry Pi, or small‑form‑factor PC. It exposes a rich set of interfaces (plain TCP/IP, SSL/TCP, HTTP) and speaks dozens of protocols out‑of‑the‑box: CUL, EnOcean, Z‑Wave, ZigBee, MQTT, X10, and many more. The core concept is a device registry that is automatically populated when new hardware reports its data; once a device is known, FHEM can log, schedule, and trigger actions on it. This dynamic discovery eliminates manual configuration for most IoT peripherals.

Architecture & Technical Stack

• Language: Perl 5, leveraging CPAN modules for networking, JSON/XML parsing, and database access.
• Runtime: Requires a standard Perl interpreter; the codebase is fully POSIX‑compatible, making it deployable on Linux, macOS, Windows (via Cygwin), and embedded ARM devices.
• Database: Optional persistence layers include plain text log files, SQLite, MySQL/MariaDB, and PostgreSQL. The schema is lightweight—primarily time‑series tables per device type—and can be swapped at runtime.
• Modularity: The framework loads modules (*.pm files) that implement protocol handlers, device abstractions, and UI components. Over 430 modules exist, each following a simple use/sub convention, making custom extensions straightforward.
• Event Loop: A single‑threaded event loop (FHEM::MainLoop) dispatches I/O events, timers, and inter‑module messages. It is highly efficient for thousands of simultaneous device connections, as the loop merely watches file descriptors and invokes callbacks.

Core Capabilities

• Multi‑protocol Support: Native drivers for Z‑Wave (via zwave.pm), EnOcean, CUL, and many radio protocols.
• APIs: Exposes three text‑based command interfaces (telnet, TCP, HTTP) and higher‑level JSON/XML REST endpoints. These can be consumed by external scripts or web dashboards.
• Event Handling: Users define rules (rule X { ... }) that react to device state changes, time conditions, or external triggers. Rules are evaluated in the same event loop, guaranteeing deterministic timing.
• Logging & Persistence: All device events can be written to files or a database, with optional regex filtering. Historical data is automatically plotted in the built‑in web UI or exported via CSV/JSON.
• Scheduling: The schedule and timed commands enable cron‑style automation (e.g., “turn on lamp at sunset until midnight”).
• Extensibility: New modules can be added by placing a Perl file in the modules/ directory; the system reloads them on the fly. Webhooks and custom HTTP endpoints can be defined in modules to integrate with third‑party services.

Deployment & Infrastructure

• Self‑Hosting: Runs on any machine with Perl and a network interface. Recommended hosts include Raspberry Pi 4, Intel NUCs, or NAS units.
• Scalability: The single‑threaded event loop scales linearly with I/O; a typical deployment can handle hundreds of Z‑Wave devices and thousands of sensor readings without additional threads. For high‑throughput scenarios, multiple FHEM instances can be clustered behind a reverse proxy (NGINX) and share the same database.
• Containerization: Official Docker images exist, simplifying CI/CD pipelines. The container exposes the standard ports (80/443 for HTTP, 4711 for telnet/TCP) and mounts a persistent volume for configuration and logs.
• High Availability: Because the state is persisted in a database, multiple instances can run concurrently; only one instance should accept write traffic to avoid race conditions.

Integration & Extensibility

• Plugin Ecosystem: The module system allows developers to write custom device drivers or UI widgets. Popular community modules include weather APIs, calendar integrations, and media‑control protocols (e.g., UPnP/DLNA).
• Webhooks & Scripts: Rules can trigger external programs via system, exec, or HTTP POST requests, enabling integration with Home Assistant, Node‑RED, or custom microservices.
• Custom Frontends: The built‑in web UI can be overridden by custom HTML/CSS/JS dashboards that consume the JSON API.
• API Hooks: Advanced users can tap into the event dispatcher (FHEM::Event) to create real‑time websockets or push notifications.

Developer Experience

• Configuration: The fhem.cfg file is a plain text script that defines devices, rules, and modules. Perl’s expressive syntax makes it easy to embed logic directly in configuration.
• Documentation: The official Wiki and module documentation are comprehensive, with example snippets for each protocol. Community forums provide rapid support for edge cases.
• Community & Licensing: GPLv2 licensing ensures that any derivative work remains open source. The active mailing list and IRC channel (#fhem on irc.libera.chat) foster rapid knowledge sharing.

Use Cases

1. Home Automation Hub – Central control of Z‑Wave, EnOcean, and MQTT devices with automated scheduling.
2. Energy Monitoring – Log power consumption from smart plugs and feed data into a time‑series database