`entity-state-to-chart-data`

entity-state-to-chart-data extracts time-series, event and marker channels from entity-state records. Optional sub-configurations choose which channels are emitted.

Entity-state records are the JSON records array that hydrate-protobuf-v2 emits with extractionTarget: EntityState. Each sub-configuration reads one kind of value through JMESPath (a query language for JSON) and writes one or more channels into a data service payload. With no sub-configuration the node discovers entities that carry altitude or speed and emits one series per entity.

It is not a stats node. For single-number summaries use entity-state-to-flight-stats.

When to use

Use this node when a Next dashboard chart needs depth, altitude or speed over time, detection on and off events, or lifecycle markers for a set of entities.

Pipeline position


hydrate-protobuf-v2 (EntityState) -> entity-state-to-chart-data -> json-merge -> dashboard-v2

The node reads the latest output of one parent.

Configuration

Configuration is required, but every key is optional. The presence of any sub-configuration disables auto-discovery.

Key	Type	Required	Default	Description
`entriesPath`	string	No	`records[*]`	JMESPath to the array of time-ordered records.
`timeField`	string	No	`simulation_time_seconds`	Dotted path from each record to its simulation time.
`entitiesPath`	string	No	`entity_state.entity`	JMESPath from each record to its entity object or array of objects.
`entityNameField`	string	No	`name`	Dotted path from each entity to its name.
`baseCapturedAt`	string	No	`""`	ISO 8601 base time stamp. When set, simulation time is a relative offset from this base. When empty, simulation time is absolute Unix epoch seconds.
`depthConfig`	object	No	none	One `series` channel for one entity’s depth.
`sonobuoyDepthConfig`	object	No	none	One `series` channel per sensor entity matching a name prefix.
`detectionConfig`	object	No	none	One `events` channel for detection transitions on one entity.
`speedConfig`	object	No	none	One `series` channel for one entity’s speed.
`lifecycleEventsConfig`	object	No	none	One `timestamps` channel per lifecycle event type.
`perBuoyRealms`	boolean	No	`false`	When true, emit one Realm per sensor entity instead of one shared realm.
`groupId`	string	No	`chart`	Group id for the output channels.
`groupName`	string	No	`Chart`	Group display name.
`realmName`	string	No	`overview`	Realm name when `perBuoyRealms` is false.

depthConfig and speedConfig

Both objects share the same keys.

Key	Type	Required	Default	Description
`entityName`	string	Yes	none	Entity to read.
`valueField`	string	Yes	none	JMESPath from the entity to the numeric value.
`channelId`	string	No	`depth` or `speed`	Channel id.
`channelName`	string	No	`Kilo-01 Depth` or `Speed`	Display name.
`metadata`	object	No	none	Passed through onto the channel, for example `{ "units": "m" }`.

sonobuoyDepthConfig

Key	Type	Required	Default	Description
`sonobuoyNamePattern`	string	Yes	none	Name prefix that identifies sensor entities.
`valueField`	string	Yes	none	JMESPath from the entity to the depth value.
`maxSeries`	integer	No	`5`	Maximum number of per-sensor channels. Entities are sorted alphabetically first.
`buoyEntities`	array of string	No	none	Explicit list of sensor entity names.

Channels are named sonobuoy-depth-0, sonobuoy-depth-1 and so on. Entities with no data at any frame are omitted.

detectionConfig

Key	Type	Required	Default	Description
`entityName`	string	Yes	none	Entity that carries the detection beams.
`beamsField`	string	Yes	none	JMESPath from the entity to the beams array.
`channelId`	string	No	`detections`	Channel id.
`channelName`	string	No	`Sonar Detections`	Display name.

A detection is active when any beam has has_detection: true. Points are emitted only when that state changes.

lifecycleEventsConfig

Key	Type	Required	Default	Description
`entityPattern`	string	Yes	none	Name prefix that identifies the entities to track.
`events`	array	Yes	none	Event definitions, each with `type`, `name` and `channelId`.

type is first_seen (one point per entity at its first appearance) or cross_reference_detection (one point the first time a detecting entity links to a tracked entity). Each point carries timeMs and an annotation holding the entity name.

Output

A data service payload. In the default mode all channels sit in one realm.


{
  "$heat-dataservice": {
    "version": "1.0",
    "groups": [{ "id": "chart", "name": "Chart" }],
    "realms": [
      {
        "name": "overview",
        "channels": [
          { "id": "sonobuoy-depth-0", "name": "sonobuoy-depth-0", "groupId": "chart", "shape": "series", "data": [{ "timeMs": 0, "value": 5.0 }] },
          { "id": "detections", "name": "detections", "groupId": "chart", "shape": "events", "data": [{ "timeMs": 10000, "occurred": true }] }
        ]
      }
    ]
  },
  "dashboard_users": []
}

Auto-discovery emits <entity>-altitude and <entity>-speed series channels. Entity names are lowercased and spaces and underscores become hyphens.
With perBuoyRealms: true and sonobuoyDepthConfig set, each sensor entity gets its own realm containing a buoy-depth series and one timestamps channel per lifecycle event. No shared realm is produced. dashboard-v2 adds each realm to the layout and enables the realm filter dropdown when there is more than one.
timeMs is baseCapturedAt plus the offset in milliseconds, or the simulation time in milliseconds when baseCapturedAt is empty.

Limitations

One parent, latest output only.
A frame where a value is missing is skipped for that entity. A frame where the value is zero is kept.
The node fails when perBuoyRealms produces no realm.

ComposableChart (Next) is the recommended widget for these channels.
TimelineChart (Next) still renders them but is only partially migrated.
entity-state-to-flight-stats reduces one value to min, max and average.

HEAT documentation team. Last updated 2 October 2026.

Opens your browser's print dialog. Choose "Save as PDF" as the destination.