espectre_protocol.h File Reference

Wire types and payload builders for the ESPectre Protocol. More...

#include <cstddef>
#include <cstdint>
#include <string>
#include "runtime_snapshot.h"

Go to the source code of this file.

Classes
struct	espectre::EspectreDeviceConfig
	Device identity and broker settings. More...
struct	espectre::EspectreNetworkInfo
	Link details available to frontends. More...
struct	espectre::EspectreDeviceInfo
	What the device advertises about itself. More...
struct	espectre::EspectreCommand
	A parsed control command. More...
struct	espectre::EspectreOtaStatus
	Full OTA status: state, the versions involved, and the resolved URLs. More...

Namespaces
namespace	espectre

Enumerations
enum class	espectre::EspectreOtaState : uint8_t {   espectre::IDLE = 0 , espectre::CHECKING , espectre::UPDATE_AVAILABLE , espectre::UP_TO_DATE ,   espectre::DOWNLOADING , espectre::APPLYING , espectre::REBOOT_SCHEDULED , espectre::ERROR }
	OTA progress, as reported to clients. More...

Functions
Device identity
Resolve, format, and parse the identity a device presents on the wire.
std::string	espectre::format_espectre_device_id (uint64_t device_id)
	Format a device id in its canonical wire form.
bool	espectre::parse_espectre_device_id (const std::string &value, uint64_t *device_id)
	Parse a device id from its wire form.
uint64_t	espectre::espectre_device_id_from_mac (const uint8_t *mac, size_t mac_len)
	Pack the first six MAC bytes into the historical numeric representation.
std::string	espectre::espectre_device_name (uint64_t device_id, const char *chip=nullptr)
	Conventional device name derived from the immutable device identifier.
uint64_t	espectre::espectre_effective_device_id_u64 (const EspectreDeviceConfig &config)
	The id actually in use.
std::string	espectre::espectre_effective_device_id (const EspectreDeviceConfig &config)
	espectre_effective_device_id_u64() in wire form.
std::string	espectre::espectre_effective_device_label (const EspectreDeviceConfig &config)
	The configured label, or the effective device id when no label is set.
EspectreDeviceInfo	espectre::normalize_protocol_device_info (const EspectreDeviceInfo &info, const RuntimeSnapshot *snapshot, bool supports_ota, const char *default_frontend, const char *default_chip=nullptr)
	Fill in the parts of a device info block the frontend did not set.
void	espectre::clear_espectre_mqtt_config (EspectreDeviceConfig *config)
	Erase broker settings while preserving identity, for a config reset.
Topics and payloads
Build the wire representation from runtime state. Each returns a complete payload ready to hand to a transport.
std::string	espectre::espectre_topic (const EspectreDeviceConfig &config, const char *suffix)
	Build a full topic from this device's prefix and a trailing segment.
std::string	espectre::espectre_status_payload (const EspectreDeviceConfig &config, bool online, uint32_t timestamp_ms)
	Availability payload.
std::string	espectre::espectre_info_payload (const EspectreDeviceConfig &config, const EspectreDeviceInfo &info)
	Device description, supported controls, and optional CSI traffic settings.
std::string	espectre::espectre_commands_payload (const EspectreDeviceConfig &config, const EspectreDeviceInfo &info)
	MQTT command catalog for the current frontend.
std::string	espectre::espectre_telemetry_payload (const EspectreDeviceConfig &config, const RuntimeSnapshot &snapshot, uint32_t timestamp_ms, uint32_t uptime_s, const char *frontend)
	Motion state, metric, and threshold.
std::string	espectre::espectre_stats_payload (const EspectreDeviceConfig &config, const RuntimeSnapshot &snapshot, uint32_t timestamp_ms, uint32_t uptime_s, float free_memory_kb, float loop_time_ms, const RuntimeDiagnosticsSample *diagnostics=nullptr)
	Health counters plus optional rate and link diagnostics.
std::string	espectre::espectre_command_result_payload (const EspectreDeviceConfig &config, const EspectreCommand &command, bool accepted, const char *message)
	Acknowledge a command, echoing its command_id.
std::string	espectre::espectre_ota_status_payload (const EspectreDeviceConfig &config, const EspectreOtaStatus &status, uint32_t timestamp_ms)
	OTA progress payload, for each IOtaService status callback worth publishing.
Command parsing
Turn received bytes into validated values.
bool	espectre::parse_espectre_command (const std::string &payload, EspectreCommand *command, std::string *error)
	Parse a JSON command payload from the MQTT command topic.
bool	espectre::parse_espectre_command_request (const std::string &command_id, const std::string &command_name, const std::string &params_json, EspectreCommand *command, std::string *error)
	Parse a transport-neutral command name plus a JSON parameter object.
bool	espectre::espectre_ota_channel_accepted (const std::string &channel)
	Whether channel is a published OTA channel name.
std::string	espectre::espectre_ota_manifest_url (const char *frontend, const char *chip, const std::string &channel)
	Built-in GitHub Releases manifest URL for a frontend, chip, and channel.
bool	espectre::parse_espectre_config_command (const std::string &command, EspectreDeviceConfig *config, std::string *error)
	Parse a legacy ASCII SET_DEVICE_CONFIG: command.
bool	espectre::parse_espectre_mqtt_config_command (const std::string &command, EspectreDeviceConfig *config, std::string *error)
	Parse a SET_MQTT_CONFIG: command, carrying the broker settings.

Variables
constexpr const char *	espectre::ESPECTRE_PROTOCOL_VERSION = "1.0"
	Protocol version reported in payloads.
constexpr const char *	espectre::ESPECTRE_TOPIC_PREFIX = "espectre/v1/devices"
	Default MQTT topic root.
constexpr const char *	espectre::ESPECTRE_OTA_CHANNEL_RELEASE = "release"
	Official tagged GitHub Release OTA channel.
constexpr const char *	espectre::ESPECTRE_OTA_CHANNEL_PREVIEW = "preview"
	Rolling main OTA channel.
constexpr const char *	espectre::ESPECTRE_OTA_CHANNEL_DEVELOP = "develop"
	Rolling develop OTA channel.
constexpr const char *	espectre::ESPECTRE_OTA_RELEASE_TAG_PREVIEW = "snapshot"
	GitHub Releases tag for the preview OTA channel.
constexpr const char *	espectre::ESPECTRE_OTA_RELEASE_TAG_DEVELOP = "snapshot-dev"
	GitHub Releases tag for the develop OTA channel.
constexpr uint64_t	espectre::ESPECTRE_DEFAULT_DEVICE_ID = 0U
	Sentinel meaning "use the runtime-generated device id".
constexpr const char *	espectre::ESPECTRE_DEFAULT_DEVICE_LABEL = ""
	Empty label, meaning the device id is used as the display name.

Detailed Description

Wire types and payload builders for the ESPectre Protocol.

The protocol is the contract between a device and whatever consumes it: MQTT topics, Direct WebSocket messages, JSON payloads, and the OTA status model. It is specified in docs/ESPECTRE_PROTOCOL.md; this header is the C++ view of that specification.

Use it whenever your integration should stay interoperable with the shipped clients — the CLI, Home Assistant discovery, and the web portal all speak it. The builders take a RuntimeSnapshot and return a serialized payload, so your transport only moves bytes and never formats them.

The parsers never throw: they validate and report failure through an out parameter. They do not all roll back cleanly on rejection, so parse into a copy of your live configuration and commit it only on success, which is what the shipped frontends do.

Definition in file espectre_protocol.h.