Component Reference

Overview

Components define the capabilities and attributes of entities. This page documents all available components, their fields, and usage patterns.

Core Metadata Components

Controller

Identifies which system contributed this entity to the common operating picture.

Fields:

• id (string, optional) - Unique identifier of the controlling system
• node (string, optional) - Node where the controller runs
• origin (string, optional) - ID of another entity from which the controller received this entity (for example a radio)

Example:

controller: {
  id: 'sensor-array-alpha',
  node: 'edge-node-1'
}

When to use: Attach to entities created by your system to track ownership and data provenance.

Lifetime

Defines the temporal validity of an entity. Hydris automatically expires entities when until is reached.

Fields:

• from (Timestamp, optional) - When this entity becomes valid. Set to now automatically if omitted
• until (Timestamp, optional) - When this entity expires
• fresh (Timestamp, optional) - Last time this entity was seen. Updates with an older fresh value are ignored by default

Example:

lifetime: {
  from: new Date('2025-01-15T10:00:00Z'),
  until: new Date('2025-01-15T18:00:00Z'),
  fresh: new Date('2025-01-15T12:00:00Z')
}

When to use:

• Temporary markers or waypoints
• Time-limited detections
• Scheduled events or planned movements
• Historical data with known validity windows

Priority

Controls Quality of Service for bandwidth-constrained networks (DDIL scenarios).

Values:

• PriorityRoutine (1) - Normal day-to-day traffic. May be delayed or coalesced when bandwidth is constrained
• PriorityImmediate (2) - Delay would negatively affect the mission. Sent before lower precedence messages
• PriorityFlash (3) - Extreme urgency. Sent without respecting bandwidth limits. Misuse can jeopardize missions

Example:

priority: Priority.PriorityImmediate

When to use:

• Set PriorityFlash for immediate threats or emergency alerts
• Use PriorityImmediate for detections and tracks
• Use PriorityRoutine for auxiliary information, metadata, or non-urgent updates

Lease

Used by controllers to negotiate exclusivity on an entity. The engine rejects pushes that attempt to change the holder of an active lease.

Fields:

• controller (string) - Controller ID holding the lease
• expires (Timestamp, optional) - When the lease expires

Example:

lease: {
  controller: 'tracker-1',
  expires: new Date('2025-01-15T10:05:00Z')
}

When to use: Lock an entity so only one controller can modify it at a time. Note that leases are local and not distributed vertically.

Routing

Presence of this component marks the entity as routable to other nodes or downstream consumers. Entities without Routing stay local.

Fields:

• channels (Channel[]) - Channels this entity is routed to

Channel fields:

• name (string) - Channel name. The empty string is the default channel

Example:

routing: {
  channels: [{ name: '' }]  // route on the default channel
}

When to use: Any entity that should leave the local node — synced to other nodes, streamed to downstream C2, or bridged over radios.

Spatial Components

GeoSpatialComponent

Physical location in 3D space using WGS84 coordinates.

Fields:

• longitude (double) - Decimal degrees, -180 to 180
• latitude (double) - Decimal degrees, -90 to 90
• altitude (double, optional) - Meters above WGS84 ellipsoid
• covariance (CovarianceMatrix, optional) - Position uncertainty in ENU frame

Example:

geo: {
  longitude: 13.4050,
  latitude: 52.5200,
  altitude: 100,
  covariance: {
    mxx: 25.0,   // East variance (m²)
    myy: 25.0,   // North variance (m²)
    mzz: 100.0   // Up variance (m²)
  }
}

When to use: Nearly all entities that have a physical location. This is the most common component.

BearingComponent

Absolute bearing in the world, relative to the local ENU frame. For root entities this is set directly; for child entities with a PolarOffset the engine computes it by composing down the pose tree.

Fields:

• azimuth (double, optional) - Clockwise angle from true north in degrees [0, 360)
• elevation (double, optional) - Angle above the local horizontal plane in degrees [-90, 90]
• azimuth_extent_deg (double, optional) - Angular extent of the observed object around the center bearing
• elevation_extent_deg (double, optional) - Vertical angular extent of the observed object

For camera evidence, the engine computes the extents from ImageBoundingBox + CameraComponent.fov.

Example:

bearing: {
  azimuth: 270,    // Pointing West
  elevation: 15    // 15 degrees above horizon
}

When to use:

• Camera or sensor pointing direction
• Movement direction for tracks
• Line-of-sight vectors
• Beam directions for RF sensors

OrientationComponent

Absolute orientation in the world, relative to the local ENU frame. For root entities this is set directly; for child entities the engine computes it by composing orientations down the pose tree.

Fields:

• orientation (Quaternion) - Orientation as a unit quaternion (x, y, z, w)
• covariance (CovarianceMatrix, optional) - Orientation uncertainty

Example:

orientation: {
  orientation: { x: 0, y: 0, z: 0.383, w: 0.924 },
}

When to use: Aircraft, drones, or vehicles where full 3D attitude matters beyond simple bearing.

BoundsComponent

Physical extent of an entity as a bounding box.

Fields:

• width_m (float) - Width in meters
• height_m (float) - Height in meters
• depth_m (float) - Depth in meters
• covariance (CovarianceMatrix, optional) - Extent uncertainty (xx=width², yy=height², zz=depth²)

Example:

bounds: {
  width_m: 2.5,
  height_m: 1.8,
  depth_m: 5.2
}

When to use: Vehicles, vessels, or detected objects where the physical size matters for display or collision estimation.

PoseComponent

Defines this entity's position relative to a parent entity's coordinate frame, forming a transform tree. The engine computes absolute GeoSpatialComponent by walking the tree. If the pose cannot be fully resolved (e.g. missing range on a bearing-only sensor), no geo is produced.

Fields:

• parent (string) - Parent entity ID in the transform tree
• cartesian (CartesianOffset) - Offset in meters (east, north, up)
• polar (PolarOffset) - Offset in azimuth/elevation/range

Only one of cartesian or polar can be set.

CartesianOffset fields:

• east_m (double) - East offset in meters
• north_m (double) - North offset in meters
• up_m (double, optional) - Up offset in meters
• covariance (CovarianceMatrix, optional) - Offset uncertainty
• orientation (Quaternion, optional) - Local orientation

PolarOffset fields:

• azimuth (double) - Angle from the parent's forward axis in degrees [0, 360)
• elevation (double, optional) - Above the parent's horizontal plane in degrees [-90, 90]
• range (double, optional) - Distance in meters. Omit for bearing-only (passive sensor)
• azimuth_error_deg (double, optional) - Azimuth measurement uncertainty (1-sigma)
• elevation_error_deg (double, optional) - Elevation measurement uncertainty (1-sigma)
• range_error_m (double, optional) - Range measurement uncertainty (1-sigma)
• covariance (CovarianceMatrix, optional, deprecated) - Offset uncertainty. Prefer the error fields above; the engine fills covariance from them automatically (and vice versa)
• orientation (Quaternion, optional) - Local orientation

Example:

pose: {
  parent: 'radar-1',
  polar: {
    azimuth: 45.0,
    elevation: 10.0,
    range: 5000
  }
}

When to use: Sensor detections relative to a sensor, camera gimbal joints, or any entity whose position is naturally defined relative to another entity.

TargetPoseComponent

Desired pose for a joint, same shape as PoseComponent's offset. A device-specific reconciler continuously drives the actual PoseComponent toward this target.

Fields:

• cartesian (CartesianOffset) - Target offset in meters
• polar (PolarOffset) - Target offset in azimuth/elevation/range

Only one of cartesian or polar can be set.

Example:

target_pose: {
  polar: {
    azimuth: 180.0,
    elevation: -5.0,
    range: 1000
  }
}

When to use: Commanding a PTZ camera gimbal, robotic arm, or any actuated joint to move to a target position.

Visual Representation

SymbolComponent

Visual representation using military symbology standards.

Fields:

• milStd2525C (string) - MIL-STD-2525C symbol identification code (SIDC)

Common SIDCs:

Example:

symbol: {
  milStd2525C: 'SFGPES----'
}

When to use: Any entity that should appear on a tactical display or map.

InteractivityComponent

UI interaction hints for an entity, such as a custom icon or a reference URL where a user can learn more.

Fields:

• icon (string, optional) - Icon name (use Lucide icon names for max compatibility)
• reference_url (string, optional) - URL where a user can learn more about this entity

Example:

interactivity: {
  icon: 'radio',
  reference_url: 'https://example.com/asset/123'
}

When to use: Entities that benefit from a custom icon in the UI or link to an external detail page.

Sensor and Detection Components

DetectionComponent

Links a detection to its source sensor and provides evidence, bounding box, and confidence.

Fields:

• detectorEntityId (string, optional) - ID of the sensor entity that made this detection
• evidence (string[]) - Entity IDs of evidence that triggered or supports this detection (e.g. the source entity being detected)
• image_bbox (ImageBoundingBox, optional) - Bounding box in the detector's video frame
• confidence (float, optional) - Detection confidence score (0.0–1.0)

ImageBoundingBox fields:

• x (uint32) - Left edge of the bounding box in pixels
• y (uint32) - Top edge of the bounding box in pixels
• width (uint32) - Bounding box width in pixels
• height (uint32) - Bounding box height in pixels
• frame_width (uint32) - Full video frame width in pixels
• frame_height (uint32) - Full video frame height in pixels

Example — camera detection with bounding box:

detection: {
  detectorEntityId: 'camera-north',
  evidence: ['vessel-123'],
  confidence: 0.87,
  imageBbox: {
    x: 312,
    y: 140,
    width: 96,
    height: 54,
    frameWidth: 1920,
    frameHeight: 1080
  }
}

Example — radar detection (no bounding box):

detection: {
  detectorEntityId: 'radar-1',
  evidence: ['track-42'],
  confidence: 0.95
}

When to use: Raw sensor detections before track fusion. See the External Detectors guide for a full walkthrough of pushing detections from a computer-vision pipeline.

TrackComponent

Marks an entity as a fused track and optionally links to track history, prediction geometries, and contributing detections.

Fields:

• tracker (string, optional) - ID of the tracker/fusion engine that owns this track
• history (string, optional) - Entity ID of a GeoShapeComponent containing the track history
• prediction (string, optional) - Entity ID of a GeoShapeComponent containing the predicted forward track
• evidence (string[]) - Entity IDs (typically detections) that contribute to this track
• confidence (float, optional) - Confidence that this is a valid track

Example:

track: {
  tracker: 'fusion-engine-1',
  history: 'track-42.history',
  prediction: 'track-42.orbit',
  evidence: ['det-1', 'det-2', 'det-3'],
  confidence: 0.9
}

When to use: After correlating multiple detections from different sensors into a unified track. Link to history/prediction shape entities for trail and forecast visualization.

SensorComponent

Describes a sensor's coverage area by linking to GeoShapeComponent entities.

Fields:

• coverage (string[]) - Entity IDs of GeoShapeComponent entities that describe the sensor's coverage area

Example:

sensor: {
  coverage: ['radar-1.coverage-left', 'radar-1.coverage-right']
}

When to use: Radars, cameras, or any sensor where you want to visualize the coverage footprint on the map.

LocatorComponent

Indicates this sensor is actively locating another entity.

Fields:

• locatedEntityId (string) - ID of the entity being located/tracked

Example:

locator: {
  locatedEntityId: 'target-001'
}

When to use: Show which sensors are tracking which targets, sensor-to-target associations.

TransponderComponent

Transponder identifiers for AIS (maritime) and ADS-B (aviation) targets.

Fields:

• ais (TransponderAIS, optional) - AIS transponder data
• adsb (TransponderADSB, optional) - ADS-B transponder data

TransponderAIS fields:

• mmsi (uint32, optional) - Maritime Mobile Service Identity
• imo (uint32, optional) - IMO ship identification number
• callsign (string, optional) - Radio callsign
• vessel_name (string, optional) - Vessel name

TransponderADSB fields:

• icao_address (uint32, optional) - ICAO 24-bit aircraft address
• flight_id (string, optional) - Flight identification / callsign

Example:

transponder: {
  ais: {
    mmsi: 211234567,
    imo: 9876543,
    callsign: 'DABC',
    vessel_name: 'MS EXAMPLE'
  }
}

When to use: Entities originating from AIS or ADS-B sources. Set automatically by the AIS and ADS-B builtins.

AdministrativeComponent

Administrative and registration data for vessels, aircraft, or other registered assets.

Fields:

• id (string, optional) - Registration ID (e.g. tail number, hull number)
• flag (string, optional) - Flag state or ICAO type code
• owner (string, optional) - Registered owner or operator
• manufacturer (string, optional) - Manufacturer name
• model (string, optional) - Model designation
• year_built (uint32, optional) - Year of manufacture
• length_m (float, optional) - Length in meters
• width_m (float, optional) - Beam / lateral extent in meters
• height_m (float, optional) - Vertical extent in meters (e.g. air draft)
• tonnage_gt (float, optional) - Gross tonnage
• engine_power_kw (float, optional) - Engine power in kilowatts
• images (string[]) - Image URLs of the asset

Example:

administrative: {
  id: 'D-AIBL',
  owner: 'Lufthansa',
  manufacturer: 'Airbus',
  model: 'A319-112',
  year_built: 2010
}

When to use: Enrichment data for tracked assets. Set automatically by the adsbdb and hexdb enrichment builtins.

Camera and Observation

CameraComponent

Provides video feed URLs and optical parameters for cameras and observation sensors.

Fields:

• streams (array of MediaStream) - List of available media streams
• focal_point (string, optional) - If the camera is PTZ, the entity ID representing where this camera is looking. The device driver reconciles target_pose with physical actuation of the gimbal
• fov (double, optional) - Horizontal field of view in degrees, centered on the entity's azimuth. For varifocal cameras, this is the current effective FOV
• range_min (double, optional) - Minimum detection range in meters (blind zone)
• range_max (double, optional) - Maximum detection range in meters
• fov_wide (double, optional) - Horizontal FOV at widest zoom in degrees (varifocal cameras)
• fov_tele (double, optional) - Horizontal FOV at max zoom in degrees (varifocal cameras)

MediaStream fields:

• label (string) - Display name for this stream
• url (string) - Streaming URL
• protocol (MediaStreamProtocol) - Streaming protocol type
• role (MediaStreamRole) - Stream role
• codec (string) - Video codec (e.g. "H264", "H265")
• width (int32, optional) - Resolution width in pixels
• height (int32, optional) - Resolution height in pixels
• epoch (Timestamp, optional) - Wall-clock time of the first frame (mediaTime=0)

MediaStreamProtocol values:

• MediaStreamProtocolWebrtc - WebRTC stream
• MediaStreamProtocolHls - HLS stream
• MediaStreamProtocolMjpeg - MJPEG stream
• MediaStreamProtocolImage - Static image URL
• MediaStreamProtocolIframe - Embedded iframe
• MediaStreamProtocolRtsp - RTSP stream

MediaStreamRole values:

• MediaStreamRoleMain - Primary high-resolution stream
• MediaStreamRoleSub - Lower-resolution sub stream
• MediaStreamRoleSnapshot - Still image capture

Example:

camera: {
  streams: [
    {
      label: 'Main View',
      url: 'https://camera.example.com/stream1',
      protocol: MediaStreamProtocol.MediaStreamProtocolHls,
      role: MediaStreamRole.MediaStreamRoleMain,
      codec: 'H264',
      width: 1920,
      height: 1080
    },
    {
      label: 'Thermal',
      url: 'https://camera.example.com/thermal',
      protocol: MediaStreamProtocol.MediaStreamProtocolMjpeg,
      role: MediaStreamRole.MediaStreamRoleSub
    }
  ],
  focal_point: 'camera-1.target',
  fov: 60.0,
  range_min: 5,
  range_max: 10000,
  fov_wide: 90.0,
  fov_tele: 3.5
}

When to use: PTZ cameras, UAV feeds, fixed surveillance cameras.

CaptureComponent

Raw payload capture from a device, for example LoRaWAN uplinks or UDP packets.

Fields:

• payload (bytes, optional) - Last raw payload received
• port (uint32, optional) - Application-level port (e.g. LoRaWAN FPort, UDP port)
• content_type (string, optional) - Content type hint (e.g. "application/octet-stream", "application/json")
• captured_by (string, optional) - Entity ID of the device that captured this data
• captured_at (Timestamp, optional) - When the payload was captured
• content (string[]) - Entity IDs of additional captured content, such as artifacts when the payload is too large

Example:

capture: {
  payload: new Uint8Array([0x01, 0x02, 0x03]),
  port: 1,
  content_type: 'application/octet-stream',
  captured_by: 'lorawan-gw-1',
  captured_at: new Date('2025-01-15T10:30:00Z')
}

When to use: IoT/LPWAN devices, raw data ingestion pipelines, protocol decoding.

Task and Assignment

TaskableComponent

Defines an assignable task with context, assignees, and a strongly-typed target describing what input the task accepts.

Fields:

• priority (uint32, optional) - Priority for which task should be shown first (higher = more important)
• label (string, optional) - Human-readable task description
• context (array of TaskableContext) - Entities this task relates to
• assignee (array of TaskableAssignee) - Entities assigned to execute this task
• mode (TaskableMode) - Execution mode
• target (TaskableTarget, optional) - What kind of input this task accepts
• icon (string, optional) - Icon name for the UI
• effect (string, optional) - Human or LLM readable description of the effect this task will have (e.g. "power up the sensor", "closes the entry gate")
• grouping (string, optional) - Group key for emitting multiple alternative options of the same task
• grouping_priority (uint32, optional) - Ranking within the group; a UI may show only the best-ranked alternative
• taxonomy (TaskingTaxonomy, optional) - Semantic meaning of the task (look-at, scan, track, move-to, patrol, follow, ...), independent of target
• schema (Struct, deprecated) - JSON schema describing task parameters. Taskables are now strongly typed via target

TaskableContext/TaskableAssignee fields:

• entityId (string, optional) - ID of referenced entity

TaskableTarget fields (any combination):

• position (TaskableTargetPosition) - Task accepts a single position
• waypoints (TaskableTargetWaypoints) - Task accepts a list of waypoints. max limits the count; loop marks a closed loop (e.g. patrol)
• entity (TaskableTargetEntity) - Task accepts entity IDs as targets. entity restricts to specific IDs (empty = any); max limits the count (default 1)

TaskableMode values:

Example:

taskable: {
  label: 'View with Camera',
  effect: 'points the camera at the target entity',
  context: [
    { entityId: 'target-001' }
  ],
  assignee: [
    { entityId: 'camera-1' }
  ],
  target: {
    entity: { max: 1 }
  },
  taxonomy: { kind: { case: 'observe', value: { kind: { case: 'lookAt', value: {} } } } },
  mode: TaskableMode.TaskableModeExclusive
}

When to use:

• Assign sensors to track targets
• Create inspection tasks
• Coordinate multiple assets on a mission
• Workflow automation between systems

TaskExecutionComponent

An instance of a task being executed. Created by RunTask, referencing a TaskableComponent entity as the definition. The controller that owns the taskable watches for these and executes them.

Fields:

• task (string) - Entity ID of the TaskableComponent that defines this task
• state (TaskExecutionState) - Current execution state, updated by the controller
• reason (string, optional) - Human-readable error or result message
• priority (uint32, optional) - Priority level for PriorityQueue mode (higher = more important)
• target (TaskExecutionTarget, optional) - The concrete target supplied by the caller, matching the taskable's target shape
• parameters (Struct, optional, deprecated) - Untyped parameters. Executions are now strongly typed via target

TaskExecutionTarget (oneof):

• position (PlanarPoint) - A single target position
• waypoints (TaskExecutionTargetWaypoints) - waypoint: list of PlanarPoints
• entity (TaskExecutionTargetEntity) - entity: list of target entity IDs

TaskExecutionState values:

Example:

task_execution: {
  task: 'taskable-view-camera',
  target: {
    kind: { case: 'entity', value: { entity: ['target-001'] } }
  },
  state: TaskExecutionState.TaskExecutionStateRunning
}

When to use: Automatically created by RunTask. Controllers watch for these on their taskable entities and execute accordingly.

Kinematics

KinematicsComponent

Velocity, acceleration, and angular velocity. Linear components use the local East-North-Up (ENU) coordinate frame.

Fields:

• velocityEnu (KinematicsEnu, optional) - Velocity vector in m/s
• accelerationEnu (KinematicsEnu, optional) - Acceleration vector in m/s²
• angularVelocityBody (AngularVelocity, optional) - Angular velocity around the entity's body axes

KinematicsEnu fields:

• east (double, optional) - East component in m/s (or m/s² for acceleration)
• north (double, optional) - North component
• up (double, optional) - Up component
• covariance (CovarianceMatrix, optional) - Velocity/acceleration uncertainty

AngularVelocity fields:

• roll_rate (double) - Roll rate in radians/second
• pitch_rate (double) - Pitch rate in radians/second
• yaw_rate (double) - Yaw rate in radians/second

The ENU frame is a right-handed Cartesian coordinate system with origin at the entity's position, where:

• East axis: tangent to the latitude line, pointing eastward
• North axis: tangent to the longitude line, pointing northward
• Up axis: perpendicular to the WGS84 ellipsoid, pointing away from Earth center

Note: This is NOT a body frame - the axes do not rotate with the entity's heading/attitude.

Example:

kinematics: {
  velocityEnu: {
    east: 10.5,   // Moving east at 10.5 m/s
    north: -5.2,  // Moving south at 5.2 m/s
    up: 0.0       // No vertical movement
  },
  accelerationEnu: {
    east: 0.1,
    north: 0.0,
    up: 0.0
  },
  angularVelocityBody: {
    roll_rate: 0.0,
    pitch_rate: 0.0,
    yaw_rate: 0.1   // Turning right
  }
}

When to use: Moving tracks, aircraft, vehicles, or any entity with known velocity/acceleration.

Geometry

GeoShapeComponent

Defines geographic shapes beyond simple point locations.

Fields:

• geometry (Geometry, optional) - The shape definition
• extrusion (GeometryExtrusion, optional) - 3D extrusion and fill styling

Geometry types:

• planar.point - A single 2.5D point (longitude, latitude, optional altitude)
• planar.line - A path/line defined by multiple points (ring)
• planar.polygon - An enclosed area with optional holes
• planar.circle - A circle defined by center point and radius
• planar.collection - A collection of multiple planar geometries

Each planar geometry can also set line_style (LineStyleSolid, LineStyleDashed, LineStyleDotted).

PlanarPoint fields:

• longitude (double) - Decimal degrees, -180 to 180
• latitude (double) - Decimal degrees, -90 to 90
• altitude (double, optional) - Meters above WGS84 ellipsoid

PlanarPolygon fields:

• outer (PlanarRing) - The outer boundary (must be closed: first point = last point)
• holes (array of PlanarRing, optional) - Interior holes

PlanarCircle fields:

• center (PlanarPoint) - Center point
• radius_m (double) - Radius in meters
• inner_radius_m (double, optional) - Inner radius in meters (omit for solid circle)

GeometryExtrusion fields:

• height_m (double, optional) - Extrusion height in meters
• fill (FillStyle, optional) - Fill styling: color, opacity, texture, texture_scale_m

Example:

shape: {
  geometry: {
    planar: {
      polygon: {
        outer: {
          points: [
            { longitude: 13.4, latitude: 52.5 },
            { longitude: 13.5, latitude: 52.5 },
            { longitude: 13.5, latitude: 52.6 },
            { longitude: 13.4, latitude: 52.6 },
            { longitude: 13.4, latitude: 52.5 }  // Closed ring
          ]
        }
      }
    }
  }
}

When to use: Zones, boundaries, flight corridors, no-fly areas, search areas.

LocalShapeComponent

Geometry defined in a local ENU frame relative to another entity, using meter offsets instead of geographic coordinates.

Fields:

• relative_to (string) - Entity ID whose frame this geometry is defined in
• geometry (LocalGeometry, optional) - The local shape definition
• extrusion (GeometryExtrusion, optional) - 3D extrusion and fill styling (same as GeoShapeComponent)

LocalGeometry types:

• point - A single point (east_m, north_m, optional up_m)
• line - A path defined by multiple local points
• polygon - An enclosed area in local coordinates
• circle - A circle with center in local coordinates and radius in meters
• collection - A collection of multiple local geometries

Each local geometry can also set line_style (LineStyleSolid, LineStyleDashed, LineStyleDotted).

Example:

local_shape: {
  relative_to: 'radar-1',
  geometry: {
    circle: {
      center: { east_m: 0, north_m: 0, up_m: 0 },
      radius_m: 5000
    }
  }
}

When to use: Sensor coverage areas, exclusion zones around assets, or any geometry naturally defined relative to an entity rather than in absolute coordinates.

Classification

ClassificationComponent

Structured classification of what an entity is, using a hierarchical taxonomy.

Fields:

• taxonomy (ClassificationTaxonomy[]) - One or more taxonomy classifications, each with a confidence
• dimension (ClassificationBattleDimension, optional, deprecated) - The battle dimension
• identity (ClassificationIdentity, optional, deprecated) - Friend/foe identification

ClassificationTaxonomy fields:

• confidence (ClassificationConfidence) - confidence (float, 0.0–1.0) and pending (bool)
• kind (oneof) - The classification:
  • person - A person
  • animal - An animal, refinable to air.bird or land.horse
  • infrastructure - Infrastructure, refinable to tower, bridge, road, dam
  • vehicle - A vehicle. Optional unmanned marker plus a domain: land (tracked, two-wheeled, multi-wheeled), air (fixed wing, lighter than air, rotary), sea, subsurface
  • equipment - Equipment, refinable to sensor (radar, EW, CBRN, acoustic, electro-optical; optional emplaced marker)
  • emitter - An RF emitter

Example:

classification: {
  taxonomy: [{
    confidence: { confidence: 0.85 },
    kind: {
      case: 'vehicle',
      value: {
        unmanned: {},
        domain: { case: 'air', value: { kind: { case: 'rotary', value: {} } } }
      }
    }
  }]
}

ClassificationIdentity values (deprecated):

ClassificationBattleDimension values (deprecated):

When to use: Tracks and detections where the type of object is known or estimated, separate from or in addition to MIL-STD-2525C symbology.

Navigation and Mission

NavigationComponent

Live navigation telemetry of an asset - its current mode, arming state, and mission progress.

Fields:

• mode (NavigationMode, optional) - Current navigation mode
• armed (bool, optional) - Whether the asset is armed / active
• emergency (bool, optional) - Emergency flag (squawk 7700, etc.)
• waypoint_current (uint32, optional) - Current waypoint index in the active mission
• waypoint_total (uint32, optional) - Total number of waypoints

NavigationMode values:

Example:

navigation: {
  mode: NavigationMode.NavigationModeAutonomous,
  armed: true,
  waypoint_current: 3,
  waypoint_total: 12
}

When to use: Drones, autonomous vehicles, vessels, or any asset reporting navigation telemetry.

MissionComponent

Groups assets into a mission with a description, destination, and ETA.

Fields:

• members (string[], optional) - Entity IDs of assets participating in this mission
• description (string, optional) - Human-readable status (can be multi-line / markdown)
• destination (string, optional) - Human-readable destination (e.g. port name)
• eta (Timestamp, optional) - Estimated time of arrival

Example:

mission: {
  members: ['vessel-1', 'vessel-2'],
  description: 'Transit to port',
  destination: 'Hamburg',
  eta: new Date('2026-03-15T14:00:00Z')
}

When to use: Vessel voyages with destination/ETA, drone missions, convoy tracking, or any coordinated multi-asset operation.

Link and Power

LinkComponent

Communication link quality and status for an entity, typically set by radio or mesh integrations.

Fields:

• status (LinkStatus, optional) - Link health
• rssi_dbm (sint32, optional) - Received signal strength in dBm
• snr_db (sint32, optional) - Signal-to-noise ratio in dB
• via (string, optional) - Entity ID of the device managing the link
• last_latency_ms (uint32, optional) - Last measured end-to-end latency in milliseconds
• avg_latency_ms (uint32, optional) - Exponential moving average of latency in milliseconds
• last_seen (Timestamp, optional) - Last time data was received over this link
• link_quality_percent (uint32, optional) - Link quality as percentage (0-100)
• tx_power_mw (uint32, optional) - Transmit power in milliwatts
• active_antenna (uint32, optional) - Active antenna index (e.g. 0 or 1 for antenna diversity)
• rf_mode (string, optional) - Protocol-specific RF mode label (e.g. "250Hz", "50Hz")
• packet_rate_hz (uint32, optional) - Packet rate in Hz

LinkStatus values:

Example:

link: {
  status: LinkStatus.LinkStatusConnected,
  rssi_dbm: -85,
  snr_db: 12,
  via: 'meshtastic.radio-1',
  last_latency_ms: 250,
  avg_latency_ms: 180
}

When to use: Set automatically by the Meshtastic builtin for mesh-received entities. Can also be set manually to indicate link quality for any networked asset.

PowerComponent

Battery and power status for an entity.

Fields:

• battery_charge_remaining (float, optional) - Charge level from 0.0 to 1.0
• voltage (float, optional) - Battery or board voltage in volts
• remaining_seconds (uint32, optional) - Estimated remaining operating time in seconds
• current_a (float, optional) - Instantaneous current draw in amps
• capacity_used_mah (float, optional) - Cumulative battery capacity consumed in milliamp-hours

Example:

power: {
  battery_charge_remaining: 0.73,
  voltage: 3.85,
  remaining_seconds: 7200
}

When to use: Battery-powered assets like drones, mesh radios, or remote sensors. Set automatically by the Meshtastic builtin from device telemetry.

Device and Configuration

DeviceComponent

Represents a physical or logical device in the device tree. Describes hardware topology only - can be discovered automatically or created by hand.

Fields:

• parent (string, optional) - Parent device entity ID, forming the device tree. Unset for root (node)
• composition (string[], optional) - Non-direct ancestor entity IDs
• unique_hardware_id (string, optional) - Stable hardware identifier (e.g. USB serial number, MAC address)
• state (DeviceState) - DeviceStatePending, DeviceStateActive, or DeviceStateFailed
• error (string, optional) - Error message if state is failed
• class (string, optional) - Device class (e.g. "usb_serial", "radio", "camera")
• category (string, optional) - Human-readable category for UI grouping (e.g. "Air", "Sea", "Network")
• node (NodeDevice, optional) - Node descriptor (hostname, OS, OS version, arch, CPU count, hydris version, available update, loaded mission pack)
• usb (UsbDevice, optional) - USB descriptor (VID, PID, manufacturer, product, serial)
• ip (IpDevice, optional) - IP descriptor (host, port)
• serial (SerialDevice, optional) - Serial descriptor (path, baud rate)
• ethernet (EthernetDevice, optional) - Ethernet descriptor (MAC address, vendor)
• lpwan (LPWANDevice, optional) - LPWAN descriptor (EUI, address)
• meshtastic (MeshtasticDevice, optional) - Meshtastic descriptor (node number, long/short name, hardware model, public key)
• ble (BleDevice, optional) - Bluetooth LE descriptor (address, name, GATT service UUIDs)

EthernetDevice fields:

• mac_address (string, optional) - MAC address in canonical colon-separated hex (e.g. "aa:bb:cc:dd:ee:ff")
• vendor (string, optional) - Vendor name resolved from the OUI prefix

LPWANDevice fields:

• eui (string, optional) - IEEE 802 EUI-64 identifier (e.g. "a84041c6545d1429")
• address (string, optional) - Network address assigned after join/activation (e.g. "012a7125")

When to use: You generally don't create device entities directly. They are published by builtins like serial and meshtastic when hardware is discovered.

ConfigurableComponent

Presence of this component indicates a controller is managing this entity. It declares what can be configured and reports the controller's state. Always on the same entity as a DeviceComponent.

Fields:

• schema (Struct) - JSON schema describing accepted configuration
• value (Struct) - Current state reported by the controller
• state (ConfigurableState) - Current configurable state
• error (string, optional) - Error message if state is failed
• label (string, optional) - Human-readable label for the UI (e.g. "Defaults", "USB Device")
• applied_version (uint64) - Echoed from ConfigurationComponent.version after the controller has finished processing
• supported_device_classes (array of DeviceClassOption) - Device classes that can be attached underneath this entity
• scheduled_at (Timestamp, optional) - When the controller will activate this entity

ConfigurableState values:

When to use: Published by controllers to advertise their configuration schema and report state. Users interact with this indirectly through ConfigurationComponent.

ConfigurationComponent

Configuration pushed onto an entity. The engine delivers entities with this component to the matching controller via Reconcile.

Fields:

• value (Struct) - Configuration values as a JSON object
• version (uint64) - Monotonically increasing counter. The controller echoes this back in ConfigurableComponent.applied_version once processed

Example:

config: {
  value: {
    host: '153.44.253.27',
    port: 5631,
    entity_expiry_seconds: 300
  },
  version: 1
}

When to use: Activating and configuring builtin integrations. See the Builtin Integrations reference for all available config keys.

ArtifactComponent

Binary data (files, images, documents) stored in the artifact system. The blob is stored separately — this component holds metadata and optional external location references. Artifacts are persisted across engine restarts. When an artifact entity expires (via lifetime.until), the blob is automatically deleted from storage.

Field number: 61

Fields:

• content_type (string) - MIME type (e.g. image/jpeg, application/pdf)
• location (repeated ArtifactLocation) - External URLs where the blob is stored (e.g. S3). Empty when stored locally
• size_bytes (int64, optional) - Size of the blob in bytes. Set automatically on upload
• sha256 (string, optional) - SHA-256 hex digest of the blob. Set automatically on upload

The entity ID is the storage key.

Example:

{
  id: "report:2026-04-08",
  artifact: {
    contentType: "application/pdf",
    sizeBytes: 1048576,
    sha256: "a4244aa43ddd...",
    location: [{ url: "https://bucket.s3.amazonaws.com/report:2026-04-08" }]
  },
  lifetime: {
    until: new Date("2026-05-08T00:00:00Z")  // auto-deletes after 30 days
  }
}

Upload via CLI:

# Upload a file — creates entity + stores blob
hydris artifact put report.pdf --id report:2026-04-08 --type application/pdf --expires 30d

# Download by ID
hydris artifact get report:2026-04-08 -o report.pdf

# Download by SHA-256 hash
hydris artifact get a4244aa43ddd... -o report.pdf

# List all artifacts
hydris artifact list

# Delete (expires entity + removes blob)
hydris artifact delete report:2026-04-08

Upload via API:

// 1. Create entity with ArtifactComponent
await client.push({
  changes: [{
    id: "report:2026-04-08",
    artifact: {
      contentType: "application/pdf",
    },
    lifetime: { until: expiry },
  }],
});

// 2. Upload blob via ArtifactService.UploadArtifact (streaming RPC)
const stream = artifactClient.uploadArtifact();
await stream.send({ id: "report:2026-04-08" });
await stream.send({ chunk: fileData });
await stream.close();

Storage backends: By default, blobs are stored on local disk. Storage plugins (like S3) can provide alternative backends. When a plugin backend is active, uploaded blobs go to the plugin and location is set automatically. See Object Storage for setup and Storage Plugins for writing custom backends.

When to use:

• Storing evidence files (images, documents, logs) alongside detections or events
• Attaching captured data to sensor entities via CaptureComponent.content
• Large payloads that don't fit in entity components

GNSS

GnssComponent

Quality metadata for a GNSS (GPS) position fix. Always used alongside GeoSpatialComponent to describe how reliable the reported position is.

Fields:

• fix_type (GnssFixType, optional) - Fix quality: GnssFixTypeNone, GnssFixType2D, GnssFixType3D, GnssFixTypeDGPS, GnssFixTypeRtkFloat, GnssFixTypeRtkFixed
• satellites_visible (uint32, optional) - Number of satellites the receiver can see
• satellites_used (uint32, optional) - Number of satellites used in the solution
• hdop (float, optional) - Horizontal dilution of precision
• vdop (float, optional) - Vertical dilution of precision
• pdop (float, optional) - Position (3D) dilution of precision

Example:

gnss: {
  fixType: GnssFixType.GnssFixType3D,
  satellitesVisible: 12,
  satellitesUsed: 8,
  hdop: 1.2,
  vdop: 1.8,
  pdop: 2.1,
}

When to use: Any entity whose position comes from a GNSS receiver — drones, vehicles, handheld trackers, EdgeTX telemetry. Operators can use the fix type and DOP values to judge how much to trust the reported location.

Metrics

MetricComponent

A collection of strongly-typed sensor readings on an entity. Each metric carries a kind, unit, value, and optional alerting level, making it self-describing for display and downstream processing.

Fields:

• metrics (Metric[]) - One or more metric readings

Metric fields:

• unit (MetricUnit) - Physical unit (e.g. MetricUnitCelsius, MetricUnitPercent, MetricUnitMeterPerSecond)
• id (uint32, optional) - Stable identifier, unique within this entity
• kind (MetricKind, optional) - What is being measured (e.g. MetricKindTemperature, MetricKindHeartRate, MetricKindWindSpeed)
• label (string, optional) - Human-readable display name, e.g. "Engine Bay Temperature"
• measured_at (Timestamp, optional) - When the reading was taken
• range (MetricRange, optional) - Expected min/max bounds for the sensor
• clipping (SensorClip, optional) - SensorClipHigh or SensorClipLow when the sensor range is exceeded
• val (oneof) - The reading: double, float, sint64, or uint64
• alerting (AlertLevel, optional) - None, Warning, Alarm, or Critical

Example — weather station:

metric: {
  metrics: [
    {
      kind: MetricKind.MetricKindTemperature,
      unit: MetricUnit.MetricUnitCelsius,
      label: "Temperature",
      id: 1,
      measuredAt: now,
      val: { case: "double", value: 14.3 },
    },
    {
      kind: MetricKind.MetricKindWindSpeed,
      unit: MetricUnit.MetricUnitMeterPerSecond,
      label: "Wind Speed",
      id: 2,
      measuredAt: now,
      val: { case: "double", value: 8.7 },
    },
  ],
}

Example — CBRN hazard with alert:

metric: {
  metrics: [{
    kind: MetricKind.MetricKindRadiationHazard,
    unit: MetricUnit.MetricUnitMicrosievertPerHour,
    label: "Dose Rate",
    id: 1,
    measuredAt: now,
    val: { case: "double", value: 3.2 },
    alerting: AlertLevel.AlertLevelAlarm,
  }],
}

When to use: Environmental sensors (temperature, humidity, pressure, wind), vital signs monitors (heart rate, SpO2, body temperature), CBRN detectors, or any entity that reports numeric readings. Pair with SensorComponent and DeviceComponent for a complete sensor station.

Communication

ChatComponent

A single chat message in the common operating picture. Each message is its own entity with a lifetime, so messages naturally expire and can be routed across nodes.

Fields:

• sender (string, optional) - Entity ID of the sender
• to (string, optional) - Entity ID of the recipient (if known)
• message (string) - Message text
• reply_to (string, optional) - ID of the chat entity this replies to. Falls back to a regular message if the downstream doesn't support replies
• reaction (bool, optional) - When true, this is a reaction rather than a text reply. Falls back to a regular reply if unsupported

Example:

{
  id: "team1.chat.42.0",
  label: "Alice",
  routing: { channels: [{}] },
  chat: {
    sender: "team1.alice",
    message: "Reached waypoint bravo, visibility is poor",
  },
  lifetime: {
    from: now,
    until: oneHourFromNow,
  },
}

When to use: Tactical messaging between operators, sensor-generated status reports, or bridging external messaging systems (e.g. Meshtastic text) into the COP.

Assembly

AssemblyComponent

Groups entities into a logical assembly — for example, a vehicle and its attached sensors, or a soldier and their gear. The parent field creates a hierarchy distinct from the spatial pose tree.

Fields:

• parent (string, optional) - Entity ID of the parent assembly
• outline (string[], optional) - Entity IDs of GeoShapeComponent entities that describe the outline of this assembly

Example:

// Wind sensor attached to a hiker
{
  id: "hiker-1.wind",
  label: "Wind Sensor",
  device: { parent: "hiker-1", state: DeviceState.DeviceStateActive },
  assembly: { parent: "hiker-1" },
  pose: {
    parent: "hiker-1",
    offset: { case: "cartesian", value: { upM: 0.3 } },
  },
  metric: { metrics: [/* ... */] },
}

When to use: Sensors mounted on vehicles or personnel, sub-devices of a larger platform, or any entity that logically belongs to another. Typically combined with PoseComponent (spatial relationship) and DeviceComponent (device hierarchy).

Map Overlays

MapLayerComponent

A toggleable overlay rendered on top of the base map. Supports either XYZ tile layers or a single georeferenced image.

Fields:

• z_index (int32) - Draw order relative to other layers
• opacity (float) - Layer opacity, 0.0 (transparent) to 1.0 (opaque)
• tiles (Tile) - XYZ tile source
  • url (string) - Tile URL template, e.g. https://.../{z}/{x}/{y}.png
• image (Image) - Single georeferenced bitmap
  • url (string) - Image URL
  • west (double) - Western bound in WGS84 degrees
  • south (double) - Southern bound
  • east (double) - Eastern bound
  • north (double) - Northern bound

Example — tile layer:

mapLayer: {
  zIndex: 10,
  opacity: 0.7,
  source: {
    case: "tiles",
    value: { url: "https://tiles.example.com/{z}/{x}/{y}.png" },
  },
}

Example — georeferenced image:

mapLayer: {
  zIndex: 5,
  opacity: 0.9,
  source: {
    case: "image",
    value: {
      url: "https://example.com/overlay.png",
      west: 13.3,
      south: 52.4,
      east: 13.5,
      north: 52.6,
    },
  },
}

When to use: Weather radar overlays, satellite imagery, heatmaps, zone overlays, or any raster layer that should be displayed on the map alongside entities.

Access Control

PolicyComponent

CEL-based access policy evaluated on incoming requests. The authz.policy entity carries the global authorization chain and authn.policy the connection-identity chain; attach to other entities (identities, protected resources) for per-entity rules reached via Defer.

Fields:

• rules (PolicyRule[]) - Rules evaluated top to bottom; first match wins

PolicyRule fields:

• action (PolicyAction) - Allow, Deny, Log, or Defer
• cel (string, optional) - CEL condition. Omit for unconditional match
• label (string, optional) - Human-readable label for this rule, shown in logs and UI

Example — global authorization chain (on authz.policy):

policy: {
  rules: [
    { action: PolicyAction.PolicyActionDefer, cel: 'actor.id', label: "defer to the actor's policy" },
    { action: PolicyAction.PolicyActionDeny,  label: 'fail closed' },
  ],
}

Example — entity-level policy:

policy: {
  rules: [
    { action: PolicyAction.PolicyActionAllow, cel: 'source.address.inCIDR("10.0.0.0/8")' },
    { action: PolicyAction.PolicyActionDeny },
  ],
}

When to use: Restrict who can read or write entities, log access for auditing, or delegate per-entity permissions. See the full Policy reference for available CEL variables, functions, and examples.

Manual Control

ManualControlComponent / TargetManualControlComponent

Direct axis control of an asset, like a gamepad. TargetManualControlComponent holds the desired input pushed by an operator; the device driver reconciles it into ManualControlComponent, which reflects the actual applied input.

Fields (both components):

• input (ManualControlInput[]) - Control inputs, each with an axes field

ManualControlAxes fields (all float, optional):

• forward, right, up - Translation axes
• yaw, pitch, roll - Rotation axes
• pan, tilt, zoom - Gimbal/camera axes

Example:

target_manual_control: {
  input: [{
    axes: { forward: 0.5, yaw: -0.2 }
  }]
}

When to use: Teleoperation of drones, vehicles, or PTZ cameras where an operator drives axes directly instead of issuing tasks.

Component Combinations

Common Patterns

Basic Position Marker:

{ id, geo, symbol }

Sensor Station:

{ id, geo, symbol, bearing, camera, sensor }

Detection (positioned):

{ id, geo, detection, bearing }

Camera Detection (with bounding box):

{ id, label, detection, controller, priority }
// detection includes detectorEntityId, evidence, imageBbox, confidence

Fused Track:

{ id, geo, symbol, track, bearing, kinematics, classification }

Maritime Vessel (from AIS):

{ id, geo, symbol, kinematics, transponder, administrative, navigation, mission }

Aircraft (from ADS-B):

{ id, geo, symbol, kinematics, transponder, administrative, classification }

Mesh Radio Node:

{ id, geo, symbol, link, power }

Zone/Area:

{ id, label, shape, symbol }

PTZ Camera with Gimbal:

{ id, geo, symbol, camera, bearing }
// + child entity with pose (relative to camera) and target_pose

Task Assignment:

{ id, taskable }

Builtin Config:

{ id, config }

IoT Device:

{ id, geo, capture, link, power }

Weather Station:

{ id, geo, symbol, sensor, metric, device, link, power }

Personnel with Sensors:

{ id, geo, symbol, gnss, mission }
// + child entities with assembly, pose, device, metric

Chat Message:

{ id, label, routing, chat, lifetime }

Next Steps

• Entity Cookbook - These components assembled into complete, downloadable examples
• Understanding Entities - Learn about the Entity Component System