Publish entities
This page explains how to create and update assets, tracks, and geo-entities - the most common Entity templates in Lattice.
In the following steps, you publish various entities and learn how the entity model lets you represent a variety of real-world objects and geographic areas.
Before you begin
- To publish entities, set up the Lattice SDK and set up a Lattice environment.
- The following examples use
uuidto generate unique entity IDs. To use the TypeScript examples, install@types/uuid:TypeScript - Learn about required components and various entity shapes in Lattice.
These gRPC examples authenticate with a static environment token attached as request metadata. If you are using OAuth 2.0 client credentials instead, set up the token refresh module before running the examples on this page.
Publish an asset
An asset is an entity under your control, or under the control of another operator or system. Assets may accept tasks such as search or tracking. To publish an asset, do the following:
Drone
Define the entity model’s required components. Together with the asset-specific fields, you get the following entity object:
Take a closer look at the following components in entity.json and familiarize yourself
with common patterns used to model an asset in Lattice. In this example:
- Set
templatetoTEMPLATE_ASSET. - Set
platform_typetoUAVrendering a drone icon in the Lattice UI. - Use
taskCatalogto publicize the assets tasks. The asset can listen for, and act upon, any task assigned to it, matching its specifiedtaskDefinition. - Use
healthto define the health status of the asset. Health reporting is exclusive to assets. Tracks and geo-entities never report health. When an asset sends updates to Lattice, Lattice automatically setshealth.connection_statustoCONNECTION_STATUS_ONLINE. If there are no updates after one minute, the field value changes toCONNECTION_STATUS_OFFLINE. Alongside the top-levelhealth_status, report at least one entry incomponentsto describe the health of an individual subsystem, such as the drone’s battery.
The position component supports four altitude references, specified in meters.
Populate the references available to your integration:
The entity’s height above the World Geodetic System 1984 (WGS84) ellipsoid.
The entity’s height above the terrain. This is typically measured with a radar altimeter or by using a terrain tile set lookup.
The entity’s height above the sea floor.
The depth of the entity from the surface of the water.
Lattice doesn’t support Mean Sea Level (MSL) references,
such as EGM-96 and EGM-08. If the only altitude reference available to your
integration is MSL, convert it to Height Above Ellipsoid (HAE) and populate the
altitude_hae_meters field. To apply this conversion, use an open-source library,
such as EGM96 for Go.
Publish a track
A track represents any entity tracked by another asset or integration source.
Tracks are not directly under the control of friendly forces. This includes aircraft
tracks from radar or sensor hits, signal detections, and vehicles, people, or animals detected through cameras. You can specify the type of track you want to publish by
setting ontology.template field:
Airplane
Define the entity model’s required components. To create a generic track, such as an airplane:
- Set
templatetoTEMPLATE_TRACK. - Set
platform_typetoAIRPLANE.
Together with the track-specific fields, you get the following entity object:
Take a closer look at the components in entity.json to
familiarize yourself with the track’s properties.
Because the airplane is moving, the example also reports the track’s velocity and
heading through the following location fields:
The track’s velocity in an East-North-Up (ENU) reference frame centered on the track’s position, measured in meters per second.
The track’s heading in the ENU frame, represented as a quaternion that rotates from the entity body frame to the ENU frame.
If both attitude_enu and velocity_enu are populated, Lattice prioritizes the
value from the attitude_enu component.
Convert the track’s velocity into the attitude_enu quaternion. Sensors typically
report velocity rather than heading, so derive the heading in two steps:
- Convert the ENU velocity vector into a yaw angle with
atan2(velocity_north, velocity_east). This uses the ENU mathematical convention, where a yaw of 0 points East and a yaw of π/2 points North. - Convert the yaw angle into a quaternion. Yaw is a rotation about the ENU Up (Z)
axis, so the quaternion has only
z = sin(yaw / 2)andw = cos(yaw / 2)components. The result is already unit-normalized.
The example defines two helper functions for this conversion:
Use the PublishEntity API method to publish the entity.
The example derives the velocity from the simulated circular motion, then populates
velocity_enu and attitude_enu:
Publish a geo-entity
A geo-entity is a shape, region, or point of interest drawn on the map, which may not physically exist. Use geo-entities to represent an geographical areas of interest, such as airfield, or a control zone for autonomous vehicles to operate in. To publish a geo-entity, do the following:
Polygon
Define the entity model’s required components. Together with the geo-entity-specific fields, you get the following entity object:
Take a closer look at the following components in entity_model.json and familiarize yourself
with common patterns used to model a get-entity in Lattice. You define rings to create the polygon.
Each ring must have at least four points, each represented by a position component.
The last point must be the same as the first point you define for the ring component.
Each point in the polygon has a minimum altitude defined as altitudeAglMeters.
The first and the last point have a heightM component, which sets
additional height, in meters, above altitudeAglMeters.
This represents a three-sided polygon that defines a control area. Control areas
include, for example, CONTROL_AREA_TYPE_KEEP_IN_ZONE, CONTROL_AREA_TYPE_KEEP_OUT_ZONE,
and CONTROL_AREA_TYPE_LOITER_ZONE.
Use the PublishEntity API method to publish the entity:
The example uses noExpiry instead
of expiryTime used in the previous steps. Setting noExpiry to true indicates that the entity
does not expire and persists indefinitely. Use this option only when the entity contains information
that should be available to other tasks or integrations beyond its immediate operational context. In this case
we assume that this long-living geographical entity maintains persistent relevance across multiple operations or tasks.
Even when using noExpiry: true, entities must be republished at least every 5 minutes
to ensure persistence across Lattice service restarts. If Lattice restarts and an entity hasn’t been
republished within the previous 5 minutes, it won’t be restored after the restart. This is
demonstrated in the example code, which republishes the entity every 10 seconds in an indefinite loop.
Set platform type
For iconography within Lattice, add a platform_type
value to the ontology component. The Lattice UI supports the following types:
Airplane
Animal
Car
Person
Radar
Satellite
Surface Vessel
Submarine
UAV
Vehicle
What’s next?
- Learn more about the Entities API in REST and gRPC.
- Learn how to task an asset.
- Check out the Lattice sample apps.