Skip to content

configuration.md

Latest commit

 

History

History
175 lines (141 loc) · 5.94 KB

configuration.md

File metadata and controls

175 lines (141 loc) · 5.94 KB
Raw

Spanda Configuration

Spanda uses TOML as the primary human-authored configuration format for autonomous systems. Machine-generated configs and API interchange may use JSON; both formats load through the same resolver.

Architecture

spanda.toml
    ↓
ConfigResolver (spanda-config)
    ↓
ResolvedSystemConfig
    ↓
Package Loader / Provider Registry
    ↓
Hardware + Capability Verification
    ↓
Readiness / Assurance / Diagnosis
    ↓
Runtime / Simulator

Runtime, verifier, readiness, assurance, health, recovery, and package loading consume ResolvedSystemConfig via spanda-config integration helpers — not raw TOML/JSON files.

Auto-resolution

Commands that accept a .sd file automatically resolve config from the nearest spanda.toml:

  • spanda run / spanda sim / spanda fleet run — --config optional; attaches config to RunOptions
  • spanda verify — merges config validation into compatibility report
  • spanda readiness — uses fleet hardware profile, readiness weights, robot alignment
  • spanda replay — resolves config from trace source for deterministic replay and playback
  • spanda assure / spanda diagnose / spanda mission verify / spanda recovery-coverage — apply [assurance], [mission], [recovery] thresholds
  • spanda heal / spanda recover — validate config before evaluation

Use --config <path/to/spanda.toml> to point at a non-default manifest.

Root manifest

spanda.toml at the project root references domain-specific fragments:

[project]
name = "Warehouse Patrol"
version = "0.1.0"
language = "0.2"

[config]
hardware = "spanda.hardware.toml"
devices = "spanda.devices.toml"
providers = "spanda.providers.toml"
fleet = "spanda.fleet.toml"
security = "spanda.security.toml"
health = "spanda.health.toml"
readiness = "spanda.readiness.toml"
assurance = "spanda.assurance.toml"
recovery = "spanda.recovery.toml"
mission = "spanda.mission.toml"

The existing [package] section for package management remains supported. When [project] is absent, the resolver derives project metadata from [package].

Cascading overrides

Layer environment, deployment, and robot-specific settings with [extends]:

[extends]
base = "configs/base.toml"
environment = "configs/warehouse-a.toml"
deployment = "configs/production.toml"
robot = "configs/rover-001.toml"

Later layers override earlier layers. Control array behavior per section:

[merge]
fleet = "merge_by_id"
tags = "append"

Strategies: replace (default), append, merge_by_id.

Device identity

Declare flat [[devices]] records (or extend fleet [[fleet.robots.compute.devices]]) with network and bus identity fields:

[[devices]]
id = "camera-front-001"
type = "Camera"
logical_name = "front_camera"
ip = "192.168.1.42"
mac = "AA:BB:CC:DD:EE:FF"
serial = "CAM-12345"
provider = "spanda-vision"
protocol = "rtsp"
endpoint = "rtsp://192.168.1.42/stream"
capabilities = ["capture_image", "stream_video"]
trust_level = "verified"
security_identity = "camera-front-001"
robot_id = "rover-001"

Supported identity fields include: logical_name, serial, mac/mac_address, ip/ip_address, hostname, dns_name, mdns_name, endpoint/endpoint_url, protocol, port, bus, can_id, usb_path, pci_path, bluetooth_address, ble_uuid, cellular_imei, sim_iccid, gps_device_id, firmware_version, hardware_revision, security_identity, certificate_fingerprint, trust_level, redundant_group, failover_priority.

Reference fragments via [config] network_devices = "spanda.network-devices.toml" (merged into [[devices]] with merge_by_id).

CLI

Command Purpose
spanda config resolve Print merged configuration
spanda config validate Run validation rules
spanda config graph Show config dependency graph
spanda config diff <a> <b> Diff two config files
spanda config drift --baseline <dir> Semantic drift vs approved baseline
spanda drift <file.sd> [--agent Robot@HW] Program + agent drift vs deploy/fleet agents
spanda config report Full configuration report
spanda config report --network Network/device identity report only
spanda device discover List configured devices; optional --subnet scan
spanda device inspect <id> Inspect one device identity record
spanda device-tree inspect <robot> Inspect one robot's hierarchy
spanda device-tree graph Print device hierarchy
spanda network scan --subnet CIDR TCP probe hosts on a subnet
spanda map verify <file.sd> Verify logical-to-physical mapping
spanda readiness <file.sd> --config spanda.toml Readiness with config validation
spanda readiness <file.sd> --baseline <dir> Readiness with baseline drift checks

Add --json to any command for machine-readable output. Use --config <path> to point at a non-default manifest location.

Integration

Subsystem Config access
Hardware verification ResolvedSystemConfig::device_tree, hardware profiles
Capability verification Device capabilities, provider registry
Readiness --config loads and validates before evaluation
Device registry [[devices]] identity records merged into DeviceRegistry
Assurance / diagnosis assurance, mission, recovery sections + traceability rows
Health framework health section and per-robot policies
Provider registry providers fragment + package dependencies
Security security.devices.* identities and trust flags

Reports

spanda config report generates:

  • Resolved configuration summary
  • Device hierarchy
  • Logical-to-physical mapping counts
  • Capability mapping per device
  • Health policy coverage
  • Trust/security identity mapping

See also