diff --git a/README.md b/README.md index 46b08b5..ef3ade4 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,59 @@ You should have received a copy of the GNU Affero General Public License along with this program. If not, see . -## Important Note +## Executive Summary -This software is experimental and should be considered a subject to -change at any time. +This is an educational tool designed for experimentation with Hamming +codes. A hamming code consists of a certain number of data bits and a +smaller number of check bits. The data bits are used to store +information, and the check bits are used to verify the integrity of +the message as a whole. In the event of a single bit error, the code +provides enough information to restore the original message. + +For more information on hamming codes, see [this +video](https://youtu.be/X8jsijhllIA) on YouTube. + +## Installation + +This program is written in [Haskell](https://haskell.org) using the +Stack package manager. The easiest way to install it is by first +installing [GHCup](https://www.haskell.org/ghcup/), and then from +within the project directory, run the command: `stack install` + +You should then be able to run it by simply typing `hamming` on the +command line. There are currently no command-line options. + +## Usage + +When run, the program will display a 16-bit extended hamming code in a +4x4 grid. The rows and columns are numbered 0-3 and a green check +mark or red X will be displayed in the upper left hand corner of the +code indicating whether or not it's valid. The check bits will be +highlighted to make them more easily identifiable. + +The program begins in display mode, but can be switched into edit mode +to change the value of the individual bits. While in edit mode, the +cursor will appear indicating the bit currently being edited. + +## Keyboard Commands + +In both modes of operation, these keys will have the following +effects: + +- CTRL-C/Q: Quit the program. +- C: Set the check bits to reflect the values in the data bits. +- V: Correct to the nearest valid code (if possible). +- R: Reset the code to all zeroes. + +### Display Mode + +- E: Enter edit mode. + +### Edit Mode + +- ESC: Return to display mode. +- Up/K: Move the cursor up. +- Down/J: Move the cursor down. +- Left/H: Move the cursor left. +- Right/L: Move the cursor right. +- F: Flip the bit under the cursor (1 becomes 0; 0 becomes 1).