Re: Communicating with WSJT-X over UDP #udp

Bill Somerville

On 22/11/2020 07:31, s53c.lado@... wrote:
I'm working on (yet another) ham logging program written in c#. I do not have big plans for it: It is just a project I am using as a means to learn something new and to help me pass my retirement days. Right now I am trying to add communication between WSJT-X and this logging program. So far I am able to decode most of the messages coming from WSJT-X , Where I am stuck is that I don't understand the schema negotiation between WSJT-X  and UDP server. Datagram from UDP server to WSJT-X seems to be defined in NetworkMessage part of NetworkMessage.hpp. But as I know practically nothing of C++, I am not able to read and interpret what's written there. So I kindly ask if there is someone to show how the message from UDP server to WSJT-X  should be constructed in a way like messages from WSJT-X to UDP servers are described.

Lado, S53C
Hi Lado,

firstly you need to understand that there may be many WSJT-X instances *and* interoperating server applications like your logging program working together in what I will refer to as a "mesh". Each may be written and updated at different times and can only be expected to understand the data type schema at the time they were last updated. To allow the "mesh" of applications to interoperate there must be a lowest common denominator schema that they all understand. The schema negotiation is how this is occurs. Each new application joining the "mesh" shall wait for a Heartbeat message and examine the current schema being used, it shall then reply with another Heartbeat message that contains the highest schema number it can work with. The WSJT-X client receiving that Heartbeat message will adjust it's outgoing schema by lowering it to match if necessary. That in turn will be received by all server applications in the "mesh" and they in turn will adjust if necessary. The result, eventually, will be all applications will settle on the adjusted schema number. You application shall always monitor the schema number of incoming traffic and be prepared to move to a lower schema number. It is forbidden to send a message with a higher schema number than any previously received schema number in a given operating session.

Note that the schema number is not the schema of the data messages and fields within them, it is the schema of the underlying data types. This means the schema only changes very rarely when a data type encoding has to change. Note also that neither new fields appended to existing messages, or new message types, even if new data types included,do not require a new schema number. A new schema number is *only* necessary if an data type of a field used in an already published message type has a change in the encoding of that type.

To make this schema scheme work we guarantee that no message field in existing messages will be changed, only new fields appended to existing message types, or new message types will be added. To comply with this your application must be prepared to receive datagrams that are longer than the expected sum of fields, or indeed new unknown message types. Both of these cases should be silently ignored as they represent updates to the messages for a newer version than the one your application was coded to support. Of course you can update you application to recognize those new fields and message types in your own time.

You application shall be prepared to receive messages with any schema up to and equal to the maximum schema it understands. There are currently three possible schema numbers (1, 2, and 3), but as noted in Network/NetworkMessage.hpp schema number 1 is broken and obsolete so will never be used, so currently you must support schema numbers 2 and 3. The difference lies in the encoding of the QDateTime type, in schema 2 QTime components with a value of 0 represent NULL whereas in schema 3 -1 represents NULL. There are also changes in the QDate component but only in the timespec field and we guarantee to only use the UTC timespec where there is no difference be tween schema numbers 2 and 3.

The current list of message types and fields is documented in the WSJT-X project source repository in this file:

in the commentary at the top. This file may be updated at any WSJT-X public release so authors of interoperating applications should monitor the history of this file for changes at those times if they wish to track any recent changes. No C++ knowledge is required as the commentary has all the information you need, or hyperlinks to further reading for it.


Join to automatically receive all group messages.