OpenEdge32

An open-source, autonomous and fault-tolerant edge runtime for ESP32.

OpenEdge32 is a reusable C++/PlatformIO runtime for building ESP32 edge applications that must keep operating locally when cloud connectivity is unavailable or degraded.

The project provides reusable runtime services for state, timing, health, configuration, local rules, schedules, connectivity, observability, and signed A/B firmware updates. Application-specific sensors, actuators, displays, GPIO maps, user interfaces, and domain workflows belong outside the Core.

OpenEdge32 starts as a clean public source line with no Git history from its internal development laboratory.

The initial public runtime is derived from a physically validated ESP32 Classic baseline. The public project has its own versioning, governance, release process, signing identity, and contribution history.

• ESP32 Classic / Xtensa
• NodeMCU-32S
• ESP-WROOM-32
• 4 MB flash
• A/B OTA partition layout

Other ESP32 families may build or work, but are not considered supported until they have their own validation evidence. See docs/SUPPORTED_HARDWARE.md.

TaskScheduler  -> when work becomes eligible
FSM            -> state and behavior
EventBus       -> what happened
Component      -> subsystem responsibility and health
Supervisor     -> aggregate health
RuleEngine     -> desired consequence
Driver         -> physical hardware access

Core principles:

• local control remains authoritative;
• cloud/network services manage and observe rather than directly own physical control;
• failures should be isolated to affected components;
• the RuleEngine never accesses GPIO directly;
• critical configuration uses transactional persistence;
• firmware updates are signed and use native A/B rollback semantics;
• lab-only test surfaces are compile-time isolated from the normal build.

The initial Core includes:

• cooperative TaskScheduler + FSM runtime;
• component registry and health model;
• bounded EventBus;
• Supervisor health aggregation;
• Wi-Fi provisioning and recovery;
• MQTT/TLS transport;
• HTTP status surfaces and WebSerial;
• signed A/B OTA with boot validation and rollback;
• transactional NVS configuration;
• local RuleEngine / RuleRuntime;
• persisted delayed actions;
• dependency fault policies:
  • SAFE_OFF
  • SAFE_ON
  • KEEP_LAST_STATE
  • DISABLE_RULE
  • ALARM_ONLY

Machine-readable capabilities and compatibility metadata are in core-manifest.json.

Install PlatformIO, then:

pio run -e esp32-nodemcu-32s

Upload with the serial port appropriate for your machine:

pio run -e esp32-nodemcu-32s -t upload --upload-port <serial-port>

No serial device path is hard-coded into the project.

esp32-nodemcu-32s is the normal build.

esp32-nodemcu-32s-lab enables controlled lab/test surfaces. Lab firmware is intentionally not suitable for untrusted networks.

The initial Core intentionally preserves two known hardening items from the validated development baseline:

• MQTT TLS currently uses encrypted transport without CA certificate validation;
• local HTTP administration surfaces do not yet provide production authentication.

Do not expose the development HTTP surface to untrusted networks. See SECURITY.md and ROADMAP.md.

OpenEdge32 uses Semantic Versioning.

A release exists only as an immutable Git tag such as:

v1.0.0
v1.0.1
v1.1.0

Published release tags are never moved or silently redefined. See RELEASING.md.

Issues, pull requests, hardware validation, documentation improvements, and AI-assisted reviews are welcome.

All commits contributed through pull requests must include a Developer Certificate of Origin sign-off:

Signed-off-by: Your Name <[email protected]>

Use git commit -s to add it automatically.

AI-generated findings and patches are welcome, but they must satisfy the same evidence, review, security, and validation standards as human contributions.

See CONTRIBUTING.md.

Project Maintainer:

Kernel Panic / kernelpanic2015

See GOVERNANCE.md.

Apache License 2.0. See LICENSE.

Copyright 2026 Kernel Panic and OpenEdge32 contributors.