How to Use CommsChampion Tools
The CommsChampion Tools are there to provide consistent environment for binary protocols visualization, traffic monitor and analysis. They are all plugin based. Plugins are used to select I/O socket, protocol definition itself as well as zero or more data filters in between.
The "socket" and "protocol" plugins are "must have" ones, without them the tools won't be able to operate properly. The "filters", on the other hand, are optional. They need to be used when there are any additional transport layers between the raw data received by the I/O socket and the data delivered to the analyzed communication protocol for processing. Good example would be analyzing custom protocol, when messages are delivered using MQTT-SN transport protocol over UDP/IP socket. The plugins configuration would look like this:
The filters may modify the incoming data prior to reporting the result to the following filter or protocol itself, or drop the data altogether when its irrelevant to the other filters or protocol itself. The filters are also allowed to generate data regardless of any protocol activity.
The "mqttsn filter" plugin from the example above is responsible to manage the whole underlying MQTT-SN protocol communication while forwarding only received "protocol" relevant data. When the "protocol" plugin generates data to be sent, the "mqttsn filter" wraps it in its internal PUBLISH message and forwards the result to the socket to be delivered over the I/O link.
The main application of the provided CommsChampion Tools is called cc_view. It is a GUI application, which allows visual analysis of the exchanged messages. When the application is started, the only available button is in the top left corner. It must be used to select plugins to load:
When clicked the plugin selection dialog pops up. The left side contains available plugins. They are split by their types: "sockets" are at the top, "protocols" are at the bottom and "filters" are in the middle. Selection of the plugin is performed via double-click on it. The tooltip of the hovered plugin shows a description of what it is.
When plugin is selected it appears at the top right area.
The "Plugins Configuration" area below allows configuration of all the selected plugins (if applicable).
The save/load of the plugins with their configuration is also available. Please read the Starting CC_VIEW Application section below for information on the directories where default configuration is expected to be.
SIDE NOTE: The cc_tools_qt project provides only a basic set of the plugins. Please refer to the CommsChampion Ecosystem's projects page for the full list of the available plugins (developed and stored as separate repositories).
When both necessary "socket" and "protocol" are selected, the "Apply" button at the bottom right becomes available. When clicked the selected plugins will be applied and some message control buttons become available. Use tooltips to see the meaning of the button as well as keyboard shortcut for the action.
Depending on the socket type, the connection to the server / device may be required. It is performed by clicking to the
button at the top left corner.
The top left area is used to display all the messages that have been sent or received. The
/
interchangeable button allows control of the reception of the incoming messages. The "toggle" buttons to
the right (
)
allow control of what kind of messages to display. They allow to enable / disable display of filtered, received
and sent messages as well as display of detected garbage input.
The bottom left area is used to create and send messages of the protocol. The
button can be used to create and configure new single message. The
button can be used to create new message(s) out of raw data dump.
When is clicked,
new dialog pops up where the selected protocol message can be chosen and values configured.
The bottom right area allows selection of the wrapping "transport" information to be displayed above
or raw bytes of the serialized message:
The "Extra Info" selection allows adding extra JSON object elements of which can provide extra information to the underlying plugins and change the behaviour of the latter. For example, when using "CC UDP Socket" it is possible to force broadcasting the message rather than uni-casting it to the configured address.
Please refer to the documentation of the relevant plugin for the list of the supported configuration values.
The top right area allows to configure multiple sends of the same message. The "Initial delay" specifies the delay from the first time the previous message in the "send" list was sent.
Once added, the newly created message is prefixed with configured delay and repetition information.
The first number is the initial delay in milliseconds, second number is a period between sends also in milliseconds, and the third number is amount of times the message is going to be sent (0 means infinite).
The displayed messages in the top left area (showing the traffic of the incoming / outgoing messages) are prefixed with the timestamp information.
When any of the messages is newly selected (or newly added when not selected), it is displayed at the right half of the application window.
When the selected message is in the "Messages to Send" area, it is possible to edit its values right away by modifying them in the right pane. However, when selected message is in the "All Messages" area, it is read-only and its modification is not possible.
To change the message type of the selected message in the "Messages to Send" area there is a need to either double-click it or
click the 
button when
selected. The message edit dialog will pop up allowing the change.
The created messages can be saved into the files and loaded later when needed.
There are several other useful buttons, if not covered below please try them yourself and see what they do.
When is clicked,
new dialog pops up where it is possible to provide dump of raw data. The application will parse the data and try to create proper messages out of it. It can be useful when copy-pasting traffic dump from some debug terminal.
There can be multiple messages of the same type in the "Messages to Send" area but with different inner data. To make it
easy to distinguish between them the comments can be attached to them using the
When the messages exchange is too quick or there are too many messages in the "All Messages" section, it can be
useful to show / hide particular type of messages. For this purpose
button can be used. The filter dialog will pop up.
To immediately enable / disable filter application the
toggle button can be used.
The bin subdirectory contains installed application binary. When built under Linux the wrapping script cc_view.sh is also installed. The scripts set environment variables to appropriate values and starts cc_view executable. The script as well as binary itself may receive several command line parameters. Use -h option for help.
When the cc_view application is started without any additional parameters, it looks for default.cfg file in the following locations (in the listed order):
- Application Persistent Storage Directory
(retrieved using QStandardPaths::AppDataLocation)
- Windows:
C:\Users\<user_name>\AppData\Roaming\cc_tools_qt
- Windows:
- share/cc_tools_qt/ subfolder of the installation path.
If default.cfg file exists, the plugins configuration from this file is loaded. In other words, in order to force loading custom plugins configuration file upon startup by default, save it as default.cfg in the one of the listed locations.
As was mentioned earlier, both "socket" and "protocol" plugins must be selected for the cc_view tool to work properly. However, quite often there is only a need to visualize the message out of the available raw data. In this case, no connection to the real device is needed. The CommsChampion Tools provide two dummy sockets. One is "NULL Socket", which drops all the sent messages and does not produce any input. Another one is "Echo Socket", which immediately reports sent data as received one. It can be useful when developing new communication protocol and making sure both "read" and "write" functionalities of the messages are properly implemented.
The CommsChampion Tools provide another application, called cc_dump. It can be used to send the messages out of configuration files created by cc_view and record all the incoming messages into a file, which can be opened later with cc_view for visual analysis.