Define a task

This guide describes best practices for authoring custom task definitions for use in Lattice. Custom task definitions allow you to extend Lattice’s tasking capabilities with your own specialized workflows.

Before you begin

• Familiarize yourself with tasks in Lattice.
• To create tasks, set up your Lattice environment.
• Review the Protobuf files and packages guide to understand Protobuf fundamentals.

Authoring tasks

A custom task is a Protobuf message type that contains the information your asset requires to execute a task autonomously. The complexity of your task definition depends on your integration’s requirements. For example:

• Simple tasks: A sensor may define an on/off toggle message
• Entity-targeted tasks: A tracking system may define a message containing an entity_id to track
• Complex tasks: An autonomous vehicle may define multiple parameters including waypoints, speed limits, sensor configurations, and priority levels

Custom tasks give you the flexibility to model domain-specific workflows while maintaining type safety and compatibility across your Lattice deployment.

Create a package

Define your tasks as Protobuf messages as part of a package. A package should contain all relevant message types to compose tasks that express an integration’s capabilities. Naming your package clearly and precisely is crucial to avoid potential naming conflicts.

Use a consistent package naming pattern: org.repository.package.version

Where:

• org: Your organization name in the Schema Registry.
• repository: Your repository name in the Schema Registry.
• package: A descriptive name for your task domain, for example, surveillance, navigation, or sensor.
• version: The API version, for example, v1, v2 v1alpha or v2test.

1
// Example
2
package company.isr.imaging.v1test;

During early development, mark your package as unstable by appending a stability marker (alpha, beta, or test) to the version.

1
package org.example.surveillance.v1alpha;
2
package org.example.navigation.v2beta;

Fully qualified names

The fully qualified name of a message is the package name with the message name:

1
package company.isr.imaging.v1test;
2
3
message AerialSurveillance {
4
  // ...
5
}

For the example above, this would create the fully qualified name: company.isr.imaging.v1test.AerialSurveillance.

All protobuf type URLs are prefixed with type.googleapis.com. You will always reference your task definition by its type URL, for example: type.googleapis.com/company.isr.imaging.v1test.AerialSurveillance.

For more information about Protobuf packages and naming, see Protobuf files and packages in the Buf documentation.

Breaking change protection

The Schema Registry enforces breaking change detection for all packages. This ensures backward compatibility for consumers of your schemas. You can deprecate old fields, or if necessary, release a new version of your package.

Common breaking changes that are prevented:

• Removing or renaming fields
• Changing field types
• Changing field numbers
• Removing enumerated values

Non-breaking changes that are allowed:

• Adding new fields
• Adding new enumerated values
• Adding new messages
• Deprecating fields (using the deprecated option)

For a complete guide on breaking changes, see the Buf breaking change detector documentation.

Define a custom schema

Protobuf’s Any type enables creating flexible, extensible schemas. It allows you to embed arbitrary serialized protocol buffer messages in an existing schema:

1
message Any {
2
  // A resource name that uniquely identifies
3
  // the type of the serialized protocol buffer message.
4
  string type_url = 1;
5
6
  // The serialized protocol buffer message.
7
  bytes value = 2;
8
}

The Lattice SDK uses the Any type as an entrypoint for custom task specifications. Create a new file called surveillance.proto with the following contents:

1
syntax = "proto3";
2
3
package org.example.surveillance.v1alpha;
4
5
import "google/protobuf/wrappers.proto";
6
7
// AerialSurveillance represents a task to perform aerial surveillance of an area or entity.
8
// This task specification is used with autonomous aerial assets to define surveillance parameters.
9
message AerialSurveillance {
10
  // Entity to perform surveillance on. Optional - if not provided, the task
11
  // applies to the entire surveillance area.
12
  string entity_id = 1;
13
14
  // Surveillance pattern to use during the mission.
15
  SurveillancePattern pattern = 2;
16
17
  // Minimum altitude in meters for the surveillance.
18
  google.protobuf.FloatValue min_altitude_m = 3;
19
20
  // Maximum altitude in meters for the surveillance.
21
  google.protobuf.FloatValue max_altitude_m = 4;
22
23
  // Priority of the surveillance mission (0-100, where 100 is highest priority).
24
  google.protobuf.UInt32Value priority = 5;
25
}
26
27
// Different patterns that can be used for aerial surveillance.
28
enum SurveillancePattern {
29
  // Invalid default value, must not be used.
30
  SURVEILLANCE_PATTERN_INVALID = 0;
31
32
  // Grid pattern covers the area systematically in a grid formation.
33
  SURVEILLANCE_PATTERN_GRID = 1;
34
35
  // Spiral pattern moves outward from a central point.
36
  SURVEILLANCE_PATTERN_SPIRAL = 2;
37
38
  // Random pattern provides unpredictable coverage.
39
  SURVEILLANCE_PATTERN_RANDOM = 3;
40
41
  // Perimeter pattern follows the boundary of the surveillance area.
42
  SURVEILLANCE_PATTERN_PERIMETER = 4;
43
}

Common patterns

1
syntax = "proto3";
2
3
package company.sensor.v1;
4
5
// Use empty messages to issue simple commands to your Asset
6
message SensorOn {}
7
8
// Stop Detecting
9
message SensorOff {}

1
syntax = "proto3";
2
3
package company.sensor.v1;
4
5
// Use the entity_id field task your Asset against an Entity
6
message TrackEntity {
7
    string entity_id = 1;
8
}

1
syntax = "proto3";
2
3
package company.uas.v1;
4
5
// Use Message types to compose a more complex Task
6
message Coordinate {
7
    double lat = 1;
8
    double lon = 2;
9
}
10
11
// A target could be either a lat/lon, or an Entity that we can track
12
message Target {
13
    oneof target {
14
        string entity_id = 1;
15
        Coordinate coordinate = 2; 
16
    }
17
}
18
19
message FlightConstraints {
20
    float min_altitude_agl_m = 1;
21
    float max_altitude_agl_m = 2;
22
    float max_ias_kts = 3;
23
    float min_ias_kts = 4;
24
}
25
26
enum FlightPattern {
27
    FLIGHT_PATTERN_GRID = 1;
28
    FLIGHT_PATTERN_ORBIT = 2;
29
    FLIGHT_PATTERN_SECTOR_SEARCH = 3;
30
}
31
32
// Task Message
33
message Survey {
34
    Target target = 1;
35
    FlightPattern flight_pattern = 2;
36
    FlightConstraints flight_constraints = 3;
37
}

What’s next?

• Publish your schema to the Schema Registry to make it available for use
• Use your custom definition to create tasks in Lattice
• Configure your agents to listen for tasks assigned to them
• Update task status as your agents make progress on assigned tasks