Eimdall Documentation v0.9

Eimdall is the edge-first product intelligence and predictive maintenance platform for robotics. It runs fully air-gapped — no cloud dependency, no data leaving your infrastructure.

What Eimdall gives you

• Feature adoption analytics — know which robot capabilities are used, ignored or constantly overridden
• Usage journeys — track session flows, repeated paths and abandonment moments across your entire fleet
• Friction detection — surface retries, overrides and operator workarounds automatically
• Failure prediction — detect anomalies before they become downtime with a local ML pipeline
• LLM insights — Ollama generates recommendations, daily digests and cross-environment comparisons — all on-premise

Architecture

Eimdall is composed of two binaries that communicate via a structured report format. No raw sensor stream is ever transmitted.

Data flow

1. Your robot bridge pushes sensor readings to the Edge Core via a local HTTPS endpoint (127.0.0.1:8787)
2. Edge Core aggregates readings into DailyReports — compact protobuf summaries (typically <50 KB)
3. Reports are stored in an on-robot spool (up to 14 days of autonomy) and uploaded to Central when connectivity is available
4. Central indexes reports and exposes them to the dashboards via a REST API
5. Insights are generated on demand by triggering a local Ollama model against the indexed data

Quickstart — first robot in 30 minutes

This guide connects a single robot to a running Central instance.

# Extract the archive you received
tar -xzf eimdall-edge-core-v0.9.2-linux-x86_64.tar.gz

# Verify integrity (SHA256 provided in the email)
sha256sum eimdall-edge-core

# Install
sudo mkdir -p /opt/eimdall/bin
sudo install -m 755 eimdall-edge-core /opt/eimdall/bin/eimdall-edge

# Verify
/opt/eimdall/bin/eimdall-edge --version

feature_set_version: "fs-2026-04"

sensors:
  - sensor_id: "body_imu"
    family: "imu"
    enabled: true
    sample_rate_hz: 10

spool_disk:
  path: "/var/lib/eimdall/spool"
  ttl_days: 14
  max_bytes: 1073741824   # 1 GB

upload:
  central_url: "https://YOUR_CENTRAL_IP:8080"
  retry_base_ms: 1000
  max_retries: 8
  tls_ca_cert_path: "/etc/eimdall/tls/central-ca.crt"

local_service:
  enabled: true
  bind: "127.0.0.1:8787"
  require_pairing: true
  token_file: "/etc/eimdall/eimdall-local-service.token"

sudo mkdir -p /etc/eimdall /var/lib/eimdall/spool /var/log/eimdall
echo "token-$(head -c 8 /dev/urandom | xxd -p)" | \
  sudo tee /etc/eimdall/eimdall-local-service.token

sudo /opt/eimdall/bin/eimdall-edge \
  --config /etc/eimdall/edge.runtime.yaml

# Verify
curl --cacert /etc/eimdall/tls/edge-local-ca.crt \
  https://127.0.0.1:8787/v1/local/ping
# → {"status":"ok","version":"0.9.2"}

TOKEN=$(cat /etc/eimdall/eimdall-local-service.token)

curl -sk https://127.0.0.1:8787/v1/local/bridge/ingest \
  -H "X-Eimdall-Bridge-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "robot_id":   "robot-01",
    "bridge_id":  "bridge-main",
    "source":     "constructor_sdk",
    "sensor_id":  "body_imu",
    "family":     "imu",
    "ts_unix_ms": '$(date +%s000)',
    "values": {
      "accel_x_g": 0.01, "accel_y_g": -0.02, "accel_z_g": 1.01,
      "gyro_x_dps": 0.5, "gyro_y_dps": -0.3, "gyro_z_dps": 0.1
    }
  }'

SESSION=$(curl -sk -X POST https://127.0.0.1:8787/v1/local/pair/session \
  -H "X-Eimdall-Bridge-Token: $TOKEN" | jq -r .session_token)

curl -sk -X POST https://127.0.0.1:8787/v1/local/upload/trigger \
  -H "Authorization: Bearer $SESSION"

The bridge

The bridge is the only code you write. It reads your robot's native SDK and pushes readings to the Edge Core's local HTTPS endpoint. Eimdall provides no SDK dependency — any HTTP client works.

Python bridge — minimal example

import requests, time

EDGE_URL  = "https://127.0.0.1:8787/v1/local/bridge/ingest"
HB_URL    = "https://127.0.0.1:8787/v1/local/bridge/heartbeat"
TOKEN     = open("/etc/eimdall/eimdall-local-service.token").read().strip()
HEADERS   = {"X-Eimdall-Bridge-Token": TOKEN, "Content-Type": "application/json"}
CA        = "/etc/eimdall/tls/edge-local-ca.crt"

def push_imu(ax, ay, az, gx, gy, gz):
    requests.post(EDGE_URL, headers=HEADERS, verify=CA, timeout=2, json={
        "robot_id":   "robot-01",
        "bridge_id":  "bridge-main",
        "source":     "constructor_sdk",
        "sensor_id":  "body_imu",
        "family":     "imu",
        "ts_unix_ms": int(time.time() * 1000),
        "values": {
            "accel_x_g": ax, "accel_y_g": ay, "accel_z_g": az,
            "gyro_x_dps": gx, "gyro_y_dps": gy, "gyro_z_dps": gz,
        }
    })

def send_heartbeat():
    requests.post(HB_URL, headers=HEADERS, verify=CA, timeout=2, json={
        "robot_id": "robot-01", "bridge_id": "bridge-main",
        "ts_unix_ms": int(time.time() * 1000),
        "status": "ok", "uptime_s": int(time.monotonic()), "errors_5m": 0
    })

last_hb = 0
while True:
    # ← replace with your robot SDK call
    push_imu(0.01, -0.02, 1.01, 0.5, -0.3, 0.1)
    if time.time() - last_hb > 5:
        send_heartbeat()
        last_hb = time.time()
    time.sleep(0.1)

Ingest payload format

Sensor families

Each family defines a set of expected keys in the values payload. Unknown keys are accepted and stored as generic numerics.

ROS 2 integration

The eimdall_ros2_bridge package translates ROS 2 topic messages into Eimdall bridge payloads. It runs as a sidecar node alongside your ROS 2 stack with no dependency on Eimdall binaries in your ROS workspace.

Install

# Clone into your ROS 2 workspace
cd ~/ros2_ws/src
git clone https://github.com/YvesData/eimdall-ros2-bridge.git

cd ~/ros2_ws
colcon build --packages-select eimdall_ros2_bridge
source install/setup.bash

Launch

ros2 launch eimdall_ros2_bridge bridge.launch.py \
  robot_id:=robot-01 \
  edge_url:=https://127.0.0.1:8787 \
  token_file:=/etc/eimdall/eimdall-local-service.token

The bridge automatically maps standard ROS 2 message types to Eimdall sensor families: sensor_msgs/Imu → imu, sensor_msgs/BatteryState → battery, nav_msgs/Odometry → encoder, etc.

Key concepts

DailyReport

The unit of data exchange between Edge and Central. A DailyReport is a compact protobuf summary built over a rolling 24-hour window. It contains aggregated feature vectors, anomaly counts, session summaries and usage patterns — no raw sensor values. Typical size: 10–50 KB per robot per day.

Anomaly scoring

The Edge Core maintains per-sensor baselines using an online learning pipeline. When a sensor reading deviates significantly from its baseline, an anomaly event is recorded with a severity level (low / medium / high / critical) and attached to the next DailyReport.

Insights

Insights are natural-language analysis results generated by a local Ollama LLM model against the indexed DailyReports. Available insight kinds:

Multi-tenancy

A single Central instance supports multiple manufacturers (constructor tenants) and their clients (client tenants). Each robot belongs to one tenant. Clients can access only the data shared by their manufacturer — the sharing policy (none / aggregated / full) is set per-tenant by the manufacturer.

Security

Transport

All communication between Edge, bridge, and Central uses HTTPS/TLS. The local Edge service (127.0.0.1:8787) uses a self-signed certificate. The Central API supports mutual TLS (mTLS) for robot authentication.

Authentication

• Bridge → Edge: static token via X-Eimdall-Bridge-Token header
• Edge → Central: mTLS client certificate (optional) + robot registration token
• Dashboard / API: JWT Bearer (HS256, 12h TTL), renewed via /v1/auth/refresh

Data privacy

No raw sensor data is ever transmitted over the network. Only aggregated DailyReports move between Edge and Central. The LLM never sees raw values — it receives pre-computed feature summaries.

API overview

The Central REST API uses JSON throughout. All routes except /v1/auth/login require Authorization: Bearer <token>.

Base URL: https://YOUR_CENTRAL:8080

Authentication

Fleet & robots

Intelligence

Webhooks

Prometheus & Grafana integration

Eimdall exposes a Prometheus-compatible metrics endpoint on a dedicated port 9091, completely isolated from the main API. Your existing Grafana stack continues to work — Eimdall publishes what it knows, you visualise it the way you want.

Security model (4 independent layers)

The metrics endpoint is hardened by design. There is no configuration that allows a non-authenticated, non-encrypted scrape.

Environment variables

EIMDALL_METRICS_TOKEN=<secret>          # Required — bearer token for Prometheus scrape
EIMDALL_METRICS_TLS_CERT=/path/cert.pem  # Required — server TLS certificate (PEM)
EIMDALL_METRICS_TLS_KEY=/path/key.pem   # Required — server TLS private key (PEM)
EIMDALL_METRICS_CLIENT_CA=/path/ca.pem  # Recommended — CA to verify Prometheus client cert (mTLS)
EIMDALL_METRICS_PORT=9091               # Optional — default 9091

If EIMDALL_METRICS_TOKEN or TLS variables are absent, the metrics server does not start — no fallback, no plaintext endpoint.

Prometheus scrape configuration

Add the following job to your prometheus.yml:

scrape_configs:
  - job_name: eimdall
    scrape_interval: 30s
    scheme: https
    tls_config:
      ca_file: /etc/prometheus/certs/eimdall-ca.pem       # CA that signed Eimdall's cert
      cert_file: /etc/prometheus/certs/prometheus.pem     # Prometheus client cert (mTLS)
      key_file: /etc/prometheus/certs/prometheus-key.pem  # Prometheus client key
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/eimdall-token     # File containing the bearer token
    static_configs:
      - targets: ["YOUR_CENTRAL_HOST:9091"]

Generating certificates (quick start)

# 1. Create CA
openssl req -x509 -newkey rsa:4096 -keyout ca-key.pem -out ca.pem \
  -days 3650 -nodes -subj "/CN=eimdall-metrics-ca"

# 2. Server cert for Eimdall
openssl req -newkey rsa:4096 -keyout server-key.pem -out server.csr \
  -nodes -subj "/CN=YOUR_CENTRAL_HOST"
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out server.pem -days 365

# 3. Client cert for Prometheus (mTLS)
openssl req -newkey rsa:4096 -keyout prometheus-key.pem -out prometheus.csr \
  -nodes -subj "/CN=prometheus-scraper"
openssl x509 -req -in prometheus.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out prometheus.pem -days 365

# 4. Generate bearer token
openssl rand -hex 32 > eimdall-token

Available metrics

Grafana dashboard

An importable Grafana dashboard is available at monitoring/grafana-dashboard.json in the eimdall-ros2-bridge repository.

Import steps:

1. In Grafana → Dashboards → Import
2. Upload grafana-dashboard.json
3. Select your Prometheus datasource when prompted
4. Click Import

The dashboard includes: fleet KPIs (total/online/critical robots, insights, reports), online robots over time, anomaly events per hour, per-robot status table with ONLINE/OFFLINE badge, and cumulative insights/reports time series.

OpenTelemetry integration

Eimdall supports OpenTelemetry natively on two channels:

• Metrics — the existing Prometheus endpoint (port 9091) is scraped by the OTel Collector via its prometheus receiver, then forwarded as OTLP to any backend.
• Traces — Eimdall Central pushes OTLP gRPC spans directly to the Collector (or any OTLP endpoint) when EIMDALL_OTEL_ENDPOINT is set.

Activating trace export

Set one environment variable before starting Eimdall Central:

EIMDALL_OTEL_ENDPOINT=http://otel-collector:4317

If the variable is absent or empty, Eimdall runs in console-only mode — no OTLP traffic, zero overhead.

Eimdall sends spans with these resource attributes:

• service.name = "eimdall-central"
• service.version = "0.9.x"

OTel Collector configuration

A ready-to-use Collector config is available at monitoring/otel-collector-config.yaml in the eimdall-ros2-bridge repository. It wires both channels (metrics scrape + traces receive) and forwards to Grafana Tempo.

receivers:
  prometheus:          # scrape Eimdall metrics (port 9091, mTLS + bearer)
    config:
      scrape_configs:
        - job_name: eimdall
          scrape_interval: 30s
          scheme: https
          tls_config:
            ca_file:   /etc/otelcol/certs/eimdall-ca.pem
            cert_file: /etc/otelcol/certs/collector-client.pem
            key_file:  /etc/otelcol/certs/collector-client-key.pem
          authorization:
            type: Bearer
            credentials_file: /etc/otelcol/eimdall-token
          static_configs:
            - targets: ["EIMDALL_HOST:9091"]

  otlp:                # receive Eimdall traces (EIMDALL_OTEL_ENDPOINT)
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    timeout: 5s

exporters:
  otlp/tempo:
    endpoint: GRAFANA_TEMPO_HOST:4317

service:
  pipelines:
    metrics:
      receivers:  [prometheus]
      processors: [batch]
      exporters:  [otlp/tempo]
    traces:
      receivers:  [otlp]
      processors: [batch]
      exporters:  [otlp/tempo]

Running the Collector with Docker

docker run --rm \
  -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml \
  -v /etc/eimdall/certs:/etc/otelcol/certs \
  -v /etc/eimdall/eimdall-token:/etc/otelcol/eimdall-token \
  -p 4317:4317 -p 4318:4318 \
  otel/opentelemetry-collector-contrib:latest

Supported OTel backends