Complete readme

Author: nqtronix

README.md

@@ -13,6 +13,124 @@
 
 
 ## Introduction
-Generating arbitrary values from a small range of input values is easy with LUTs (look up tables). The reverse operation, condensing a large set of values into a small range, is typically either computation intensive (linear search through all values) or memory intensive (requires a LUT with 1000s of entries).
+Generating arbitrary values from a small range of input values is easy with look up tables (LUTs). The reverse operation, condensing a large set of values into a small range, is typically either computation intensive (linear search through all values) or memory intensive (requires a LUT with 1000s of entries).
+
+**avr-quantizer** converts arbitrary values into a compact range (0..n) efficently with neither drawback. The value ranges assigned to each output ("binning") is fully user defined and semi-automatically generated by the included excel file. Possible applications include identifying resistor values (E-series) or assigning the nearest octave in audio processing.
+
+<br>
+
+## Key Features
+
+ - **flexible:** easy custom LUTs with the included excel file
+ - **accurate:** less than ±0.4% quantisation error
+ - **lightweight:** function typ. <100 bytes; LUT typ. <50 bytes 
+ - **efficient:** <120 cycles per call (test loop avarage)
+
+<br>
+
+## Limitations
+
+ - The algorithm accesses the flash memory directly and thus it can't be used on "reduced core" AVRs such as the attiny4/5/9/10/20
+
+<br>
+
+## Getting Started
+This section is written especially for everyone who is **not familiar** with the used tools. If you run into problems, please [ask for clarification](#get-help).<br>
+
+### Step 0: Software
+ - [**Atmel Studio 7.0**][tool-atmel-studio-7-0] (Build 1931) [free]<br>
+   The installer contains all tools you need to open, edit, compile, simulate and flash this code. If you favor another development tool, feel free to use it instead. (But please understand that I can not provide any support).
+
+### Step 1: Download avr-tinyuart
+ - Clone this repository or hit [Download][git-download] and extract the .zip file.
+
+### Step 2: Browse the project
+ - **Open the project in Atmel Studio:**<br>
+   Either double click `quantizer.atsln` or open Atmel Studio and select "File -> Open -> Project/Solution..."
+
+### Step 3: Run the demo
+ - **Select your MCU & Programming tool:**<br>
+   Press `F5`to run the demo code in the simulator. Pause the simulation and mouse over the variables to see the results
+   
+### Step 4: Generate a custom LUT
+ - **Edit the included Excel file:**
+	Edit the orange fields with the values you need (do not leave any row empty) and copy the *grey* cell labeled "generated LUT" and paste it into your code. Don't forget to remove the leading and trailling `"`.
+
+<br>
+
+## Under the Hood
+
+Typically LUTs are direct mapped, for each input value a specific output value is stored. A quantisation assigns multiple values one output value, which would require a lot of memory that is filled with redundant information. This implementation instead stores the threshold values at which the output value changes.
+
+Depending on the size of the input value (2/4 byte) and the range of output values, the resulting LUT can be quite large still. Finding the correct value would require a search across all values and multiple 2/4 byte comparisons, which are rather slow on a AVR8 MCU. Because this level of accuracy is rarely required, this algorithm only compares the 8 most significant bits, ignoring the leading zeros. If the input value is larger than 8bit, it is shifted right until it can be compared. To represent numbers >8bit correctly, a header row is added to the LUT, which contains the LUT offset for each amount of shifts required.
+
+<br>
+
+## Support
+
+### Get Help
+
+**Something doesn't work as expected?** No worries! Just open up a new issue in the [GitHub issue tracker][git-issues]. Please provide all information to reproduce your problem. If you don't have a GitHub account (and can't be bothered to create one,) you can [contact](#contact) me directly.
+
+<br>
+
+### Contribute
+
+**Spotted an error?** [Open an issue][git-issues] or submit a pull request.
+
+There is no CONTRIBUTING.md yet, sorry. Contributions will inherit the [license](#license) of this project. If you have any questions, just ask.
+
+<br>
+
+## About
+### Status
+**This project is currently classified as** <a href="https://github.com/nqtronix/git-template/blob/master/badges.md#project-status"><img src="https://img.shields.io/badge/status-maintained-green.svg" alt="status: maintained"></a><br>
+_The developers intend to keep the code in working condition by updating dependencies, fixing bugs and solving issues._
+
+As my testing needs increase I will likely add the functionality I need.
+
+<br>
+
+### Changelog
+This project uses [**Semantic Versioning 2.0.0**][semver.org]. During initial development (0.x.x versions) any _major_ increase is substituted with a _minor_ increase (0.1.0->0.2.0 instead of 0.1.0->1.0.0).
+
+The message of each commit contains detailed information about the changes made. The list below is a summary about all significant improvements.
+
+ - **0.1.0** <br>
+	- initial release
+
+<br>
+
+### Contact
+
+If you haven't done so already, please check out [Get Help](#get-help) for the fastest possible help on your issue. Alternatively you can find my public email address on my [profile][git-profile].
+
+<br>
+
+## Credits and References
+
+### Projects Used
+- [**git-template**][git-repo-git-template] - _A simple and clean git repository template._<br>
+
+<br>
+
+
+## License
+This project is proudly licensed under the [MIT license][git-license].
+
+The MIT license was chosen to give you the freedom to use this project in any way you want, while protecting all contributors from legal claims. Good code works, great code works for everyone. If this code has become a part of one of your projects, a link back to us would be highly appreciated. Thanks!
+
+<!-- Links -->
+
+[git-readme]:README.md
+[git-license]:LICENSE.md
+[git-profile]:https://github.com/nqtronix
+[git-issues]:https://github.com/nqtronix/unittrace/issues
+[git-download]:https://github.com/nqtronix/unittrace/archive/master.zip
+
+[git-repo-git-template]:https://github.com/nqtronix/git-template
+
+[semver.org]:semver.org
+
+[tool-atmel-studio-7-0]:https://www.microchip.com/mplab/avr-support/atmel-studio-7
 
-**avr-quantizer** converts arbitrary values into a compact range (0..n) efficently with neither drawback. The value ranges assigned to each output ("binning") is fully user defined and semi-automatically generated by the included excel file. Possible applications include identifying resistor values (E-series) or assigning the nearest octave in audio processing.