Reed-Solomon error correction over GF(2^8)
ocaml-linkedin: apply dune fmt
Pure formatting changes from `dune fmt`: doc comment placement moves
from above the binding to below it for `type`s, multi-line `match`
expressions collapse onto one line where they fit, and infix operator
applications pick up spaces (`Soup.($?)` -> `Soup.( $? )`). No
semantic changes.
+90
-1
+82
README.md
+82
README.md
···
1
+
# reed-solomon
2
+
3
+
Reed-Solomon error correction over GF(2^8) for OCaml.
4
+
5
+
Systematic Reed-Solomon encoder and decoder with configurable code
6
+
parameters. The decoder recovers up to `t = (n - k) / 2` symbol
7
+
errors using syndrome computation, Berlekamp-Massey, Chien search,
8
+
and the Forney algorithm. Ships with the CCSDS [131.0-B-4][ccsds]
9
+
RS(255,223) preset (`t = 16`) used on TM downlinks and spacecraft
10
+
telemetry; other codes are defined by populating
11
+
`Reed_solomon.config` directly (field polynomial, primitive element,
12
+
first root).
13
+
14
+
[ccsds]: https://public.ccsds.org/Pubs/131x0b4.pdf
15
+
16
+
## Installation
17
+
18
+
Install with opam:
19
+
20
+
<!-- $MDX skip -->
21
+
```sh
22
+
$ opam install reed-solomon
23
+
```
24
+
25
+
If opam cannot find the package, it may not yet be released in the
26
+
public `opam-repository`. Add the overlay repository, then install
27
+
it:
28
+
29
+
<!-- $MDX skip -->
30
+
```sh
31
+
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
32
+
$ opam update
33
+
$ opam install reed-solomon
34
+
```
35
+
36
+
## Usage
37
+
38
+
`encode_systematic` takes exactly `k` data bytes and returns an
39
+
`n`-byte codeword whose first `k` bytes are the data unchanged and
40
+
whose last `2t` bytes are parity. For the CCSDS preset, that's 223
41
+
data bytes in and 255 codeword bytes out:
42
+
43
+
```ocaml
44
+
# let data = Bytes.make 223 '\x42' in
45
+
let codeword = Reed_solomon.encode_systematic Reed_solomon.ccsds data in
46
+
Bytes.length codeword
47
+
- : int = 255
48
+
```
49
+
50
+
Round-trip a message, corrupting up to `t = 16` symbols on the
51
+
channel:
52
+
53
+
```ocaml
54
+
# let data = Bytes.make 223 '\x00' in
55
+
Bytes.blit_string "hello, reed-solomon" 0 data 0 19;
56
+
let codeword = Reed_solomon.encode_systematic Reed_solomon.ccsds data in
57
+
(* Flip 16 arbitrary symbols — at the limit of what we can recover. *)
58
+
for i = 0 to 15 do
59
+
Bytes.set_uint8 codeword (i * 11) (Bytes.get_uint8 codeword (i * 11) lxor 0xa5)
60
+
done;
61
+
match Reed_solomon.decode Reed_solomon.ccsds codeword with
62
+
| Ok recovered -> String.sub (Bytes.to_string recovered) 0 19
63
+
| Error e -> Fmt.str "decode failed: %a" Reed_solomon.pp_error e
64
+
- : string = "hello, reed-solomon"
65
+
```
66
+
67
+
When the channel flips more than `t = 16` symbols, the decoder
68
+
reports failure rather than returning silently corrupted data:
69
+
70
+
```ocaml
71
+
# let data = Bytes.make 223 '\x00' in
72
+
let codeword = Reed_solomon.encode_systematic Reed_solomon.ccsds data in
73
+
for i = 0 to 16 do Bytes.set_uint8 codeword i 0xff done;
74
+
match Reed_solomon.decode Reed_solomon.ccsds codeword with
75
+
| Ok _ -> "unexpectedly recovered"
76
+
| Error e -> Fmt.str "decode failed: %a" Reed_solomon.pp_error e
77
+
- : string = "decode failed: Chien search failed to find roots"
78
+
```
79
+
80
+
## Licence
81
+
82
+
ISC
+4
dune
+4
dune
+3
-1
dune-project
+3
-1
dune-project