Omni-IO — Open-Source ESP32 io-homecontrol® Gateway

Next-Generation Open-Source 868MHz Gateway for io-homecontrol® Devices

Omni-IO stands on the shoulders of giants. This project is built upon the pioneering research, reverse engineering, and codebase contributions of several key members of the open-source home automation community:

• Velocet — Author of Velocet/iown-homecontrol: The groundbreaking reverse engineering, protocol specifications, CRC algorithms, and AES cryptography implementations for the io-homecontrol® protocol.
• cridp — Author of cridp/iown-homecontrol-esp32sx1276: Hardware adaptation and timing optimizations for the ESP32 and Semtech SX1276 radio transceiver.
• djbenbe — Author of djbenbe/miopen.io: Core firmware development, UI concept, graphics, and initial integration.
• rspaargaren — Community documentation, troubleshooting guides, and io-homecontrol Wiki.

All respective trademarks and copyrights belong to their respective owners.

• 📡 868.95 MHz io-homecontrol® Radio Engine:
  • Native 1-Way (1W) control for shutters, blinds, screens, and Velux/Somfy window openers.
  • 2-Way (2W) protocol frame sniffing, device discovery, and temperature/mode controls for compatible HVAC systems (Atlantic / Sauter / Thermor).
• 🌐 Modern Built-in Web UI:
  • Fully responsive mobile & desktop web interface served directly from LittleFS.
  • Real-time WebSocket connection for instant feedback and live RF traffic log stream.
  • Multi-language support with instant live switching (Dutch, English, German, and French).
  • Live status pills for both MQTT and ESPHome in the navbar with one-click settings navigation.
  • Direct device pairing, unpairing, renaming, and travel-time configuration.
  • Physical remote controller map manager.
• 🚀 Home Assistant ESPHome Native API (Zero-Broker Integration):
  • Direct plug-and-play connection over TCP (port 6053) without requiring an external MQTT broker.
  • Automatic mDNS discovery (_esphomelib._tcp.local.) under Settings → Devices & Services.
  • Dynamic entity discovery & re-enumeration: automatically refreshes entities in Home Assistant when devices are added, renamed, or removed.
  • Native cover entities with smooth position slider and Open/Close/Stop controls (device_class: shutter).
  • Number slider entity for live motor travel time calibration with instant feedback.
  • Button entities for Pairing, Adding, and Removing devices, plus a gateway soft restart button.
  • Gateway diagnostic sensors (WiFi RSSI, Free Memory, IP address).
• 🏠 Home Assistant Auto-Discovery via MQTT:
  • Automatic discovery for cover entities (blinds, screens, shutters).
  • Smooth percentage-based position control with travel time tracking.
  • Dedicated pairing and maintenance button entities.
  • Real-time state reporting (OPEN, CLOSED, OPENING, CLOSING, STOP).
  • Independent runtime toggle to enable/disable MQTT without clearing configuration.
• 🖥️ OLED Display & Advanced Screen Manager:
  • Real-time status display showing device name, WiFi signal, IP / mDNS address, CPU temperature, and status icons for both MQTT and ESPHome.
  • Pixel-art ESPHome status icon indicating connected / waiting Home Assistant sessions.
  • Runtime configurable screensaver timeout, screen-off timeout, and 3 dimming levels (Low, Medium, High).
• 📜 Syslog & Remote Logging:
  • Sends log messages directly to remote Syslog servers (RFC3164 / RFC5424 compliant).
• 💾 Backup & Restore:
  • One-click JSON backup and restore for device configurations and remote mappings.
  • Full backward-compatibility with legacy backup files.
• 🔄 OTA (Over-The-Air) & Partitioning:
  • Built-in OTA updates for both firmware and LittleFS filesystem from the web interface.

Download the latest ready-to-flash binaries from the Releases page:

• Use the merged single-file binary (<Board>.bin) with ESP Web Tools or esptool.py.

1. On first boot, the ESP32 creates a setup Access Point named iohc-setup.
2. Connect to this WiFi network from your phone or PC.
3. The captive portal will open automatically. Select your home WiFi network and enter your password.

Once connected to your network, open your web browser and navigate to: 👉 http://omni-io.local
(or use the device IP address shown on the OLED screen / Serial monitor)

Omni-IO provides two seamless integration paths into Home Assistant:

1. Ensure Omni-IO and your Home Assistant server are on the same local network.
2. In Home Assistant, go to Settings → Devices & Services.
3. Omni-IO will appear automatically as a discovered ESPHome device! Click Configure and Submit.
4. That's it! All configured covers, travel-time configuration sliders, pairing buttons, and diagnostic sensors appear immediately with sub-millisecond local response.

When MQTT is enabled, Omni-IO can also publish standard Home Assistant MQTT discovery topics:

1. In the Web UI, go to Settings → MQTT.
2. Enable MQTT, enter your MQTT Broker IP, port, username, and password.
3. Click Save Settings.
4. Home Assistant will discover the covers via MQTT!

• Command Topic: iown/<ID>/set (OPEN, CLOSE, STOP)
• Position Set Topic: iown/<ID>/position/set (0 to 100)
• State Topic: iown/<ID>/state (OPEN, CLOSED, OPENING, CLOSING, STOP)
• Position Feedback: iown/<ID>/position (0 to 100)
• Availability: iown/status (online / offline)

Comprehensive guides and technical documentation are available in the docs/ directory:

• 🔌 Hardware Setup & Pinouts — Detailed wiring diagrams, pin definitions, antenna sizing, and board comparison.
• 🔄 Pairing & Calibration Guide — Step-by-step motor pairing, travel time measurement, and wall remote mapping.
• 🏠 Home Assistant Integration — Zero-config MQTT discovery, dashboard cards, and automation examples.
• 🌐 REST API & MQTT Reference — Complete API documentation for all REST endpoints, WebSockets, and MQTT topics.
• 🔧 Troubleshooting Guide — Common issues and fixes for WiFi, mDNS, RF range, and OLED screens.
• 💻 Terminal & Serial Commands — Full command reference for the serial console and web terminal.

This tool is designed for educational, testing, and smart-home integration purposes and is provided "as is" without warranty of any kind. The creators and contributors are not responsible for any misuse, damage, or malfunction caused by using this software or hardware.

This repository contains upstream and derivative components licensed under the Apache License 2.0. See LICENSE.

Files explicitly marked with: SPDX-License-Identifier: LicenseRef-CloudAXS-Proprietary are proprietary contributions of CloudAXS and are governed by LICENSE-CLOUDAXS.

The CloudAXS proprietary license applies only to fully original, specifically marked CloudAXS files. It does not restrict any rights granted for upstream or third-party components under Apache-2.0 or their respective licenses.

The Omni-IO logo (extras/web_interface_data/img/logo.svg) and associated branding are exclusive, proprietary assets of CloudAXS. They are NOT licensed under the open-source Apache License 2.0. You may not use, copy, or distribute the logo or product names in derivative works or forks without prior written permission from CloudAXS.

Third-party components, icons, fonts and other assets may have separate terms. No trademark permission is implied.