spanda-reference.md

Spanda Language Reference

Complete reference for the Spanda language (.sd): reserved words, triggers, std.* packages, global functions, built-in methods, and the spanda CLI.

Structured like JavaDoc (hierarchical packages and types) and man pages (NAME / SYNOPSIS / DESCRIPTION / OPTIONS for CLI commands).

Generated by spanda reference / scripts/generate_spanda_reference.py. Signatures come from the type checker (spanda-core).

See also: spanda-language.md (tutorial-style guide), standard-library.md (stdlib overview), spanda-type-system.md (type rules).

Safety motion guarantee

Compile time: AI output is ActionProposal. Actuator execute() accepts only SafeAction from safety.validate(ActionProposal). ActionProposal motion components (UntrustedLinear / UntrustedAngular) cannot feed DifferentialDrive.drive / follow (including via let bindings). Non-AI literal drive / follow(path:) remain available. Runtime (interpreter run/sim): safety { max_speed = … } clamps linear velocity on drive, execute, and follow(path:) cruise speed; optional max_angular = … rad/s clamps turn rate on drive / execute; stop_if, zones, and emergency stop still gate motion. Not claimed: follow(path:) does not re-derive SafeAction per waypoint. Full write-up: spanda-type-system.md.

Contents

• Safety motion guarantee
• Keywords
• Triggers
• Standard library (std.*)
• Global functions
• Robot methods
• Type methods
• Object properties
• Scan properties
• Hardware sensor libraries
• CLI reference (man pages)

Keywords

Reserved words recognized by the Spanda lexer. Identifiers cannot reuse these names.

Modules and visibility

• module
• import
• export
• public
• private
• use

Types and generics

• struct
• enum
• trait
• impl
• for
• dyn
• fn
• async
• await
• return

Robot graph

• robot
• behavior
• sensor
• actuator
• ai_model
• agent
• safety
• twin
• topic
• service
• action
• message
• node
• device
• bus

Triggers and tasks

• on
• every
• when
• task
• spawn
• select
• parallel
• priority
• entered
• exited
• event
• subscribe
• publish
• receive

Control flow

• let
• if
• else
• match
• loop
• while
• and
• or
• not
• true
• false

Safety and contracts

• assert
• verify
• observe
• emergency_stop
• reset_emergency_stop
• stop_if
• requires
• ensures
• invariant
• can
• warning
• certify

Reliability and realtime

• pipeline
• watchdog
• recover
• retry
• fallback
• fault
• mission
• deadline
• timing
• min_period
• duration
• jitter
• isolated
• backoff
• times

Hardware and deploy

• hardware
• deploy
• hal
• soc
• requires_hardware
• requires_network
• simulate_compatibility
• budget
• cpu
• storage
• gpu
• battery
• capacity
• sensors
• actuators
• network
• bandwidth
• latency

Other reserved words

• adc
• ai
• at
• baud
• best_effort
• ble_service
• bluetooth
• call
• circle
• connectivity
• connectivity_policy
• discover
• emit
• enter
• env
• execute
• extern
• faults
• feedback
• file
• fleet
• frequency
• from
• geofence
• goal
• gpio
• history
• i2c
• in
• includes
• matches
• memory
• mirror
• out
• packet_loss
• permissions
• pin
• plan
• policy
• provider
• pwm
• qos
• radius
• rate
• rect
• reliable
• remember
• replay
• request
• requires_connectivity
• resource
• response
• result
• safety_zone
• secret
• secure
• send_goal
• signed_by
• size
• skill
• spi
• state
• state_machine
• swarm
• switch_if
• telemetry
• to
• tools
• transition
• trust
• trusted_only
• uart
• uses
• where
• with
• zone

Triggers

Unified reactive handlers on robots and agents. See triggers.md.

Form	Syntax	Fires when
Event	on event_name { ... }	Named event is emitted
Message	on message topic_name { ... }	Message received on topic
Timer	every 100 ms { ... }	Periodic wall-clock interval
Condition	when condition { ... }	Boolean expression becomes true
State	on entered StateName { ... }	State machine enters state
State	on exited StateName { ... }	State machine exits state
Safety	on safety event_name { ... }	Safety subsystem event
Hardware	on hardware event_name { ... }	HAL / hardware event
AI	on ai event_name { ... }	AI runtime event
Twin	on twin event_name { ... }	Digital twin event
Log match	on log matches /pattern/ { ... }	Log line matches regex
Message match	on message field matches /pattern/ { ... }	Topic field matches regex

Standard library (std.*)

Import with import std.robotics; (or any namespace below). Types resolve with or without the std.<module>. prefix.

std.actuators {#std-actuators}

Actuator types: motors, servos, grippers.

Types

• Actuator
• Motor
• Servo
• Gripper
• DriveUnit
• JointCommand
• TorqueCommand
• VelocityCommand

std.ai {#std-ai}

AI models, prompts, completions, reasoning traces.

Types

• LLM — 2 method(s)
• VisionModel — 1 method(s)
• EmbeddingModel
• Prompt
• Completion
• Embedding
• Token
• Context
• Memory
• Plan
• ReasoningTrace
• ActionProposal
• SafeAction

std.audit {#std-audit}

Audit logs, provenance, mission records.

Types

• AuditEvent
• AuditLog
• ProvenanceRecord
• MissionRecord
• RecordId

std.bluetooth {#std-bluetooth}

Standard library namespace.

Types

• BluetoothConnection
• BleConnection
• BleService

std.cellular {#std-cellular}

Standard library namespace.

Types

• CellularConnection
• LTEConnection
• FourGConnection
• FiveGConnection
• RoamingStatus
• SimIdentity

std.collections {#std-collections}

Containers: arrays, maps, sets, queues.

Types

• Array
• Map
• Set
• Queue
• Stack
• Tuple

std.communication {#std-communication}

Topics, services, actions, events, bus.

Types

• Transport
• QosProfile
• QoS
• Bandwidth
• Latency
• TopicPath
• ServiceEndpoint
• MessageEnvelope
• DiscoveryFilter
• NetworkRequirements
• Reliability
• HistoryPolicy
• CommBus
• Endpoint
• Topic
• Message
• Service
• Action
• Event
• Bus

std.connectivity {#std-connectivity}

Standard library namespace.

Types

• WifiConnection
• BluetoothConnection
• BleConnection
• CellularConnection
• LTEConnection
• FourGConnection
• FiveGConnection
• EthernetConnection
• MeshConnection
• NetworkStatus
• SignalStrength
• Bandwidth
• Latency
• PacketLoss
• RoamingStatus
• SimIdentity

std.core {#std-core}

Foundation types: results, options, errors.

Types

• Result
• Option
• Error
• Void

std.crypto {#std-crypto}

Hashing and signature primitives.

Types

• Hash
• Signature

std.environment {#std-environment}

Standard library namespace.

Types

• Weather
• Temperature
• Humidity
• AirQuality
• LightLevel

std.fusion {#std-fusion}

Standard library namespace.

Types

• FusedObservation
• StateEstimate
• Confidence
• SensorFusion

std.geofence {#std-geofence}

Standard library namespace.

Types

• GeoFence
• GeoPoint

std.hardware {#std-hardware}

Deploy targets and compatibility reports.

Types

• HardwareProfile
• CompatibilityReport
• SensorSpec
• ActuatorSpec
• BusConfig
• PinConfig
• DeviceTree
• Peripheral
• Interface

std.hri {#std-hri}

Human–robot interaction: commands, intent, approval.

Types

• Command
• Conversation
• Speech
• Gesture
• Emotion
• Feedback
• Intent
• Approval

std.io {#std-io}

File and stream abstractions.

Types

• File
• Reader
• Writer
• Bytes

std.log {#std-log}

Structured logging.

Types

• Logger
• LogLevel

std.maintenance {#std-maintenance}

Standard library namespace.

Types

• HealthScore
• MaintenanceAlert
• FailurePrediction

std.manipulation {#std-manipulation}

Standard library namespace.

Types

• Arm
• Gripper
• EndEffector
• Grasp
• Pick
• Place

std.math {#std-math}

Scalar math types.

Types

• Float
• Int

std.navigation {#std-navigation}

Standard library namespace.

Types

• NavigationGoal
• Path
• Waypoint
• Trajectory
• CostMap

std.network {#std-network}

Transport, QoS, endpoints, discovery.

Types

• Transport
• QosProfile
• QoS
• Bandwidth
• Latency
• TopicPath
• ServiceEndpoint
• MessageEnvelope
• DiscoveryFilter
• NetworkRequirements
• Reliability
• HistoryPolicy
• CommBus
• Endpoint
• Topic
• Message
• Service
• Action

std.positioning {#std-positioning}

Standard library namespace.

Types

• GpsFix
• GnssFix
• GeoPoint
• GeoFence
• Altitude
• Heading
• SpeedOverGround
• SatelliteInfo
• PositionAccuracy
• NavigationStatus

std.result {#std-result}

Error-handling types.

Types

• Result
• Option
• Error

std.robotics {#std-robotics}

Robot graph: motion, agents, goals, safe actions.

Types

• Robot
• Sensor
• Actuator
• MotionCommand
• ControlSignal
• PIDConfig
• ActionProposal
• SafeAction
• Agent — 1 method(s)
• Goal
• Task
• Skill
• Capability
• Intent

std.safety {#std-safety}

Risk, hazards, constraints, emergency stop.

Types

• Risk
• Hazard
• SafetyConstraint
• EmergencyStop
• SafeAction

std.security {#std-security}

Identity, permissions, signatures, trust.

Types

• Identity
• RobotIdentity
• Signature
• Permission
• Capability
• TrustLevel

std.sensors {#std-sensors}

Sensor payload types (LiDAR, camera, IMU, …).

Types

• CameraFrame
• Image
• DepthImage
• PointCloud
• LidarScan
• GpsFix
• ImuData
• AudioFrame

std.sim {#std-sim}

Simulation worlds, scenarios, replay buffers.

Types

• Simulator
• Scenario
• Fault
• Replay
• WorldState
• PhysicsConfig
• Scene
• Entity
• SensorModel
• ActuatorModel
• Tick
• ReplayBuffer

std.slam {#std-slam}

Standard library namespace.

Types

• Map
• OccupancyGrid
• Landmark
• LocalizationEstimate
• MapLayer

std.spatial {#std-spatial}

Geometry: poses, transforms, paths, trajectories.

Types

• Point2D
• Point3D
• Vector2D
• Vector3D
• Quaternion
• Pose
• Transform
• Trajectory
• Path
• Waypoint

std.time {#std-time}

Time, duration, timestamps, and intervals.

Types

• Time
• Duration
• Timestamp
• Interval

std.twin {#std-twin}

Digital twin state and telemetry.

Types

• Twin — 5 method(s)
• SimulationState
• Telemetry
• Replay
• Fault
• Scenario

std.units {#std-units}

Physical units: distance, velocity, mass, temperature, and more.

Types

• Distance
• Velocity
• Acceleration
• Angle
• AngularVelocity
• Mass
• Force
• Power
• Voltage
• Current
• Temperature
• Pressure
• Humidity
• Illuminance
• Luminance
• Concentration
• SoundLevel
• MagneticField
• RotationalSpeed
• Torque
• Energy
• UvIndex
• Ph
• Conductivity
• ParticulateMatter
• Turbidity
• Salinity
• Radiation
• SoilMoisture

std.wifi {#std-wifi}

Standard library namespace.

Types

• WifiConnection
• SignalStrength
• NetworkStatus

Global functions

Top-level functions available in every Spanda program.

assert {#fn-assert}

fn assert() -> Void

Assert a condition at runtime (test / verify blocks).

channel {#fn-channel}

fn channel() -> Channel

Create an async channel for task communication.

deserialize {#fn-deserialize}

fn deserialize(format: String) -> Void

Deserialize a value from string (format parameter).

goal {#fn-goal}

fn goal(text: String) -> Goal

Create an agent goal from text.

peer_send {#fn-peer_send}

fn peer_send(peer: String, topic: String, value: Void) -> Void

Publish to a peer robot over the fleet bus.

pose {#fn-pose}

fn pose(theta: Number(rad), x: Number(m), y: Number(m), z: Number(m)) -> Pose

Construct a Pose from coordinates (optional z).

recall {#fn-recall}

fn recall(key: String) -> Memory

Recall a value from agent memory by key.

recv {#fn-recv}

fn recv() -> Void

Receive a value from a channel.

recv_agent {#fn-recv_agent}

fn recv_agent() -> Void

Receive a message from another agent.

send {#fn-send}

fn send() -> Void

Send a value on a channel.

send_agent {#fn-send_agent}

fn send_agent(to: String, value: Void) -> Void

Send a message to another agent.

serialize {#fn-serialize}

fn serialize(format: String) -> String

Serialize a value to string (format parameter).

trajectory {#fn-trajectory}

fn trajectory(from: Pose, steps: Number(none), to: Pose) -> Path

Interpolate a path between two poses.

transform {#fn-transform}

fn transform(from: String, pose: Pose, to: String) -> Transform

Transform a pose between coordinate frames.

velocity {#fn-velocity}

fn velocity(angular: Number(rad/s), linear: Number(m/s)) -> Velocity

Construct a Velocity from linear and angular components.

Robot methods

Methods on the implicit robot receiver inside behavior blocks.

robot.connectivity_link {#robot-connectivity_link}

robot.connectivity_link() -> String

Built-in method.

robot.identity {#robot-identity}

robot.identity() -> RobotIdentity

Robot identity for signing and audit.

robot.in_geofence {#robot-in_geofence}

robot.in_geofence(String) -> Bool

Built-in method.

robot.in_zone {#robot-in_zone}

robot.in_zone(String) -> Bool

True when the robot is inside a named zone.

robot.pose {#robot-pose}

robot.pose() -> Pose

Current robot pose.

robot.sim_identity {#robot-sim_identity}

robot.sim_identity() -> SimIdentity

Built-in method.

robot.velocity {#robot-velocity}

robot.velocity() -> Velocity

Current robot velocity.

Type methods

Built-in methods on sensor, actuator, AI, safety, and twin types. Actuator/sensor instances use the type declared in the robot graph.

AdafruitBH1750 {#type-AdafruitBH1750}

calibrate {#type-AdafruitBH1750-calibrate}

adafruitbh1750.calibrate() -> Void

Built-in method.

read {#type-AdafruitBH1750-read}

adafruitbh1750.read() -> Number(lux)

Built-in method.

AdafruitVEML6075 {#type-AdafruitVEML6075}

calibrate {#type-AdafruitVEML6075-calibrate}

adafruitveml6075.calibrate() -> Void

Built-in method.

read {#type-AdafruitVEML6075-read}

adafruitveml6075.read() -> Number(uvi)

Built-in method.

AdafruitVL53L0X {#type-AdafruitVL53L0X}

calibrate {#type-AdafruitVL53L0X-calibrate}

adafruitvl53l0x.calibrate() -> Void

Built-in method.

read {#type-AdafruitVL53L0X-read}

adafruitvl53l0x.read() -> Number(m)

Built-in method.

Agent {#type-Agent}

plan {#type-Agent-plan}

agent.plan() -> Void

Built-in method.

AtlasPH {#type-AtlasPH}

calibrate {#type-AtlasPH-calibrate}

atlasph.calibrate() -> Void

Built-in method.

read {#type-AtlasPH-read}

atlasph.read() -> Number(pH)

Built-in method.

AtlasSalinity {#type-AtlasSalinity}

calibrate {#type-AtlasSalinity-calibrate}

atlassalinity.calibrate() -> Void

Built-in method.

read {#type-AtlasSalinity-read}

atlassalinity.read() -> Number(ppt)

Built-in method.

BoschBME280 {#type-BoschBME280}

calibrate {#type-BoschBME280-calibrate}

boschbme280.calibrate() -> Void

Built-in method.

read {#type-BoschBME280-read}

boschbme280.read() -> Number(rh)

Built-in method.

BoschBMP388 {#type-BoschBMP388}

calibrate {#type-BoschBMP388-calibrate}

boschbmp388.calibrate() -> Void

Built-in method.

read {#type-BoschBMP388-read}

boschbmp388.read() -> Number(m)

Built-in method.

BoschBNO055 {#type-BoschBNO055}

calibrate {#type-BoschBNO055-calibrate}

boschbno055.calibrate() -> Void

Built-in method.

read {#type-BoschBNO055-read}

boschbno055.read() -> IMUReading

Built-in method.

Camera {#type-Camera}

analyze {#type-Camera-analyze}

camera.analyze() -> Detection

Built-in method.

frame {#type-Camera-frame}

camera.frame() -> CameraFrame

Built-in method.

read {#type-Camera-read}

camera.read() -> CameraFrame

Read latest sensor data.

DfrobotTurbidity {#type-DfrobotTurbidity}

calibrate {#type-DfrobotTurbidity-calibrate}

dfrobotturbidity.calibrate() -> Void

Built-in method.

read {#type-DfrobotTurbidity-read}

dfrobotturbidity.read() -> Number(NTU)

Built-in method.

DifferentialDrive {#type-DifferentialDrive}

drive {#type-DifferentialDrive-drive}

differentialdrive.drive(angular: Number(rad/s), linear: Number(m/s)) -> Void

Drive with linear and angular velocity (non-AI); runtime-clamped by max_speed / max_angular. ActionProposal fields cannot feed drive().

execute {#type-DifferentialDrive-execute}

differentialdrive.execute(SafeAction) -> Void

Execute a safety-validated SafeAction (only path for AI motion).

follow {#type-DifferentialDrive-follow}

differentialdrive.follow(path: Path) -> Void

Follow a trajectory path. Cruise speed is clamped by safety.max_speed / zone caps; ActionProposal fields cannot feed follow().

stop {#type-DifferentialDrive-stop}

differentialdrive.stop() -> Void

Stop all motion.

DroneRotors {#type-DroneRotors}

hover {#type-DroneRotors-hover}

dronerotors.hover() -> Void

Built-in method.

set_thrust {#type-DroneRotors-set_thrust}

dronerotors.set_thrust(thrust: Number(none)) -> Void

Built-in method.

GqGMC {#type-GqGMC}

calibrate {#type-GqGMC-calibrate}

gqgmc.calibrate() -> Void

Built-in method.

read {#type-GqGMC-read}

gqgmc.read() -> Void

Built-in method.

HokuyoUST10 {#type-HokuyoUST10}

calibrate {#type-HokuyoUST10-calibrate}

hokuyoust10.calibrate() -> Void

Built-in method.

read {#type-HokuyoUST10-read}

hokuyoust10.read() -> Scan

Built-in method.

HokuyoUTM30 {#type-HokuyoUTM30}

calibrate {#type-HokuyoUTM30-calibrate}

hokuyoutm30.calibrate() -> Void

Built-in method.

read {#type-HokuyoUTM30-read}

hokuyoutm30.read() -> Scan

Built-in method.

IntelRealSenseD435 {#type-IntelRealSenseD435}

calibrate {#type-IntelRealSenseD435-calibrate}

intelrealsensed435.calibrate() -> Void

Built-in method.

read {#type-IntelRealSenseD435-read}

intelrealsensed435.read() -> Scan

Built-in method.

IntelRealSenseD455 {#type-IntelRealSenseD455}

calibrate {#type-IntelRealSenseD455-calibrate}

intelrealsensed455.calibrate() -> Void

Built-in method.

read {#type-IntelRealSenseD455-read}

intelrealsensed455.read() -> Scan

Built-in method.

LLM {#type-LLM}

reason {#type-LLM-reason}

llm.reason(goal: Goal, input: Scan, prompt: String) -> ActionProposal

Run LLM reasoning over sensor input and goal.

summarize {#type-LLM-summarize}

llm.summarize(input: Scan) -> Completion

Summarize sensor input.

Lidar {#type-Lidar}

nearest_distance {#type-Lidar-nearest_distance}

lidar.nearest_distance() -> Number(m)

Built-in method.

read {#type-Lidar-read}

lidar.read() -> Scan

Read latest sensor data.

OusterOS1 {#type-OusterOS1}

calibrate {#type-OusterOS1-calibrate}

ousteros1.calibrate() -> Void

Built-in method.

read {#type-OusterOS1-read}

ousteros1.read() -> Scan

Built-in method.

PlantowerPMS5003 {#type-PlantowerPMS5003}

calibrate {#type-PlantowerPMS5003-calibrate}

plantowerpms5003.calibrate() -> Void

Built-in method.

read {#type-PlantowerPMS5003-read}

plantowerpms5003.read() -> Number(ug/m3)

Built-in method.

RoboticArm {#type-RoboticArm}

grip {#type-RoboticArm-grip}

roboticarm.grip() -> Void

Built-in method.

move_to {#type-RoboticArm-move_to}

roboticarm.move_to(x: Number(m), y: Number(m), z: Number(m)) -> Void

Built-in method.

release {#type-RoboticArm-release}

roboticarm.release() -> Void

Built-in method.

Safety {#type-Safety}

validate {#type-Safety-validate}

safety.validate(ActionProposal) -> SafeAction

Validate an ActionProposal; clamps max_speed / max_angular and returns SafeAction.

SparkfunEC {#type-SparkfunEC}

calibrate {#type-SparkfunEC-calibrate}

sparkfunec.calibrate() -> Void

Built-in method.

read {#type-SparkfunEC-read}

sparkfunec.read() -> Number(uS/cm)

Built-in method.

SparkfunLSM9DS1 {#type-SparkfunLSM9DS1}

calibrate {#type-SparkfunLSM9DS1-calibrate}

sparkfunlsm9ds1.calibrate() -> Void

Built-in method.

read {#type-SparkfunLSM9DS1-read}

sparkfunlsm9ds1.read() -> IMUReading

Built-in method.

Twin {#type-Twin}

frame_count {#type-Twin-frame_count}

twin.frame_count() -> Number(none)

Built-in method.

mirror {#type-Twin-mirror}

twin.mirror(field: String) -> Pose

Mirror a field from the digital twin.

pose {#type-Twin-pose}

twin.pose() -> Pose

Built-in method.

replay {#type-Twin-replay}

twin.replay(field: String, index: Number(none)) -> Pose

Replay twin state at an index.

velocity {#type-Twin-velocity}

twin.velocity() -> Velocity

Built-in method.

UbloxNEOM8N {#type-UbloxNEOM8N}

calibrate {#type-UbloxNEOM8N-calibrate}

ubloxneom8n.calibrate() -> Void

Built-in method.

read {#type-UbloxNEOM8N-read}

ubloxneom8n.read() -> Void

Built-in method.

VegetronixSoil {#type-VegetronixSoil}

calibrate {#type-VegetronixSoil-calibrate}

vegetronixsoil.calibrate() -> Void

Built-in method.

read {#type-VegetronixSoil-read}

vegetronixsoil.read() -> Number(%VWC)

Built-in method.

VelodyneVLP16 {#type-VelodyneVLP16}

calibrate {#type-VelodyneVLP16-calibrate}

velodynevlp16.calibrate() -> Void

Built-in method.

read {#type-VelodyneVLP16-read}

velodynevlp16.read() -> Scan

Built-in method.

VelodyneVLP32 {#type-VelodyneVLP32}

calibrate {#type-VelodyneVLP32-calibrate}

velodynevlp32.calibrate() -> Void

Built-in method.

read {#type-VelodyneVLP32-read}

velodynevlp32.read() -> Scan

Built-in method.

VisionModel {#type-VisionModel}

detect {#type-VisionModel-detect}

visionmodel.detect(CameraFrame) -> Detection

Built-in method.

WaveshareUWMF {#type-WaveshareUWMF}

calibrate {#type-WaveshareUWMF-calibrate}

waveshareuwmf.calibrate() -> Void

Built-in method.

read {#type-WaveshareUWMF-read}

waveshareuwmf.read() -> Number(m)

Built-in method.

YdlidarG4 {#type-YdlidarG4}

calibrate {#type-YdlidarG4-calibrate}

ydlidarg4.calibrate() -> Void

Built-in method.

read {#type-YdlidarG4-read}

ydlidarg4.read() -> Scan

Built-in method.

YdlidarX4 {#type-YdlidarX4}

calibrate {#type-YdlidarX4-calibrate}

ydlidarx4.calibrate() -> Void

Built-in method.

read {#type-YdlidarX4-read}

ydlidarx4.read() -> Scan

Built-in method.

Object properties

Fields on structured runtime values returned by sensors and AI.

Detection

Field	Type
confidence	Number(none)
label	String
nearest_distance	Number(m)

FusedObservation

Field	Type
count	Number(none)
pose	Pose

IMUReading

Field	Type
pitch	Number(rad)
roll	Number(rad)
yaw	Number(rad)

Scan properties

Fields on LiDAR Scan values.

Field	Type
nearest_distance	Number(m)

Hardware sensor libraries

Vendor sensor drivers registered in the runtime. Each sensor type exposes read() and calibrate() unless noted otherwise.

bosch.bme280

bme280 — Bosch v1.0.0: Bosch BME280 environmental sensor (humidity, pressure, temperature)

sparkfun.ec

ec — SparkFun v1.0.0: SparkFun conductivity sensor

vegetronix.soil

soil — Vegetronix v1.0.0: Vegetronix soil moisture sensor

intel.realsense

realsense — Intel v1.0.0: Intel RealSense depth cameras

atlas.salinity

salinity — Atlas v1.0.0: Atlas Scientific salinity sensor

adafruit.veml6075

veml6075 — Adafruit v1.0.0: Adafruit VEML6075 UV index sensor

velodyne.vlp16

vlp16 — Velodyne v1.0.0: Velodyne VLP-16 3D LiDAR puck

velodyne.vlp32

vlp32 — Velodyne v1.0.0: Velodyne VLP-32C ultra puck

plantower.pms5003

pms5003 — Plantower v1.0.0: Plantower PMS5003 particulate matter sensor

dfrobot.turbidity

turbidity — DFRobot v1.0.0: DFRobot turbidity sensor

atlas.ph

ph — Atlas v1.0.0: Atlas Scientific pH sensor

adafruit.bh1750

bh1750 — Adafruit v1.0.0: Adafruit BH1750 digital light sensor

adafruit.vl53l0x

vl53l0x — Adafruit v1.0.0: Adafruit VL53L0X time-of-flight distance sensor

sparkfun.lsm9ds1

lsm9ds1 — SparkFun v1.0.0: SparkFun LSM9DS1 9-DOF IMU breakout

ublox.neo_m8n

neo_m8n — u-blox v1.0.0: u-blox NEO-M8N multi-GNSS receiver (UART NMEA)

hokuyo.utm30

utm30 — Hokuyo v1.0.0: Hokuyo UTM-30LX-EW outdoor LiDAR

ouster.os1

os1 — Ouster v1.0.0: Ouster OS1 digital LiDAR sensor

hokuyo.ust10

ust10 — Hokuyo v1.0.0: Hokuyo UST-10LX 2D LiDAR

bosch.bno055

bno055 — Bosch v1.0.0: Bosch BNO055 9-DOF absolute orientation IMU

bosch.bmp388

bmp388 — Bosch v1.0.0: Bosch BMP388 barometric pressure sensor

waveshare.uwmf

uwmf — Waveshare v1.0.0: Waveshare ultrasonic distance module

ydlidar.g4

g4 — YDLIDAR v1.0.0: YDLIDAR G4 2D LiDAR

gq.gmc

gmc — GQ v1.0.0: GQ GMC geiger counter

ydlidar.x4

x4 — YDLIDAR v1.0.0: YDLIDAR X4 2D LiDAR

CLI reference (man pages)

Manual-page style reference for the spanda command-line tool. Individual pages also live under man/.

spanda(1)

NAME

spanda — Spanda autonomous systems platform toolchain

SYNOPSIS

spanda <command> [options] [arguments]

DESCRIPTION

The Spanda CLI drives the autonomous systems platform: check, verify, simulate, replay, fleet, and document .sd programs.

COMMANDS

• check
• verify
• run
• sim
• replay
• telemetry
• test
• readiness
• assure
• diagnose
• heal
• continuity
• fleet
• package
• trace
• security
• fmt
• lint
• doc
• man
• reference
• codegen
• debug

Package commands: init, build, test, add, remove, install, publish, registry search, registry info. See packages.md.

spanda-check(1) {#cli-check}

NAME

check — Type-check and parse a Spanda program or project.

SYNOPSIS

spanda check [--json] [<file.sd> | --project]

DESCRIPTION

Type-check and parse a Spanda program or project.

OPTIONS

--json — machine-readable diagnostics --readiness-json — readiness + recovery + continuity policy hints --project — check all modules in the current project

EXAMPLES

spanda check examples/rover.sd
spanda check --project

EXIT STATUS

0 on success; 1 on parse, type, or lint errors.

FILES

spanda.toml — project manifest when using --project

SEE ALSO

spanda-verify(1), spanda-run(1), spanda-continuity(1)

spanda-verify(1) {#cli-verify}

NAME

verify — Check hardware compatibility for a deploy target (not formal verification). Alias: spanda compatibility.

SYNOPSIS

spanda verify [--json] [--target <profile>] [--all-targets] [--simulate] <file.sd>

DESCRIPTION

Check hardware compatibility for a deploy target (not formal verification). Alias: spanda compatibility.

OPTIONS

--target — hardware profile name --all-targets — compatibility matrix --simulate — include simulator checks --json — JSON report --strict-certify — fail when certify metadata is missing/incomplete (metadata only)

EXAMPLES

spanda verify robot.sd --target RoverV1
spanda compatibility robot.sd --all-targets --simulate

EXIT STATUS

0 when compatible; 1 on compatibility failures or errors.

FILES

Hardware profile definitions in the program or hardware/ package paths.

SEE ALSO

spanda-check(1), spanda-run(1), verification-vocabulary.md

spanda-run(1) {#cli-run}

NAME

run — Execute a Spanda program on the interpreter backend.

SYNOPSIS

spanda run [--json] [--verbose] [--trace-*] [--record] [--persist-telemetry] <file.sd>

DESCRIPTION

Execute a Spanda program on the interpreter backend.

OPTIONS

--trace-scheduler, --trace-tasks, --trace-triggers, --trace-events — scheduler telemetry --trace-realtime, --metrics-json — realtime metrics --record — write mission trace --persist-telemetry — append device/sensor/heartbeat events to .spanda/telemetry-store.jsonl

EXAMPLES

spanda run examples/rover.sd
spanda run robot.sd --trace-realtime --metrics-json
spanda run rover.sd --persist-telemetry

EXIT STATUS

0 on successful execution; 1 on runtime or compile errors.

FILES

Mission traces when using --record (default: mission.trace). Persistent telemetry when using --persist-telemetry (.spanda/telemetry-store.jsonl).

SEE ALSO

spanda-sim(1), spanda-replay(1)

spanda-sim(1) {#cli-sim}

NAME

sim — Run a program in the built-in simulator with optional trace recording.

SYNOPSIS

spanda sim [--json] [--replay] [--wall-clock] [--record] [--trace-*] <file.sd>

DESCRIPTION

Run a program in the built-in simulator with optional trace recording.

OPTIONS

--replay — replay mode --wall-clock — real-time pacing --record — mission trace output

EXAMPLES

spanda sim examples/rover.sd --record
spanda sim robot.sd --wall-clock

EXIT STATUS

0 on successful simulation; 1 on errors.

FILES

Mission traces when using --record.

SEE ALSO

spanda-run(1), spanda-replay(1), spanda-telemetry(1)

spanda-replay(1) {#cli-replay}

NAME

replay — Replay or deterministically verify a recorded mission trace.

SYNOPSIS

spanda replay <mission.trace> [--from T+mm:ss] [--deterministic] [--playback]

DESCRIPTION

Replay or deterministically verify a recorded mission trace.

OPTIONS

--from — start offset --deterministic — verify reproducibility --playback — frame-by-frame playback

EXAMPLES

spanda replay mission.trace --deterministic
spanda replay mission.trace --playback --from T+00:30

EXIT STATUS

0 when replay succeeds or deterministic check passes; 1 otherwise.

FILES

Input mission trace file (.trace).

SEE ALSO

spanda-sim(1), spanda-run(1)

spanda-telemetry(1) {#cli-telemetry}

NAME

telemetry — Query the persistent telemetry store written by --persist-telemetry or SPANDA_TELEMETRY_STORE=1.

SYNOPSIS

spanda telemetry list|latest|heartbeats|devices|stats|export|prometheus|otlp|push|serve|sessions|replay|info [flags]

DESCRIPTION

Query the persistent telemetry store written by --persist-telemetry or SPANDA_TELEMETRY_STORE=1.

OPTIONS

list — filter by device, sensor, task, session, kind, since, limit latest — most recent device metric, sensor read, task heartbeat, or device liveness heartbeats / devices — index sidecar for tasks and devices stats — event counts (includes session and runtime_metrics) info — backend, paths, retention, migration backup sessions — list persisted run sessions with linked mission traces replay — replay the mission trace linked to a session (--record runs) export — copy event log (JSONL from SQLite when needed) prometheus — Prometheus text exposition otlp — OTLP/JSON metrics export push — POST OTLP/JSON to a remote collector (--endpoint or SPANDA_OTLP_ENDPOINT) serve — HTTP server (/metrics, /otlp/v1/metrics, /healthz)

EXAMPLES

spanda telemetry stats
spanda telemetry info
spanda telemetry push --endpoint http://localhost:4318/v1/metrics
spanda telemetry sessions --json
spanda telemetry replay --session rover-123 --deterministic

EXIT STATUS

0 on success; 1 when the store cannot be read.

FILES

.spanda/telemetry-store.jsonl or .spanda/telemetry-store.db when SPANDA_TELEMETRY_BACKEND=sqlite (override with SPANDA_TELEMETRY_STORE_PATH).

SEE ALSO

spanda-run(1), spanda-sim(1)

spanda-test(1) {#cli-test}

NAME

test — Run in-language test blocks and package test suites for a Spanda project.

SYNOPSIS

spanda test [--project <dir>]

DESCRIPTION

Run in-language test blocks and package test suites for a Spanda project.

OPTIONS

--project — project root (default: current directory)

EXAMPLES

spanda test
spanda test --project examples/rover

EXIT STATUS

0 when all tests pass; 1 on failures.

FILES

spanda.toml, spanda.lock, project .sd sources.

SEE ALSO

spanda-check(1), spanda-package(1)

spanda-readiness(1) {#cli-readiness}

NAME

readiness — Evaluate operational readiness: health, safety, fleet, and deployment gates.

SYNOPSIS

spanda readiness [--json] [--readiness-json] <file.sd>

DESCRIPTION

Evaluate operational readiness: health, safety, fleet, and deployment gates.

OPTIONS

--json / --readiness-json — structured readiness report

EXAMPLES

spanda readiness robot.sd --readiness-json

EXIT STATUS

0 when ready; 1 when blocking issues are found.

FILES

Readiness reports may reference spanda.toml safety metadata.

SEE ALSO

spanda-verify(1), spanda-assure(1)

spanda-assure(1) {#cli-assure}

NAME

assure — Run assurance workflows: anomaly coverage, prognostics, and assurance cases.

SYNOPSIS

spanda assure [--json] <file.sd>

DESCRIPTION

Run assurance workflows: anomaly coverage, prognostics, and assurance cases.

OPTIONS

--json — machine-readable assurance report

EXAMPLES

spanda assure robot.sd --json

EXIT STATUS

0 when assurance checks pass; 1 on gaps or violations.

FILES

Assurance metadata in program declarations.

SEE ALSO

spanda-readiness(1), spanda-diagnose(1)

spanda-diagnose(1) {#cli-diagnose}

NAME

diagnose — Diagnose failures from static analysis and optional mission traces.

SYNOPSIS

spanda diagnose [--json] <file.sd> [<mission.trace>]

DESCRIPTION

Diagnose failures from static analysis and optional mission traces.

OPTIONS

--json — structured diagnosis report

EXAMPLES

spanda diagnose robot.sd
spanda diagnose robot.sd mission.trace

EXIT STATUS

0 when diagnosis completes; 1 on errors.

FILES

Optional mission trace input.

SEE ALSO

spanda-assure(1), spanda-heal(1)

spanda-heal(1) {#cli-heal}

NAME

heal — Execute self-healing and recovery policies declared in the program.

SYNOPSIS

spanda heal [--json] <file.sd>

DESCRIPTION

Execute self-healing and recovery policies declared in the program.

OPTIONS

--json — recovery report

EXAMPLES

spanda heal robot.sd --json

EXIT STATUS

0 when recovery succeeds; 1 on unrecoverable faults.

FILES

Recovery policies in .sd source.

SEE ALSO

spanda-diagnose(1), spanda-recovery(1)

spanda-continuity(1) {#cli-continuity}

NAME

continuity — Mission continuity, takeover, delegation, and succession planning.

SYNOPSIS

spanda continuity|takeover|delegate|succession <file.sd> [options]

DESCRIPTION

Mission continuity, takeover, delegation, and succession planning.

OPTIONS

--failed <name> — failed robot or entity --progress <pct> — mission progress percent --trigger <kind> — continuity trigger (e.g. robot_failed) --successor / --to <name> — designated successor for takeover/delegate --scope fleet|swarm|robot — succession scope --json / --markdown / --html — report format

EXAMPLES

spanda continuity examples/showcase/continuity/warehouse.sd --failed ScannerAlpha --progress 72
spanda takeover examples/showcase/takeover/patrol.sd --failed RoverA
spanda delegate examples/showcase/delegation/survey.sd --failed SurveyBot --to RelayBot
spanda succession examples/showcase/fleet_succession/delivery.sd --scope fleet
spanda demo continuity

EXIT STATUS

0 when planning succeeds; 1 on validation or safety gate failures.

FILES

continuity_policy and mission_plan declarations in .sd source.

SEE ALSO

spanda-recovery(1), spanda-fleet(1), mission-continuity.md

spanda-fleet(1) {#cli-fleet}

NAME

fleet — Run a multi-robot fleet program with peer communication.

SYNOPSIS

spanda fleet run [--json] [--trace-*] <file.sd>

DESCRIPTION

Run a multi-robot fleet program with peer communication.

OPTIONS

Same trace flags as spanda run.

EXAMPLES

spanda fleet run examples/communication/multi_robot_fleet.sd

EXIT STATUS

0 on successful fleet run; 1 on errors.

FILES

Fleet mesh state when using remote agents.

SEE ALSO

spanda-run(1)

spanda-package(1) {#cli-package}

NAME

package — Manage Spanda packages: manifests, dependencies, builds, and registry operations.

SYNOPSIS

spanda <init|build|test|add|remove|install|publish|registry> [options]

DESCRIPTION

Manage Spanda packages: manifests, dependencies, builds, and registry operations.

OPTIONS

See spanda init, build, test, add, remove, install, publish, registry search, registry info.

EXAMPLES

spanda init my-robot
spanda add std.robotics
spanda publish

EXIT STATUS

0 on success; 1 on manifest, lockfile, or registry errors.

FILES

spanda.toml, spanda.lock, packages/ registry mirror.

SEE ALSO

spanda-check(1), spanda-test(1)

spanda-trace(1) {#cli-trace}

NAME

trace — Record scheduler, task, trigger, and event traces from a program run.

SYNOPSIS

spanda trace [--json] [--out <file>] <file.sd>

DESCRIPTION

Record scheduler, task, trigger, and event traces from a program run.

OPTIONS

--out — trace output path --json — structured trace summary

EXAMPLES

spanda trace robot.sd --out mission.trace

EXIT STATUS

0 on success; 1 on runtime errors.

FILES

Output trace file (.trace).

SEE ALSO

spanda-replay(1), spanda-run(1)

spanda-security(1) {#cli-security}

NAME

security — Validate security policies, identities, and audit configuration.

SYNOPSIS

spanda security <check|audit> [--json] <file.sd>

DESCRIPTION

Validate security policies, identities, and audit configuration.

OPTIONS

check — static security validation audit — audit log review --json — machine-readable report

EXAMPLES

spanda security check robot.sd --json
spanda security audit robot.sd

EXIT STATUS

0 when policies pass; 1 on violations.

FILES

Security metadata in program and spanda.toml when present.

SEE ALSO

spanda-verify(1), spanda-readiness(1)

spanda-fmt(1) {#cli-fmt}

NAME

fmt — Format Spanda source to canonical style.

SYNOPSIS

spanda fmt [--json] <file.sd>

DESCRIPTION

Format Spanda source to canonical style.

OPTIONS

--json — report whether the file changed

EXAMPLES

spanda fmt examples/rover.sd

EXIT STATUS

0 on success; 1 on parse errors.

FILES

In-place .sd source file.

SEE ALSO

spanda-check(1)

spanda-lint(1) {#cli-lint}

NAME

lint — Run linter rules beyond parse/type checking.

SYNOPSIS

spanda lint [--json] <file.sd>

DESCRIPTION

Run linter rules beyond parse/type checking.

OPTIONS

--json — structured lint report

EXAMPLES

spanda lint robot.sd

EXIT STATUS

0 when no lint issues; 1 when issues are found.

FILES

Input .sd source file.

SEE ALSO

spanda-check(1)

spanda-doc(1) {#cli-doc}

NAME

doc — Generate JavaDoc-style API docs for .sd modules (markdown or HTML).

SYNOPSIS

spanda doc [--json] [--html] [--out <file>] <file.sd|dir/>

DESCRIPTION

Generate JavaDoc-style API docs for .sd modules (markdown or HTML).

OPTIONS

--out — write output file or directory --html — emit HTML instead of markdown --json — wrap output in JSON

EXAMPLES

spanda doc module.sd --out module-api.md
spanda doc --html examples/

EXIT STATUS

0 on success; 1 on lex/parse errors.

FILES

Output docs under --out or stdout.

SEE ALSO

spanda-reference(1), spanda-man(1)

spanda-man(1) {#cli-man}

NAME

man — Display man-page style documentation for Spanda CLI commands.

SYNOPSIS

spanda man [<command>] [--roff]

DESCRIPTION

Display man-page style documentation for Spanda CLI commands.

OPTIONS

--roff — emit roff for Unix man viewers No argument — list available pages

EXAMPLES

spanda man
spanda man verify
spanda man run --roff

EXIT STATUS

0 on success; 1 when the command page is not found.

FILES

Man pages are generated from compiler metadata into docs/man/.

SEE ALSO

spanda-reference(1), spanda-doc(1)

spanda-reference(1) {#cli-reference}

NAME

reference — Emit the full Spanda language reference and optional man pages.

SYNOPSIS

spanda reference [--json] [--out <file.md>] [--man-dir <dir>]

DESCRIPTION

Emit the full Spanda language reference and optional man pages.

OPTIONS

--out — write reference markdown --man-dir — write man pages --json — wrap markdown in JSON

EXAMPLES

spanda reference --out docs/spanda-reference.md --man-dir docs/man

EXIT STATUS

0 on success.

FILES

docs/spanda-reference.md, docs/man/ when generating.

SEE ALSO

spanda-doc(1), spanda-man(1)

spanda-codegen(1) {#cli-codegen}

NAME

codegen — Generate deployable artifacts from a Spanda program.

SYNOPSIS

spanda codegen [--target native|wasm|esp32] [--out <file>] <file.sd>

DESCRIPTION

Generate deployable artifacts from a Spanda program.

OPTIONS

--target — output format

EXAMPLES

spanda codegen --target wasm robot.sd --out robot.wasm

EXIT STATUS

0 on success; 1 on codegen errors.

FILES

Generated artifact at --out.

SEE ALSO

spanda-deploy(1), spanda-compile-native(1)

spanda-debug(1) {#cli-debug}

NAME

debug — Start an interactive debug session.

SYNOPSIS

spanda debug [--break <line>] <file.sd>

DESCRIPTION

Start an interactive debug session.

OPTIONS

--break — initial breakpoint line

EXAMPLES

spanda debug robot.sd --break 42

EXIT STATUS

0 on clean exit; 1 on errors.

FILES

Debug session uses source .sd file.

SEE ALSO

spanda-run(1)