Virtual Communication Units

A Virtual Communication Unit (VCU) is an agrirouter endpoint that represents a physical machine: a tractor, an implement, or an ISOBUS-connected unit. In the current API each machine is its own full endpoint of type virtual_communication_unit, registered in an end user's agrirouter account via its own PUT /endpoints/{externalId} call. Every VCU has its own external ID, capabilities, subscriptions, and feed, and is addressable as a distinct source and destination when the end user configures routes.

For where VCUs fit in the ecosystem, see Ecosystem: virtual_communication_unit.

Before you start

VCUs follow the same lifecycle as every other endpoint in the current API. Before you register a VCU on behalf of an end user, the application must already be authorized for that user's agrirouter account, and the external ID you are about to use must not yet exist in that tenant.

• Authorization and Security for the one-time authorization flow.
• Endpoint Management for the create, update, and delete lifecycle that VCUs share with software endpoints.
• Tenant IDs for what a tenant is and how the tenant ID is passed on each call.

Register a VCU

Create a VCU with the standard endpoint creation call:

PUT /endpoints/{externalId}

Set endpoint_type to virtual_communication_unit in the request body. The externalId is your own stable identifier for the machine, for example a serial number, an internal fleet ID, or a URN such as urn:yourcompany:vcu:tractor-1234. Every VCU needs its own external ID, unique within the tenant.

The request body has the same shape as for any other endpoint. See PUT /endpoints/{externalId} for the full reference and Endpoint Management for the full lifecycle.

Capabilities and subscriptions

Each VCU declares its own capabilities and subscriptions, independent of any other endpoint in the account. For most VCUs the declaration covers EFDI telemetry and ISOBUS task data:

See Message Types for the full catalogue, and the individual message-type pages for payload details.

Report TeamSets with Device Descriptions

Every VCU should publish an EFDI Device Description reporting the machines and implements currently attached to it. A Device Description is identified by a TeamSet context ID, which receivers use to correlate device descriptions, time logs, and task data that belong to the same on-machine setup.

Carry the TeamSet context ID in the x-agrirouter-teamset-context-id request header on POST /messages. See TeamSet Context ID for the full contract, including how the identifier relates to x-agrirouter-context-id and when to generate a new one.

Send a Device Description:

• Immediately after the VCU endpoint is created.
• Whenever the machine configuration changes, for example when an implement is attached or a device is replaced.
• Periodically to confirm the machine is still active, typically at an interval between once per hour and once per day.

Send and receive as a VCU

Messages sent on behalf of a VCU use that VCU's own endpoint ID in the x-agrirouter-endpoint-id header. Each VCU has its own feed and its own events stream on GET /events, and there is no shared connection between a VCU and any other endpoint. A cloud-hosted application managing a fleet acts as each VCU in turn, setting the appropriate x-agrirouter-endpoint-id per request.

See Sending & Receiving for the full messaging flow, and Messaging for the conceptual model.

VCU Lifecycle

API Reference

VCUs share the current API with every other endpoint type. Try the operations a fleet platform exercises per machine in the API playground:

Next Steps