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.
When plugin is selected it appears at the top right area.
Once selected, it becomes possible to configure the plugin if needed.
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.
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 rest of the buttons become available.
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 
button allows 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 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 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, which shows the traffic of the incoming / outgoing messages, are prefixed with the timestamp information.
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.
When any of the messages is newly added or selected, its info is displayed at the right half of the application window.
The created messages can be saved into the files and loaded later when needed.
The bin subdirectory contains installed scripts cc_view.sh for Linux and cc_view.bat for Windows. The scripts set environment variables to appropriate values and start cc_view(.exe) executable. The scripts 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\CommsChampion - Linux:
/home/<user_name>/.local/share/CommsChampion(depends on setting of XDG_DATA_HOME environment variable - see XDG Base Directory Specification)
- Windows:
- share/CommsChampion/ 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.