Communication Unit (Legacy API)
How to integrate a Communication Unit (CU) or hardware device with agrirouter using the legacy API
This guide is for hardware device manufacturers building physical Communication Units that use the legacy API with MQTT or REST transport. CUs cannot use the current REST API with SSE.
If you are building a cloud application, see the Cloud Software guide instead.
A Communication Unit (CU) is a physical hardware device installed on an agricultural machine. CUs include terminals, telemetry boxes, and ISOBUS gateways. They collect machine data and exchange it with farming software and telemetry platform endpoints through agrirouter.
For the conceptual overview of endpoint types, see the ecosystem documentation.
Key Characteristics
- CUs are hardware devices running firmware, not cloud applications.
- CUs connect to machines via ISOBUS (ISO 11783) and report device descriptions for attached implements.
- Onboarding uses a registration code (TAN) entered by the user. No OAuth flow required.
- CUs typically send telemetry data (EFDI, GPS) and receive task data (TaskData).
- CUs use the legacy API. See the Legacy API documentation for protocol details.
Typical Capabilities
| Direction | Message Types |
|---|---|
| Send | EFDI Device Description, EFDI Time Log, GPS positions |
| Receive | TaskData (ISO 11783) |
Integration Steps
Register Your CU Application
Register your CU application in the agrirouter developer portal. You receive an applicationId and certificationVersionId.
Generate a Registration Code
The end user generates a registration code (TAN) in the agrirouter UI. This code authorizes your CU to onboard to their agrirouter account.
Since agrirouter 2.0, the registration code (TAN) is valid for any CU application. The user no longer needs to select a specific CU type when generating the code.
Onboard Using the Registration Code
Send an onboarding request with:
- Your
applicationIdandcertificationVersionId - The registration code (TAN)
- A unique
externalIdfor this CU instance - Your preferred gateway type (
RESTorMQTT)
The response contains connection credentials (certificate and keys) for all subsequent communication.
Declare Capabilities
Send a capabilities message declaring the message types your CU supports. This is what lets routing work between your CU and other endpoints.
Sending capabilities clears existing subscriptions. Always re-send subscriptions immediately after capabilities.
Set Up Subscriptions
Subscribe to message types your CU wants to receive (typically TaskData).
Send Device Descriptions
Send an EFDI Device Description to agrirouter describing the machine and any attached implements. Re-send the description whenever the ISOBUS configuration changes (new implement connected, implement removed).
Exchange Messages
Your CU can now send telemetry and receive task instructions through agrirouter.
Sending and Receiving Messages6 minISOBUS Connection
CUs that connect to machines via ISOBUS should:
- Discover implements: read the ISOBUS network to identify attached implements and their Device Description (DD).
- Report device descriptions: send EFDI Device Descriptions to agrirouter reflecting the current machine configuration.
- Collect time logs: record EFDI Time Logs during field operations and send them to agrirouter.
- Receive tasks: accept incoming TaskData files and load them onto the machine's task controller.
Router Devices
A router device is a CU that manages multiple sub-CUs under a single connection. This is useful for hardware that aggregates data from several machines.
Since agrirouter 2.0, router devices can have display names, making them easier to identify in the agrirouter UI.
Re-Onboarding
To refresh credentials or recover from a lost certificate, re-onboard using the same externalId. Re-onboarding returns new credentials and preserves the endpoint's identity, routes, and feed history.
Certificate Management
CU certificates have an expiration date. The expiration is visible to the user in the agrirouter UI. Plan for certificate renewal by implementing re-onboarding before certificates expire.
If a certificate expires before re-onboarding, the CU loses connectivity. Renew certificates well before they expire.