VDA 5050 is an open protocol devised by the German association of car manufacturers (Verband der Automobilindustrie), it is meant to become the common language that AGVs (autonomous guided vehicles) use to exchange information with a controller. To get an idea of what it looks like - imagine a fleet of robots moving pieces and materials from one spot to another on a factory floor. A controlling server sends instructions, telling each robot where to go, which checkpoints to drive through, what actions to perform and with what settings (e.g. "pick up this specific box and bring it over there, place it on the second shelf").

VDA 5050 uses MQTT to transmit JSON payloads to several purpose-specific topics. In the screenshot you can see several windows, each displaying the data arriving to these topics.

Notes about nodes, edges, and orders

In VDA 5050 terms, the control server commands AGVs by sending them orders, each order is represented through a set of nodes connected by edges. Each node and edge has a sequence number, indicating the succession in which it has to be traversed. Optionally, any node or edge can be associated with some actions (e.g., load, unload) that have to be performed there.

In addition to that, nodes and edges can be "released" or "unreleased". An AGV is only allowed to traverse released nodes and edges, which are collectively referred to as the "base". The unreleased part is called the "horizon". Thus, when an order is sent to the AGV, it has a base and a horizon, such that the AGV knows what it has to do in the long term, but until further notice, it will only move up to the end of the base, but no further.

Troubleshooting VDA 5050 implementations

Suppose you sent an order to the AGV, expecting it to stop at the end of the base. However, there's a problem - it stopped sooner than it should. When you build a list of possible explanations, you might come up with this:

• the succession of nodes and edges is wrong
• the succession is correct, but their actual sequence numbers are wrong
• everything is correct, but there's a problem on the AGV's side

To test each hypothesis, you have to look at the JSON payload, find each node and edge, see if it is in the right position in the list (i.e. are in the correct sequence), then check the sequenceNumber attribute of each node, then check whether the released parameter is true where necessary, etc.

Since JSON payloads are usually minified, this is no easy task, because everything is written in one line. In practice you usually need to scroll to the right point in the log, copy/paste the payload to a text editor that prettifies it for you, so you can look at an indented structure that is more readable.

More readable doesn't mean "piece of cake", it is just a step ahead of the raw thing, but you are still dealing with a "find a needle in a haystack" type of problem. Clearly, this is time consuming and boring. Moreover, it is error-prone, because we can easily lose count, misremember, or simply forget something.

Asking the right questions

When dealing with monotonous tasks we can keep our focus for a while, but it definitely doesn't make work joyful. To make things better, we ask ourselves "what are we looking for when debugging VDA 5050 implementations?". Here's a list:

• are there any gaps in the base?
• are all there duplicate sequence numbers?
• are there gaps in the sequence numbers?
• are the sequence numbers monotonically increasing?

Notice that each question gets a yes/no answer, just one bit. However, getting each bit is a tedius task.

The next step, if either of those answers is "yes", would be to dig a bit deeper:

• where (which node or edge) does the gap occur?
• at what position is the sequence number is duplicated?
• what is the duplicated value?

The VDA 5050 payload visualizer

While implementing this protocol myself, I spent a lot of time looking for needles in haystacks, answering the questions above. You can try to do it in your mind, but when orders are complex you end up sketching them on paper, because otherwise you end up juggling too many items in your head.

After going through that multiple times, I developed a payload visualizer which is now freely shared by [arculus](arculus.de).

This is a debugging aid built to "scratch my own itch" - I had a problem and I had to do something about it.

An overview

The VDA 5050 visualizer is inspired by a mixture of several concepts:

• Network sniffers like Wireshark (formerly Ethereal)
• Chat programs that show a conversation
• A dashboard that shows a laconic representation of the state of a system
• Computer games that show a minimap of the world in some corner

Basically, the visualizer illustrates the data exchange between the AGV and the control node in the form of a chat. You can scroll through the history of messages, while the alignmnent of "bubbles" indicates who sent the message.

Each entry is not just a piece of text, but a visual representation of the JSON payload that was sent.

Thus, you can easily grasp the big picture and observe the dynamics of the relationship between the AGV and the control server.

Answers on a plate

Usability is further improved by sprinkling a bit of logic on top. Let's say you see the nodes, but you want to check their sequence numbers - you do that by going through each node and edge.

The payload visualizer takes that burden off your mind, because it will display problematic sequence numbers in red. So, the problem is now changed from "find the sequence number of each node, then look at the subsequent node, compare the numbers and see if anything is fishy about it" into "is there anything red?".

The former task is more complex from the cognitive point of view, whereas the latter is a purely visual problem that your eyes can solve on their own.

The same applies to out-of-order headerIds that come with each message. The only way to know whether you've received a duplicate, or if you've missed a message is by keeping track of the header ID. The payload visualizer makes it easy - anomalies are highlighted in red. The same applies to updateIds.

What about unexpected gaps within base (i.e., some unreleased nodes surrounded by released ones)? That's easy - the base is "bold and green", whereas the horizon is "thin and gray". As in the previous case, the problem with a high cognitive load was transformed into a less demanding one - "are there any gray blobs surrounded by green ones?".

Other goodies

The VDA 5050 payload visualizer also displays the various flags that the AGV sends with each message, e.g., does it need a base extension? Is it driving? Is it charging? Is it carrying loads? and so on.

Besides that, you can click a button to see the raw JSON payload itself, in case you don't trust the visualizer, or if you want to be able to replicate the problem by storing the message and sending it later.

Each status message is accompanied by a minimap where you can see where the AGV was at the time.

Whenever a new order is set, a "separator line" is rendered, so you can easily identify such orders; otherwise you'd have to compare the orderIds, which happen to be UUIDs, so they're pretty long.

Pressing Ctrl+P will allow you to print the entire "chat history" between the AGV and the control node, as well as export it to a PDF. This way you can share logs with your colleagues, so they can all troubleshoot a case by following the exact sequence of events that lead to an error.

All the graphical information rendered on the screen is SVG, so it brings several benefits:

• everything is searchable, press Ctrl+F and type an order ID, a header ID, or an action - anything, really! You can quickly find it, because the graphics are not "just a picture", but they're semantically annotated too
• zoom in to look at the details, or zoom out to see the big picture - everything remains crisp

Under the hood

The visualizer works in your browser and connects directly to your broker. Thus, everything runs on your own infrastructure, so nothing potentially sensitive could leak out (e.g., that you're working on VDA 5050 in the first place, how many AGVs you have, what kind of errors you encounter, etc.).

Moreover, since the visualizer simply subscribes to the same topics as the AGV and the control node - it gets copies of all the messages, but doesn't publish any messages on its own. Thus, it is guaranteed not to interfere with anything.

Another benefit is that you don't need to change anything in your AGV or in the controlling node. The payload visualizer is just another MQTT subscriber connecting to your broker, that's it.

Since everything runs in the browser, it can also be used on your mobile phone if you want to have a look at the traffic while debugging something on-site.

Configuring the MQTT broker

The tool requires an MQTT broker that supports websockets. This feature is widely supported by many brokers, I'll illustrate how to do it in Mosquitto:

1. Edit /etc/mosquitto/conf.d/websocket.conf

2. Add this to the contents (adjust port numbers to your needs)

     listener 1883
     listener 1884
     protocol websockets

3. Restart it with systemctl mosquitto restart

As a result, you'll have the regular MQTT over TCP on port 1883, and MQTT over websockets on port 1884.

Conclusion

This payload visualizer is a tool I wish I had at hand when I was implementing VDA 5050, it would have saved me a lot of time and mental effort. It transforms boring and error-prone problems like "find the wrong number in this mountain of data" into purely visual problems that can be solved much easier, by the visual equivalent of "muscle memory".

Drop by vda5050.arculus.de to see it in action. Feel free to provide feedback and request new features.