VDA 5050 AGV Integration
How to use Connectware as the MQTT broker between VDA 5050 compliant AGVs and a master control system, including the topic structure, user permissions, and AGV state in the Unified Namespace.
This guide describes how to use Connectware as the MQTT broker between automated guided vehicles (AGVs) that implement the VDA 5050 interface and a master control system. You configure a service commissioning file that creates the users and permissions for both sides and maps AGV state data into a Unified Namespace (UNS). A complete example file is available at the end of this guide.
Objectives
Understanding the VDA 5050 topic structure and which side publishes on which topic.
Creating Connectware users and roles with least-privilege permissions for AGVs and the master control system.
Making AGV battery and position data visible in a UNS topic hierarchy.
Verifying the integration with an MQTT client.
Prerequisites
To follow this guide, you will need the following:
A running instance of Cybus Connectware.
One or more AGVs or autonomous mobile robots (AMRs) that implement VDA 5050 version 2, and a master control system (often called fleet manager) that implements the same version. Both must have network access to the Connectware MQTT broker on port
8883(TLS) or1883.Access to the Admin UI with sufficient user permissions.
Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, mappings, and roles).
It helps to be familiar with Connecting an MQTT Client to Publish and Subscribe Data.
Connectware and VDA 5050 Integration
VDA 5050 is a standardized interface for the communication between AGVs and a master control system, published by the German Association of the Automotive Industry (VDA) and the VDMA Materials Handling and Intralogistics Association. The interface is broker-centric by design: AGVs and the master control never talk to each other directly. Both connect as MQTT clients to a broker and exchange JSON messages on well-defined topics.
VDA 5050 defines the topics and messages, but not the broker. Connectware fills this role:
Central broker: AGVs from different manufacturers and the master control system all connect to the same Connectware instance. No vehicle-specific broker or gateway is required.
Governed access: Connectware permissions restrict each AGV to its own topic subtree, so one misconfigured vehicle cannot publish state for another.
Plain JSON payloads: Unlike binary payload formats such as Sparkplug B, VDA 5050 messages are plain JSON. Connectware can read, transform, and route them with the Rule Engine, for example to republish battery and position data into a UNS.
Monitoring: You can inspect all VDA 5050 traffic live in the Data Explorer.
This guide follows VDA 5050 version 2.1.0. The topic examples use the major version v2.
VDA 5050 Topic Structure
VDA 5050 suggests the following MQTT topic structure for local brokers:
For example, the master control sends orders to the AGV with the serial number 0001 of the manufacturer KIT on the topic uagv/v2/KIT/0001/order. The interface name and the major version are subject to agreement between the AGV vendors and the master control vendor. This guide uses uagv/v2, which matches the example in the specification.
The subtopic names are mandatory. The following subtopics are defined:
order
Master control → AGV
A driving order as a graph of nodes and edges, including actions to execute.
0
No
instantActions
Master control → AGV
Actions that the AGV executes immediately, for example pausing or starting a charging process.
0
No
state
AGV → Master control
The full AGV state: order progress, battery, position, errors. Sent on relevant events, at the latest every 30 seconds.
0
No
visualization
AGV → Master control
Position and velocity at a higher, integrator-defined update rate, for near real-time visualization.
0
No
connection
AGV → Master control
The connection state of the AGV, maintained with the MQTT last will mechanism.
1
Yes
factsheet
AGV → Master control
The capabilities and parameters of the AGV, such as its physical dimensions and supported actions.
0
Yes
The quality of service (QoS) and retained flags in the table are the conventions that the specification mandates. The AGV and the master control set them on their own publishes; there is nothing to configure in Connectware for this.
Connection Topic and MQTT Last Will
The connection topic tells the master control whether an AGV is reachable. Its payload contains a connectionState field with one of the following values:
ONLINE
The AGV is connected to the broker.
OFFLINE
The AGV disconnected gracefully and published this message before closing the connection.
CONNECTIONBROKEN
The connection between the AGV and the broker ended unexpectedly.
The CONNECTIONBROKEN message is never sent by the AGV itself. When the AGV connects, it registers an MQTT last will on its connection topic with connectionState: CONNECTIONBROKEN, QoS 1, and the retained flag. If the connection drops unexpectedly, the Connectware broker publishes this last will on behalf of the AGV. Right after connecting, the AGV publishes connectionState: ONLINE as a retained message, so the topic always carries the current availability of the vehicle.
Because the broker publishes the last will under the identity of the AGV client, the AGV user needs write permission on its connection topic like on any other topic it publishes to. The permission setup in this guide includes it.
Creating Users and Permissions
Both the AGV and the master control system authenticate against Connectware with username and password, like any other MQTT client. For more information, see MQTT Client Authentication. We create the users and their roles in the service commissioning file with the Cybus::User and Cybus::Role resources.
Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.
Integration Parameters
We add the manufacturer and serial number of the AGV, the passwords, and the UNS topic root as parameters, so you can set them when you install the service:
manufacturerandserialNumber: Identify the AGV in the VDA 5050 topic structure. They must match the values that the AGV uses in its own configuration.agvPasswordandmasterControlPassword: The passwords for the two MQTT users.topicRoot: The root of the UNS topic hierarchy. Defaults toenterprise.
AGV User and Role
The AGV subscribes to its order and instantActions topics and publishes on its state, visualization, connection, and factsheet topics. The role grants exactly these permissions, restricted to the subtree of this one vehicle:
The resource identifier of the user becomes the username, prefixed with the service ID that you assign when you install the service. For example, with the service ID vda5050, the AGV authenticates as vda5050.agv_kit_0001. If you change the manufacturer or serialNumber parameters, rename the user resource accordingly. When you operate several AGVs, add one user and one role per vehicle, so each vehicle stays restricted to its own subtree.
Instead of defining AGV users in the service commissioning file, you can also let vehicles register themselves via the Client Registry and assign the permissions in the Admin UI. This is convenient when vehicles are commissioned one by one on the shop floor.
Master Control User and Role
The master control system needs the opposite permissions, across all vehicles: it publishes orders and instant actions to any AGV and subscribes to everything the AGVs report. The single-level wildcard + matches any manufacturer and serial number:
Making AGV State Visible in the UNS
The state message carries everything the master control needs to run the fleet, but consumers such as dashboards, historians, or an andon board usually only need a few fields. Because the payload is plain JSON, a Cybus::Mapping with a transform rule can extract these fields and republish them into an ISA-95-style UNS hierarchy (<enterprise>/<site>/<area>/<line>/<cell>).
The following abridged state message shows the fields used in this guide. A complete state message also contains fields such as orderUpdateId, nodeStates, edgeStates, actionStates, driving, operatingMode, errors, and safetyState:
The mapping subscribes to the state topics of all vehicles with the named wildcards +manufacturer and +serial and reuses the matched values in the output topics as $manufacturer and $serial. Two transform rules extract the battery and position fields. A third mapping entry republishes the connectionState with the retained flag, so the UNS always shows the current availability of each vehicle:
Adjust the site and area segments (hamburg/intralogistics/agv-fleet) to your own hierarchy. With the state message shown earlier, the mapping publishes the following message to enterprise/hamburg/intralogistics/agv-fleet/KIT/0001/battery:
The agvPosition object is optional in VDA 5050. For vehicles that do not report a position, the transform output simply omits the position fields.
The mapping deliberately uses the state topic, not the visualization topic. The visualization topic carries the same position data at a much higher, integrator-defined update rate. Running transforms on it multiplies the processing load for every vehicle. Only add a mapping on the visualization topic if a consumer really needs the higher update rate.
Verifying the Integration
Install the service and set the parameters, including the two passwords. See Installing Services.
Configure the AGV and the master control system with the Connectware hostname, port
8883(TLS) or1883, and their usernames and passwords. Remember that the usernames are prefixed with the service ID, for examplevda5050.agv_kit_0001andvda5050.master_control.Open the Data Explorer and subscribe to
uagv/v2/#. When the AGV connects, its retainedONLINEmessage appears on theconnectiontopic, followed bystatemessages.Check the UNS topics, for example
enterprise/hamburg/intralogistics/agv-fleet/KIT/0001/battery. The extracted battery and position messages appear whenever the AGV publishes its state.
If no real vehicle is available yet, you can simulate one with an MQTT client such as mosquitto_pub:
Replace the following values:
${CONNECTWARE_HOST}: The hostname or IP address of your Connectware instance.${SERVICE_ID}: The service ID that you assigned when you installed the service.${AGV_PASSWORD}: The value of theagvPasswordparameter.
Service Commissioning File Example
Last updated
Was this helpful?