Skip to main content

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

GitHub Actions Status Badge: CI/CD GitHub Actions Status Badge: cpp_build centos7_build pre-commit.ci status Code style: black License: MIT

Table of Contents

  1. Requirements
  2. Installation
  3. Python Usage
  4. C++ Usage
  5. Error-correction
  6. References

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:

  1. Copy the file hamming_codec.h into your project's include path.
  2. Add hamming-codec as a sub-module (or equivalent) and use CMake to expose the HAMMING_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

hamming_codec-0.3.1.tar.gz (181.4 kB view hashes)

Uploaded Source

Built Distributions

hamming_codec-0.3.1-pp37-pypy37_pp73-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (430.0 kB view hashes)

Uploaded PyPy manylinux: glibc 2.12+ x86-64

hamming_codec-0.3.1-pp37-pypy37_pp73-manylinux_2_12_i686.manylinux2010_i686.whl (446.7 kB view hashes)

Uploaded PyPy manylinux: glibc 2.12+ i686

hamming_codec-0.3.1-pp37-pypy37_pp73-macosx_10_9_x86_64.whl (380.6 kB view hashes)

Uploaded PyPy macOS 10.9+ x86-64

hamming_codec-0.3.1-cp310-cp310-musllinux_1_1_x86_64.whl (939.7 kB view hashes)

Uploaded CPython 3.10 musllinux: musl 1.1+ x86-64

hamming_codec-0.3.1-cp310-cp310-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.10 musllinux: musl 1.1+ i686

hamming_codec-0.3.1-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (433.6 kB view hashes)

Uploaded CPython 3.10 manylinux: glibc 2.12+ x86-64

hamming_codec-0.3.1-cp310-cp310-manylinux_2_12_i686.manylinux2010_i686.whl (448.5 kB view hashes)

Uploaded CPython 3.10 manylinux: glibc 2.12+ i686

hamming_codec-0.3.1-cp310-cp310-macosx_10_9_x86_64.whl (383.3 kB view hashes)

Uploaded CPython 3.10 macOS 10.9+ x86-64

hamming_codec-0.3.1-cp39-cp39-musllinux_1_1_x86_64.whl (940.1 kB view hashes)

Uploaded CPython 3.9 musllinux: musl 1.1+ x86-64

hamming_codec-0.3.1-cp39-cp39-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.9 musllinux: musl 1.1+ i686

hamming_codec-0.3.1-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (433.9 kB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.12+ x86-64

hamming_codec-0.3.1-cp39-cp39-manylinux_2_12_i686.manylinux2010_i686.whl (448.8 kB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.12+ i686

hamming_codec-0.3.1-cp39-cp39-macosx_10_9_x86_64.whl (383.5 kB view hashes)

Uploaded CPython 3.9 macOS 10.9+ x86-64

hamming_codec-0.3.1-cp38-cp38-musllinux_1_1_x86_64.whl (939.5 kB view hashes)

Uploaded CPython 3.8 musllinux: musl 1.1+ x86-64

hamming_codec-0.3.1-cp38-cp38-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.8 musllinux: musl 1.1+ i686

hamming_codec-0.3.1-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (433.8 kB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.12+ x86-64

hamming_codec-0.3.1-cp38-cp38-manylinux_2_12_i686.manylinux2010_i686.whl (448.3 kB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.12+ i686

hamming_codec-0.3.1-cp38-cp38-macosx_10_9_x86_64.whl (383.3 kB view hashes)

Uploaded CPython 3.8 macOS 10.9+ x86-64

hamming_codec-0.3.1-cp37-cp37m-musllinux_1_1_x86_64.whl (942.1 kB view hashes)

Uploaded CPython 3.7m musllinux: musl 1.1+ x86-64

hamming_codec-0.3.1-cp37-cp37m-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.7m musllinux: musl 1.1+ i686

hamming_codec-0.3.1-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (438.3 kB view hashes)

Uploaded CPython 3.7m manylinux: glibc 2.12+ x86-64

hamming_codec-0.3.1-cp37-cp37m-manylinux_2_12_i686.manylinux2010_i686.whl (456.9 kB view hashes)

Uploaded CPython 3.7m manylinux: glibc 2.12+ i686

hamming_codec-0.3.1-cp37-cp37m-macosx_10_9_x86_64.whl (379.7 kB view hashes)

Uploaded CPython 3.7m macOS 10.9+ x86-64

hamming_codec-0.3.1-cp36-cp36m-musllinux_1_1_x86_64.whl (942.1 kB view hashes)

Uploaded CPython 3.6m musllinux: musl 1.1+ x86-64

hamming_codec-0.3.1-cp36-cp36m-musllinux_1_1_i686.whl (1.0 MB view hashes)

Uploaded CPython 3.6m musllinux: musl 1.1+ i686

hamming_codec-0.3.1-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (438.2 kB view hashes)

Uploaded CPython 3.6m manylinux: glibc 2.12+ x86-64

hamming_codec-0.3.1-cp36-cp36m-manylinux_2_12_i686.manylinux2010_i686.whl (457.0 kB view hashes)

Uploaded CPython 3.6m manylinux: glibc 2.12+ i686

hamming_codec-0.3.1-cp36-cp36m-macosx_10_9_x86_64.whl (379.6 kB view hashes)

Uploaded CPython 3.6m macOS 10.9+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page