Skip to content

README: Drone

Purpose

Defines the KNAT surface for a Drone — a modular aerial system with distributed propulsion, fly-by-wire control, and optional autonomous behavior.

Enables clients to:

  • observe propulsion, attitude, and motion state
  • inject control inputs (manual or autonomous)
  • bind pilot or operate autonomously
  • control camera framing (cinemabot integration)
  • subscribe to signals (collision, battery, instability)

Conceptual Model

A drone is a force-distributed system, not a drivetrain.

Vehicle → mechanical transmission
Drone   → thrust + control distribution

It may be:

  • pilot-controlled
  • assisted
  • autonomous

Root Graph

/drone::<entity_id>/
    /spec
    /engine
    /location
    /propulsion
    /attitude
    /physics
    /control
    /pilot
    /camera
    /signals

Spec Surface

/drone::<id>/spec/ref
/drone::<id>/spec/genome
/drone::<id>/spec/architecture

Same semantics as vehicle.

Propulsion Surface

/drone::<id>/propulsion/motor_<id>/rpm
/drone::<id>/propulsion/motor_<id>/thrust
/drone::<id>/propulsion/total_thrust

Represents distributed thrust generation.

Attitude Surface

/drone::<id>/attitude/pitch
/drone::<id>/attitude/roll
/drone::<id>/attitude/yaw
/drone::<id>/attitude/angular_velocity

Orientation and rotational dynamics.

Physics Surface

Shared with other entities:

/world/physics/velocity
/world/physics/altitude

Control Surface

/drone/control/pitch
/drone/control/roll
/drone/control/yaw
/drone/control/throttle
/drone/control/mode

Supports scalar or structured values:

  • direct
  • assist
  • override

Same arbitration model as vehicle

Pilot Surface

/drone::<id>/pilot/bound
/drone::<id>/pilot/entity_id
/drone::<id>/pilot/mode

Modes:

  • manual
  • assist
  • autonomous

Camera Surface

/drone::<id>/camera/target
/drone::<id>/camera/gimbal_pitch
/drone::<id>/camera/gimbal_yaw
/drone::<id>/camera/mode

This is the cinemabot integration surface.

Signals Surface

/drone::<id>/signals/<signal_id>/
    kind
    intensity
    frame

Examples:

  • collision
  • battery_low
  • instability
  • gps_loss

Responsibilities Boundary

DroneOwned     — propulsion + attitude state
PhysicsOwned   — motion integration
PilotOwned     — control input
CinemabotOwned — camera framing

MVP Presence

Minimum snapshot:

  • spec
  • propulsion
  • attitude
  • physics
  • pilot
  • signals
  • frame