avr-quantizer

A quantizer with support for arbitrary bins designed for AVR MCUs.

Getting Started • Under the Hood • Need Help? • About • Credits

Introduction

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.

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)

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

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.

Step 0: Software

• Atmel Studio 7.0 (Build 1931) [free]
  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 and extract the .zip file.

Step 2: Browse the project

• Open the project in Atmel Studio:
  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:
  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 ".

Under the Hood

Typically LUTs are direct mapped, for each input value a specific output value is stored. A quantisation assigns one output value to multiple input values, which would require a lot of memory 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 still be quite large. 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, the 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.

Support

Get Help

Something doesn't work as expected? No worries! Just open up a new issue in the GitHub issue tracker. 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 me directly.

Contribute

Spotted an error? Open an issue or submit a pull request.

There is no CONTRIBUTING.md yet, sorry. Contributions will inherit the license of this project. If you have any questions, just ask.

About

Status

This project is currently classified as
The developers intend to keep the code in working condition by updating dependencies, fixing bugs and solving issues.

Changelog

This project uses Semantic Versioning 2.0.0. 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
  
  • initial release

Contact

If you haven't done so already, please check out Get Help for the fastest possible help on your issue. Alternatively you can find my public email address on my profile.

Credits and References

Projects Used

• git-template - A simple and clean git repository template.
  

License

This project is proudly licensed under the MIT 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!