Constellation Overwatch

Learn how to structure your telemetry data using Constellation Overwatch's ontological data primitives.

Overview

Constellation Overwatch uses an ontological approach to telemetry data, organizing sensor readings into semantic categories that reflect the physical reality of your entities.

Data Primitives

Position

Geographic location in 3D space:

{
  "position": {
    "lat": 37.7749,
    "lon": -122.4194,
    "alt": 100.5
  }
}

Field	Type	Description
`lat`	float	Latitude in degrees
`lon`	float	Longitude in degrees
`alt`	float	Altitude in meters (MSL)

Orientation

Attitude in 3D space (Euler angles):

{
  "orientation": {
    "roll": 0.1,
    "pitch": -0.2,
    "yaw": 1.5
  }
}

Field	Type	Description
`roll`	float	Roll angle in radians
`pitch`	float	Pitch angle in radians
`yaw`	float	Yaw/heading in radians

Sensors

Environmental and onboard sensor readings:

{
  "sensors": {
    "temperature": 22.5,
    "humidity": 65,
    "pressure": 1013.25,
    "battery_voltage": 22.2
  }
}

State

Operational state and status:

{
  "state": {
    "battery": 85,
    "mode": "autonomous",
    "armed": true,
    "health": "nominal"
  }
}

Performance

Performance metrics:

{
  "performance": {
    "velocity": 5.2,
    "thrust": 0.7,
    "efficiency": 0.92
  }
}

Complete Telemetry Payload

A complete telemetry update combines all primitives:

{
  "timestamp": "2024-01-01T12:00:00Z",
  "entity_id": "drone-001",
  "position": {"lat": 37.7749, "lon": -122.4194, "alt": 100},
  "orientation": {"roll": 0.1, "pitch": -0.2, "yaw": 1.5},
  "sensors": {"temperature": 22.5, "humidity": 65, "pressure": 1013.25},
  "state": {"battery": 85, "mode": "autonomous", "armed": true},
  "performance": {"velocity": 5.2, "thrust": 0.7, "efficiency": 0.92}
}

Publishing Telemetry

Publish to the global state KV bucket:

nats kv put CONSTELLATION_GLOBAL_STATE "$ENTITY_ID" '{"position": {...}}'

Best Practices

Include timestamps - Always include ISO 8601 timestamps
Use SI units - Meters, radians, Celsius, etc.
Batch updates - Combine related data in single updates
Validate data - Check ranges before publishing

Ontological Data Design