mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-09-20 00:55:58 -04:00
157 lines
5.2 KiB
Markdown
157 lines
5.2 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/FLETCHER/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/FLETCHER/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/FLETCHER/issues)
|
|
|
|
[](https://github.com/RobTillaart/FLETCHER/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/FLETCHER/releases)
|
|
[](https://registry.platformio.org/libraries/robtillaart/FLETCHER)
|
|
|
|
|
|
# FLETCHER
|
|
|
|
Arduino Library for Fletcher's checksum
|
|
|
|
|
|
## Description
|
|
|
|
This library provides a Fletcher checksum of a data array.
|
|
|
|
Fletcher's checksum is in general faster than CRC but possibly not as
|
|
good in detecting errors.
|
|
See https://en.wikipedia.org/wiki/Fletcher%27s_checksum for details.
|
|
|
|
Relates to https://github.com/RobTillaart/CRC
|
|
|
|
Use https://github.com/RobTillaart/printHelpers to print the Fletcher64().
|
|
|
|
Tested on Arduino UNO + ESP32 + SAMD (See PR #7).
|
|
|
|
|
|
#### Related
|
|
|
|
- https://en.wikipedia.org/wiki/Fletcher%27s_checksum
|
|
- https://github.com/RobTillaart/Adler
|
|
- https://github.com/RobTillaart/CRC
|
|
- https://github.com/RobTillaart/Fletcher
|
|
- https://github.com/RobTillaart/LUHN
|
|
|
|
|
|
## Interface
|
|
|
|
|
|
## Fletcher16
|
|
|
|
These interfaces are very similar for Fletcher16, Fletcher32 and Fletcher64 class.
|
|
|
|
```cpp
|
|
#include "Fletcher16.h"
|
|
```
|
|
|
|
- **Fletcher16()** Constructor, initializes internals.
|
|
- **void begin(uint8_t s1 = 0, uint8_t s2 = 0)** resets the internals.
|
|
optional setting start values for s1 and s2. Note this is not part of the standard.
|
|
- **void add(uint8_t value)** add a single value to the checksum.
|
|
- **void add(const uint8_t \* array, uint8_t length)** add an array of values to the checksum.
|
|
- **uint16_t getFletcher()** get the current checksum.
|
|
- **uint32_t count()** get the number of items added. Merely a debugging feature, can overflow without affecting checksum.
|
|
|
|
The checksum from **getFletcher()** can be split into a high and a low part
|
|
to be used to "feed" **begin()** again. See restart example.
|
|
|
|
|
|
## Interface static functions
|
|
|
|
The functions are straightforward, however one should define **length**
|
|
in terms of the data type and optional pad it with zeros.
|
|
|
|
A string "abcdef" has length 2 for **fletcher64()** as it needs 2x4 bytes.
|
|
|
|
```cpp
|
|
#include "Fletcher.h"
|
|
```
|
|
|
|
- **uint16_t fletcher16(uint8_t \*data, uint16_t length, uint32_t s1 = 0, uint32_t s2 = 0)** length in units of 1 byte = 8 bits.
|
|
- **uint32_t fletcher32(uint16_t \*data, uint16_t length, uint32_t s1 = 0, uint32_t s2 = 0)** length in units of 2 bytes = 16 bits.
|
|
- **uint64_t fletcher64(uint32_t \*data, uint16_t length, uint64_t s1 = 0, uint64_t s2 = 0)** length in units of 4 bytes = 32 bits.
|
|
|
|
Since 0.1.8:
|
|
Added parameters s1 and s2 to make the functions more versatile.
|
|
Defaults are backwards compatible.
|
|
|
|
|
|
#### Performance I
|
|
|
|
Not tested ESP32 (and many other platforms) yet.
|
|
First numbers of **.add(value)** measured with test sketch shows the following timing.
|
|
|
|
| Checksum | UNO 16 MHz | ESP32 240 MHz |
|
|
|:------------|:-----------:|:-------------:|
|
|
| Fletcher16 | 3.8 us | 0.22 us |
|
|
| Fletcher32 | 5.6 us | 0.23 us |
|
|
| Fletcher64 | 10.1 us | 0.26 us |
|
|
| Average | 6.5 us | 0.24 us |
|
|
|
|
|
|
#### Performance II
|
|
|
|
Not tested extensively, first numbers of **.add(array, length)**
|
|
measured with **Fletcher_performance.ino** sketch shows the following timing.
|
|
|
|
Lorem Ipsum text = 868 bytes.
|
|
|
|
Version 0.1.3.
|
|
|
|
| Checksum | UNO 16 MHz | ESP32 240 MHz | Notes |
|
|
|:------------|:-----------:|:-------------:|:-------------------|
|
|
| Fletcher16 | 1120 us | 62 us | first run slower ? |
|
|
| Fletcher32 | 728 us | 33 us | |
|
|
| Fletcher64 | 1952 us | 35 us | |
|
|
| Average | 1267 us | 43 us | |
|
|
| Avg / char | 1.46 us | 0.0495 us | 868 bytes |
|
|
|
|
|
|
Note 0.1.4 has improved the performance. See PR #7 for some numbers.
|
|
|
|
|
|
## Operation
|
|
|
|
See examples.
|
|
|
|
|
|
## Future ideas
|
|
|
|
#### Must
|
|
|
|
- improve documentation
|
|
- update performance figures.
|
|
|
|
#### Should
|
|
|
|
- test other platforms
|
|
- extend unit tests
|
|
- start parameters static functions.
|
|
- redo performance tests static functions after parameter addition.
|
|
- create defines for MAGIC NRS (0.2.0).
|
|
|
|
#### Could
|
|
|
|
- others e.g. Fletcher24?
|
|
- generic FletcherN(). for N = 1..32
|
|
- add Print interface
|
|
- or Printable() ?
|
|
- Stream ??
|
|
- add getters for S1 and S2 in the classes
|
|
|
|
#### Wont
|
|
|
|
|
|
## Support
|
|
|
|
If you appreciate my libraries, you can support the development and maintenance.
|
|
Improve the quality of the libraries by providing issues and Pull Requests, or
|
|
donate through PayPal or GitHub sponsors.
|
|
|
|
Thank you,
|