Simple encode/decode utilities for bit-error correcting Hamming codes
Project description
hamming-codec
Simple encode/decode utilties for single-bit error correcting Hamming codes
Table of Contents
Requirements
Tested on Python >=3.6
and requires C++ compilers supporting C++17 features.
Installation
Python Installation
Install using pip
as follows:
$ python -m pip install hamming-codec
C++ Installation
If you wish to use the hamming-codec
encoding/decoding from within C++,
one needs to include the single header file
src/cpp/hamming_codec.h in their project.
There are a few ways to do this:
- Copy the file hamming_codec.h into your project's include path.
- Add
hamming-codec
as a sub-module (or equivalent) and use CMake to expose theHAMMING_CODEC_INCLUDE_DIRS
variable. See src/cpp/examples/CMakeLists.txt for an example.
Following either approach, you should be able to add #include "hamming_codec.h"
to your
source code.
Python Usage
From the Command-line
After following the Python installation, a commandline utility
hamming
will be available to you, which can be used for simple encoding and decoding
of data words. Use hamming --help
to show the full set of options and commands.
Encoding
You can use the hamming
commandline utility to encode messages of specified length
(in number of bits) as follows:
$ hamming encode 0x1234 16
0x2a3a1 21
Which shows that the 16-bit message 0x1234
is encoded as a 21-bit word 0x2a3a1
.
Decoding
You can use the hamming
commandline utility to decode messages of specified length (in number of bits) as follows:
$ hamming decode 0x2a3a1 21
0x1234 16
Which shows that the 21-bit encoded message 0x2a3a1
is decoded back into the 16-bit word 0x1234
.
Importing as a Module
Once you have installed hamming-codec, you can import the hamming_codec
module and perform encoding/decoding like so:
>>> import hamming_codec
>>> encoded_message = hamming_codec.encode(0x4235, 16)
>>> print(encoded_message)
010001010001110101100
>>> hex(int(encoded_message,2))
'0x8a3ac'
>>> decoded_message = hamming_codec.decode(int(encoded_message,2), len(encoded_message))
>>> print(decoded_message)
0100001000110101
>>> hex(int(decoded_message,2))
'0x4235'
C++ Usage
Including in your Project
Following the steps to add hamming-codec
to your include path,
you can encode/decode messages as follows:
#include "hamming_codec.h"
...
uint32_t n_bits = 16;
uint32_t input_message = 0x4235;
std::string encoded_message = hamming_codec::encode(input_message, n_bits);
std::cout << "Encoded message: 0x" << std::hex << std::stoul(encoded_message, 0, 2) << std::endl; // prints "Encoded message: 0x8a3ac"
std::string decoded_message = hamming_codec::decode(std::stoul(encoded_message, 0, 2), encoded_message.length());
std::cout << "Decoded message: 0x" << std::hex << std::stoul(decoded_message, 0, 2) << std::endl; // prints "Decoded message: 0x4235"
C++ Examples
After following the steps to build the C++ library, you can run the C++ examples. For example,
$ ./build/bin/example_encode 0x4235 16
0x8a3ac 21
Single-bit Error Correction
The Hamming encoding algorithm used within hamming-codec
allows for single-bit error corrections. That
is, during the decoding process, errors in which a single bit has been flipped in the encoded message
can both be detected and corrected.
For example, if we flip a single bit
in the encoded message from a previous section such that the 21-bit word 0x2a3a1
becomes 0x2a1a1
,
you will get the same decoded message as before:
$ hamming encode 0x1234 16
0x2a3a1 21
$ hamming decode 0x2a3a1 21
0x1234 16
$ hamming decode 0x2a1a1 21 # flipped a bit
0x1234 16 # ...but decodes the same as before!
References
Further information about the Hamming encoding algorithm employed within hamming-codec
can be found in the following resources:
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for hamming_codec-0.3.2-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 03cb241d4a15fdc15c9d4ce40bb0ebb0e4b9d7894d79d352fee01371511a0e9c |
|
MD5 | 754153f3091c792c5b689c43d6fc6c63 |
|
BLAKE2b-256 | d4fc5e930e8ca061d4d072512faca5b59eb31c354a14404540bc56655b2846ac |
Hashes for hamming_codec-0.3.2-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c1094a3c50d90fea27da139a340d8cab857be76a4d1012c8fe5f976e4cf80b9c |
|
MD5 | 98499678c1c9f1d105ee1967aad60fe3 |
|
BLAKE2b-256 | 77e52a3b2ffc3869636f9e8dc6c667eb79bb1b63c3f2c124657c3972a5acf55b |