How to code ASCII Text Based protocol over RS-232 in C

Question

I have to implement a relatively simple communication protocol on top of RS-232. It's an ASCII based text protocol with a couple of frame types.

Each frame looks something like this:

 * ___________________________________
 * |     |         |         |        |
 * | SOH |   Data  | CRC-16  | EOT    |
 * |_____|_________|_________|________|
 *   1B    nBytes      2B       1B

1. Start Of Header (1 Byte)
2. Data (n-Bytes)
3. CRC-16 (2 Bytes)
4. EOT (End Of Transmission)

Each data-field needs to be separated by semicolon ";": for example, for HEADER type data (contains code,ver,time,date,src,id1,id2 values):

{code};{ver};{time};{date};{src};{id1};{id2}

what is the most elegant way of implementing this in C is my question?

I have tried defining multiple structs for each type of frame, for example:

typedef struct {
    uint8_t soh;
    char code;
    char ver;
    Time_t time;
    Date_t date;
    char src; // Unsigned char
    char id1[20]; // STRING_20
    char id2[20]; // STRING_20
    char crlf;
    uint16_t crc;
    uint8_t eot;
} stdHeader_t;

I have declared a global buffer:

uint8_t DATA_BUFF[BUFF_SIZE];

I then have a function sendHeader() in which I want to use RS-232 send function to send everything byte by byte by casting the dataBuffer to header struct and filling out the struct:

static enum_status sendHeader(handle_t *handle)
{
    uint16_t len;
    enum_RETURN_VALUE rs232_err = OK;
    enum_status err = STATUS_OK;

    stdHeader_t *header = (stdHeader_t *)DATA_BUFF;

    memset(DATA_BUFF, 0, size);

    header ->soh= SOH,
    header ->code= HEADER,
    header ->ver= 10, // TODO
    header ->time= handle->time,
    header ->date= handle->date,
    header ->src= handle->config->source,
    memset(header ->id1,handle->config->id1, strlen(handle->config->id1));
    memset(header ->id2,handle->config->id2, strlen(handle->config->id1));
    header ->crlf = '\r\n',
    header ->crc  = calcCRC();
    header ->eot = EOT;

    len = sizeof(stdHeader_t );

    do
    {
        for (uint16_t i = 0; i < len; i++) 
        {
            rs232_err= rs232_tx_send(DATA_BUFF[i], 1); // Send one byte
            if (rs232_err!= OK)
            {
                err = STATUS_ERR;
                break;
            }
        }
        // Break do-while loop if there is an error
        if (err == STATUS_ERR)
        {
            break;
        }
    } while (conditions); 


    return err;
}

My problem is that I do not know how to approach the problem of handling ascii text based protocol, the above principle would work very well for byte based protocols.

Also, I do not know how to implement semicolon ";" seperation of data in the above snippet, as everything is sent byte by byte, I would need aditional logic to know when it is needed to send ";" and with current implementation, that would not look very good.

For fields id1 and id2, I am receiveing string values as a part of handle->config, they can be of any lenght, but max is 20. Because of that, with current implementation, I would be sending more than needed in case actual lenght is less than 20, but I cannot use pointers to char inside the struct, because in that case, only the pointer value would get sent.

So to sumarize, the main question is:

How to implement the above described text based protocol for rs-232 in a nice and proper way?

Answer 1

what is the most elegant way of implementing this (ASCII Text Based protocol) in C is my question?

• Since this is ASCII, avoid endian issues of trying to map a multi-byte integer. Simply send an integer (including char) as decimal text. Likewise for floating point, use exponential notation and sufficient precision. E.g. sprintf(buf, "%.*e", DBL_DECIMAL_DIG-1, some_double);. Allow "%a" notation.

• Do not use the same code for SOH and EOT. Different values reduce receiver confusion.

• Send date and time using ISO 8601 as your guide. E.g. "2022-11-10", "23:38:42".

• Send string with a leading/trailing ". Escape non-printable ASCII characters, and ", \, ;. Example for 10 long string 123\\;\"\xFF456 --> "123\\\;\"\xFF456".

• Error check, like crazy, the received data. Reject packets of data for all sorts of reasons: field count wrong, string too long, value outside field range, bad CRC, timeout, any non-ASCII character received.

• Use ASCII hex characters for CRC: 4 hex characters instead of 2 bytes.

• Consider a CRC 32 or 64.

• Any out-of-band input, (bytes before receiving a SOF) are silently dropped. This nicely allows an optional LF after each command.

• Consider the only characters between SOH/EOT should be printable ASCII: 32-126. Escape others as needed.

• Since "it's an ASCII based text protocol with a couple of frame types.", I'd expect a type field.

See What type of framing to use in serial communication for more ideas.

Answer 2

First of all, structs are really not good for representing data protocols. The struct in your example will be filled to the brim with padding bytes everywhere, so it is not a proper nor portable representation of the protocol. In particular, forget all about casting a struct to/from a raw uint8_t array - that's problematic for even more reasons: the first address alignment and pointer aliasing.

In case you insist on using a struct, you must write serialization/deserialization routines that manually copy to/from each member into the raw uint8_t buffer, which is the one that must be used for the actual transmission.

(De)serialization routines might not be such a bad idea anyway, because of another issue not addressed by your post: network endianess. RS-232 protocols are by tradition almost always Big Endian, but don't count on it - endianess must be documented explicitly.

My problem is that I do not know how to approach the problem of handling ascii text based protocol, the above principle would work very well for byte based protocols.

That is a minor problem compared to the above. Often it is acceptable to have a mix of raw data (essentially everything but the data payload) and ASCII text. If you want a pure ASCII protocol you could consider something like "AT commands", but they don't have much in the way of error handling. You really should have a CRC16 as well as sync bytes. Hint: preferably pick the first sync byte as something that don't match 7 bit ASCII. That is something with MSB set. 0xAA is popular.

Once you've sorted out data serialization, endianess and protocol structure, you can start to worry about details such as string handling in the payload part.

And finally, RS232 is dinosaur stuff. There's not many reasons why one shouldn't use RS422/RS485. The last argument for using RS232, "computers come with RS232 COM ports", went obsolete some 15-20 years back.

Answer 3

One thing your struct implementation is missing is packing. For efficiency reasons, depending on which processor your code is running on, the compiler will add padding to the structure to align on certain byte boundaries. Normally this doesn't effect you code that much, but if you are sending this data across a serial stream where every byte matters, then you will be sending random zeros across as well.

This article explains padding well, and how to pack your structures for use cases like yours

Structure Padding