Bentuino ESPHome API — a from-scratch native API library for ESP32 & ESP8266

Bentuino ESPHome API is a from-scratch implementation of the device side of the ESPHome native API — written in portable C++ for the ESP32, ESP32-C3, and ESP8266. It lets your own firmware be discovered and controlled by Home Assistant exactly like a genuine ESPHome node, without pulling in the ESPHome codebase.

⚠️ Disclosure: this is entirely AI-generated code. The full library, firmware, examples, protocol specification, and the Python compliance test bed were generated with AI assistance. It passes the compliance suite described below, but it has not been through extensive production hardening or independent security audit — review it yourself before relying on it.

The repository is live on GitHub:

👉 github.com/knkaiser/BentuinoESPHomeAPI

Why I built it

ESPHome is wonderful to build something quick, but sometimes you need to venture out off the beaten path and require a custom firmware — your own control loop, your own hardware quirks — while still getting the seamless Home Assistant integration that the native API provides over MQTT-free, encrypted, auto-discovered TCP. This project re-implements that protocol cleanly so you can drop it into any PlatformIO/Arduino project.

What's in the box

• A complete C++ server library (lib/ESPHomeAPI) — TCP transport on port 6053, the full Hello/Connect lifecycle, keepalive, access control, and entity state push.
• All 22 standard entity types — sensor, binary_sensor, text_sensor, switch, button, cover, fan, light, number, select, lock, climate, media_player, alarm_control_panel, text, date, time, datetime, valve, update, event, and camera.
• Noise encryption (Noise_NNpsk0_25519_ChaChaPoly_SHA256) and plaintext — the mode is chosen automatically based on whether an encryption key is set.
• A self-contained protobuf codec and crypto stack — vendored TweetNaCl for X25519 plus in-tree SHA-256/HKDF and ChaCha20-Poly1305. No external dependencies; it builds identically on ESP32, ESP8266, and host.
• FNV-1 entity keys, log streaming, time sync, and Home Assistant service calls / state subscriptions.
• 22 ready-to-flash examples — one minimal PlatformIO project per entity type, with mDNS discovery built in.
• A full protocol specification — a README, an implementation guide (Noise handshake, FNV-1 hashing, a worked hex example), and a Native-API-vs-MQTT comparison.
• A Python compliance test bed — runs the conformance suite against a real device or against a host simulator with no hardware at all.

It's small

With Noise encryption enabled, the reference demo fits comfortably:

It's tested

The same server code that runs on the chip is compiled into a host TCP simulator and run over localhost — including the full Noise handshake and encrypted transport.

Using it looks like this

#include "api_server.h"
using namespace esphome_api;

DeviceConfig cfg;
APIServer api(cfg);

Sensor temperature;
Switch  relay;

void setup() {
  temperature.set_object_id("temperature");
  temperature.set_name("Temperature");
  temperature.set_unit_of_measurement("°C");

  relay.set_object_id("relay");
  relay.set_name("Relay");
  relay.on_control = [](bool on) { digitalWrite(RELAY_PIN, on); };

  api.add_sensor(&temperature);
  api.add_switch(&relay);
  api.begin();
}

void loop() {
  api.loop();
  temperature.publish_state(read_temp());   // pushed to Home Assistant
}

Point Home Assistant at the device IP on port 6053 (entering the base64 Noise key if you set one), and your custom board shows up as a first-class ESPHome device.

How it was built

To be fully transparent: every part of this project — the C++ library, the firmware, the examples, the protocol documentation, and the test bed — was written by AI. I directed and reviewed the work, and the result passes the compliance suite above, but treat it as a capable starting point rather than audited production code. Read it, test it, and harden it for your own use case.

Credit and licensing

All credit for the architecture and development of esphome and the API protocol goest to the great team at http://esphome.io.

This project documents and interoperates with the ESPHome native API as implemented by the ESPHome project (AGPL-3.0). For the authoritative, always-current message definitions, refer to the upstream ESPHome source.

Have a look, flash an example, and let me know what you build.