tutorial

This tutorial shows how to use the generated code in your program. It uses the simplest and most common version of CRC code, where all parameters are defined. We will generate the header file, the CRC source code and a sample main program file compile (using GCC) and check the result.

How to run pycrc.py

This section explains how to run a python script. If you know how to do that, then skip to the next section. The safest way to run pycrc.py is to add the command python at the beginning of the line as in this example:

python pycrc.py --help

Please see also the Python on Windows FAQ.

On a Unix-style system you can make pycrc.py executable and call it like a command:

chmod +x pycrc.py
./pycrc.py --help

Generate the code

Generate the header file (crc.h) with the following command.

python pycrc.py --model crc-16 --algorithm table-driven --generate h -o crc.h

The CRC source code (crc.c) is generated in a similar way:

python pycrc.py --model crc-16 --algorithm table-driven --generate c -o crc.c

We are using the CRC-16 model and the table-driven algorithm. You can choose from a variety of different models or you can specify your own model using the command line options described in the pycrc man page.

Write the main file

This is a very basic main.c that calculates the CRC over the constant string "123456789".

#include <stdio.h>
#include <string.h>
#include "crc.h"

int main(void)
{
    static char str[] = "123456789";
    crc_t crc;

    crc = crc_init();
    crc = crc_update(crc, (unsigned char *)str, strlen(str));
    crc = crc_finalize(crc);

    printf("0x%lx\n", (unsigned long)crc);
    return 0;
}

Please note that you can call crc_update() many times. That means you don't have to calculate the CRC on the whole data in one go. You could in theory call crc_update() once for each byte in your input data. Just remember to pass the previously calculated CRC value (the variable crc in the example) as parameter to crc_update().

As an example, here is the same code that calculates the CRC value one character at a time. Obviously this code gives the same result as the one above.

#include <stdio.h>
#include <string.h>
#include "crc.h"

int main(void)
{
    static char str[] = "123456789";
    crc_t crc;
    int i;

    crc = crc_init();
    for (i = 0; i < strlen(str); i++) {
        crc = crc_update(crc, (unsigned char *)&str[i], 1);
    }
    crc = crc_finalize(crc);

    printf("0x%lx\n", (unsigned long)crc);
    return 0;
}

Compile and hope for the best

The two lines below compile the code and call the binary. Hopefully you will see the expected result 0xbb3d.

gcc -W -Wall -std=c99 crc.c main.c -o crc
./crc

Verify the result

Now check if your binary gave you the expected result:

python pycrc.py --model crc-16

You can also verify the result using one of the online calculators like the CRC calculator on breitbandkatze.de or the CRC calculator on lammertbies.nl.

Tips

A slightly more complicated main.c file can be generated using the --generate c-main command line option of pycrc. Note that this option combines a sample crc.c file and a main.c file in one output. Use this option if you are not sure how to call the generated functions.

The pycrc man page and the generator page contain other examples of how pycrc can be used.