API Reference

OEM code includes the public headers and links against the EdgeEmbed Runtime library (libedgeembed.so).

#include <edgeembed.h>
#include <edgeembed_types.h>

Lifecycle

Function	Purpose
`edgeembed_init(edgeembed_t** out_runtime, const edgeembed_config_t* config)`	Allocate runtime pools and enter `EDGEEMBED_RUNTIME_STATE_INITIALIZED`
`edgeembed_load_bundle(edgeembed_t* runtime, const char* bundle_path)`	Validate and load a bundle directory before start
`edgeembed_start(edgeembed_t* runtime)`	Start event processing and internal scheduling
`edgeembed_runtime_step(edgeembed_t* runtime, uint64_t now_us)`	Advance one decision-loop iteration when `EDGEEMBED_FLAG_MANUAL_STEP` is set
`edgeembed_stop(edgeembed_t* runtime)`	Stop processing and drain queues
`edgeembed_shutdown(edgeembed_t* runtime)`	Release runtime resources; idempotent
`edgeembed_get_runtime_state(edgeembed_t* runtime)`	Read current lifecycle state

edgeembed_config_t cfg = {
    .default_namespace = "robotics_bundle",
};

edgeembed_t* runtime = NULL;
edgeembed_result_t rc = edgeembed_init(&runtime, &cfg);
if (rc == EDGEEMBED_OK) {
    rc = edgeembed_load_bundle(runtime, "robotics_bundle");
}
if (rc == EDGEEMBED_OK) {
    rc = edgeembed_start(runtime);
}

The typical lifecycle is edgeembed_init() to edgeembed_load_bundle() to optional callback and record-path setup to edgeembed_start(). After submitting work and reading diagnostics or traces, call edgeembed_stop() and edgeembed_shutdown().

Event Input

Function	Purpose
`edgeembed_submit_event(edgeembed_t* runtime, const char* event_name, const edgeembed_payload_t* payload, edgeembed_event_id_t* out_event_id)`	Submit an event by bundle event name
`edgeembed_submit_event_by_id(edgeembed_t* runtime, edgeembed_symbol_t event_sym, const edgeembed_payload_t* payload, edgeembed_event_id_t* out_event_id)`	Submit an event by a previously resolved symbol
`edgeembed_cancel_event(edgeembed_t* runtime, edgeembed_event_id_t event_id)`	Cancel a queued or active event when possible
`edgeembed_resolve_symbol(edgeembed_t* runtime, edgeembed_symbol_kind_t kind, const char* name, edgeembed_symbol_t* out_sym)`	Resolve a bundle name to a symbol ID
`edgeembed_symbol_name(edgeembed_t* runtime, edgeembed_symbol_kind_t kind, edgeembed_symbol_t sym, const char** out_name)`	Reverse lookup a symbol ID

edgeembed_payload_t payload = {
    .urgency = 1.0f,
    .confidence = 0.95f,
    .value = 42.0f,
    .ttl_ms = 2500u,
};

edgeembed_event_id_t event_id = 0;
edgeembed_submit_event(runtime, "evt_cliff_detected", &payload, &event_id);

For repeated submissions, resolve once and reuse the symbol:

edgeembed_symbol_t cliff = EDGEEMBED_SYMBOL_NONE;
edgeembed_resolve_symbol(runtime,
                         EDGEEMBED_KIND_EVENT,
                         "evt_cliff_detected",
                         &cliff);

edgeembed_submit_event_by_id(runtime, cliff, &payload, &event_id);

Both submit calls are non-blocking. The generated edgeembed_event_id_t is used for tracking and cancellation.

Stream State

Function	Purpose
`edgeembed_update_resource_state(edgeembed_t* runtime, const edgeembed_resource_update_t* update)`	Report actual external resource state to the runtime

edgeembed_symbol_t drive = EDGEEMBED_SYMBOL_NONE;
edgeembed_resolve_symbol(runtime,
                         EDGEEMBED_KIND_RESOURCE,
                         "drive_base",
                         &drive);

edgeembed_resource_update_t update = {
    .resource_sym = drive,
    .state_valid = true,
    .state_value = 1u,
    .timestamp_ms = 123456u,
};

edgeembed_update_resource_state(runtime, &update);

Resource updates report facts. They do not directly dispatch act_drive_stop, act_drive_slow, or act_drive_resume; dispatch is produced by policy and action planning.

Callbacks

Function	Purpose
`edgeembed_set_event_callback(edgeembed_t* runtime, edgeembed_event_callback_t cb, void* user_data)`	Register event lifecycle callback
`edgeembed_set_state_change_callback(edgeembed_t* runtime, edgeembed_runtime_state_cb_t cb, void* user_data)`	Register runtime state transition callback
`edgeembed_set_trace_callback(edgeembed_t* runtime, edgeembed_trace_callback_t cb, void* user_data)`	Register structured trace callback
`edgeembed_set_completion_callback(edgeembed_t* runtime, edgeembed_completion_callback_t cb, void* user_data)`	Register per-event completion summary callback

Callbacks fire on the decision thread. Do not block, submit events, or cancel events from inside callbacks. Calls to edgeembed_submit_event(), edgeembed_submit_event_by_id(), or edgeembed_cancel_event() from inside a callback are rejected with EDGEEMBED_ERR_REENTRANT_FORBIDDEN.

static void event_cb(edgeembed_event_id_t id,
                     edgeembed_event_status_t status,
                     const edgeembed_trace_t* trace,
                     void* user_data) {
    (void)id;
    (void)status;
    (void)trace;
    (void)user_data;
}

static void trace_cb(const edgeembed_trace_record_t* record,
                     void* user_data) {
    (void)record;
    (void)user_data;
}

edgeembed_set_event_callback(runtime, event_cb, NULL);
edgeembed_set_trace_callback(runtime, trace_cb, NULL);

edgeembed_trace_t is the compact event-lifecycle timing record delivered to event callbacks. edgeembed_trace_record_t is the structured trace-ring record used by trace callbacks and edgeembed_drain_trace().

Diagnostics

Function	Purpose
`edgeembed_get_diagnostics(edgeembed_t* runtime, edgeembed_diagnostics_t* out_diag)`	Snapshot runtime counters
`edgeembed_reset_diagnostics(edgeembed_t* runtime)`	Reset runtime counters
`edgeembed_drain_trace(edgeembed_t* runtime, edgeembed_trace_record_t* out, uint32_t max_records, uint32_t* out_count)`	Drain structured trace-ring records
`edgeembed_drain_probe(edgeembed_t* runtime, edgeembed_probe_record_t* out, uint32_t max_records, uint32_t* out_count)`	Drain probe records
`edgeembed_get_last_config_errors(edgeembed_t* runtime, edgeembed_config_error_report_t* out_report)`	Read the last structured bundle validation report after `edgeembed_load_bundle()` rejects a bundle
`edgeembed_runtime_set_record_path(edgeembed_t* r, const char* path)`	Set the record log path before start when `EDGEEMBED_FLAG_RECORD` is enabled
`edgeembed_runtime_set_replay_path(edgeembed_t* r, const char* path)`	Set the replay log path before start when `EDGEEMBED_FLAG_REPLAY` is enabled
`edgeembed_runtime_version(void)`	Return the runtime version string
`edgeembed_runtime_abi(void)`	Return `EDGEEMBED_ABI_VERSION`

edgeembed_diagnostics_t diag = {0};
edgeembed_get_diagnostics(runtime, &diag);

edgeembed_trace_record_t records[32];
uint32_t count = 0;
edgeembed_drain_trace(runtime, records, 32u, &count);

Bundle validation happens in edgeembed_load_bundle(). When it returns a bundle or plugin validation error, call edgeembed_get_last_config_errors() before shutdown if the integration needs file, field, and message details.

Lifecycle​

Event Input​

Stream State​

Callbacks​

Diagnostics​

Lifecycle

Event Input

Stream State

Callbacks

Diagnostics