OpenATV IR Gateway

OpenATV IR Gateway is a local ESP32/M5Stack based infrared gateway for Enigma2 receivers, TVs, AVRs, soundbars and other IR controlled devices.

It provides a browser-based WebIF for sending, learning, importing and exporting IR remote-control profiles. The gateway is designed for local home-network use and does not require a cloud service.

Highlights

• Local IR gateway for Enigma2 and other IR devices
• Web-based remote-control interface
• Learn Wizard for original remote controls
• IR sniffer / analyzer for protocol diagnostics
• Profile, template, layout and bundle import/export
• Visual Layout Editor for custom remote-control layouts
• LittleFS based local storage
• Wi-Fi setup with fallback access point
• mDNS hostname for easy access in the home network
• Browser-based web flasher workflow for end users

Hardware

Recommended hardware:

• M5Stack ATOM Lite ESP32
• M5Stack IR Unit
• USB-C data cable
• USB power supply for permanent operation

Default firmware configuration:

IR sender:   GPIO26
IR receiver: GPIO32
Filesystem:  LittleFS
Flash:       4 MB
OTA:         disabled

The default firmware target is m5stack-atom.

Other ESP32 boards can work, but may require GPIO, wiring and PlatformIO configuration changes.

Supported IR protocols

Currently implemented protocol handling includes:

NEC
RC6
SAMSUNG

Unknown or unsupported remotes can be analyzed with:

/ir/sniff

Web flasher

End users can install the firmware with the browser-based web flasher:

https://webflascher.mynonpublic.com/

The browser flashes the M5Atom locally through USB/WebSerial. The web server only provides the static web page, manifest and firmware file.

First setup

After flashing, the gateway starts a fallback Wi-Fi access point if no Wi-Fi credentials are configured:

SSID:     OpenATV-IR-Gateway
Password: openatv1234
URL:      http://192.168.4.1/

Open the setup page:

http://192.168.4.1/setup

Enter and save your home Wi-Fi credentials.

After the gateway connects to your home network, open:

http://openatv-ir.local/

or use the IP address shown by your router.

The default network hostname is:

openatv-ir-gateway

WebIF endpoints

Useful gateway endpoints:

/                  Remote-control page
/setup             Wi-Fi setup
/status            JSON status
/debug             Debug page
/debug.json        Debug JSON
/profiles          Profile manager
/templates         Template manager
/learn/wizard      Learn Wizard
/layout            Layout editor
/layout/visual     Visual Layout Editor
/bundle/import     Bundle import
/bundle/export     Bundle export
/ir/sniff          IR sniffer / analyzer

Remote-control bundles

A bundle contains the data required to share a complete remote-control profile:

• learned IR codes
• layout
• learn template
• metadata

Bundles can be imported through /bundle/import and exported through /bundle/export.

Storage IDs are intentionally short. The current maximum storage ID length is 15 characters to avoid LittleFS path and temporary filename issues.

Good examples:

vu5
gb_silver
gb_long
dmm_full
dmm_compact
edision
portal_black

Visual Layout Editor

The Visual Layout Editor is available at:

/layout/visual

It provides a grid-based editor for the active profile layout.

Supported layout operations include:

• add key
• key select
• add OK cluster
• add rocker
• add section
• clear layout
• save grid layout
• open JSON layout
• move and resize widgets
• cycle background color
• cycle text color
• cycle shape: standard, round, pill
• edit label, key and class tokens
• remove widget

Build from source

Install PlatformIO and build the firmware:

pio run -e m5stack-atom

Build the LittleFS image:

pio run -e m5stack-atom -t buildfs

Upload firmware with PlatformIO:

pio run -e m5stack-atom -t upload

Upload LittleFS with PlatformIO:

pio run -e m5stack-atom -t uploadfs

The WebIF assets are stored in LittleFS. The visual editor requires the Gridstack files in the project data/ directory:

data/assets/gridstack-all.js
data/assets/gridstack.min.css

Factory binary

The web flasher uses a single factory binary flashed at offset 0x0.

The factory binary contains:

• bootloader
• partition table
• boot_app0
• firmware/app
• LittleFS image

Create a factory binary from the PlatformIO project root:

python3 tools/build_factory_bin_v2.py --version 2.7

Windows example:

py tools\build_factory_bin_v2.py --version 2.7

Documentation

• German user guide
• English user guide
• Visual Layout Editor
• Remote-control bundles
• Web flasher
• Contributing
• Third-party licenses

Contributing

Useful contributions include:

• tested remote-control bundles
• remote-control photos
• IR sniffer JSON outputs
• protocol tests
• layout improvements
• documentation improvements
• bug reports with /debug.json
• hardware range and stability feedback

For IR related issues, include the /ir/sniff output when possible.

For firmware or WebIF issues, include:

firmware version
hardware used
browser/device used
/status output
/debug.json output
steps to reproduce

Security and privacy

OpenATV IR Gateway is designed for local network use.

• no cloud dependency
• no external API required for normal operation
• Wi-Fi credentials are stored locally on the ESP32
• the gateway should not be exposed directly to the public internet

License

OpenATV IR Gateway is released under the GNU General Public License v3.0 or later.

SPDX-License-Identifier: GPL-3.0-or-later

Distributed modified versions must remain open under the same license. Firmware binaries must be distributed together with the corresponding source code.

Third-party assets keep their own licenses. See THIRD_PARTY_LICENSES.md.