SDK Integration

This guide combines the SDK surface, build integration, backend loading, and runtime integration checklist for teams embedding the generic EdgeEmbed runtime into an embedded platform.

SDK Deliverables

edgeembed-runtime-sdk/
  include/
    edgeembed.h
    edgeembed_types.h
    edgeembed_backend_abi.h
    edgeembed_config.h
  lib/
    libedgeembed.so
    libmock_hal.so
  robotics_bundle/
    manifest.json
    events.json
    intents.json
    actions.json
    action_mapping.json
    policy.json
    resources.json
    concurrency.json
    backends/
      robot_mock_plugin.so
      robot_mock_plugin.manifest.json
  examples/
  docs/

Asset	Purpose
include/edgeembed.h	Runtime lifecycle, bundle loading, symbol resolution, event input, resource updates, callbacks, diagnostics
include/edgeembed_types.h	Public enums, structs, trace fields, runtime config, payloads, completion records
include/edgeembed_backend_abi.h	ABI for platform backend plugin implementations
include/edgeembed_config.h	Build-time pool and timing override macros; the public runtime API does not depend on it
lib/libedgeembed.so	In-process runtime library
lib/libmock_hal.so	Reference mock backend for deterministic evaluation

Integration Layers

Layer	Integrator owns	SDK owns
Event sources	Map platform signals to bundle event names such as evt_cliff_detected, evt_obstacle_close, and evt_path_clear	Validate, normalize, queue, coalesce
Resource state	Report facts about resources such as drive_base, speaker, and led_ring	Maintain point-in-time resource snapshots
Policy	Define event-to-intent rules in policy.json	Evaluate policy deterministically
Concurrency	Define resource-class conflicts for class_drive and class_hmi	Enforce group behavior before actions
Action mapping	Define intent-to-action templates for intent_safe_stop, intent_slow_down, and intent_resume	Build ordered plans and dependencies
Platform backend	Implement the backend plugin ABI for act_drive_stop, act_drive_slow, and act_drive_resume	Dispatch actions through edgeembed_backend_ops_t
Fallback path	Provide any independent platform fallback required by the product	Report state, diagnostics, trace fields

Build Integration

cmake_minimum_required(VERSION 3.16)
project(my_robot_controller C)

set(EDGEEMBED_SDK_DIR "/opt/edgeembed-runtime-sdk" CACHE PATH "SDK root")

add_executable(my_app main.c)
target_include_directories(my_app PRIVATE ${EDGEEMBED_SDK_DIR}/include)
target_link_libraries(my_app PRIVATE ${EDGEEMBED_SDK_DIR}/lib/libedgeembed.so pthread m)
set_target_properties(my_app PROPERTIES BUILD_RPATH ${EDGEEMBED_SDK_DIR}/lib)

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
      -DEDGEEMBED_SDK_DIR=/opt/edgeembed-runtime-sdk
cmake --build build --parallel

Minimal Runtime Flow

#include <edgeembed.h>

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;
}

int main(void) {
    edgeembed_config_t cfg = {
        .default_namespace = "robotics_bundle",
    };

    edgeembed_t* runtime = NULL;
    edgeembed_result_t rc = edgeembed_init(&runtime, &cfg);
    if (rc != EDGEEMBED_OK) {
        return 1;
    }

    rc = edgeembed_load_bundle(runtime, "robotics_bundle");
    if (rc != EDGEEMBED_OK) {
        edgeembed_shutdown(runtime);
        return 1;
    }

    edgeembed_set_event_callback(runtime, event_cb, NULL);

    rc = edgeembed_start(runtime);
    if (rc != EDGEEMBED_OK) {
        edgeembed_shutdown(runtime);
        return 1;
    }

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

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

    edgeembed_stop(runtime);
    edgeembed_shutdown(runtime);
    return rc == EDGEEMBED_OK ? 0 : 1;
}

For hot paths, resolve names once with edgeembed_resolve_symbol() and submit with edgeembed_submit_event_by_id().

Backend Loading

The runtime never links concrete platform code. edgeembed_load_bundle() reads the bundle directory, validates manifest.json and the vocabulary files, loads backend shared objects from backends/, resolves edgeembed_backend_entry(), and queries capabilities through the returned edgeembed_backend_ops_t.

If a bundle is invalid, edgeembed_load_bundle() returns an error such as EDGEEMBED_ERR_BUNDLE_INVALID, EDGEEMBED_ERR_PLUGIN_LOAD, or EDGEEMBED_ERR_BACKEND_ABI_MISMATCH. Use edgeembed_get_last_config_errors() to retrieve the last structured bundle validation report.

Latency Target

Stage	Budget
Event enqueue	50 microseconds or less
Decision thread wakeup	100 microseconds or less
Policy evaluation	200 microseconds or less
Action planning	100 microseconds or less
Backend dispatch	500 microseconds or less
Library-mode target	10 ms p99 on production target

Latency is measured from event receipt to backend dispatch using edgeembed_trace_t, trace callbacks, and records drained through edgeembed_drain_trace(). Backend ACK time belongs to the platform backend contract and is outside the core runtime SLA.

Integration Checklist

• Load the bundle with edgeembed_load_bundle() before entering RUNNING.
• Keep callbacks short and non-blocking.
• Never submit or cancel events from inside an event callback.
• Use edgeembed_update_resource_state() for actual resource-state facts, not for direct control commands.
• Preserve any independent platform fallback required when runtime state is EDGEEMBED_RUNTIME_STATE_ERROR.
• Replace the reference mock backend with a production backend before deployment validation.