Node Description

Broadcast MessageTypeEnum_NODE_DESCRIPTION

A node introduces itself and declares its capabilities.


Direction	node → controller (and peers)
Cadence	Once on join, and whenever capabilities change.
Delivery	Broadcast — telemetry plane (QoS 0)
Schema	`catl/hibw/messages/node/NodeDescription.json`
Worked examples	2

Purpose

The first message a node emits. It advertises the node's identity, endurance, the task-condition / template modes it supports, and any specialization (vehicle role, sensors, payloads) and standing constraints. A controller uses it to decide what the node can be tasked to do before it sends a single TASK_ADMIN.

When to send it

On startup / when the node joins the network.
When the node's capabilities, specialization, or endurance change.
On request, to re-announce after a controller restart.

Where it fits

Loading diagram…

Message header

Every CATL message carries this envelope header.

Field	Type	Multiplicity	Description
`message_type`	MessageTypeEnum	`[1..1]`	An enumeration.
`source`	GUID	`[1..1]`	Source that send this message. Often same as source of information, but different when relaying.
`version`	string	`[1..1]`	Version of the schema used to create and validate this message. Has to follow major.minor.patch notation. For study draft 3 it should be 0.3.0.
`time_sent`	Time	`[1..1]`

Body — `NodeDescriptionBody`

Inherits from base::node::Node.

Field	Type	Multiplicity	Description
`source_of_information` (inherited)	GUID	`[0..1]`	Holds source of information. Its a identifier of a node that provided that information. It can be a node that created a region, task. It can be a node that detected contact or is maintaining track. For self reports it should be same as identifier.
`external_identifiers` (inherited)	ExternalSystemIdentifier `[]`	`[0..*]`	Holds identifiers of this entity in other systems.
`identifier` (inherited)	GUID	`[1..1]`	Unique identifier for this entity.
`description` (inherited)	EntityDescription	`[0..1]`	Description of this entity. Contains APP6 symbol definition and human readable description.
`extra` (inherited)	Any	`[0..1]`	Placeholder for experimentation.
`timestamp` (inherited)	Time	`[1..1]`	Time in which this entity was last updated.
`time_of_initiation` (inherited)	Time	`[0..1]`	Time when this entity was created or spotted.
`time_of_validity` (inherited)	Time	`[0..1]`
`endurance` (inherited)	Duration	`[0..1]`
`parent_id` (inherited)	GUID	`[0..1]`	Identifier of parent, if that node is a member of squad or swarm.
`members` (inherited)	GUID `[]`	`[0..*]`	If that node is a squad leader, list of identifiers of members of this squad (same for swarms and similar cases).
`roles` (inherited)	Role `[]`	`[0..*]`
`pose` (inherited)	Pose	`[0..1]`
`capabilities` (inherited)	Capabilities	`[0..1]`
`velocity` (inherited)	Velocity	`[0..1]`

Field	Type	Multiplicity
`constraints`	ConstraintAnnouncement `[]`	`[0..*]`
`binding`	BindingInformationType	`[0..1]`
`specialization`	NodeSpecializationDescription	`[0..1]`
`initialization`	Initialization	`[0..1]`

Full NodeDescriptionBody reference →

Key fields

capabilities — Which task-condition and task-template modes the node honours. A controller must not send constructs the node reports as NOT_SUPPORTED.
endurance — ISO-8601 duration (e.g. PT3H) — the mission time budget the controller plans against.
specialization — Node role/type detail (optional but recommended): what the platform is and what it carries.
constraints — Standing constraint announcements the node operates under (emission control, ranges, equipment).

Worked examples

✅ validates against catl/hibw/messages/node/NodeDescription.json. Routes to 4817/exercise-alpha/v0.3.0/src/a895f8f5-46b0-5603-bdf0-b270a2867c09/description (QoS 0, retained).

catl_1_node_description.json

{
  "header": {
    "message_type": "MessageTypeEnum_NODE_DESCRIPTION",
    "source": "a895f8f5-46b0-5603-bdf0-b270a2867c09",
    "version": "0.3.0",
    "time_sent": "2025-03-18T12:05:00+00:00"
  },
  "body": {
    "identifier": "73efad3c-8336-597c-a3f3-f6ae5b3b3f8e",
    "timestamp": "2025-03-18T12:05:00+00:00",
    "endurance": "PT3H",
    "capabilities": {
      "task_conditions_mode": "TaskConditionModeEnum_NOT_SUPPORTED",
      "task_conditions_template": "TaskTemplateModeEnum_NOT_SUPPORTED"
    }
  }
}

Node Description Complex

✅ validates against catl/hibw/messages/node/NodeDescription.json. Routes to 4817/exercise-alpha/v0.3.0/src/a895f8f5-46b0-5603-bdf0-b270a2867c09/description (QoS 0, retained).

catl_17_node_description_complex.json

{
  "header": {
    "message_type": "MessageTypeEnum_NODE_DESCRIPTION",
    "source": "a895f8f5-46b0-5603-bdf0-b270a2867c09",
    "version": "0.3.0",
    "time_sent": "2025-03-18T12:05:00+00:00"
  },
  "body": {
    "identifier": "0d421b7b-03ab-5c51-9128-ba72e6deec3f",
    "timestamp": "2025-03-18T12:05:00+00:00",
    "endurance": "PT3H",
    "capabilities": {
      "task_conditions_mode": "TaskConditionModeEnum_NOT_SUPPORTED",
      "task_conditions_template": "TaskTemplateModeEnum_NOT_SUPPORTED"
    },
    "constraints": [
      {
        "constraint": {
          "$discriminator": "GeneralConstraintTypeEnum_TOGGLE",
          "toggle": {
            "default_value": false
          }
        },
        "identifier": "82a65d35-842a-5007-9c3c-888674e51cdf",
        "description": "Enable obstacle avoidance",
        "name": "obstacle_avoidance"
      },
      {
        "constraint": {
          "$discriminator": "GeneralConstraintTypeEnum_RANGE",
          "range": {
            "minimum": 0,
            "maximum": 100,
            "default_value": 12
          }
        },
        "identifier": "bb96a649-b0fd-5cbd-8bfe-4cfe44371a83",
        "description": "Minimum distance",
        "name": "distance"
      },
      {
        "constraint": {
          "$discriminator": "GeneralConstraintTypeEnum_ENUMERATION",
          "enumeration": {
            "default_value": {
              "name": "ON"
            },
            "possible_values": [
              {
                "name": "ON"
              },
              {
                "name": "OFF"
              },
              {
                "name": "AUTO"
              }
            ],
            "enumeration_type": {
              "name": "CUSTOM"
            }
          }
        },
        "identifier": "b956d1a5-d9ff-5b4d-9e9b-f4eb60c830ce",
        "description": "Enable tracking",
        "name": "tracking"
      },
      {
        "constraint": {
          "$discriminator": "GeneralConstraintTypeEnum_EQUIPMENT",
          "equipment": {
            "default_emission_control": "ConstraintTypeEmissionControlEnum_ROUTINE",
            "equipment_type": "AnyEquipmentEnum_OPTICAL_SENSOR_VIDEO_SENSOR"
          }
        },
        "identifier": "11757cb1-0ba2-5664-9fa5-f6c37e4c38b4",
        "description": "Sonar configuration",
        "name": "sonar"
      }
    ]
  }
}

Integrate it

The two calls every integrator needs — validate the message, then resolve its MQTT route:

# 1 · fetch a worked Node Description example
curl -s https://4817.r2d2.office.ilab.zone/examples/catl_1_node_description.json | jq '.message' > msg.json

# 2 · validate it against the 0.3.0 schema
curl -s https://4817.r2d2.office.ilab.zone/validate -H 'content-type: application/json' \
  -d "{\"message\": $(cat msg.json)}" | jq '{valid, schema_ref, errors}'

# 3 · resolve where it publishes on MQTT
curl -s "https://4817.r2d2.office.ilab.zone/route" -H 'content-type: application/json' \
  -d "{\"message\": $(cat msg.json)}" | jq

Try them interactively in the Integration API reference.

All worked examples · Type reference · Integration API
Concept: /docs/concepts/state-model
Concept: /docs/concepts/autonomy-and-doctrine

Node Description

On this page