#LyX file created by tex2lyx 2.0.6
\lyxformat 413
\begin_document
\begin_header
\textclass report
\begin_preamble

\renewcommand*{\familydefault}{\ttdefault}
\usepackage{listings}\usepackage{float}\usepackage{indentfirst}\usepackage{url}\urlstyle{same}
\graphicspath{{./}}
\title{Entropy Library Documentation}
\author{Walter Anderson}
\date{April 2014}

\lstset{
 language=C++,
 showstringspaces=false,
 formfeed=\newpage,
 tabsize=4,
 commentstyle=\itshape,
 basicstyle=\ttfamily\footnotesize,
 numberstyle=\ttfamily\footnotesize,
 moredelim=[il][\large\textbf]{\#\# },
 morekeywords={models}
}
     
\newcommand{\code}[2]{
 \hrulefill
 \subsection*{#1}
 \lstinputlisting{#2}
 \vspace{2em}
}


\end_preamble
\use_default_options false
\language english
\language_package none
\inputencoding auto
\fontencoding T1
\font_roman default
\font_sans default
\font_typewriter beramono
\font_default_family ttdefault
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\default_output_format default
\output_sync 0
\paperfontsize 10
\spacing single
\use_hyperref 0
\papersize letterpaper
\use_geometry true
\use_amsmath 1
\use_esint 1
\use_mhchem 0
\use_mathdots 0
\cite_engine natbib_authoryear
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\use_refstyle 0
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
pagenumbering{roman}
\end_layout

\end_inset

 
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
maketitle
\end_layout

\end_inset

 
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Chapter

Introduction
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
pagenumbering{arabic}
\end_layout

\end_inset

 
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
setcounter{page}{1}
\end_layout

\end_inset

 The updated Entropy library works on all AVR based Arduino platforms, and now has been ported to the ARM based platforms, Teensy 3.x and the Due. On the Teensy, it is still using clock jitter, though not the watch dog timer, and produces at about twice the rate of the an AVR based Arduino. When the library is used with the Due, it makes use of the Atmel SAM3X chips built in hardware random number generator. This allows the library to produce at a rate of XX unsigned longs per second, versus the 2 longs per second on a standard Arduino.
\end_layout

\begin_layout Standard

This updated version of the library also includes the option of producing floating point random numbers. More detail on how to use this functionality is included with the documentation for the randomf() method. Related to the inclusion of floating point is another method that will provide random numbers in a gaussian distribution (normal, bell curve) with a specified mean and standard deviation. 
\end_layout

\begin_layout Section

Background
\end_layout

\begin_layout Standard

The Arduino currently lacks a means of obtaining true random numbers. One pre-existing library exists, TrueRandom, but a review of the performance and code base confirms that the TrueRandom library does not make use of a truly random entropy source (the unconnected analog pin) 
\begin_inset CommandInset citation
LatexCommand citet
after ""
before ""
key "Krisston2011"

\end_inset

 which is further biased by methods which introduce additional biases into the results which it does return. When using the Arduino's pseudo-random number generator, random(), will produce a predictable sequence of numbers unless some random mechanism is used to seed it. The manual recommends using the results from an unconnected analog pin; however, there is ample evidence that this mechanism does not introduce much randomness to the sequences produced by the internal psuedo-random number generator.
\end_layout

\begin_layout Standard

The purpose of this library is to provide a mechanism to produce a series of true random numbers based upon the entropy associated with the jitter of the AVR's watch dog timer, and the standard Timer 1. 
\begin_inset CommandInset citation
LatexCommand citet
after ""
before ""
key "Pedersen2006"

\end_inset

 Since this mechanism produces entropy at a relatively slow rate (approximately 8 bytes per second) its best use is as a seed value to the internal pseudo-random number generator or for those demands that do not require large numbers of random numbers, such as generating cryptographically secure passwords. 
\begin_inset CommandInset citation
LatexCommand citet
after ""
before ""
key "Hlavac2010"

\end_inset


\end_layout

\begin_layout Standard

Preliminary testing indicates that this mechanism produces cryptographically secure random numbers, but the mechanism is subject to potential biases introduced by alterations to the host environment. Prior to deploying this library it is suggested that the end-user perform any testing required to establish that the specific implementation will meet the user's needs.
\end_layout

\begin_layout Section

Testing
\end_layout

\begin_layout Standard

The underlying mechanism that the library uses to generate true random numbers were tested on a number of different arduino devices; leonardo, uno, uno (smd), and the mega (R3), etc... Details of this preliminary testing is available 
\begin_inset CommandInset citation
LatexCommand citet
after ""
before ""
key "ARDWDTRN"

\end_inset

 which was also the source of the idea for the mechanism used by this library. The early tests performed on this library used methods published by John Walker. 
\begin_inset CommandInset citation
LatexCommand citet
after ""
before ""
key "Walker2011"

\end_inset

 The raw data used in the testing of the mechanism is available a link in the testing section of the project web page from:
\end_layout

\begin_layout Standard


\size tiny
https://sites.google.com/site/astudyofentropy/project-definition/timer-jitter-entropy-sources/entropy-library/ 
\size default

\end_layout

\begin_layout Standard

Since the basic method only produces about 2 long integer values per second, the more detailed testing of a single device is an ongoing process, which is estimated to take 1-2 years to collect enough data to perform more vigourous testing. The project's website should be checked for the status of this long-term testing if interested.
\end_layout

\begin_layout Chapter

Usage
\end_layout

\begin_layout Standard

The library directory should be placed in your libraries sub-folder where your Arduino IDE is configured to keep your sketches. When you first place this library, you will need to re-start your Arduino IDE in order for it to recognize the new library.
\end_layout

\begin_layout Standard

To use the library, you will need to include the libraries header file, Entropy.h in your sketch. Prior to calling any of the entropy retrieval methods, you need to initialize the library using its Initialize method.
\end_layout

\begin_layout Standard

The library only produces uniformly distributed integers (bytes, ints, and longs) and single precision floats. Since they are so useful for certain applications the library will also produce gaussian distributed floats with a specified mean and standard deviation. If other distributions are needed it is recommended that the user consult an appropriate reference 
\begin_inset CommandInset citation
LatexCommand citet
after ""
before ""
key "Matloff2006"

\end_inset

 on generating different distributions. One of the examples provided with the library demonstrates how to convert the random long integer returned by this library into a uniformly distributed random floating point in the range of [0,1].
\end_layout

\begin_layout Section

Initialize()
\end_layout

\begin_layout Standard

This method configures the chip's timers and set-ups the internal structures nescessary to convert the hardware timer's jitter into an unbiased stream of entropy. On the Due it configures the chips hardware random number generator. This method should only be called once, in the setup function of your sketch. After this method is executed, it will take the Arduino approximately five hundred milli-seconds before the first unsigned long (32-bit) random integer is available, and much faster for the Due platform.
\end_layout

\begin_layout Standard

For this reason, the call to the initialize method should occur fairly early in the set-up function, allowing ample time to perform other set-up activities, before requesting any entropy.
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset

Initialize Example
\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

initializeexample.ino
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Section

available()
\end_layout

\begin_layout Standard

This method returns an unsigned char value that represents the number of unsigned long integers in the entropy pool. Since the entropy retrieval methods (random) will block any further program execution until at least one value exists in the entropy pool, this function should be used to only call the retrieval methods when entropy is available.
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset

available() Example
\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

availableexample.ino
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Section

random()
\end_layout

\begin_layout Standard

The random method is the mechanism to retrieve the generated entropy. It comes in three flavors, of which, this one returns a single unsigned long (32-bit) integer value in the range of 0 to 0xFFFFFFFF. Since this method will prevent any further program execution until a value is available to return, it can take up to a maximum of 500 milliseconds to execute. If the delay is not desirable, the available method can be used to test if entropy is available prior to calling this method. If desired the returned value can be cast from unsigned to signed if needed.
\end_layout

\begin_layout Standard

The library does not produce floating point random values but if those are wanted, it is a simple matter to use the value returned by this method to produce a random floating point value.
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset

random() Example
\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

availableexample.ino
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Section

random(max)
\end_layout

\begin_layout Standard

The random method is the mechanism to retrieve the generated entropy. It comes in three flavors, of which, this one returns a single unsigned long (32-bit) integer value in the range of [0,max). Note that the returned value will always be less than max. The returned value can be cast to any integer type that will contain the result. In other words, if max is 256 or less the returned value can be stored in a char variable or an unsigned char variable, depending upon whether negative values are required. Similiarly, if max is 65536 or less the returned value can be stored in a int or unsigned int, again depending upon whether negative numbers are required.
\end_layout

\begin_layout Standard

Like the previous implementation of this method described, this method will prevent any further program execution until a value is available to return. This method behaves differently from the previous if max is less than 256 or max is less than 65536. In the first case the 32-bit unsigned integer in the entropy pool is broken into four byte sized integers. Consequently four byte sized values are returned for every 32-bit integer in the entropy pool. In a similar way, values less than 65536 but greater than or equal to 256 will return two 16-bit integer values for every 32-bit integer in the entropy pool. Note that the latter means that the method will need to use two bytes of the entropy to provide a uniformly distributed random byte (max = 256). This is nescessary to allow the function to maintain uniform distribution of returned values for other values of max... More detail is available as comments in the library code.
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset

random(max) Example
\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

randommaxexample.ino
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Section

random(min,max)
\end_layout

\begin_layout Standard

The random method is the mechanism to retrieve the generated entropy. It comes in three flavors, of which, this one returns a single unsigned long (32-bit) integer value in the range of [min,max). Note that the returned value will always be greater than or equal to min and less than max. The returned value can be cast to any integer type that will contain the result. In other words, if max is 256 or less the returned value can be stored in a char variable or an unsigned char variable, depending upon whether negative values are required. Similiarly, if max is 65536 or less the returned value can be stored in a int or unsigned int, again depending upon whether negative numbers are required.
\end_layout

\begin_layout Standard

This function is useful for simulating the role of dice, or the drawing of cards, etc.. Like the previous implementation of this method described, this method will prevent any further program execution until a value is available to return. This method behaves differently from the previous if (max-min) is less than 256 or (max-min) is less than 65536. In the first case the 32-bit unsigned integer in the entropy pool is broken into four byte sized integers. Consequently four byte sized values are returned for every 32-bit integer in the entropy pool. In a similar way, value differences less than 65536 but greater than or equal to 256 will return two 16-bit integer values for every 32-bit integer in the entropy pool.
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset

random(min,max) Example
\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

randomminmaxexample.ino
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Section

randomByte()
\end_layout

\begin_layout Standard

This method is included to overcome the efficiency problem mentioned when attempting to retrieve a full byte of entropy using the random(256) method. Since that method will need to consume two full bytes from the entropy stream to return a single byte of entropy this method was included for the special case, where a single complete byte of entropy is needed at a time. This allows four such bytes to be returned from each entropy value, rather than two. In all other ways it behaves in a manner consistent with the random() method.
\end_layout

\begin_layout Section

randomWord()
\end_layout

\begin_layout Standard

This method is included to overcome the efficiency problem mentioned when attempting to retrieve a full word (16-bit integer) of entropy using the random(65536) method. Since that method will need to consume four bytes from the entropy stream to return only two bytes, this method was included for the special case where a single integer is needed. This allows two such integers to be returned from each entropy value, rather than only one. In all other ways it behaves in a manner consistent with the random() method.
\end_layout

\begin_layout Section

randomf()
\end_layout

\begin_layout Standard

This method will produce uniformly distributed random float in the range of [0-1).
\end_layout

\begin_layout Section

randomf(max)
\end_layout

\begin_layout Standard

This method will produce a uniformly distributed random float in the range of [0 - max).
\end_layout

\begin_layout Section

randomf(min, max)
\end_layout

\begin_layout Standard

This method will produce a uniformly distributed random float in the range of [min - max).
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset

randomf(...) Example
\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

randomfexample.ino
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Section

rnorm(mean, stdDev)
\end_layout

\begin_layout Standard

This method will produce a gaussian distributed (normal, bell curve) random float with the specified mean that will collective exhbit the characteristic standard deviation.
\end_layout

\begin_layout Chapter

Library Source
\end_layout

\begin_layout Section

Header
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset

Entropy.h
\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

../Entropy.h
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Section

Code
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset

Entropy.cpp
\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

../Entropy.cpp
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Section

Keywords
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset

keywords.txt
\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

../keywords.txt
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Section

Software license
\end_layout

\begin_layout Standard


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
code{
\end_layout

\end_inset


\begin_inset ERT
status collapsed

\begin_layout Standard

}{
\end_layout

\end_inset

../gpl.txt
\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Standard


\begin_inset CommandInset bibtex
LatexCommand bibtex
bibfiles "research"
options "plainnat"

\end_inset


\end_layout

\end_body
\end_document
