You might, or might not have heard about a tool called Wireshark, it is quite popular in the software development world.
Wireshark is a free and open-source packet analyzer. It is used for network troubleshooting, analysis, communications protocol development and education. It makes analyzing what is going on with packet based protocols easier.
Most often Wireshark is used for network based protocols like TCP and UDP, to try to figure out what is happening with your networking code. But! Wireshark also allows you to write your own packet dissector plugin, this means that you can register some code to make Wireshark handle your custom packet based protocol.
For the latest release of the Crazyflie Python Library we added support for generating a log of the Crazy Real Time Protocol (CRTP) packets the library sends and receives. This is the (packet based) protocol that we use to communicate with the Crazyflie via radio and USB.
We generate this log in the special PCAP format that Wireshark expects. And we also created an initial version of a dissector plugin, written in the programming language LUA.
When we put this two things together it turns into a pretty cool way of debugging what goes on between your computer and the Crazyflie!
What does it look like?
Wireshark gives you a graphical interface where you can view all the packets in a PCAP file. You will see the timestamps of when they arrived. Selecting a packet will give you the information that the dissector has managed to deduce as well as how the packet looked on the wire.
On top of that you get powerful filtering tools. In the below image we have set a filter to view only packets that are received or sent on the CRTP port 8, which is the port for the High level commander. This means that from a log file that contain 44393 packets we now only display 9. Which makes following what goes on with high level commands a bit easier.
The dissector knows about the different types of CRTP ports and channels and knows how to dissect an high level set-point, as seen by the image above.
What can this be used for?
This functionality is, we think, most useful for when developing new functionality in the Crazyflie firmware, or in the library. You can easily inspect what the library receives or sends and make sure it matches what your code indented.
But it can also be useful when doing client type work! We recently located the source of a bug in the Crazyflie client with the use of this Wireshark plugin.
It was when updating the Parameter tab of the client to handle persistent parameters, and to use a sidebar for extra documentation and value control. As I was testing the code I noticed that every time I changed the value of ring.effect to a valid integer and then disconnected and reconnected, the value was set to 0. Regardless of the value I had set.
I recorded a session using the PCAP log functionality:
$ CRTP_PCAP_LOG=ring.pcap cfclient
And the I fired up wireshark:
$ wireshark ring.pcap
It was now possible for me to track what the library and firmware thought was going on with the ring.effect parameter, by tracking the crtp.parameter_varid field using Wireshark. Filtering down from from 3282 packets to 12 packets.
I had earlier figured out that the varid of the ring.effect variable was 183. This is a quasi-internal representation of a parameter that we do not expose in a good way. In the future we will try to make this Wireshark tracking work with the parameter name as well.
Looking at the write parameter packet from USB #3 to the Crazyflie I could see where I set the value of the parameter to 5, so far so good.
The surprising part however was seeing a write further down setting the parameter to 0! This mean that something in the client was actually setting this to zero!
After seeing this, locating the actual issue was trivial. I noticed that the Flight Control tab was setting the ring.effect parameter to the current index of the combo box in the UI. And when no LED-ring deck was attached, this amounted to always setting the value to zero.
But having confirmation that this was something happening on the client side, and not some kind of bug with the new persistent parameters was very helpful!
How do you use this?
We have added documentation to the repository documentation for the library on how to generate the PCAP log and how install the Wireshark plugin.
But the quick-start guide is this:
- Copy the tools/crtp-dissector.lua script to the default Wireshark plugin folder
- Windows: %APPDATA%\Wireshark\plugin or WIRESHARK\plugins
- Linux: ~/.local/lib/wireshark/plugins
- Restart Wireshark or hit
CTRL+SHIFT+L - Set the environmental variable CRTP_PCAP_LOG to the filename of the PCAP log you want to generate
- Run Wireshark with the filename as an argument
And please report any issues you find!
Happy hacking!