GY-63_MS5611/libraries/CRC/README.md

137 lines
5.1 KiB
Markdown
Raw Normal View History

2021-01-29 06:31:58 -05:00
[![Arduino CI](https://github.com/RobTillaart/CRC/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
2021-10-27 07:42:30 -04:00
[![Arduino-lint](https://github.com/RobTillaart/CRC/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/CRC/actions/workflows/arduino-lint.yml)
[![JSON check](https://github.com/RobTillaart/CRC/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/CRC/actions/workflows/jsoncheck.yml)
2021-01-29 06:31:58 -05:00
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/CRC/blob/master/LICENSE)
[![GitHub release](https://img.shields.io/github/release/RobTillaart/CRC.svg?maxAge=3600)](https://github.com/RobTillaart/CRC/releases)
# CRC
2021-12-14 14:22:40 -05:00
Arduino library with CRC8, CRC16, CRC32 and CRC64 functions.
2021-01-29 06:31:58 -05:00
## Description
2021-12-14 14:22:40 -05:00
Goal of this library is to have a flexible and portable set of generic
CRC functions and classes.
2021-01-29 06:31:58 -05:00
2021-12-14 14:22:40 -05:00
The CRCx classes have a number of added values. Most important is that
they allow one to verify intermediate CRC values. This is useful if one
sends a "train of packets" which include a CRC so far. This detects both
errors in one packet but also missing packets, or injected packages.
2021-01-29 06:31:58 -05:00
2021-12-14 14:22:40 -05:00
Another trick one can do is change the polynome or the reverse flag during
the process. This makes it harder to imitate.
2021-04-07 07:31:22 -04:00
Furthermore the class allows to add values in single steps and continue too.
2021-12-14 14:22:40 -05:00
Finally the class version gives more readable code (imho) as the parameters
are explicitly set.
2021-01-29 06:31:58 -05:00
**Note** the classes have same names as the static functions, except the class
is UPPER case. So CRC8 is a class and **crc8()** is the function.
Deeper tech info -https://en.wikipedia.org/wiki/Cyclic_redundancy_check
and many other websites.
## Interface CRC classes
These interfaces are very similar for CRC8, CRC16, CRC32 and CRC64 class.
2021-12-14 14:22:40 -05:00
The only difference is the data type for polynome, start- and end-mask,
and the returned CRC.
2021-01-29 06:31:58 -05:00
Use **\#include "CRC8.h"**
- **CRC8()** Constructor
- **void reset()** set all internals to constructor defaults.
2021-12-14 14:22:40 -05:00
- **void restart()** reset internal CRC and count only; reuse values for other
e.g polynome, XOR masks and reverse flags.
2021-04-07 07:31:22 -04:00
- **void setPolynome(polynome)** set polynome, note reset sets a default polynome.
2021-10-27 07:42:30 -04:00
- **void setStartXOR(start)** set start-mask, default 0.
- **void setEndXOR(end)** set end-mask, default 0.
- **void setReverseIn(bool reverseIn)** reverse the bit pattern of input data (MSB vs LSB).
- **void setReverseOut(bool reverseOut)** reverse the bit pattern of CRC (MSB vs LSB).
2021-01-29 06:31:58 -05:00
- **void add(value)** add a single value to CRC calculation.
2021-12-14 14:22:40 -05:00
- **void add(array, uint32_t length)** add an array of values to the CRC.
In case of a warning/error use casting to (uint8_t \*).
- **uint8_t getCRC()** returns CRC calculated so far. This allows to check the CRC of
a really large stream at intermediate moments, e.g. to link multiple packets.
- **uint32_t count()** returns number of values added so far. Default 0.
2021-01-29 06:31:58 -05:00
### Example snippet
2021-12-14 14:22:40 -05:00
A minimal usage only needs:
2021-01-29 06:31:58 -05:00
- the constructor, the add() function and the getCRC() function.
```cpp
2021-04-07 07:31:22 -04:00
#include "CRC32.h"
...
2021-01-29 06:31:58 -05:00
CRC32 crc;
...
while (Serial.available())
{
int c = Serial.read();
crc.add(c);
}
Serial.println(crc.getCRC());
```
## Interface static functions
Use **\#include "CRC.h"**
Most functions have a default polynome, same start and end masks, and default there is no reversing.
However these parameters allow one to tweak the CRC in all aspects known.
2021-10-27 07:42:30 -04:00
In all the examples encountered the reverse flags were set both to false or both to true.
2021-01-29 06:31:58 -05:00
For flexibility both parameters are kept available.
2021-12-14 14:22:40 -05:00
- **uint8_t crc8(array, length, polynome = 0xD5, start = 0, end = 0, reverseIn = false, reverseOut = false)** idem with default polynome.
- **uint16_t crc16(array, length, polynome = 0xA001, start = 0, end = 0, reverseIn = false, reverseOut = false)** idem with default polynome.
2021-01-29 06:31:58 -05:00
- **uint16_t crc16-CCITT(array, length)** fixed polynome **0x1021**, non zero start / end masks.
2021-12-14 14:22:40 -05:00
- **uint32_t crc32(array, length, polynome = 0x04C11DB7, start = 0, end = 0, reverseIn = false, reverseOut = false)** idem with default polynome.
- **uint64_t crc64(array, length, polynome, start, end, reverseIn, reverseOut)** - experimental version, no reference found except on Wikipedia.
2021-01-29 06:31:58 -05:00
Note these functions are limited to one call per block of data. For more flexibility use the classes.
2021-12-14 14:22:40 -05:00
## Operational
See examples.
## Links
- https://en.wikipedia.org/wiki/Cyclic_redundancy_check - generic background.
- https://crccalc.com/ - online CRC calculator to verify.
2021-01-29 06:31:58 -05:00
## Future
- extend examples.
- table versions for performance? (performance - memory discussion)
- example showing multiple packages of data linked by their CRC.
- stream version - 4 classes class?
2021-04-07 07:31:22 -04:00
- setCRC(value) to be able to pick up where one left ?
- getters, getPolynome() etc?
-
2021-01-29 06:31:58 -05:00
#### Exotic CRC's ?
- **CRC1()** // parity :)
2021-12-14 14:22:40 -05:00
- **CRC4(array, length, polynome, start, end, reverseIn, reverseOut)** nibbles?
2021-01-29 06:31:58 -05:00
- default polynome 0x03
2021-12-14 14:22:40 -05:00
#### Magic \#defines for "common" polynomes? verify ?
2021-01-29 06:31:58 -05:00
- \#define CRC_ISO64 0x000000000000001B
- \#define CRC_ECMA64 0x42F0E1EBA9EA3693