diff options
112 files changed, 6928 insertions, 109 deletions
diff --git a/flibbit.py b/flibbit.py new file mode 100644 index 0000000..5f149d4 --- /dev/null +++ b/flibbit.py @@ -0,0 +1,26 @@ +import os +import shutil +import re +from os.path import * + +src = '/Users/mbolivar/foo/arduino.cc/en/Reference' +dst = '/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino' + +fs = [x for x in os.listdir(src) if x.endswith('.rst')] + +def process(line): + if re.match('-+$', line.rstrip()): + return '=' * (len(line) - 1) + '\n' + elif re.match('\^+$', line.rstrip()): + return '-' * (len(line) - 1) + '\n' + return line + +for f in fs: + print 'processing:', f + with open(join(src,f), 'r') as f_in: + with open(join(dst, basename(f)), 'w') as f_out: + label = '.. _arduino-%s:\n\n' % (f.split('.')[0]) + f_out.write(label) + for line in list(f_in.readlines())[20:-22]: + f_out.write(process(line)) + diff --git a/source/adc.rst b/source/adc.rst index 4e118aa..c1281be 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -19,6 +19,10 @@ number of techniques must be used to get good precision and accuracy. D0, D1, D2, D3, D10, D11, D12, D13, D15, D16, D17, D18, D19, D20, D27, D28 + Note that pins 3, 27, and 28 are not marked AIN on the silkscreen + for Maple revisions through Rev 5, however, they **do work** as + analog input pins. + .. contents:: Contents :local: @@ -55,7 +59,7 @@ range; opamps and other powered components can also be used. Function Reference ------------------ -.. TODO function reference (figure out Doxygen first) +TODO function reference (figure out Doxygen first) .. _adc-recommended-reading: @@ -66,10 +70,8 @@ Recommended Reading * `Arduino Analog Input Tutorial <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet (pdf) <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ - * `Reference Manual (pdf) <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ - * `Application Note on ADC Modes (pdf) <http://www.st.com/stonline/products/literature/an/16840.pdf>`_ - * `Application Note on ADC Oversampling (pdf) <http://www.st.com/stonline/products/literature/an/14183.pdf>`_ - - + * `All <stm32-all>`_ + * `Datasheet <datasheet>`_ (pdf) + * `Reference Manual <full-manual>`_ (pdf) + * `Application Note on ADC Modes (pdf) <stm32-adc-modes>`_ + * `Application Note on ADC Oversampling (pdf) <stm32-adc-oversampling>`_ diff --git a/source/arduino/abs.rst b/source/arduino/abs.rst new file mode 100644 index 0000000..5d699ae --- /dev/null +++ b/source/arduino/abs.rst @@ -0,0 +1,33 @@ +.. _arduino-abs: + +abs(x) +====== + +Description +----------- + +(Macro) computes the absolute value of a number. + +Parameters +---------- + +**x**: the number + +Returns +------- + +**x**: if **x** is greater than or equal to 0. + +**-x**: if **x** is less than 0. + +Warning +------- + +Because of the way ``abs()`` is implemented, avoid using other +functions or causing side effects inside the brackets, as it may lead +to incorrect results :: + + abs(a++); // avoid this - yields incorrect results + + a++; // use this instead - + abs(a); // keep other math outside the function diff --git a/source/arduino/analogread.rst b/source/arduino/analogread.rst new file mode 100644 index 0000000..d0fa5a1 --- /dev/null +++ b/source/arduino/analogread.rst @@ -0,0 +1,134 @@ +.. highlight:: cpp + +.. _arduino-analogread: + +analogRead() +============ + + +Signature +--------- + +``int analogRead(int pin);`` + + +Description +----------- + +Reads the value from the specified analog pin. The Maple board +contains a 16-channel, 12-bit analog to digital converter. This means +that it will map input voltages between 0 and 3.3 volts into integer +values between 0 and 4095. This yields a resolution between readings +of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors +interfere with getting full accuracy and precision. For more +information, see :ref:`adc`. + +Before calling analogRead() on a pin, that pin must first be +configured for analog input, using :ref:`arduino-pinMode`. + +The input range and resolution can be changed using +:ref:`arduino-analogReference`. + +It takes about 0.8 microseconds (.0000008 seconds) to read an analog +input, so the maximum sample rate using this function is approximately +1.3 million samples per second [#fsamp]_. + + +Parameters +---------- + +**pin** + + The number of the analog input pin to read from. Header pins on the + Maple with ADC functionality (marked as "AIN" on the silkscreen) + are: + + 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 + + Note that pins 3, 27, and 28 are not marked AIN on the silkscreen + for Maple revisions through Rev 5, however, they **do work** as + analog input pins. + +Returns +------- + +Converted input voltage as an ``int``, with value 0 to 4095, inclusive. + + +Note +---- + +If the analog input pin is not connected to anything, the value +returned by analogRead() will fluctuate based on a number of factors +(e.g. the values of the other analog inputs, how close your hand is to +the board, etc.). + + +Example +------- + + :: + + + int analogPin = 3; // potentiometer wiper (middle terminal) connected to analog pin 3 + // outside leads to ground and +3.3V + int val = 0; // variable to store the value read + + void setup() { + pinMode(analogPin, INPUT_ANALOG); + SerialUSB.begin(); + } + + void loop() { + val = analogRead(analogPin); // read the input pin + SerialUSB.println(val); // debug value + } + + +Arduino Compatibility Note +-------------------------- + +The Arduino board contains a 6 channel (8 channels on the Mini and +Nano, 16 on the Mega), 10-bit analog to digital converter. This means +that it will map input voltages between 0 and 5 volts into integer +values between 0 and 1023. This yields a resolution between readings +of: 5 volts / 1024 units or, .0049 volts (4.9 mV) per unit. On the +Arduino, the input range and resolution can be changed using their +implementation of `analogReference() +<http://arduino.cc/en/Reference/AnalogReference>`_\ . + +On the Arduino, it takes about 100 microseconds (0.0001 s) to read an +analog input, so the maximum reading rate is about 10,000 times a +second. + + +See also +-------- + +- :ref:`ADC note <adc>` +- :ref:`analogReference <arduino-analogreference>` +- `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ + + +.. rubric:: Footnotes + +.. [#fsamp] This is based on the current configuration of a 55.5 cycle + sample time, at 72 MHz. However, the minimum sample time *possible* + is 1.5 cycles, leading to a theoretical maximum of approximately 48 + million samples per second (of course, doing anything with the + readings also consumes cycles, so this maximum can't be reached in + practice). + + See the `STM32 Reference Manual <full-manual>`_, ยงยง11.12.4--5 + (pp. 225--226), for more information on the low-level bit twiddling + currently necessary to change the sample time. For examples of how + the ADCs are configured in libmaple, see `adc.h + <http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.h>`_ + and `adc.c + <http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.c>`_\ + . Be aware that changing the sample time has important + consequences related to the impedance of the device connected to + the input pin. If you want to make changes, as a minimum, you + should first read ST's application notes on `ADC modes + <stm32-adc-modes>`_ and `ADC oversampling + <stm32-adc-oversampling>`_. diff --git a/source/arduino/analogreference.rst b/source/arduino/analogreference.rst new file mode 100644 index 0000000..9a25169 --- /dev/null +++ b/source/arduino/analogreference.rst @@ -0,0 +1,66 @@ +.. _arduino-analogreference: + +analogReference(type) +===================== + +Description +----------- + +Configures the reference voltage used for analog input (i.e. the +value used as the top of the input range). The options are: + + + + +- DEFAULT: the default analog reference of 5 volts (on 5V Arduino + boards) or 3.3 volts (on 3.3V Arduino boards) +- INTERNAL: an built-in reference, equal to 1.1 volts on the + ATmega168 or ATmega328 and 2.56 volts on the ATmega8. +- EXTERNAL: the voltage applied to the AREF pin is used as the + reference. + + + +Parameters +---------- + +type: which type of reference to use (DEFAULT, INTERNAL, or +EXTERNAL). + + + +Returns +------- + +None. + + + +Warning +------- + +**If you're using an external reference voltage (applied to the AREF pin), you must set the analog reference to EXTERNAL before calling analogRead().** +Otherwise, you will short together the active reference voltage +(internally generated) and the AREF pin, possibly damaging the +microcontroller on your Arduino board. + + + +Alternatively, you can connect the external reference voltage to +the AREF pin through a 5K resistor, allowing you to switch between +external and internal reference voltages. Note that the resistor +will alter the voltage that gets used as the reference because +there is an internal 32K resistor on the AREF pin. The two act as a +voltage divider, so, for example, 2.5V applied through the resistor +will yield 2.5 \* 32 / (32 + 5) = ~2.2V at the AREF pin. + + + +See also +-------- + + +- `Description of the analog input pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ +- `analogRead <http://arduino.cc/en/Reference/AnalogRead>`_\ () + + diff --git a/source/arduino/analogwrite.rst b/source/arduino/analogwrite.rst new file mode 100644 index 0000000..64ecd5b --- /dev/null +++ b/source/arduino/analogwrite.rst @@ -0,0 +1,116 @@ +.. _arduino-analogwrite: + +analogWrite() +============= + +TODO + +In libmaple, analogWrite is just a convenience alias for +:ref:`pwmWrite`. This is because PWM is not true analog output (i.e., +is not the output of a DAC), so the name was badly-chosen; however, +for the sake of compatibility, the alias was provided. + +.. doxygenfunction:: pwmWrite + +Description +----------- + +Writes an analog value +(`PWM wave <http://arduino.cc/en/Tutorial/PWM>`_) to a pin. Can be +used to light a LED at varying brightnesses or drive a motor at +various speeds. After a call to **analogWrite()**, the pin will +generate a steady square wave of the specified duty cycle until the +next call to **analogWrite()** (or a call to **digitalRead()** or +**digitalWrite()** on the same pin). The frequency of the PWM +signal is approximately 490 Hz. + + + +On most Arduino boards (those with the ATmega168 or ATmega328), +this function works on pins 3, 5, 6, 9, 10, and 11. On the Arduino +Mega, it works on pins 2 through 13. Older Arduino boards with an +ATmega8 only support analogWrite() on pins 9, 10, and 11. You do +not need to call pinMode() to set the pin as an output before +calling analogWrite(). + + + +The *analogWrite* function has nothing whatsoever to do with the +analog pins or the *analogRead* function. + + + +Syntax +------ + +analogWrite(pin, value) + + + +Parameters +---------- + +pin: the pin to write to. + + + +value: the duty cycle: between 0 (always off) and 255 (always on). + + + +Returns +------- + +nothing + + + +Notes and Known Issues +---------------------- + +The PWM outputs generated on pins 5 and 6 will have +higher-than-expected duty cycles. This is because of interactions +with the millis() and delay() functions, which share the same +internal timer used to generate those PWM outputs. This will be +noticed mostly on low duty-cycle settings (e.g 0 - 10) and may +result in a value of 0 not fully turning off the output on pins 5 +and 6. + + + +Example +------- + +Sets the output to the LED proportional to the value read from the +potentiometer. + + + +:: + + + int ledPin = 9; // LED connected to digital pin 9 + int analogPin = 3; // potentiometer connected to analog pin 3 + int val = 0; // variable to store the read value + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the pin as output + } + + void loop() + { + val = analogRead(analogPin); // read the input pin + analogWrite(ledPin, val / 4); // analogRead values go from 0 to 1023, analogWrite values from 0 to 255 + } + + + +See also +-------- + + +- `analogRead <http://arduino.cc/en/Reference/AnalogRead>`_\ () +- `Tutorial: PWM <http://arduino.cc/en/Tutorial/PWM>`_ + + diff --git a/source/arduino/arithmetic.rst b/source/arduino/arithmetic.rst new file mode 100644 index 0000000..cbe3059 --- /dev/null +++ b/source/arduino/arithmetic.rst @@ -0,0 +1,104 @@ +.. highlight:: cpp + +.. _arduino-arithmetic: + +Addition, Subtraction, Multiplication, & Division +================================================= + +Description +----------- + +These operators return the sum, difference, product, or quotient +(respectively) of the two operands. The operation is conducted using +the data type of the operands, so, for example, ``9 / 4`` gives ``2`` +since 9 and 4 are ints. + +This also means that the operation can overflow if the result is +larger than that which can be stored in the data type (e.g. adding 1 +to an :ref:`arduino-int` with the value 2147483647 gives +-2147483648). If the operands are of different types, the "larger" +type is used for the calculation. + +(The specifics of these rules are beyond the scope of this +documentation; for more information, see `The C++ Programming Language +<http://www2.research.att.com/~bs/3rd.html>`_\ , by Bjarne +Stroustroup, Appendix C, especially ยงยงC.4-C.6, or `this WikiBooks +entry on C++ type conversion +<http://en.wikibooks.org/wiki/C%2B%2B_Programming/Programming_Languages/C%2B%2B/Code/Statements/Variables/Type_Casting#Automatic_type_conversion>`_\ +. For more information on how computers represent integers, see the +Wikipedia page on `two's complement +<http://en.wikipedia.org/wiki/Two's_complement>`_\ ). + +If one of the numbers (operands) are of the type **float** or of type +**double**, floating point math will be used for the +calculation. + +Examples +-------- + + :: + + y = y + 3; + x = x - 7; + i = j * 6; + r = r / 5; + + +Syntax +------ + + :: + + result = value1 + value2; + result = value1 - value2; + result = value1 * value2; + result = value1 / value2; + + +Parameters: +----------- + +**value1**: any numeric variable or constant + +**value2**: any numeric variable or constant + + +Arduino Compatibility Note +-------------------------- + +Since the STM32 processor on the Maple is a 32-bit machine, the int +type overflows at a much higher value on Maple than on Arduino. In +particular, on Maple, ints do not overflow (become negative) until +they reach 2,147,483,648; on the Arduino, they overflow at 32,767. +Because of this, programs running on Maple are much less likely to run +into overflow issues. + + +Programming Tips: +----------------- + +- Know that :ref:`integer constants <arduino-integerconstants>` + default to :ref:`int <arduino-Int>`, so some constant calculations + may overflow (e.g., 200000 * 5000000 will yield a negative result). + +- Choose variable sizes that are large enough to hold the largest + results from your calculations. + +- Know at what point your variable will "roll over" and also what + happens in the other direction e.g. (0 - 1) for unsigned arithmetic, + or (0 - -2,147,483,648) for signed arithmetic. + +- For math that requires fractions, float variables may be used, but + be aware of their drawbacks: large size and slow computation speeds + (the STM32 has no floating point hardware, so all floating point + calculations have to be done in software). + +- Use the cast operator e.g. (int)myFloat to convert one variable type + to another on the fly. + + +See Also +-------- + +- `libmaple_types.h <http://github.com/leaflabs/libmaple/blob/master/libmaple/libmaple_types.h>`_ + diff --git a/source/arduino/array.rst b/source/arduino/array.rst new file mode 100644 index 0000000..f6bc141 --- /dev/null +++ b/source/arduino/array.rst @@ -0,0 +1,114 @@ +.. highlight:: cpp + +.. _arduino-array: + +Arrays +====== + +An array is a collection of variables that are accessed with an index +number. Arrays in the C++ programming language, in which the Maple is +programmed, can be complicated, but using simple arrays is relatively +straightforward. + + +Creating (Declaring) an Array +----------------------------- + +All of the methods below are valid ways to create (declare) an +array. :: + + int myInts[6]; + int myPins[] = {2, 4, 8, 3, 6}; + int mySensVals[6] = {2, 4, -8, 3, 2}; + char message[6] = "hello"; + +You can declare an array without initializing it, as with myInts. In +the line referring to myPins, we declare an array without explicitly +choosing a size. The compiler counts the elements and creates an +array of the appropriate size. + +Finally, you can both initialize and size your array, as in +mySensVals. Note that when declaring an array with elements of type +char, one more element than your initialization is required, to hold +the required `null character <http://en.wikipedia.org/wiki/Null-terminated_string>`_. + + +Accessing an Array +------------------ + + +.. compound:: + + Arrays are **zero indexed**; that is, referring to the array + initialization above, the first element of the array is at index 0, + hence :: + + mySensVals[0] == 2; + mySensVals[1] == 4 + + and so forth. + +It also means that in an array with ten elements, index nine is the +last element. Hence:: + + int myArray[10]={9,3,2,4,3,2,7,8,9,11}; + // myArray[9] contains 11 + // myArray[10] is invalid and contains random information (other memory address) + +For this reason, you should be careful in accessing arrays. Accessing +past the end of an array (using an index number greater than your +declared array size - 1) is reading from memory that is in use for +other purposes. Reading from these locations is probably not going to +do much except yield invalid data. Writing to random memory locations +is definitely a bad idea, and can often lead to unhappy results such +as crashes or program malfunction. This can also be a difficult bug to +track down. + +Unlike Basic or Java, the C compiler does no checking to see if array +access is within legal bounds of the array size that you have +declared. + + +To assign a value to an array: +------------------------------ + :: + + mySensVals[0] = 10; + + +To retrieve a value from an array: +---------------------------------- + + :: + + x = mySensVals[4]; + + +Arrays and ``for`` Loops +------------------------ + +Arrays are often manipulated inside :ref:`for loops <arduino-for>`, where +the loop counter is used as the index for each array element. For +example, to print the elements of an array over the serial port, you +could do something like this:: + + int i; + for (i = 0; i < 5; i = i + 1) { + SerialUSB.println(myPins[i]); + } + + +Example +------- + +For a complete program that demonstrates the use of arrays, see the +Arduino `Knight Rider example +<http://www.arduino.cc/en/Tutorial/KnightRider>`_\ (which will run +unmodified on the Maple). + + +See also +-------- + +- :ref:`Storing arrays in FLASH memory <arm-gcc-attribute-flash>` + diff --git a/source/arduino/assignment.rst b/source/arduino/assignment.rst new file mode 100644 index 0000000..8b851e8 --- /dev/null +++ b/source/arduino/assignment.rst @@ -0,0 +1,63 @@ +.. highlight:: cpp + +.. _arduino-assignment: + += assignment operator (single equal sign) +========================================= + +Stores the value to the right of the equal sign in the variable to +the left of the equal sign. + + +The single equal sign in the C++ programming language is called the +assignment operator. It has a different meaning than in algebra +class where it indicated an equation or equality. The assignment +operator tells the microcontroller to evaluate whatever value or +expression is on the right side of the equal sign, and store it in +the variable to the left of the equal sign [#fgross]_. + + + +Example +------- + +:: + + int sensVal; // declare an integer variable named sensVal + senVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal + + + +Programming Tips +---------------- + +The variable on the left side of the assignment operator ( = sign ) +needs to be able to hold the value stored in it. If it is not large +enough to hold a value, the value stored in the variable will be +incorrect. + + + +Don't confuse the assignment operator [ = ] (single equal sign) +with the comparison operator [ == ] (double equal signs), which +evaluates whether two expressions are equal. + + + +See Also +-------- + + +- `if (comparison operators) <http://arduino.cc/en/Reference/If>`_ +- `char <http://arduino.cc/en/Reference/Char>`_ +- `int <http://arduino.cc/en/Reference/Int>`_ +- `long <http://arduino.cc/en/Reference/Long>`_ + + +.. rubric:: Footnotes + + Experienced C++ programmers know this to be an oversimplification + of what happens when the variable on the left hand side is an + object. See Richard Gillam's wonderful and scary `The Anatomy of + the Assignment Operator + <http://icu-project.org/docs/papers/cpp_report/the_anatomy_of_the_assignment_operator.html>`_ diff --git a/source/arduino/attachinterrupt.rst b/source/arduino/attachinterrupt.rst new file mode 100644 index 0000000..27a1d77 --- /dev/null +++ b/source/arduino/attachinterrupt.rst @@ -0,0 +1,114 @@ +.. _arduino-attachinterrupt: + +attachInterrupt(interrupt, function, mode) +========================================== + + + +Description +----------- + +Specifies a function to call when an external interrupt occurs. +Replaces any previous function that was attached to the interrupt. +Most Arduino boards have two external interrupts: numbers 0 (on +digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an +additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 +(pin 18). + + + +Parameters +---------- + +**interrupt**: the number of the interrupt (*int*) + + + +**function**: the function to call when the interrupt occurs; this +function must take no parameters and return nothing. This function +is sometimes referred to as an *interrupt service routine.* + + + +**mode** defines when the interrupt should be triggered. Four +contstants are predefined as valid values: + + +- **LOW** to trigger the interrupt whenever the pin is low, +- **CHANGE** to trigger the interrupt whenever the pin changes + value +- **RISING** to trigger when the pin goes from low to high, +- **FALLING** for when the pin goes from high to low. + + + +Returns +------- + +none + + + +Note +---- + +*Inside the attached function, delay() won't work and the value returned by millis() will not increment. Serial data received while in the function may be lost. You should declare as volatile any variables that you modify within the attached function.* + + + +Using Interrupts +---------------- + +Interrupts are useful for making things happen automatically in +microcontroller programs, and can help solve timing problems. A +good task for using an interrupt might be reading a rotary encoder, +monitoring user input. + + + +If you wanted to insure that a program always caught the pulses +from a rotary encoder, never missing a pulse, it would make it very +tricky to write a program to do anything else, because the program +would need to constantly poll the sensor lines for the encoder, in +order to catch pulses when they occurred. Other sensors have a +similar interface dynamic too, such as trying to read a sound +sensor that is trying to catch a click, or an infrared slot sensor +(photo-interrupter) trying to catch a coin drop. In all of these +situations, using an interrupt can free the microcontroller to get +some other work done while not missing the doorbell. + + + +Example +------- + +:: + + int pin = 13; + volatile int state = LOW; + + void setup() + { + pinMode(pin, OUTPUT); + attachInterrupt(0, blink, CHANGE); + } + + void loop() + { + digitalWrite(pin, state); + } + + void blink() + { + state = !state; + } + + + +See also +-------- + + +- `detachInterrupt <http://arduino.cc/en/Reference/DetachInterrupt>`_ + + diff --git a/source/arduino/bit.rst b/source/arduino/bit.rst new file mode 100644 index 0000000..f8241a5 --- /dev/null +++ b/source/arduino/bit.rst @@ -0,0 +1,42 @@ +.. _arduino-bit: + +bit() +===== + +Description +----------- + +Computes the value of the specified bit (bit 0 is 1, bit 1 is 2, +bit 2 is 4, etc.). + + + +Syntax +------ + +bit(n) + + + +Parameters +---------- + +n: the bit whose value to compute + + + +Returns +------- + +the value of the bit + + + +See also +-------- + + +- `bitRead <http://arduino.cc/en/Reference/BitRead>`_\ () +- `bitWrite <http://arduino.cc/en/Reference/BitWrite>`_\ () +- `bitSet <http://arduino.cc/en/Reference/BitSet>`_\ () +- `bitClear <http://arduino.cc/en/Reference/BitClear>`_\ () diff --git a/source/arduino/bitclear.rst b/source/arduino/bitclear.rst new file mode 100644 index 0000000..e86dbc5 --- /dev/null +++ b/source/arduino/bitclear.rst @@ -0,0 +1,48 @@ +.. _arduino-bitclear: + +bitClear() +========== + +Description +----------- + +Clears (writes a 0 to) a bit of a numeric variable. + + + +Syntax +------ + +bitClear(x, n) + + + +Parameters +---------- + +x: the numeric variable whose bit to clear + + + +n: which bit to clear, starting at 0 for the least-significant +(rightmost) bit + + + +Returns +------- + +none + + + +See also +-------- + + +- `bit <http://arduino.cc/en/Reference/Bit>`_\ () +- `bitRead <http://arduino.cc/en/Reference/BitRead>`_\ () +- `bitWrite <http://arduino.cc/en/Reference/BitWrite>`_\ () +- `bitSet <http://arduino.cc/en/Reference/BitSet>`_\ () + + diff --git a/source/arduino/bitread.rst b/source/arduino/bitread.rst new file mode 100644 index 0000000..3d0b1a4 --- /dev/null +++ b/source/arduino/bitread.rst @@ -0,0 +1,48 @@ +.. _arduino-bitread: + +bitRead() +========= + +Description +----------- + +Reads a bit of a number. + + + +Syntax +------ + +bitRead(x, n) + + + +Parameters +---------- + +x: the number from which to read + + + +n: which bit to read, starting at 0 for the least-significant +(rightmost) bit + + + +Returns +------- + +the value of the bit (0 or 1). + + + +See also +-------- + + +- `bit <http://arduino.cc/en/Reference/Bit>`_\ () +- `bitWrite <http://arduino.cc/en/Reference/BitWrite>`_\ () +- `bitSet <http://arduino.cc/en/Reference/BitSet>`_\ () +- `bitClear <http://arduino.cc/en/Reference/BitClear>`_\ () + + diff --git a/source/arduino/bitset.rst b/source/arduino/bitset.rst new file mode 100644 index 0000000..882ec92 --- /dev/null +++ b/source/arduino/bitset.rst @@ -0,0 +1,47 @@ +.. _arduino-bitset: + +bitSet() +======== + +Description +----------- + +Sets (writes a 1 to) a bit of a numeric variable. + + + +Syntax +------ + +bitSet(x, n) + + + +Parameters +---------- + +x: the numeric variable whose bit to set + + + +n: which bit to set, starting at 0 for the least-significant +(rightmost) bit + + + +Returns +------- + +none + + + +See also +-------- + + +- `bit <http://arduino.cc/en/Reference/Bit>`_\ () +- `bitRead <http://arduino.cc/en/Reference/BitRead>`_\ () +- `bitWrite <http://arduino.cc/en/Reference/BitWrite>`_\ () +- `bitClear <http://arduino.cc/en/Reference/BitClear>`_\ () + diff --git a/source/arduino/bitshift.rst b/source/arduino/bitshift.rst new file mode 100644 index 0000000..f59b489 --- /dev/null +++ b/source/arduino/bitshift.rst @@ -0,0 +1,127 @@ +.. _arduino-bitshift: + +bitshift left (<<), bitshift right (>>) +======================================= + +Description +----------- + +From *The Bitmath Tutorial* in The Playground + + + +There are two bit shift operators in C++: the left shift operator +<< and the right shift operator >>. These operators cause the bits +in the left operand to be shifted left or right by the number of +positions specified by the right operand. +More on bitwise math may be found +`here. <http://www.arduino.cc/playground/Code/BitMath>`_ + + + +Syntax +------ + +variable << number\_of\_bits + + + +variable >> number\_of\_bits + + + +Parameters +---------- + +variable - (byte, int, long) number\_of\_bits integer <= 32 + + + +Example: +-------- + +:: + + int a = 5; // binary: 0000000000000101 + int b = a << 3; // binary: 0000000000101000, or 40 in decimal + int c = b >> 3; // binary: 0000000000000101, or back to 5 like we started with + + + +When you shift a value x by y bits (x << y), the leftmost y bits in +x are lost, literally shifted out of existence: + + + +:: + + int a = 5; // binary: 0000000000000101 + int b = a << 14; // binary: 0100000000000000 - the first 1 in 101 was discarded + + + +If you are certain that none of the ones in a value are being +shifted into oblivion, a simple way to think of the left-shift +operator is that it multiplies the left operand by 2 raised to the +right operand power. For example, to generate powers of 2, the +following expressions can be employed: + + + +:: + + 1 << 0 == 1 + 1 << 1 == 2 + 1 << 2 == 4 + 1 << 3 == 8 + ... + 1 << 8 == 256 + 1 << 9 == 512 + 1 << 10 == 1024 + ... + + + +When you shift x right by y bits (x >> y), and the highest bit in x +is a 1, the behavior depends on the exact data type of x. If x is +of type int, the highest bit is the sign bit, determining whether x +is negative or not, as we have discussed above. In that case, the +sign bit is copied into lower bits, for esoteric historical +reasons: + + + +:: + + int x = -16; // binary: 1111111111110000 + int y = x >> 3; // binary: 1111111111111110 + + + +This behavior, called sign extension, is often not the behavior you +want. Instead, you may wish zeros to be shifted in from the left. +It turns out that the right shift rules are different for unsigned +int expressions, so you can use a typecast to suppress ones being +copied from the left: + + + +:: + + int x = -16; // binary: 1111111111110000 + int y = (unsigned int)x >> 3; // binary: 0001111111111110 + + + +If you are careful to avoid sign extension, you can use the +right-shift operator >> as a way to divide by powers of 2. For +example: + + + +:: + + int x = 1000; + int y = x >> 3; // integer division of 1000 by 8, causing y = 125. + + diff --git a/source/arduino/bitwiseand.rst b/source/arduino/bitwiseand.rst new file mode 100644 index 0000000..8d4eb3f --- /dev/null +++ b/source/arduino/bitwiseand.rst @@ -0,0 +1,230 @@ +.. _arduino-bitwiseand: + +Bitwise AND (&), Bitwise OR (\|), Bitwise XOR (^) +================================================= + +Bitwise AND (&) +--------------- + +The bitwise operators perform their calculations at the bit level +of variables. They help solve a wide range of common programming +problems. Much of the material below is from an excellent tutorial +on bitwise math wihch may be found +`here. <http://www.arduino.cc/playground/Code/BitMath>`_ + + + +Description and Syntax +---------------------- + +Below are descriptions and syntax for all of the operators. Further +details may be found in the referenced tutorial. + + + +Bitwise AND (&) +--------------- + +The bitwise AND operator in C++ is a single ampersand, &, used +between two other integer expressions. Bitwise AND operates on each +bit position of the surrounding expressions independently, +according to this rule: if both input bits are 1, the resulting +output is 1, otherwise the output is 0. Another way of expressing +this is: + + + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) - returned result + + + +In Arduino, the type int is a 16-bit value, so using & between two +int expressions causes 16 simultaneous AND operations to occur. In +a code fragment like: + + + +:: + + int a = 92; // in binary: 0000000001011100 + int b = 101; // in binary: 0000000001100101 + int c = a & b; // result: 0000000001000100, or 68 in decimal. + + + +Each of the 16 bits in a and b are processed by using the bitwise +AND, and all 16 resulting bits are stored in c, resulting in the +value 01000100 in binary, which is 68 in decimal. + + + +One of the most common uses of bitwise AND is to select a +particular bit (or bits) from an integer value, often called +masking. See below for an example + + + +Bitwise OR (\|) +--------------- + +The bitwise OR operator in C++ is the vertical bar symbol, \|. Like +the & operator, \| operates independently each bit in its two +surrounding integer expressions, but what it does is different (of +course). The bitwise OR of two bits is 1 if either or both of the +input bits is 1, otherwise it is 0. In other words: + + + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) - returned result + + + +Here is an example of the bitwise OR used in a snippet of C++ +code: + + + +:: + + int a = 92; // in binary: 0000000001011100 + int b = 101; // in binary: 0000000001100101 + int c = a | b; // result: 0000000001111101, or 125 in decimal. + + + +Example Program +--------------- + +A common job for the bitwise AND and OR operators is what +programmers call Read-Modify-Write on a port. On microcontrollers, +a port is an 8 bit number that represents something about the +condition of the pins. Writing to a port controls all of the pins +at once. + + + +PORTD is a built-in constant that refers to the output states of +digital pins 0,1,2,3,4,5,6,7. If there is 1 in an bit position, +then that pin is HIGH. (The pins already need to be set to outputs +with the pinMode() command.) So if we write ``PORTD = B00110001;`` +we have made pins 2,3 & 7 HIGH. One slight hitch here is that we +*may* also have changeed the state of Pins 0 & 1, which are used by +the Arduino for serial communications so we may have interfered +with serial communication. + + + +:: + + Our algorithm for the program is: + + +- Get PORTD and clear out only the bits corresponding to the pins + we wish to control (with bitwise AND). +- Combine the modified PORTD value with the new value for the pins + under control (with biwise OR). + + + +:: + + int i; // counter variable + int j; + + void setup(){ + DDRD = DDRD | B11111100; // set direction bits for pins 2 to 7, leave 0 and 1 untouched (xx | 00 == xx) + // same as pinMode(pin, OUTPUT) for pins 2 to 7 + Serial.begin(9600); + } + + void loop(){ + for (i=0; i<64; i++){ + + PORTD = PORTD & B00000011; // clear out bits 2 - 7, leave pins 0 and 1 untouched (xx & 11 == xx) + j = (i << 2); // shift variable up to pins 2 - 7 - to avoid pins 0 and 1 + PORTD = PORTD | j; // combine the port information with the new information for LED pins + Serial.println(PORTD, BIN); // debug to show masking + delay(100); + } + } + + + +Bitwise XOR (^) +--------------- + +There is a somewhat unusual operator in C++ called bitwise +EXCLUSIVE OR, also known as bitwise XOR. (In English this is +usually pronounced "eks-or".) The bitwise XOR operator is written +using the caret symbol ^. This operator is very similar to the +bitwise OR operator \|, only it evaluates to 0 for a given bit +position when both of the input bits for that position are 1: + + + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) - returned result + + + +Another way to look at bitwise XOR is that each bit in the result +is a 1 if the input bits are different, or 0 if they are the same. + + + +Here is a simple code example: + + + +:: + + int x = 12; // binary: 1100 + int y = 10; // binary: 1010 + int z = x ^ y; // binary: 0110, or decimal 6 + + + +The ^ operator is often used to toggle (i.e. change from 0 to 1, or +1 to 0) some of the bits in an integer expression. In a bitwise OR +operation if there is a 1 in the mask bit, that bit is inverted; if +there is a 0, the bit is not inverted and stays the same. Below is +a program to blink digital pin 5. + + + +:: + + // Blink_Pin_5 + // demo for Exclusive OR + void setup(){ + DDRD = DDRD | B00100000; // set digital pin five as OUTPUT + Serial.begin(9600); + } + + void loop(){ + PORTD = PORTD ^ B00100000; // invert bit 5 (digital pin 5), leave others untouched + delay(100); + } + + + +See Also + + +- `&& <http://arduino.cc/en/Reference/Boolean>`_ (Boolean AND) +- `\|\| <http://arduino.cc/en/Reference/Boolean>`_ (Boolean OR) + diff --git a/source/arduino/bitwisecompound.rst b/source/arduino/bitwisecompound.rst new file mode 100644 index 0000000..c3c808f --- /dev/null +++ b/source/arduino/bitwisecompound.rst @@ -0,0 +1,227 @@ +.. _arduino-bitwisecompound: + +compound bitwise AND (&=), compound bitwise OR (\|=) +==================================================== + +The compound bitwise operators perform their calculations at the +bit level of variables. They are often used to clear and set +specific bits of a variable. + + + +See the +`bitwise AND (&) <http://arduino.cc/en/Reference/BitwiseAnd>`_ and +`bitwise OR (\|) <http://arduino.cc/en/Reference/BitwiseAnd>`_ +operators for the details of their operation, and also the +`Bitmath Tutorial <http://www.arduino.cc/playground/Code/BitMath>`_ +for more information on bitwise operators. + + + +compound bitwise AND (&=) +========================= + +Description +----------- + +The compound bitwise AND operator (&=) is often used with a +variable and a constant to force particular bits in a variable to +the LOW state (to 0). This is often referred to in programming +guides as "clearing" or "resetting" bits. + + + +Syntax: +------- + +:: + + x &= y; // equivalent to x = x & y; + + + +Parameters +---------- + +x: a char, int or long variable +y: an integer constant or char, int, or long + + + +Example: +-------- + +First, a review of the Bitwise AND (&) operator + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) - returned result + + + +Bits that are "bitwise ANDed" with 0 are cleared to 0 so, if myByte +is a byte variable, +``myByte & B00000000 = 0;`` + + + +Bits that are "bitwise ANDed" with 1 are unchanged so, +``myByte & B11111111 = myByte;`` + + + +Note: because we are dealing with bits in a bitwise operator - it +is convenient to use the binary formatter with +`constants. <http://arduino.cc/en/Reference/IntegerConstants>`_ The +numbers are still the same value in other representations, they are +just not as easy to understand. Also, B00000000 is shown for +clarity, but zero in any number format is zero (hmmm something +philosophical there?) + + + +Consequently - to clear (set to zero) bits 0 & 1 of a variable, +while leaving the rest of the variable unchanged, use the compound +bitwise AND operator (&=) with the constant B11111100 + +:: + + 1 0 1 0 1 0 1 0 variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + 1 0 1 0 1 0 0 0 + + variable unchanged + bits cleared + + +Here is the same representation with the variable's bits replaced +with the symbol x + + + +:: + + x x x x x x x x variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + x x x x x x 0 0 + + variable unchanged + bits cleared + + +So if: + +:: + + myByte = 10101010; + + myByte &= B1111100 == B10101000; + + + +compound bitwise OR (\|=) +========================= + +Description +----------- + +The compound bitwise OR operator (\|=) is often used with a +variable and a constant to "set" (set to 1) particular bits in a +variable. + + + +Syntax: +------- + +:: + + x |= y; // equivalent to x = x | y; + + + +Parameters +---------- + +x: a char, int or long variable +y: an integer constant or char, int, or long + + + +Example: +-------- + +First, a review of the Bitwise OR (\|) operator + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) - returned result + +Bits that are "bitwise ORed" with 0 are unchanged, so if myByte is +a byte variable, +myByte \| B00000000 = myByte; + + + +Bits that are "bitwise ORed" with 1 are set to 1 so: +myByte & B11111111 = B11111111; + + + +Consequently - to set bits 0 & 1 of a variable, while leaving the +rest of the variable unchanged, use the compound bitwise AND +operator (&=) with the constant B00000011 + +:: + + 1 0 1 0 1 0 1 0 variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + 1 0 1 0 1 0 1 1 + + variable unchanged + bits set + + +Here is the same representation with the variables bits replaced +with the symbol x + + + +:: + + x x x x x x x x variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + x x x x x x 1 1 + + variable unchanged + bits set + +So if: + +:: + + myByte = B10101010; + + myByte |= B00000011 == B10101011; + + + +See Also + + +- `& <http://arduino.cc/en/Reference/BitwiseAnd>`_ (bitwise AND) +- `\| <http://arduino.cc/en/Reference/BitwiseAnd>`_ (bitwise OR) +- `&& <http://arduino.cc/en/Reference/Boolean>`_ (Boolean AND) +- `\|\| <http://arduino.cc/en/Reference/Boolean>`_ (Boolean OR) + + diff --git a/source/arduino/bitwisexornot.rst b/source/arduino/bitwisexornot.rst new file mode 100644 index 0000000..25389cb --- /dev/null +++ b/source/arduino/bitwisexornot.rst @@ -0,0 +1,51 @@ +.. _arduino-bitwisexornot: + +Bitwise NOT (~) +=============== + +The bitwise NOT operator in C++ is the tilde character ~. Unlike & +and \|, the bitwise NOT operator is applied to a single operand to +its right. Bitwise NOT changes each bit to its opposite: 0 becomes +1, and 1 becomes 0. For example: + + + +:: + + 0 1 operand1 + + + +:: + + ---------- + 1 0 ~ operand1 + + + +:: + + int a = 103; // binary: 0000000001100111 + int b = ~a; // binary: 1111111110011000 = -104 + + + +You might be surprised to see a negative number like -104 as the +result of this operation. This is because the highest bit in an int +variable is the so-called sign bit. If the highest bit is 1, the +number is interpreted as negative. This encoding of positive and +negative numbers is referred to as two's complement. For more +information, see the Wikipedia article on +`two's complement. <http://en.wikipedia.org/wiki/Twos_complement>`_ + + + +As an aside, it is interesting to note that for any integer x, ~x +is the same as -x-1. + + + +At times, the sign bit in a signed integer expression can cause +some unwanted surprises. + + diff --git a/source/arduino/bitwrite.rst b/source/arduino/bitwrite.rst new file mode 100644 index 0000000..5d95506 --- /dev/null +++ b/source/arduino/bitwrite.rst @@ -0,0 +1,52 @@ +.. _arduino-bitwrite: + +bitWrite() +========== + +Description +----------- + +Writes a bit of a numeric variable. + + + +Syntax +------ + +bitWrite(x, n, b) + + + +Parameters +---------- + +x: the numeric variable to which to write + + + +n: which bit of the number to write, starting at 0 for the +least-significant (rightmost) bit + + + +b: the value to write to the bit (0 or 1) + + + +Returns +------- + +none + + + +See also +-------- + + +- `bit <http://arduino.cc/en/Reference/Bit>`_\ () +- `bitRead <http://arduino.cc/en/Reference/BitRead>`_\ () +- `bitSet <http://arduino.cc/en/Reference/BitSet>`_\ () +- `bitClear <http://arduino.cc/en/Reference/BitClear>`_\ () + + diff --git a/source/arduino/boolean.rst b/source/arduino/boolean.rst new file mode 100644 index 0000000..f109bdb --- /dev/null +++ b/source/arduino/boolean.rst @@ -0,0 +1,94 @@ +.. _arduino-boolean: + +Boolean Operators +================= + +These can be used inside the condition of an +`if <http://arduino.cc/en/Reference/If>`_ statement. + + + +&& (logical and) +~~~~~~~~~~~~~~~~ + +True only if both operands are true, e.g. + +:: + + if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // read two switches + // ... + } + +is true only if both inputs are high. + + + +\|\| (logical or) +~~~~~~~~~~~~~~~~~ + +True if either operand is true, e.g. + +:: + + if (x > 0 || y > 0) { + // ... + } + +is true if either x or y is greater than 0. + + + +! (not) +~~~~~~~ + +True if the operand is false, e.g. + +:: + + if (!x) { + // ... + } + +is true if x is false (i.e. if x equals 0). + + + +Warning +------- + +Make sure you don't mistake the boolean AND operator, && (double +ampersand) for the bitwise AND operator & (single ampersand). They +are entirely different beasts. + + + +Similarly, do not confuse the boolean \|\| (double pipe) operator +with the bitwise OR operator \| (single pipe). + + + +The bitwise not ~ (tilde) looks much different than the boolean not +! (exclamation point or "bang" as the programmers say) but you +still have to be sure which one you want where. + + + +Examples +-------- + +:: + + if (a >= 10 && a <= 20){} // true if a is between 10 and 20 + + + +See also +-------- + + +- `& <http://arduino.cc/en/Reference/BitwiseAnd>`_ (bitwise AND) +- `\| <http://arduino.cc/en/Reference/BitwiseAnd>`_ (bitwise OR) +- `~ <http://arduino.cc/en/Reference/BitwiseXorNot>`_ (bitwise NOT +- `if <http://arduino.cc/en/Reference/If>`_ + + diff --git a/source/arduino/booleanvariables.rst b/source/arduino/booleanvariables.rst new file mode 100644 index 0000000..3bbe72a --- /dev/null +++ b/source/arduino/booleanvariables.rst @@ -0,0 +1,53 @@ +.. _arduino-booleanvariables: + +boolean +======= + +A **boolean** holds one of two values, +`true <http://arduino.cc/en/Reference/Constants>`_ or +`false <http://arduino.cc/en/Reference/Constants>`_. (Each boolean +variable occupies one byte of memory.) + + + +Example +------- + +:: + + int LEDpin = 5; // LED on pin 5 + int switchPin = 13; // momentary switch on 13, other side connected to ground + + boolean running = false; + + void setup() + { + pinMode(LEDpin, OUTPUT); + pinMode(switchPin, INPUT); + digitalWrite(switchPin, HIGH); // turn on pullup resistor + } + + void loop() + { + if (digitalRead(switchPin) == LOW) + { // switch is pressed - pullup keeps pin high normally + delay(100); // delay to debounce switch + running = !running; // toggle running variable + digitalWrite(LEDpin, running) // indicate via LED + } + } + + + + + + +See also +-------- + + +- `constants <http://arduino.cc/en/Reference/Constants>`_ +- `boolean operators <http://arduino.cc/en/Reference/Boolean>`_ +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ + + diff --git a/source/arduino/braces.rst b/source/arduino/braces.rst new file mode 100644 index 0000000..c7bd148 --- /dev/null +++ b/source/arduino/braces.rst @@ -0,0 +1,113 @@ +.. _arduino-braces: + +{} Curly Braces +=============== + +Curly braces (also referred to as just "braces" or as "curly +brackets") are a major part of the C programming language. They are +used in several different constructs, outlined below, and this can +sometimes be confusing for beginners. + + + +An opening curly brace "{" must always be followed by a closing +curly brace "}". This is a condition that is often referred to as +the braces being balanced. The Arduino IDE (integrated development +environment) includes a convenient feature to check the balance of +curly braces. Just select a brace, or even click the insertion +point immediately following a brace, and its logical companion will +be highlighted. + + + +At present this feature is slightly buggy as the IDE will often +find (incorrectly) a brace in text that has been "commented out." + + + +Beginning programmers, and programmers coming to C from the BASIC +language often find using braces confusing or daunting. After all, +the same curly braces replace the RETURN statement in a subroutine +(function), the ENDIF statement in a conditional and the NEXT +statement in a FOR loop. + + + +Because the use of the curly brace is so varied, it is good +programming practice to type the closing brace immediately after +typing the opening brace when inserting a construct which requires +curly braces. Then insert some carriage returns between your braces +and begin inserting statements. Your braces, and your attitude, +will never become unbalanced. + + + +Unbalanced braces can often lead to cryptic, impenetrable compiler +errors that can sometimes be hard to track down in a large program. +Because of their varied usages, braces are also incredibly +important to the syntax of a program and moving a brace one or two +lines will often dramatically affect the meaning of a program. + + + +**The main uses of curly braces** +--------------------------------- + +Functions +--------- + +:: + + void myfunction(datatype argument){ + statements(s) + } + + + +Loops +----- + +:: + + while (boolean expression) + { + statement(s) + } + + do + { + statement(s) + } while (boolean expression); + + for (initialisation; termination condition; incrementing expr) + { + statement(s) + } + + + +Conditional statements +---------------------- + + + +:: + + if (boolean expression) + { + statement(s) + } + + else if (boolean expression) + { + statement(s) + } + else + { + statement(s) + } + + + +`Reference Home <http://arduino.cc/en/Reference/HomePage>`_ + diff --git a/source/arduino/break.rst b/source/arduino/break.rst new file mode 100644 index 0000000..d951c52 --- /dev/null +++ b/source/arduino/break.rst @@ -0,0 +1,28 @@ +.. _arduino-break: + +break +===== + +**break** is used to exit from a **do**, **for**, or **while** +loop, bypassing the normal loop condition. It is also used to exit +from a **switch** statement. + + + +Example +------- + +:: + + for (x = 0; x < 255; x ++) + { + digitalWrite(PWMpin, x); + sens = analogRead(sensorPin); + if (sens > threshold){ // bail out on sensor detect + x = 0; + break; + } + delay(50); + } + + diff --git a/source/arduino/byte.rst b/source/arduino/byte.rst new file mode 100644 index 0000000..5e94bd4 --- /dev/null +++ b/source/arduino/byte.rst @@ -0,0 +1,29 @@ +.. _arduino-byte: + +byte +==== + +Description +----------- + +A byte stores an 8-bit unsigned number, from 0 to 255. + + + +Example +------- + +:: + + byte b = B10010; // "B" is the binary formatter (B10010 = 18 decimal) + + + +See also +-------- + + +- `word <http://arduino.cc/en/Reference/Word>`_ +- `byte <http://arduino.cc/en/Reference/ByteCast>`_\ () +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ + diff --git a/source/arduino/bytecast.rst b/source/arduino/bytecast.rst new file mode 100644 index 0000000..71ab4aa --- /dev/null +++ b/source/arduino/bytecast.rst @@ -0,0 +1,41 @@ +.. _arduino-bytecast: + +byte() +====== + +Description +----------- + +Converts a value to the +`byte <http://arduino.cc/en/Reference/Byte>`_ data type. + + + +Syntax +------ + +byte(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +byte + + + +See also +-------- + + +- `byte <http://arduino.cc/en/Reference/Byte>`_ + + diff --git a/source/arduino/changes.rst b/source/arduino/changes.rst new file mode 100644 index 0000000..75cd65d --- /dev/null +++ b/source/arduino/changes.rst @@ -0,0 +1,93 @@ +.. _arduino-changes: + +Changes +======= + +This page lists major changes to the Arduino core, libraries, and +environment. For details, see the +`release notes <http://arduino.cc/en/Main/ReleaseNotes>`_. + + + +Changes in Arduino 0017 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- **Environment**: The code base for the Arduino development + environment was largely re-written to bring it back into sync with + Processing (1.0.3). The main differences include support for + multiple sketch windows open simultaneously and a dedicated window + for the serial monitor. + + +- **Icons**: The icons and about images were updated. + + +- **Arduino.app**: The Mac OS X version of Arduino is now a .app + file packaged in a .dmg. + + +- **Libraries**: Support was added for third-party libraries in + the *SKETCHBOOK*/libraries directory. This allows user-installed + libraries to persist across upgrades of the Arduino software. + + +- **Servo**: The servo library was rewritten to allow support for + up to 12 servos (on any pins) and up to 48 on the Mega. + + +- **LiquidCrystal**: The begin(), cursor(), noCursor(), blink(), + noBlink(), display(), noDisplay(), scrollDisplayLeft(), + scrollDisplayRight(), autoscroll(), noAutoscroll(), leftToRight(), + rightToLeft(), and createChar() functions were added. + + + +Changes in Arduino 0016 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- New functions for writing a string, write(str), or buffer, + write(buf, len), were added to the Print, Serial, and Ethernet + library Client and Server classes. + + + +Changes in Arduino 0015 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- Support for the Arduino Mega. + + + +Changes in Arduino 0013 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- Support for printing floats was added to the Print, Serial, and + Ethernet library Client and Server classes. + + +- The word type and word(), bitRead(), bitWrite(), bitSet(), + bitClear(), bit(), lowByte(), and highByte() functions were added. + + + +Changes in Arduino 0012 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- Added the Firmata library, which provides a standard protocol + for serial communication. + + +- Added Ethernet library. + + +- Added Servo library. + + +- Added LiquidCrystal library. + + diff --git a/source/arduino/char.rst b/source/arduino/char.rst new file mode 100644 index 0000000..e783ed6 --- /dev/null +++ b/source/arduino/char.rst @@ -0,0 +1,51 @@ +.. _arduino-char: + +char +==== + +Description +----------- + +A data type that takes up 1 byte of memory that stores a character +value. Character literals are written in single quotes, like this: +'A' (for multiple characters - strings - use double quotes: +"ABC"). + + + +Characters are stored as numbers however. You can see the specific +encoding in the +`ASCII chart <http://arduino.cc/en/Reference/ASCIIchart>`_. This +means that it is possible to do arithmetic on characters, in which +the ASCII value of the character is used (e.g. 'A' + 1 has the +value 66, since the ASCII value of the capital letter A is 65). See +`Serial.println <http://arduino.cc/en/Serial/Println>`_ reference +for more on how characters are translated to numbers. + + + +The char datatype is a signed type, meaning that it encodes numbers +from -128 to 127. For an unsigned, one-byte (8 bit) data type, use +the *byte* data type. + + + +Example +------- + +:: + + char myChar = 'A'; + char myChar = 65; // both are equivalent + + + +See also +-------- + + +- `byte <http://arduino.cc/en/Reference/Byte>`_ +- `int <http://arduino.cc/en/Reference/Int>`_ +- `array <http://arduino.cc/en/Reference/Array>`_ +- `Serial.println <http://arduino.cc/en/Serial/Println>`_ + diff --git a/source/arduino/charcast.rst b/source/arduino/charcast.rst new file mode 100644 index 0000000..daa7c92 --- /dev/null +++ b/source/arduino/charcast.rst @@ -0,0 +1,41 @@ +.. _arduino-charcast: + +char() +====== + +Description +----------- + +Converts a value to the +`char <http://arduino.cc/en/Reference/Char>`_ data type. + + + +Syntax +------ + +char(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +char + + + +See also +-------- + + +- `char <http://arduino.cc/en/Reference/Char>`_ + + diff --git a/source/arduino/comments.rst b/source/arduino/comments.rst new file mode 100644 index 0000000..189ead5 --- /dev/null +++ b/source/arduino/comments.rst @@ -0,0 +1,45 @@ +.. _arduino-comments: + +Comments +======== + +Comments are lines in the program that are used to inform yourself +or others about the way the program works. They are ignored by the +compiler, and not exported to the processor, so they don't take up +any space on the Atmega chip. + + + +Comments only purpose are to help you understand (or remember) how +your program works or to inform others how your program works. +There are two different ways of marking a line as a comment: + + + +Example +------- + +:: + + x = 5; // This is a single line comment. Anything after the slashes is a comment + // to the end of the line + + /* this is multiline comment - use it to comment out whole blocks of code + + if (gwb == 0){ // single line comment is OK inside a multiline comment + x = 3; /* but not another multiline comment - this is invalid */ + } + // don't forget the "closing" comment - they have to be balanced! + */ + + + +**Tip** +When experimenting with code, "commenting out" parts of your +program is a convenient way to remove lines that may be buggy. This +leaves the lines in the code, but turns them into comments, so the +compiler just ignores them. This can be especially useful when +trying to locate a problem, or when a program refuses to compile +and the compiler error is cryptic or unhelpful. + + diff --git a/source/arduino/comparison.rst b/source/arduino/comparison.rst new file mode 100644 index 0000000..b87e05b --- /dev/null +++ b/source/arduino/comparison.rst @@ -0,0 +1,54 @@ +.. _arduino-comparison: + +Arduino/Processing Language Comparison +====================================== + +The Arduino language (based on Wiring) is implemented in C/C++, and +therefore has some differences from the Processing language, which +is based on Java. + + + +Arrays +~~~~~~ + +*Arduino* +*Processing* +int bar[8]; +bar[0] = 1; +int[] bar = new int[8]; +bar[0] = 1; +int foo[] = { 0, 1, 2 }; +int foo[] = { 0, 1, 2 }; +*or* +int[] foo = { 0, 1, 2 }; + + +Loops +~~~~~ + +*Arduino* +*Processing* +int i; +for (i = 0; i < 5; i++) { ... } +for (int i = 0; i < 5; i++) { ... } + + +Printing +~~~~~~~~ + +*Arduino* +*Processing* +Serial.println("hello world"); +println("hello world"); +int i = 5; +Serial.println(i); +int i = 5; +println(i); +int i = 5; +Serial.print("i = "); +Serial.print(i); +Serial.println(); +int i = 5; +println("i = " + i); + diff --git a/source/arduino/const.rst b/source/arduino/const.rst new file mode 100644 index 0000000..295b817 --- /dev/null +++ b/source/arduino/const.rst @@ -0,0 +1,55 @@ +.. _arduino-const: + +const keyword +============= + +The **const** keyword stands for constant. It is a variable +*qualifier* that modifies the behavior of the variable, making a +variable "*read-only*". This means that the variable can be used +just as any other variable of its type, but its value cannot be +changed. You will get a compiler error if you try to assign a value +to a **const** variable. + + + +Constants defined with the *const* keyword obey the rules of +*`variable scoping <http://arduino.cc/en/Reference/Scope>`_* that +govern other variables. This, and the pitfalls of using*#define*, +makes the *const* keyword a superior method for defining constants +and is preferred over using +*`#define <http://arduino.cc/en/Reference/Define>`_*. + + + +Example +------- + +:: + + const float pi = 3.14; + float x; + + // .... + + x = pi * 2; // it's fine to use const's in math + + pi = 7; // illegal - you can't write to (modify) a constant + + +**#define** or **const** +------------------------ + +You can use either **const** or **#define** for creating numeric or +string constants. For +`arrays <http://arduino.cc/en/Reference/Array>`_, you will need to +use **const**. In general *const* is preferred over *#define* for +defining constants. + + + +See also: + + +- `#define <http://arduino.cc/en/Reference/Define>`_ +- `volatile <http://arduino.cc/en/Reference/Volatile>`_ + diff --git a/source/arduino/constants.rst b/source/arduino/constants.rst new file mode 100644 index 0000000..49f3933 --- /dev/null +++ b/source/arduino/constants.rst @@ -0,0 +1,144 @@ +.. _arduino-constants: + +constants +========= + +Constants are predefined variables in the Arduino language. They +are used to make the programs easier to read. We classify constants +in groups. + + + +Defining Logical Levels, true and false (Boolean Constants) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two constants used to represent truth and falsity in the +Arduino language: **true**, and **false**. + + + +false +----- + +false is the easier of the two to define. false is defined as 0 +(zero). + + + +true +---- + +true is often said to be defined as 1, which is correct, but true +has a wider definition. Any integer which is *non-zero* is TRUE, in +a Boolean sense. So -1, 2 and -200 are all defined as true, too, in +a Boolean sense. + + + +Note that the *true* and *false* constants are typed in lowercase +unlike HIGH, LOW, INPUT, & OUTPUT. + + + +Defining Pin Levels, HIGH and LOW +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When reading or writing to a digital pin there are only two +possible values a pin can take/be-set-to: **HIGH** and **LOW**. + + + +**HIGH** + + + +The meaning of HIGH (in reference to a pin) is somewhat different +depending on whether a pin is set to an INPUT or OUTPUT. When a pin +is configured as an INPUT with pinMode, and read with digitalRead, +the microcontroller will report HIGH if a voltage of 3 volts or +more is present at the pin. + + + +A pin may also be configured as an INPUT with pinMode, and +subsequently made HIGH with digitalWrite, this will set the +internal 20K pullup resistors, which will *steer* the input pin to +a HIGH reading unless it is pulled LOW by external circuitry. + + + +When a pin is configured to OUTPUT with pinMode, and set to HIGH +with digitalWrite, the pin is at 5 volts. In this state it can +*source* current, e.g. light an LED that is connected through a +series resistor to ground, or to another pin configured as an +output, and set to LOW. + + + +**LOW** + + + +The meaning of LOW also has a different meaning depending on +whether a pin is set to INPUT or OUTPUT. When a pin is configured +as an INPUT with pinMode, and read with digitalRead, the +microcontroller will report LOW if a voltage of 2 volts or less is +present at the pin. + + + +When a pin is configured to OUTPUT with pinMode, and set to LOW +with digitalWrite, the pin is at 0 volts. In this state it can +*sink* current, e.g. light an LED that is connected through a +series resistor to, +5 volts, or to another pin configured as an +output, and set to HIGH. + + + +Defining Digital Pins, INPUT and OUTPUT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Digital pins can be used either as **INPUT** or **OUTPUT**. +Changing a pin from INPUT TO OUTPUT with pinMode() drastically +changes the electrical behavior of the pin. + + + +Pins Configured as Inputs +------------------------- + +Arduino (Atmega) pins configured as **INPUT** with pinMode() are +said to be in a high-impedance state. One way of explaining this is +that pins configured as INPUT make extremely small demands on the +circuit that they are sampling, say equivalent to a series resistor +of 100 Megohms in front of the pin. This makes them useful for +reading a sensor, but not powering an LED. + + + +Pins Configured as Outputs +-------------------------- + +Pins configured as **OUTPUT** with pinMode() are said to be in a +low-impedance state. This means that they can provide a substantial +amount of current to other circuits. Atmega pins can source +(provide positive current) or sink (provide negative current) up to +40 mA (milliamps) of current to other devices/circuits. This makes +them useful for powering LED's but useless for reading sensors. +Pins configured as outputs can also be damaged or destroyed if +short circuited to either ground or 5 volt power rails. The amount +of current provided by an Atmega pin is also not enough to power +most relays or motors, and some interface circuitry will be +required. + + + +See also +-------- + + +- `pinMode() <http://arduino.cc/en/Reference/PinMode>`_ +- `Integer Constants <http://arduino.cc/en/Reference/IntegerConstants>`_ +- `boolean variables <http://arduino.cc/en/Reference/BooleanVariables>`_ + + diff --git a/source/arduino/constrain.rst b/source/arduino/constrain.rst new file mode 100644 index 0000000..2769219 --- /dev/null +++ b/source/arduino/constrain.rst @@ -0,0 +1,60 @@ +.. _arduino-constrain: + +constrain(x, a, b) +================== + +Description +----------- + +Constrains a number to be within a range. + + + +Parameters +---------- + +x: the number to constrain, all data types + + + +a: the lower end of the range, all data types + + + +b: the upper end of the range, all data types + + + +Returns +------- + +**x**: if **x** is between **a** and **b** + + + +**a**: if **x** is less than **a** + + + +**b**: if **x** is greater than **b** + + + +Example +------- + +:: + + sensVal = constrain(sensVal, 10, 150); + // limits range of sensor values to between 10 and 150 + + + +See also +-------- + + +- `min <http://arduino.cc/en/Reference/Min>`_\ () +- `max <http://arduino.cc/en/Reference/Max>`_\ () + + diff --git a/source/arduino/continue.rst b/source/arduino/continue.rst new file mode 100644 index 0000000..66c7e60 --- /dev/null +++ b/source/arduino/continue.rst @@ -0,0 +1,29 @@ +.. _arduino-continue: + +continue +======== + +The continue statement skips the rest of the current iteration of a +loop (**do**, **for**, or **while**). It continues by checking the +conditional expression of the loop, and proceeding with any +subsequent iterations. + + + +Example +------- + +:: + + + for (x = 0; x < 255; x ++) + { + if (x > 40 && x < 120){ // create jump in values + continue; + } + + digitalWrite(PWMpin, x); + delay(50); + } + + diff --git a/source/arduino/cos.rst b/source/arduino/cos.rst new file mode 100644 index 0000000..7fed4bb --- /dev/null +++ b/source/arduino/cos.rst @@ -0,0 +1,33 @@ +.. _arduino-cos: + +cos(rad) +======== + +Description +----------- + +Calculates the cos of an angle (in radians). The result will be +between -1 and 1. + +Parameters +---------- + +rad: the angle in radians (*float*) + + + +Returns +------- + +The cos of the angle ("double") + + + +See also +-------- + + +- `sin <http://arduino.cc/en/Reference/Sin>`_\ () +- `tan <http://arduino.cc/en/Reference/Tan>`_\ () +- `float <http://arduino.cc/en/Reference/Float>`_ +- `double <http://arduino.cc/en/Reference/Double>`_ diff --git a/source/arduino/define.rst b/source/arduino/define.rst new file mode 100644 index 0000000..6190cb9 --- /dev/null +++ b/source/arduino/define.rst @@ -0,0 +1,83 @@ +.. _arduino-define: + +Define +====== + +``#define`` is a useful C component that allows the programmer to +give a name to a constant value before the program is compiled. +Defined constants in arduino don't take up any program memory space +on the chip. The compiler will replace references to these +constants with the defined value at compile time. + + + +This can have some unwanted side effects though, if for example, a +constant name that had been #defined is included in some other +constant or variable name. In that case the text would be replaced +by the #defined number (or text). + + + +In general, the *`const <http://arduino.cc/en/Reference/Const>`_* +keyword is preferred for defining constants and should be used +instead of #define. + + + +Arduino defines have the same syntax as C defines: + + + +Syntax +------ + +``#define constantName value`` + + + +Note that the # is necessary. + + + +Example +------- + +:: + + #define ledPin 3 + // The compiler will replace any mention of ledPin with the value 3 at compile time. + + + +Tip +--- + +There is no semicolon after the #define statement. If you include +one, the compiler will throw cryptic errors further down the page. + + + +:: + + #define ledPin 3; // this is an error + + + +Similarly, including an equal sign after the #define statement will +also generate a cryptic compiler error further down the page. + + + +:: + + #define ledPin = 3 // this is also an error + + + +See +--- + + +- `const <http://arduino.cc/en/Reference/Const>`_ +- `Constants <http://arduino.cc/en/Reference/IntegerConstants>`_ + diff --git a/source/arduino/delay.rst b/source/arduino/delay.rst new file mode 100644 index 0000000..973c75b --- /dev/null +++ b/source/arduino/delay.rst @@ -0,0 +1,94 @@ +.. _arduino-delay: + +delay() +======= + +Description +----------- + +Pauses the program for the amount of time (in miliseconds) +specified as parameter. (There are 1000 milliseconds in a second.) + + + +Syntax +------ + +delay(ms) + + + +Parameters +---------- + +ms: the number of milliseconds to pause (*unsigned long*) + + + +Returns +------- + +nothing + + + +Example +------- + +:: + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + + + +Caveat +------ + +While it is easy to create a blinking LED with the delay() +function, and many sketches use short delays for such tasks as +switch debouncing, the use of delay() in a sketch has significant +drawbacks. No other reading of sensors, mathematical calculations, +or pin manipulation can go on during the delay function, so in +effect, it brings most other activity to a halt. For alternative +approaches to controlling timing see the +`millis() <http://arduino.cc/en/Reference/Millis>`_ function and +the sketch sited below. More knowledgeable programmers usually +avoid the use of delay() for timing of events longer than 10's of +milliseconds unless the Arduino sketch is very simple. + + + +Certain things *do* go on while the delay() function is controlling +the Atmega chip however, because the delay function does not +disable interrupts. Serial communication that appears at the RX pin +is recorded, PWM +(`analogWrite <http://arduino.cc/en/Reference/AnalogWrite>`_) +values and pin states are maintained, and +`interrupts <http://arduino.cc/en/Reference/AttachInterrupt>`_ will +work as they should. + + + +See also +-------- + + +- `millis <http://arduino.cc/en/Reference/Millis>`_\ () +- `micros <http://arduino.cc/en/Reference/Micros>`_\ () +- `delayMicroseconds <http://arduino.cc/en/Reference/DelayMicroseconds>`_\ () +- `Blink Without Delay <http://arduino.cc/en/Tutorial/BlinkWithoutDelay>`_ + example + diff --git a/source/arduino/delaymicroseconds.rst b/source/arduino/delaymicroseconds.rst new file mode 100644 index 0000000..0feaba7 --- /dev/null +++ b/source/arduino/delaymicroseconds.rst @@ -0,0 +1,93 @@ +.. _arduino-delaymicroseconds: + +delayMicroseconds() +=================== + +Description +----------- + +Pauses the program for the amount of time (in microseconds) +specified as parameter. There are a thousand microseconds in a +millisecond, and a million microseconds in a second. + + + +Currently, the largest value that will produce an accurate delay is +16383. This could change in future Arduino releases. For delays +longer than a few thousand microseconds, you should use delay() +instead. + + + +Syntax +------ + +delayMicroseconds(us) + + + +Parameters +---------- + +us: the number of microseconds to pause (*unsigned int*) + + + +Returns +------- + +None + + + +Example +------- + +:: + + + int outPin = 8; // digital pin 8 + + void setup() + { + pinMode(outPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(outPin, HIGH); // sets the pin on + delayMicroseconds(50); // pauses for 50 microseconds + digitalWrite(outPin, LOW); // sets the pin off + delayMicroseconds(50); // pauses for 50 microseconds + } + + + +configures pin number 8 to work as an output pin. It sends a train +of pulses with 100 microseconds period. + + + +Caveats and Known Issues +------------------------ + +This function works very accurately in the range 3 microseconds and +up. We cannot assure that delayMicroseconds will perform precisely +for smaller delay-times. + + + +As of Arduino 0018, delayMicroseconds() no longer disables +interrupts. + + + +See also +-------- + + +- `millis <http://arduino.cc/en/Reference/Millis>`_\ () +- `micros <http://arduino.cc/en/Reference/Micros>`_\ () +- `delay <http://arduino.cc/en/Reference/Delay>`_\ () + + diff --git a/source/arduino/detachinterrupt.rst b/source/arduino/detachinterrupt.rst new file mode 100644 index 0000000..f0342df --- /dev/null +++ b/source/arduino/detachinterrupt.rst @@ -0,0 +1,26 @@ +.. _arduino-detachinterrupt: + +detachInterrupt(interrupt) +========================== + +Description +----------- + +Turns off the given interrupt. + + + +Parameters +---------- + +interrupt: the number of interrupt to disable (0 or 1). + + + +See also +-------- + + +- `attachInterrupt <http://arduino.cc/en/Reference/AttachInterrupt>`_\ () + + diff --git a/source/arduino/digitalread.rst b/source/arduino/digitalread.rst new file mode 100644 index 0000000..ec64fb0 --- /dev/null +++ b/source/arduino/digitalread.rst @@ -0,0 +1,86 @@ +.. _arduino-digitalread: + +digitalRead() +============= + +Description +----------- + +Reads the value from a specified digital pin, either +`HIGH <http://arduino.cc/en/Reference/Constants>`_ or +`LOW <http://arduino.cc/en/Reference/Constants>`_. + + + +Syntax +------ + +digitalRead(pin) + + + +Parameters +---------- + +pin: the number of the digital pin you want to read (*int*) + + + +Returns +------- + +`HIGH <http://arduino.cc/en/Reference/Constants>`_ or +`LOW <http://arduino.cc/en/Reference/Constants>`_ + + + +Example +------- + +:: + + + int ledPin = 13; // LED connected to digital pin 13 + int inPin = 7; // pushbutton connected to digital pin 7 + int val = 0; // variable to store the read value + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin 13 as output + pinMode(inPin, INPUT); // sets the digital pin 7 as input + } + + void loop() + { + val = digitalRead(inPin); // read the input pin + digitalWrite(ledPin, val); // sets the LED to the button's value + } + + + +Sets pin 13 to the same value as the pin 7, which is an input. + + + +Note +---- + +If the pin isn't connected to anything, digitalRead() can return +either HIGH or LOW (and this can change randomly). + + + +The analog input pins can be used as digital pins, referred to as +A0, A1, etc. + + + +See also +-------- + + +- `pinMode <http://arduino.cc/en/Reference/PinMode>`_\ () +- `digitalWrite <http://arduino.cc/en/Reference/DigitalWrite>`_\ () +- `Tutorial: Digital Pins <http://arduino.cc/en/Tutorial/DigitalPins>`_ + + diff --git a/source/arduino/digitalwrite.rst b/source/arduino/digitalwrite.rst new file mode 100644 index 0000000..82e1813 --- /dev/null +++ b/source/arduino/digitalwrite.rst @@ -0,0 +1,113 @@ +.. _arduino-digitalwrite: + +digitalWrite() +============== + +Description +----------- + +Write a `HIGH <http://arduino.cc/en/Reference/Constants>`_ or a +`LOW <http://arduino.cc/en/Reference/Constants>`_ value to a +digital pin. + + + +If the pin has been configured as an OUTPUT with +`pinMode <http://arduino.cc/en/Reference/PinMode>`_\ (), its voltage +will be set to the corresponding value: 5V (or 3.3V on 3.3V boards) +for HIGH, 0V (ground) for LOW. + + + +If the pin is configured as an INPUT, writing a HIGH value with +digitalWrite() will enable an internal 20K pullup resistor (see the +`tutorial on digital pins <http://arduino.cc/en/Tutorial/DigitalPins>`_). +Writing LOW will disable the pullup. The pullup resistor is enough +to light an LED dimly, so if LEDs appear to work, but very dimly, +this is a likely cause. The remedy is to set the pin to an output +with the pinMode() function. + + + +**NOTE:** Digital pin 13 is harder to use as a digital input than +the other digital pins because it has an LED and resistor attached +to it that's soldered to the board on most boards. If you enable +its internal 20k pull-up resistor, it will hang at around 1.7 V +instead of the expected 5V because the onboard LED and series +resistor pull the voltage level down, meaning it always returns +LOW. If you must use pin 13 as a digital input, use an external +pull down resistor. + + + +Syntax +------ + +digitalWrite(pin, value) + + + +Parameters +---------- + +pin: the pin number + + + +value: `HIGH <http://arduino.cc/en/Reference/Constants>`_ or +`LOW <http://arduino.cc/en/Reference/Constants>`_ + + + +Returns +------- + +none + + + +Example +------- + +:: + + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + + + +Sets pin 13 to HIGH, makes a one-second-long delay, and sets the +pin back to LOW. + + + +Note +---- + +The analog input pins can be used as digital pins, referred to as +A0, A1, etc. + + + +See also +-------- + + +- `pinMode <http://arduino.cc/en/Reference/PinMode>`_\ () +- `digitalRead <http://arduino.cc/en/Reference/DigitalRead>`_\ () +- `Tutorial: Digital Pins <http://arduino.cc/en/Tutorial/DigitalPins>`_ + + diff --git a/source/arduino/double.rst b/source/arduino/double.rst new file mode 100644 index 0000000..4e7f20c --- /dev/null +++ b/source/arduino/double.rst @@ -0,0 +1,32 @@ +.. _arduino-double: + +double +====== + +Desciption +---------- + +Double precision floating point number. Occupies 4 bytes. + + + +The double implementation on the Arduino is currently exactly the +same as the float, with no gain in precision. + + + +Tip +--- + +Users who borrow code from other sources that includes double +variables may wish to examine the code to see if the implied +precision is different from that actually achieved on the Arduino. + + + +See: +---- + + +- `float <http://arduino.cc/en/Reference/Float>`_ + diff --git a/source/arduino/dowhile.rst b/source/arduino/dowhile.rst new file mode 100644 index 0000000..48fe75b --- /dev/null +++ b/source/arduino/dowhile.rst @@ -0,0 +1,33 @@ +.. _arduino-dowhile: + +do - while +========== + +The **do** loop works in the same manner as the **while** loop, +with the exception that the condition is tested at the end of the +loop, so the **do** loop will *always* run at least once. + + + +:: + + do + { + // statement block + } while (test condition); + + + +Example +------- + +:: + + do + { + delay(50); // wait for sensors to stabilize + x = readSensors(); // check the sensors + + } while (x < 100); + + diff --git a/source/arduino/else.rst b/source/arduino/else.rst new file mode 100644 index 0000000..f278a0d --- /dev/null +++ b/source/arduino/else.rst @@ -0,0 +1,73 @@ +.. _arduino-else: + +if / else +========= + +**if/else** allows greater control over the flow of code than the +basic **if** statement, by allowing multiple tests to be grouped +together. For example, an analog input could be tested and one +action taken if the input was less than 500, and another action +taken if the input was 500 or greater. The code would look like +this: + + + +:: + + if (pinFiveInput < 500) + { + // action A + } + else + { + // action B + } + + + +**else** can proceed another **if** test, so that multiple, +mutually exclusive tests can be run at the same time. + + + +Each test will proceed to the next one until a true test is +encountered. When a true test is found, its associated block of +code is run, and the program then skips to the line following the +entire if/else construction. If no test proves to be true, the +default **else** block is executed, if one is present, and sets the +default behavior. + + + +Note that an **else if** block may be used with or without a +terminating **else** block and vice versa. An unlimited number of +such **else if** branches is allowed. + + + +:: + + if (pinFiveInput < 500) + { + // do Thing A + } + else if (pinFiveInput >= 1000) + { + // do Thing B + } + else + { + // do Thing C + } + +Another way to express branching, mutually exclusive tests, is with +the `switch case <http://arduino.cc/en/Reference/SwitchCase>`_ +statement. + + + +See also: +--------- + +`switch case <http://arduino.cc/en/Reference/SwitchCase>`_ + diff --git a/source/arduino/float.rst b/source/arduino/float.rst new file mode 100644 index 0000000..2f83a67 --- /dev/null +++ b/source/arduino/float.rst @@ -0,0 +1,88 @@ +.. _arduino-float: + +float +===== + +Description +----------- + +Datatype for floating-point numbers, a number that has a decimal +point. Floating-point numbers are often used to approximate analog +and continuous values because they have greater resolution than +integers. Floating-point numbers can be as large as 3.4028235E+38 +and as low as -3.4028235E+38. They are stored as 32 bits (4 bytes) +of information. + + + +Floats have only 6-7 decimal digits of precision. That means the +total number of digits, not the number to the right of the decimal +point. Unlike other platforms, where you can get more precision by +using a double (e.g. up to 15 digits), on the Arduino, double is +the same size as float. + + + +Floating point numbers are not exact, and may yield strange results +when compared. For example ``6.0 / 3.0`` may not equal ``2.0``. You +should instead check that the absolute value of the difference +between the numbers is less than some small number. + + + +Floating point math is also much slower than integer math in +performing calculations, so should be avoided if, for example, a +loop has to run at top speed for a critical timing function. +Programmers often go to some lengths to convert floating point +calculations to integer math to increase speed. + + + +Examples +-------- + +:: + + float myfloat; + float sensorCalbrate = 1.117; + + + +Syntax +------ + +:: + + float var = val; + + + + +- var - your float variable name +- val - the value you assign to that variable + + + +Example Code +------------ + +:: + + int x; + int y; + float z; + + x = 1; + y = x / 2; // y now contains 0, ints can't hold fractions + z = (float)x / 2.0; // z now contains .5 (you have to use 2.0, not 2) + + + +See Also +-------- + + +- `int <http://arduino.cc/en/Reference/Int>`_ +- `double <http://arduino.cc/en/Reference/Double>`_ +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ + diff --git a/source/arduino/floatcast.rst b/source/arduino/floatcast.rst new file mode 100644 index 0000000..6b85727 --- /dev/null +++ b/source/arduino/floatcast.rst @@ -0,0 +1,51 @@ +.. _arduino-floatcast: + +float() +======= + +Description +----------- + +Converts a value to the +`float <http://arduino.cc/en/Reference/Float>`_ data type. + + + +Syntax +------ + +float(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +float + + + +Notes +----- + +See the reference for +`float <http://arduino.cc/en/Reference/Float>`_ for details about +the precision and limitations of floating point numbers on +Arduino. + + + +See also +-------- + + +- `float <http://arduino.cc/en/Reference/Float>`_ + + diff --git a/source/arduino/for.rst b/source/arduino/for.rst new file mode 100644 index 0000000..b7e2e95 --- /dev/null +++ b/source/arduino/for.rst @@ -0,0 +1,117 @@ +.. _arduino-for: + +for statements +============== + +Desciption +---------- + +The **for** statement is used to repeat a block of statements +enclosed in curly braces. An increment counter is usually used to +increment and terminate the loop. The **for** statement is useful +for any repetitive operation, and is often used in combination with +arrays to operate on collections of data/pins. + + + +There are three parts to the **for** loop header: + + + +``<strong>for</strong> (<strong>initialization</strong>;<strong> condition</strong>;<strong> increment</strong>) {`` + + + +``//statement(s);`` + + + +``}`` + +|image0| + + +The **initialization** happens first and exactly once. Each time +through the loop, the **condition** is tested; if it's true, the +statement block, and the **increment** is executed, then the +**condition** is tested again. When the **condition** becomes +false, the loop ends. + + + +Example +------- + +:: + + // Dim an LED using a PWM pin + int PWMpin = 10; // LED in series with 470 ohm resistor on pin 10 + + void setup() + { + // no setup needed + } + + void loop() + { + for (int i=0; i <= 255; i++){ + analogWrite(PWMpin, i); + delay(10); + } + } + + + +Coding Tips +----------- + +The C **for** loop is much more flexible than **for** loops found +in some other computer languages, including BASIC. Any or all of +the three header elements may be omitted, although the semicolons +are required. Also the statements for initialization, condition, +and increment can be any valid C statements with unrelated +variables, and use any C datatypes including floats. These types of +unusual **for** statements may provide solutions to some rare +programming problems. + + + +For example, using a multiplication in the increment line will +generate a logarithmic progression: + +:: + + for(int x = 2; x < 100; x = x * 1.5){ + println(x); + } + + + +Generates: 2,3,4,6,9,13,19,28,42,63,94 + + + +Another example, fade an LED up and down with one **for** loop: + + + +:: + + void loop() + { + int x = 1; + for (int i = 0; i > -1; i = i + x){ + analogWrite(PWMpin, i); + if (i = 255) x = -1; // switch direction at peak + delay(10); + } + } + + + +See also +-------- + + +- `while <http://arduino.cc/en/Reference/While>`_ + diff --git a/source/arduino/fpconstants.rst b/source/arduino/fpconstants.rst new file mode 100644 index 0000000..284342b --- /dev/null +++ b/source/arduino/fpconstants.rst @@ -0,0 +1,36 @@ +.. _arduino-fpconstants: + +floating point constants +======================== + +Similar to integer constants, floating point constants are used to +make code more readable. Floating point constants are swapped at +compile time for the value to which the expression evaluates. + + + +Examples: + + + +``n = .005;`` + + + +Floating point constants can also be expressed in a variety of +scientific notation. 'E' and 'e' are both accepted as valid +exponent indicators. + + + +:: + + + floating-point evaluates to: also evaluates to: + constant + + 10.0 10 + 2.34E5 2.34 * 10^5 234000 + 67e-12 67.0 * 10^-12 .000000000067 + + diff --git a/source/arduino/goto.rst b/source/arduino/goto.rst new file mode 100644 index 0000000..1fcceb7 --- /dev/null +++ b/source/arduino/goto.rst @@ -0,0 +1,55 @@ +.. _arduino-goto: + +goto +==== + +Transfers program flow to a labeled point in the program + + + +Syntax +------ + +label: + + + +goto label; // sends program flow to the label + + + +Tip +--- + +The use of *goto* is discouraged in C programming, and some authors +of C programming books claim that the *goto* statement is never +necessary, but used judiciously, it can simplify certain programs. +The reason that many programmers frown upon the use of *goto* is +that with the unrestrained use of *goto* statements, it is easy to +create a program with undefined program flow, which can never be +debugged. + + + +With that said, there are instances where a goto statement can come +in handy, and simplify coding. One of these situations is to break +out of deeply nested *for* loops, or *if* logic blocks, on a +certain condition. + + + +Example +------- + +:: + + for(byte r = 0; r < 255; r++){ + for(byte g = 255; g > -1; g--){ + for(byte b = 0; b < 255; b++){ + if (analogRead(0) > 250){ goto bailout;} + // more statements ... + } + } + } + bailout: + diff --git a/source/arduino/highbyte.rst b/source/arduino/highbyte.rst new file mode 100644 index 0000000..dc6a1d6 --- /dev/null +++ b/source/arduino/highbyte.rst @@ -0,0 +1,42 @@ +.. _arduino-highbyte: + +highByte() +========== + +Description +----------- + +Extracts the high-order (leftmost) byte of a word (or the second +lowest byte of a larger data type). + + + +Syntax +------ + +highByte(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +byte + + + +See also +-------- + + +- `lowByte <http://arduino.cc/en/Reference/LowByte>`_\ () +- `word <http://arduino.cc/en/Reference/WordCast>`_\ () + + diff --git a/source/arduino/if.rst b/source/arduino/if.rst new file mode 100644 index 0000000..d75f6d3 --- /dev/null +++ b/source/arduino/if.rst @@ -0,0 +1,95 @@ +.. _arduino-if: + +if (conditional) and ==, !=, <, > (comparison operators) +======================================================== + +**``if``**, which is used in conjunction with a comparison +operator, tests whether a certain condition has been reached, such +as an input being above a certain number. The format for an if test +is: + + + +:: + + if (someVariable > 50) + { + // do something here + } + + + +The program tests to see if someVariable is greater than 50. If it +is, the program takes a particular action. Put another way, if the +statement in parentheses is true, the statements inside the +brackets are run. If not, the program skips over the code. + + + +The brackets may be omitted after an *if* statement. If this is +done, the next line (defined by the semicolon) becomes the only +conditional statement. + +:: + + + if (x > 120) digitalWrite(LEDpin, HIGH); + + if (x > 120) + digitalWrite(LEDpin, HIGH); + + if (x > 120){ digitalWrite(LEDpin, HIGH); } + + if (x > 120){ + digitalWrite(LEDpin1, HIGH); + digitalWrite(LEDpin2, HIGH); + } // all are correct + + + +The statements being evaluated inside the parentheses require the +use of one or more operators: + + + +Comparison Operators: +~~~~~~~~~~~~~~~~~~~~~ + +:: + + x == y (x is equal to y) + x != y (x is not equal to y) + x < y (x is less than y) + x > y (x is greater than y) + x <= y (x is less than or equal to y) + x >= y (x is greater than or equal to y) + + + +Warning: +-------- + +Beware of accidentally using the single equal sign +(e.g.``if (x = 10)`` ). The single equal sign is the assignment +operator, and sets x to 10 (puts the value 10 into the variable x). +Instead use the double equal sign (e.g.``if (x == 10)``), which is +the comparison operator, and tests *whether* x is equal to 10 or +not. The latter statement is only true if x equals 10, but the +former statement will always be true. + + + +This is because C evaluates the statement ``if (x=10)`` as follows: +10 is assigned to x (remember that the single equal sign is the +`assignment operator <http://arduino.cc/en/Reference/Assignment>`_), +so x now contains 10. Then the 'if' conditional evaluates 10, which +always evaluates to TRUE, since any non-zero number evaluates to +TRUE. Consequently, ``if (x = 10)`` will always evaluate to TRUE, +which is not the desired result when using an 'if' statement. +Additionally, the variable x will be set to 10, which is also not a +desired action. + + + +**if** can also be part of a branching control structure using the +`if...else <http://arduino.cc/en/Reference/Else>`_] construction. diff --git a/source/arduino/include.rst b/source/arduino/include.rst new file mode 100644 index 0000000..6d53801 --- /dev/null +++ b/source/arduino/include.rst @@ -0,0 +1,42 @@ +.. _arduino-include: + +#include +======== + +**#include** is used to include outside libraries in your sketch. +This gives the programmer access to a large group of standard C +libraries (groups of pre-made functions), and also libraries +written especially for Arduino. + + + +The main reference page for AVR C libraries (AVR is a reference to +the Atmel chips on which the Arduino is based) is +`here. <http://www.nongnu.org/avr-libc/user-manual/modules.html>`_ + + + +Note that **#include**, similar to **#define**, has no semicolon +terminator, and the compiler will yield cryptic error messages if +you add one. + + + +Example +------- + +This example includes a library that is used to put data into the +program space *flash* instead of *ram*. This saves the ram space +for dynamic memory needs and makes large lookup tables more +practical. + + + +:: + + #include <avr/pgmspace.h> + + prog_uint16_t myConstants[] PROGMEM = {0, 21140, 702 , 9128, 0, 25764, 8456, + 0,0,0,0,0,0,0,0,29810,8968,29762,29762,4500}; + + diff --git a/source/arduino/increment.rst b/source/arduino/increment.rst new file mode 100644 index 0000000..f9e87c9 --- /dev/null +++ b/source/arduino/increment.rst @@ -0,0 +1,58 @@ +.. _arduino-increment: + +++ (increment) / -- (decrement) +=============================== + +Description +----------- + +Increment or decrement a variable + + + +Syntax +------ + +:: + + x++; // increment x by one and returns the old value of x + ++x; // increment x by one and returns the new value of x + + x-- ; // decrement x by one and returns the old value of x + --x ; // decrement x by one and returns the new value of x + + + +Parameters +---------- + +x: an integer or long (possibly unsigned) + + + +Returns +------- + +The original or newly incremented / decremented value of the +variable. + + + +Examples +-------- + +:: + + x = 2; + y = ++x; // x now contains 3, y contains 3 + y = x--; // x contains 2 again, y still contains 3 + + + +See also +-------- + +`+= <http://arduino.cc/en/Reference/Arithmetic>`_ +`-= <http://arduino.cc/en/Reference/Arithmetic>`_ + + diff --git a/source/arduino/incrementcompound.rst b/source/arduino/incrementcompound.rst new file mode 100644 index 0000000..0005fbc --- /dev/null +++ b/source/arduino/incrementcompound.rst @@ -0,0 +1,49 @@ +.. _arduino-incrementcompound: + ++= , -= , \*= , /= +================== + +Description +----------- + +Perform a mathematical operation on a variable with another +constant or variable. The += (et al) operators are just a +convenient shorthand for the expanded syntax, listed below. + + + +Syntax +------ + +:: + + x += y; // equivalent to the expression x = x + y; + x -= y; // equivalent to the expression x = x - y; + x *= y; // equivalent to the expression x = x * y; + x /= y; // equivalent to the expression x = x / y; + + + +Parameters +---------- + +x: any variable type + + + +y: any variable type or constant + + + +Examples +-------- + +:: + + x = 2; + x += 4; // x now contains 6 + x -= 3; // x now contains 3 + x *= 10; // x now contains 30 + x /= 2; // x now contains 15 + + diff --git a/source/arduino/int.rst b/source/arduino/int.rst new file mode 100644 index 0000000..2bb3bef --- /dev/null +++ b/source/arduino/int.rst @@ -0,0 +1,84 @@ +.. _arduino-int: + +int +=== + +Description +----------- + +Integers are your primary datatype for number storage, and store a +2 byte value. This yields a range of -32,768 to 32,767 (minimum +value of -2^15 and a maximum value of (2^15) - 1). + + + +Int's store negative numbers with a technique called +`2's complement math. <http://en.wikipedia.org/wiki/2's_complement>`_ +The highest bit, sometimes refered to as the "sign" bit, flags the +number as a negative number. The rest of the bits are inverted and +1 is added. + + + +The Arduino takes care of dealing with negative numbers for you, so +that arithmetic operations work transparently in the expected +manner. There can be an unexpected complication in dealing with the +`bitshift right operator (>>) <http://arduino.cc/en/Reference/Bitshift>`_ +however. + + + +Example +------- + +:: + + int ledPin = 13; + + + +Syntax +------ + +:: + + int var = val; + + + + +- var - your int variable name +- val - the value you assign to that variable + + + +Coding Tip +---------- + +When variables are made to exceed their maximum capacity they "roll +over" back to their minimum capacitiy, note that this happens in +both directions. + + + +:: + + int x + x = -32,768; + x = x - 1; // x now contains 32,767 - rolls over in neg. direction + + x = 32,767; + x = x + 1; // x now contains -32,768 - rolls over + + + +See Also +-------- + + +- `byte <http://arduino.cc/en/Reference/Byte>`_ +- `unsigned int <http://arduino.cc/en/Reference/UnsignedInt>`_ +- `long <http://arduino.cc/en/Reference/Long>`_ +- `unsigned long <http://arduino.cc/en/Reference/UnsignedLong>`_ +- `Integer Constants <http://arduino.cc/en/Reference/IntegerConstants>`_ +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ diff --git a/source/arduino/intcast.rst b/source/arduino/intcast.rst new file mode 100644 index 0000000..d6bcca4 --- /dev/null +++ b/source/arduino/intcast.rst @@ -0,0 +1,41 @@ +.. _arduino-intcast: + +int() +===== + +Description +----------- + +Converts a value to the `int <http://arduino.cc/en/Reference/Int>`_ +data type. + + + +Syntax +------ + +int(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +int + + + +See also +-------- + + +- `int <http://arduino.cc/en/Reference/Int>`_ + + diff --git a/source/arduino/integerconstants.rst b/source/arduino/integerconstants.rst new file mode 100644 index 0000000..d60ed24 --- /dev/null +++ b/source/arduino/integerconstants.rst @@ -0,0 +1,130 @@ +.. _arduino-integerconstants: + +Integer Constants +================= + +Integer constants are numbers used directly in a sketch, like +``123``. By default, these numbers are treated as +`int <http://arduino.cc/en/Reference/Int>`_'s but you can change +this with the U and L modifiers (see below). + + + +Normally, integer constants are treated as base 10 (decimal) +integers, but special notation (formatters) may be used to enter +numbers in other bases. + + + +:: + + Base Example Formatter Comment + + 10 (decimal) 123 none + + 2 (binary) B1111011 leading 'B' only works with 8 bit values (0 to 255) + characters 0-1 valid + + 8 (octal) 0173 leading "0" characters 0-7 valid + + 16 (hexadecimal) 0x7B leading "0x" characters 0-9, A-F, a-f valid + + + +**Decimal** is base 10. This is the common-sense math with which +you are acquainted. Constants without other prefixes are assumed to +be in decimal format. + + + +Example: +:: + + 101 // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) + +**Binary** is base two. Only characters 0 and 1 are valid. + + + +Example: +:: + + B101 // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) + +The binary formatter only works on bytes (8 bits) between 0 (B0) +and 255 (B11111111). If it is convenient to input an int (16 bits) +in binary form you can do it a two-step procedure such as: + + + +:: + + myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte + + + +**Octal** is base eight. Only characters 0 through 7 are valid. +Octal values are indicated by the prefix "0" + + + +Example: + +:: + + 0101 // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) + +Warning +It is possible to generate a hard-to-find bug by (unintentionally) +including a leading zero before a constant and having the compiler +unintentionally interpret your constant as octal. +**Hexadecimal (or hex)** is base sixteen. Valid characters are 0 +through 9 and letters A through F; A has the value 10, B is 11, up +to F, which is 15. Hex values are indicated by the prefix "0x". +Note that A-F may be syted in upper or lower case (a-f). + + + +Example: + +:: + + 0x101 // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) + + + +U & L formatters +---------------- + +By default, an integer constant is treated as an +`int <http://arduino.cc/en/Reference/Int>`_ with the attendant +limitations in values. To specify an integer constant with another +data type, follow it with: + + + + +- a 'u' or 'U' to force the constant into an unsigned data format. + Example: ``33u`` +- a 'l' or 'L' to force the constant into a long data format. + Example: ``100000L`` +- a 'ul' or 'UL' to force the constant into an unsigned long + constant. Example: ``32767ul`` + + + + + +See also +-------- + + +- `constants <http://arduino.cc/en/Reference/Constants>`_ +- `#define <http://arduino.cc/en/Reference/Define>`_ +- `byte <http://arduino.cc/en/Reference/Byte>`_ +- `int <http://arduino.cc/en/Reference/Int>`_ +- `unsigned int <http://arduino.cc/en/Reference/UnsignedInt>`_ +- `long <http://arduino.cc/en/Reference/Long>`_ +- `unsigned long <http://arduino.cc/en/Reference/UnsignedLong>`_ + + diff --git a/source/arduino/interrupts.rst b/source/arduino/interrupts.rst new file mode 100644 index 0000000..282362b --- /dev/null +++ b/source/arduino/interrupts.rst @@ -0,0 +1,59 @@ +.. _arduino-interrupts: + +interrupts() +============ + +Description +----------- + +Re-enables interrupts (after they've been disabled by +`noInterrupts <http://arduino.cc/en/Reference/NoInterrupts>`_\ ()). +Interrupts allow certain important tasks to happen in the +background and are enabled by default. Some functions will not work +while interrupts are disabled, and incoming communication may be +ignored. Interrupts can slightly disrupt the timing of code, +however, and may be disabled for particularly critical sections of +code. + + + +Parameters +---------- + +None + + + +Returns +------- + +None + + + +Example +------- + +:: + + void setup() {} + + void loop() + { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + + + +See Also +-------- + + +- `noInterrupts <http://arduino.cc/en/Reference/NoInterrupts>`_\ () +- `attachInterrupt <http://arduino.cc/en/Reference/AttachInterrupt>`_\ () +- `detachInterrupt <http://arduino.cc/en/Reference/DetachInterrupt>`_\ () + + diff --git a/source/arduino/long.rst b/source/arduino/long.rst new file mode 100644 index 0000000..3d59896 --- /dev/null +++ b/source/arduino/long.rst @@ -0,0 +1,50 @@ +.. _arduino-long: + +long +==== + +Description +----------- + +Long variables are extended size variables for number storage, and +store 32 bits (4 bytes), from -2,147,483,648 to 2,147,483,647. + + + +Example +------- + + + +:: + + long speedOfLight = 186000L; // see Integer Constants for explanation of the 'L' + + + +Syntax +------ + +:: + + long var = val; + + + + +- var - the long variable name +- val - the value assigned to the variable + + + +See Also +-------- + + +- `byte <http://arduino.cc/en/Reference/Byte>`_ +- `int <http://arduino.cc/en/Reference/Int>`_ +- `unsigned int <http://arduino.cc/en/Reference/UnsignedInt>`_ +- `unsigned long <http://arduino.cc/en/Reference/UnsignedLong>`_ +- `Integer Constants <http://arduino.cc/en/Reference/IntegerConstants>`_ +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ + diff --git a/source/arduino/longcast.rst b/source/arduino/longcast.rst new file mode 100644 index 0000000..9f31443 --- /dev/null +++ b/source/arduino/longcast.rst @@ -0,0 +1,41 @@ +.. _arduino-longcast: + +long() +====== + +Description +----------- + +Converts a value to the +`long <http://arduino.cc/en/Reference/Long>`_ data type. + + + +Syntax +------ + +long(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +long + + + +See also +-------- + + +- `long <http://arduino.cc/en/Reference/Long>`_ + + diff --git a/source/arduino/loop.rst b/source/arduino/loop.rst new file mode 100644 index 0000000..165b7b0 --- /dev/null +++ b/source/arduino/loop.rst @@ -0,0 +1,39 @@ +.. _arduino-loop: + +loop() +====== + +After creating a setup() function, which initializes and sets the +initial values, the loop() function does precisely what its name +suggests, and loops consecutively, allowing your program to change +and respond. Use it to actively control the Arduino board. + + + +Example +~~~~~~~ + +:: + + + int buttonPin = 3; + + // setup initializes serial and the button pin + void setup() + { + beginSerial(9600); + pinMode(buttonPin, INPUT); + } + + // loop checks the button pin each time, + // and will send serial if it is pressed + void loop() + { + if (digitalRead(buttonPin) == HIGH) + serialWrite('H'); + else + serialWrite('L'); + + delay(1000); + } + diff --git a/source/arduino/lowbyte.rst b/source/arduino/lowbyte.rst new file mode 100644 index 0000000..d69f66a --- /dev/null +++ b/source/arduino/lowbyte.rst @@ -0,0 +1,42 @@ +.. _arduino-lowbyte: + +lowByte() +========= + +Description +----------- + +Extracts the low-order (rightmost) byte of a variable (e.g. a +word). + + + +Syntax +------ + +lowByte(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +byte + + + +See also +-------- + + +- `highByte <http://arduino.cc/en/Reference/HighByte>`_\ () +- `word <http://arduino.cc/en/Reference/WordCast>`_\ () + + diff --git a/source/arduino/map.rst b/source/arduino/map.rst new file mode 100644 index 0000000..65647fa --- /dev/null +++ b/source/arduino/map.rst @@ -0,0 +1,119 @@ +.. _arduino-map: + +map(value, fromLow, fromHigh, toLow, toHigh) +============================================ + +Description +----------- + +Re-maps a number from one range to another. That is, a **value** of +**fromLow** would get mapped to **toLow**, a value of **fromHigh** +to **toHigh**, values in-between to values in-between, etc. + + + +Does not constrain values to within the range, because out-of-range +values are sometimes intended and useful. The constrain() function +may be used either before or after this function, if limits to the +ranges are desired. + + + +Note that the "lower bounds" of either range may be larger or +smaller than the "upper bounds" so the map() function may be used +to reverse a range of numbers, for example + + + +``y = map(x, 1, 50, 50, 1);`` + + + +The function also handles negative numbers well, so that this +example + + + +``y = map(x, 1, 50, 50, -100);`` + + + +is also valid and works well. + + + +The map() function uses integer math so will not generate +fractions, when the math might indicate that it should do so. +Fractional remainders are truncated, and are not rounded or +averaged. + + + +Parameters +---------- + +value: the number to map + + + +fromLow: the lower bound of the value's current range + + + +fromHigh: the upper bound of the value's current range + + + +toLow: the lower bound of the value's target range + + + +toHigh: the upper bound of the value's target range + + + +Returns +------- + +The mapped value. + + + +Example +------- + +:: + + /* Map an analog value to 8 bits (0 to 255) */ + void setup() {} + + void loop() + { + int val = analogRead(0); + val = map(val, 0, 1023, 0, 255); + analogWrite(9, val); + } + + + +Appendix +~~~~~~~~ + +For the mathematically inclined, here's the whole function + + + +:: + + long map(long x, long in_min, long in_max, long out_min, long out_max) + { + return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min; + } + + + +See Also +-------- + + +- `constrain <http://arduino.cc/en/Reference/Constrain>`_\ () diff --git a/source/arduino/max.rst b/source/arduino/max.rst new file mode 100644 index 0000000..375625c --- /dev/null +++ b/source/arduino/max.rst @@ -0,0 +1,71 @@ +.. _arduino-max: + +max(x, y) +========= + +Description +----------- + +Calculates the maximum of two numbers. + + + +Parameters +---------- + +x: the first number, any data type + + + +y: the second number, any data type + + + +Returns +------- + +The larger of the two parameter values. + + + +Example +------- + +:: + + sensVal = max(senVal, 20); // assigns sensVal to the larger of sensVal or 20 + // (effectively ensuring that it is at least 20) + +Note +---- + +Perhaps counter-intuitively, max() is often used to constrain the +lower end of a variable's range, while min() is used to constrain +the upper end of the range. + + + +Warning +------- + +Because of the way the max() function is implemented, avoid using +other functions inside the brackets, it may lead to incorrect +results + + + +:: + + max(a--, 0); // avoid this - yields incorrect results + + a--; // use this instead - + max(a, 0); // keep other math outside the function + + + +See also +-------- + + +- `min <http://arduino.cc/en/Reference/Min>`_\ () +- `constrain <http://arduino.cc/en/Reference/Constrain>`_\ () diff --git a/source/arduino/micros.rst b/source/arduino/micros.rst new file mode 100644 index 0000000..cdee497 --- /dev/null +++ b/source/arduino/micros.rst @@ -0,0 +1,66 @@ +.. _arduino-micros: + +micros() +======== + +Description +----------- + +Returns the number of microseconds since the Arduino board began +running the current program. This number will overflow (go back to +zero), after approximately 70 minutes. On 16 MHz Arduino boards +(e.g. Duemilanove and Nano), this function has a resolution of four +microseconds (i.e. the value returned is always a multiple of +four). On 8 MHz Arduino boards (e.g. the LilyPad), this function +has a resolution of eight microseconds. + + + +*Note*: there are 1,000 microseconds in a millisecond and 1,000,000 +microseconds in a second. + + + +Parameters +---------- + +None + + + +Returns +------- + +Number of microseconds since the program started (*unsigned long*) + + + +Example +------- + +:: + + unsigned long time; + + void setup(){ + Serial.begin(9600); + } + void loop(){ + Serial.print("Time: "); + time = micros(); + //prints time since program started + Serial.println(time); + // wait a second so as not to send massive amounts of data + delay(1000); + } + + + +See also +-------- + + +- `millis <http://arduino.cc/en/Reference/Millis>`_\ () +- `delay <http://arduino.cc/en/Reference/Delay>`_\ () +- `delayMicroseconds <http://arduino.cc/en/Reference/DelayMicroseconds>`_\ () + diff --git a/source/arduino/millis.rst b/source/arduino/millis.rst new file mode 100644 index 0000000..009517d --- /dev/null +++ b/source/arduino/millis.rst @@ -0,0 +1,67 @@ +.. _arduino-millis: + +millis() +======== + +Description +----------- + +Returns the number of milliseconds since the Arduino board began +running the current program. This number will overflow (go back to +zero), after approximately 50 days. + + + +Parameters +---------- + +None + + + +Returns +------- + +Number of milliseconds since the program started (*unsigned long*) + + + +Example +------- + +:: + + unsigned long time; + + void setup(){ + Serial.begin(9600); + } + void loop(){ + Serial.print("Time: "); + time = millis(); + //prints time since program started + Serial.println(time); + // wait a second so as not to send massive amounts of data + delay(1000); + } + + + +Tip: +---- + +Note that the parameter for millis is an unsigned long, errors may +be generated if a programmer tries to do math with other datatypes +such as ints. + + + +See also +-------- + + +- `micros <http://arduino.cc/en/Reference/Micros>`_\ () +- `delay <http://arduino.cc/en/Reference/Delay>`_\ () +- `delayMicroseconds <http://arduino.cc/en/Reference/DelayMicroseconds>`_\ () +- `Tutorial: Blink Without Delay <http://arduino.cc/en/Tutorial/BlinkWithoutDelay>`_ + diff --git a/source/arduino/min.rst b/source/arduino/min.rst new file mode 100644 index 0000000..fdd7a5f --- /dev/null +++ b/source/arduino/min.rst @@ -0,0 +1,71 @@ +.. _arduino-min: + +min(x, y) +========= + +Description +----------- + +Calculates the minimum of two numbers. + + + +Parameters +---------- + +x: the first number, any data type + + + +y: the second number, any data type + + + +Returns +------- + +The smaller of the two numbers. + + + +Examples +-------- + +:: + + sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 + // ensuring that it never gets above 100. + +Note +---- + +Perhaps counter-intuitively, max() is often used to constrain the +lower end of a variable's range, while min() is used to constrain +the upper end of the range. + + + +Warning +------- + +Because of the way the min() function is implemented, avoid using +other functions inside the brackets, it may lead to incorrect +results + + + +:: + + min(a++, 100); // avoid this - yields incorrect results + + a++; + min(a, 100); // use this instead - keep other math outside the function + + + +See also +-------- + + +- `max <http://arduino.cc/en/Reference/Max>`_\ () +- `constrain <http://arduino.cc/en/Reference/Constrain>`_\ () diff --git a/source/arduino/modulo.rst b/source/arduino/modulo.rst new file mode 100644 index 0000000..195d15b --- /dev/null +++ b/source/arduino/modulo.rst @@ -0,0 +1,84 @@ +.. _arduino-modulo: + +% (modulo) +========== + +Description +----------- + +Calculates the remainder when one integer is divided by another. It +is useful for keeping a variable within a particular range (e.g. +the size of an array). + + + +Syntax +------ + +result = dividend % divisor + + + +Parameters +---------- + +dividend: the number to be divided + + + +divisor: the number to divide by + + + +Returns +------- + +the remainder + + + +Examples +-------- + +:: + + x = 7 % 5; // x now contains 2 + x = 9 % 5; // x now contains 4 + x = 5 % 5; // x now contains 0 + x = 4 % 5; // x now contains 4 + + + +Example Code +------------ + +:: + + /* update one value in an array each time through a loop */ + + int values[10]; + int i = 0; + + void setup() {} + + void loop() + { + values[i] = analogRead(0); + i = (i + 1) % 10; // modulo operator rolls over variable + } + + + +Tip +--- + +The modulo operator does not work on floats. + + + +See also +-------- + + +- `division <http://arduino.cc/en/Reference/Arithmetic>`_ + diff --git a/source/arduino/nointerrupts.rst b/source/arduino/nointerrupts.rst new file mode 100644 index 0000000..10d504d --- /dev/null +++ b/source/arduino/nointerrupts.rst @@ -0,0 +1,56 @@ +.. _arduino-nointerrupts: + +noInterrupts() +============== + +Description +----------- + +Disables interrupts (you can re-enable them with interrupts()). +Interrupts allow certain important tasks to happen in the +background and are enabled by default. Some functions will not work +while interrupts are disabled, and incoming communication may be +ignored. Interrupts can slightly disrupt the timing of code, +however, and may be disabled for particularly critical sections of +code. + + + +Parameters +---------- + +None. + + + +Returns +------- + +None. + + + +Example +------- + +:: + + void setup() {} + + void loop() + { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + + + +See Also +-------- + + +- `interrupts <http://arduino.cc/en/Reference/Interrupts>`_\ () + + diff --git a/source/arduino/notone.rst b/source/arduino/notone.rst new file mode 100644 index 0000000..4390b52 --- /dev/null +++ b/source/arduino/notone.rst @@ -0,0 +1,47 @@ +.. _arduino-notone: + +noTone() +======== + +Description +----------- + +Stops the generation of a square wave triggered by +`tone <http://arduino.cc/en/Reference/Tone>`_\ (). Has no effect if +no tone is being generated. + + + +**NOTE:** if you want to play different pitches on multiple pins, +you need to call noTone() on one pin before calling tone() on the +next pin. + + + +Syntax +------ + +noTone(pin) + + + +Parameters +---------- + +pin: the pin on which to stop generating the tone + + + +Returns +------- + +nothing + + + +See also +-------- + + +- `tone <http://arduino.cc/en/Reference/Tone>`_ () + diff --git a/source/arduino/pinmode.rst b/source/arduino/pinmode.rst new file mode 100644 index 0000000..34c7998 --- /dev/null +++ b/source/arduino/pinmode.rst @@ -0,0 +1,67 @@ +.. highlight:: cpp + +.. _arduino-pinmode: + +pinMode() +========= + +.. doxygenfunction:: pinMode + +.. doxygenenum:: WiringPinMode + +Discussion +---------- + +pinMode() is usually called within :ref:`arduino-setup` in order to +configure a pin for a certain usage (although it may be called from +anywhere). + + +Example +------- + + :: + + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + + + +Arduino Compatibility Note +-------------------------- + +The libmaple implementation of pinMode() supports OUTPUT and INPUT +modes with a meaning identical to that of the Arduino function. + +INPUT_ANALOG and PWM modes were added because the Maple does not +distinguish between analog and digital pins the same way the Arduino +does. Unlike the Arduino, you **must call pinMode**\ () to set up a pin +for these purposes before a call to, e.g., :ref:`arduino-analogRead`. +In practice, this should only add a few lines of pinMode() calls to +your :ref:`arduino-setup` function. + +OUTPUT_OPEN_DRAIN, INPUT_PULLUP, INPUT_PULLDOWN, and PWM_OPEN_DRAIN +modes represent functionality not currently available on Arduino +boards. + +See also +-------- + +- :ref:`arduino-constants` +- :ref:`arduino-digitalwrite` +- :ref:`arduino-digitalread` +- Maple :ref:`GPIO <gpio>` reference page +- Arduino `pinMode() <http://www.arduino.cc/en/Reference/PinMode>`_ reference diff --git a/source/arduino/pointer.rst b/source/arduino/pointer.rst new file mode 100644 index 0000000..4e4b9e5 --- /dev/null +++ b/source/arduino/pointer.rst @@ -0,0 +1,16 @@ +.. _arduino-pointer: + +The pointer operators +===================== + +& (reference) and \* (dereference) +================================== + +Pointers are one of the more complicated subjects for beginners in +learning C, and it is possible to write the vast majority of +Arduino sketches without ever encountering pointers. However for +manipulating certain data structures, the use of pointers can +simplify the code, and and knowledge of manipulating pointers is +handy to have in one's toolkit. + + diff --git a/source/arduino/pow.rst b/source/arduino/pow.rst new file mode 100644 index 0000000..3a09481 --- /dev/null +++ b/source/arduino/pow.rst @@ -0,0 +1,47 @@ +.. _arduino-pow: + +pow(base, exponent) +=================== + +Description +----------- + +Calculates the value of a number raised to a power. Pow() can be +used to raise a number to a fractional power. This is useful for +generating exponential mapping of values or curves. + + + +Parameters +---------- + +base: the number (*float*) + + + +exponent: the power to which the base is raised (*float*) + + + +Returns +------- + +The result of the exponentiation (*double*) + + + +Example +------- + +See the `fscale <http://arduino.cc/playground/Main/Fscale>`_ +function in the code library. + + + +See also +-------- + + +- `sqrt <http://arduino.cc/en/Reference/Sqrt>`_\ () +- `float <http://arduino.cc/en/Reference/Float>`_ +- `double <http://arduino.cc/en/Reference/Double>`_ diff --git a/source/arduino/pulsein.rst b/source/arduino/pulsein.rst new file mode 100644 index 0000000..568d992 --- /dev/null +++ b/source/arduino/pulsein.rst @@ -0,0 +1,79 @@ +.. _arduino-pulsein: + +pulseIn() +========= + +Description +----------- + +Reads a pulse (either HIGH or LOW) on a pin. For example, if +**value** is **HIGH**, **pulseIn()** waits for the pin to go +**HIGH**, starts timing, then waits for the pin to go **LOW** and +stops timing. Returns the length of the pulse in microseconds. +Gives up and returns 0 if no pulse starts within a specified time +out. + + + +The timing of this function has been determined empirically and +will probably show errors in longer pulses. Works on pulses from 10 +microseconds to 3 minutes in length. + + + +Syntax +------ + +pulseIn(pin, value) +pulseIn(pin, value, timeout) + + + +Parameters +---------- + +pin: the number of the pin on which you want to read the pulse. +(*int*) + + + +value: type of pulse to read: either +`HIGH <http://arduino.cc/en/Reference/Constants>`_ or +`LOW <http://arduino.cc/en/Reference/Constants>`_. (*int*) + + + +timeout (optional): the number of microseconds to wait for the +pulse to start; default is one second (*unsigned long*) + + + +Returns +------- + +the length of the pulse (in microseconds) or 0 if no pulse started +before the timeout (*unsigned long*) + + + +Example +------- + +:: + + + + int pin = 7; + unsigned long duration; + + void setup() + { + pinMode(pin, INPUT); + } + + void loop() + { + duration = pulseIn(pin, HIGH); + } + + diff --git a/source/arduino/random.rst b/source/arduino/random.rst new file mode 100644 index 0000000..44f122a --- /dev/null +++ b/source/arduino/random.rst @@ -0,0 +1,92 @@ +.. _arduino-random: + +random() +======== + +Description +----------- + +The random function generates pseudo-random numbers. + + + +Syntax +------ + +random(max) +random(min, max) + + + +Parameters +---------- + +min - lower bound of the random value, inclusive *(optional)* + + + +max - upper bound of the random value, exclusive + + + +Returns +------- + +a random number between min and max-1 (*long*) + + + +Note: +----- + +If it is important for a sequence of values generated by random() +to differ, on subsequent executions of a sketch, use randomSeed() +to initialize the random number generator with a fairly random +input, such as analogRead() on an unconnected pin. + + + +Conversely, it can occasionally be useful to use pseudo-random +sequences that repeat exactly. This can be accomplished by calling +randomSeed() with a fixed number, before starting the random +sequence. + + + +Example +------- + +:: + + long randNumber; + + void setup(){ + Serial.begin(9600); + + // if analog input pin 0 is unconnected, random analog + // noise will cause the call to randomSeed() to generate + // different seed numbers each time the sketch runs. + // randomSeed() will then shuffle the random function. + randomSeed(analogRead(0)); + } + + void loop() { + // print a random number from 0 to 299 + randNumber = random(300); + Serial.println(randNumber); + + // print a random number from 10 to 19 + randNumber = random(10, 20); + Serial.println(randNumber); + + delay(50); + } + + + +See also +-------- + + +- `randomSeed <http://arduino.cc/en/Reference/RandomSeed>`_\ () + diff --git a/source/arduino/randomseed.rst b/source/arduino/randomseed.rst new file mode 100644 index 0000000..b0b5d71 --- /dev/null +++ b/source/arduino/randomseed.rst @@ -0,0 +1,70 @@ +.. _arduino-randomseed: + +randomSeed(seed) +================ + +Description +----------- + +randomSeed() initializes the pseudo-random number generator, +causing it to start at an arbitrary point in its random sequence. +This sequence, while very long, and random, is always the same. + + + +If it is important for a sequence of values generated by random() +to differ, on subsequent executions of a sketch, use randomSeed() +to initialize the random number generator with a fairly random +input, such as analogRead() on an unconnected pin. + + + +Conversely, it can occasionally be useful to use pseudo-random +sequences that repeat exactly. This can be accomplished by calling +randomSeed() with a fixed number, before starting the random +sequence. + + + +Parameters +---------- + +long, int - pass a number to generate the seed. + + + +Returns +------- + +no returns + + + +Example +------- + +:: + + long randNumber; + + void setup(){ + Serial.begin(9600); + randomSeed(analogRead(0)); + } + + void loop(){ + randNumber = random(300); + Serial.println(randNumber); + + delay(50); + } + + + +See also +-------- + + +- `random <http://arduino.cc/en/Reference/Random>`_ + + diff --git a/source/arduino/return.rst b/source/arduino/return.rst new file mode 100644 index 0000000..ae3b37d --- /dev/null +++ b/source/arduino/return.rst @@ -0,0 +1,69 @@ +.. _arduino-return: + +return +====== + +Terminate a function and return a value from a function to the +calling function, if desired. + + + +Syntax: +------- + +return; + + + +return value; // both forms are valid + + + +Parameters +---------- + +value: any variable or constant type + + + +Examples: +--------- + +A function to compare a sensor input to a threshold + +:: + + int checkSensor(){ + if (analogRead(0) > 400) { + return 1; + else{ + return 0; + } + } + + + +The return keyword is handy to test a section of code without +having to "comment out" large sections of possibly buggy code. + + + +:: + + void loop(){ + + // brilliant code idea to test here + + return; + + // the rest of a dysfunctional sketch here + // this code will never be executed + } + + + +See also +-------- + +`comments <http://arduino.cc/en/Reference/Comments>`_ + diff --git a/source/arduino/scope.rst b/source/arduino/scope.rst new file mode 100644 index 0000000..bb56246 --- /dev/null +++ b/source/arduino/scope.rst @@ -0,0 +1,56 @@ +.. _arduino-scope: + +Variable Scope +============== + +Variables in the C programming language, which Arduino uses, have a +property called *scope*. This is in contrast to languages such as +BASIC where every variable is a *global* variable. + + + +A global variable is one that can be *seen* by every function in a +program. Local variables are only visible to the function in which +they are declared. In the Arduino environment, any variable +declared outside of a function (e.g. setup(), loop(), etc. ), is a +global variable. + + + +When programs start to get larger and more complex, local variables +are a useful way to insure that only one function has access to its +own variables. This prevents programming errors when one function +inadvertently modifies variables used by another function. + + + +It is also sometimes handy to declare and initialize a variable +inside a *for* loop. This creates a variable that can only be +accessed from inside the for-loop brackets. + + + +Example: +-------- + +:: + + int gPWMval; // any function will see this variable + + void setup() + { + // ... + } + + void loop() + { + int i; // "i" is only "visible" inside of "loop" + float f; // "f" is only "visible" inside of "loop" + // ... + + for (int j = 0; j <100; j++){ + // variable j can only be accessed inside the for-loop brackets + } + + } + diff --git a/source/arduino/semicolon.rst b/source/arduino/semicolon.rst new file mode 100644 index 0000000..b3cc8c4 --- /dev/null +++ b/source/arduino/semicolon.rst @@ -0,0 +1,27 @@ +.. _arduino-semicolon: + +; semicolon +=========== + +Used to end a statement. + + + +Example +~~~~~~~ + +:: + + int a = 13; + +Tip +--- + +Forgetting to end a line in a semicolon will result in a compiler +error. The error text may be obvious, and refer to a missing +semicolon, or it may not. If an impenetrable or seemingly illogical +compiler error comes up, one of the first things to check is a +missing semicolon, in the immediate vicinity, preceding the line at +which the compiler complained. + + diff --git a/source/arduino/serial.rst b/source/arduino/serial.rst new file mode 100644 index 0000000..31ce06c --- /dev/null +++ b/source/arduino/serial.rst @@ -0,0 +1,62 @@ +.. _arduino-serial: + +Serial +====== + +Used for communication between the Arduino board and a computer or +other devices. All Arduino boards have at least one serial port +(also known as a UART or USART): **Serial**. It communicates on +digital pins 0 (RX) and 1 (TX) as well as with the computer via +USB. Thus, if you use these functions, you cannot also use pins 0 +and 1 for digital input or output. + + + +You can use the Arduino environment's built-in serial monitor to +communicate with an Arduino board. Click the serial monitor button +in the toolbar and select the same baud rate used in the call to +begin(). + + + +The Arduino Mega has three additional serial ports: **Serial1** on +pins 19 (RX) and 18 (TX), **Serial2** on pins 17 (RX) and 16 (TX), +**Serial3** on pins 15 (RX) and 14 (TX). To use these pins to +communicate with your personal computer, you will need an +additional USB-to-serial adaptor, as they are not connected to the +Mega's USB-to-serial adaptor. To use them to communicate with an +external TTL serial device, connect the TX pin to your device's RX +pin, the RX to your device's TX pin, and the ground of your Mega to +your device's ground. (Don't connect these pins directly to an +RS232 serial port; they operate at +/- 12V and can damage your +Arduino board.) + + + +Functions +--------- + + +- `begin <http://arduino.cc/en/Serial/Begin>`_\ () +- `end <http://arduino.cc/en/Serial/End>`_\ () +- `available <http://arduino.cc/en/Serial/Available>`_\ () +- `read <http://arduino.cc/en/Serial/Read>`_\ () +- `flush <http://arduino.cc/en/Serial/Flush>`_\ () +- `print <http://arduino.cc/en/Serial/Print>`_\ () +- `println <http://arduino.cc/en/Serial/Println>`_\ () +- `write <http://arduino.cc/en/Serial/Write>`_\ () + + + +Examples +-------- + + +- `ASCII Table <http://arduino.cc/en/Tutorial/ASCIITable>`_ +- `Dimmer <http://arduino.cc/en/Tutorial/Dimmer>`_ +- `Graph <http://arduino.cc/en/Tutorial/Graph>`_ +- `Physical Pixel <http://arduino.cc/en/Tutorial/PhysicalPixel>`_ +- `Virtual Color Mixer <http://arduino.cc/en/Tutorial/VirtualColorMixer>`_ +- `Serial Call Response <http://arduino.cc/en/Tutorial/SerialCallResponse>`_ +- `Serial Call Response ASCII <http://arduino.cc/en/Tutorial/SerialCallResponseASCII>`_ + diff --git a/source/arduino/setup.rst b/source/arduino/setup.rst new file mode 100644 index 0000000..05911ed --- /dev/null +++ b/source/arduino/setup.rst @@ -0,0 +1,31 @@ +.. _arduino-setup: + +setup() +======= + +The setup() function is called when a sketch starts. Use it to +initialize variables, pin modes, start using libraries, etc. The +setup function will only run once, after each powerup or reset of +the Arduino board. + + + +Example +~~~~~~~ + +:: + + + int buttonPin = 3; + + void setup() + { + Serial.begin(9600); + pinMode(buttonPin, INPUT); + } + + void loop() + { + // ... + } + diff --git a/source/arduino/shiftout.rst b/source/arduino/shiftout.rst new file mode 100644 index 0000000..2277cf1 --- /dev/null +++ b/source/arduino/shiftout.rst @@ -0,0 +1,133 @@ +.. _arduino-shiftout: + +shiftOut() +========== + +Description +----------- + +Shifts out a byte of data one bit at a time. Starts from either the +most (i.e. the leftmost) or least (rightmost) significant bit. Each +bit is written in turn to a data pin, after which a clock pin is +pulsed to indicate that the bit is available. + + + +This is a software implementation; Arduino (as of 0019) also +provides an `SPI library <http://arduino.cc/en/Reference/SPI>`_ +that uses the hardware implementation. + + + +Syntax +------ + +shiftOut(dataPin, clockPin, bitOrder, value) + + + +Parameters +---------- + +dataPin: the pin on which to output each bit (*int*) + + + +clockPin: the pin to toggle once the **dataPin** has been set to +the correct value (*int*) + + + +bitOrder: which order to shift out the bits; either **MSBFIRST** or +**LSBFIRST**. +(Most Significant Bit First, or, Least Significant Bit First) + + + +value: the data to shift out. (*byte*) + + + +Returns +------- + +None + + + +Note +---- + +The **dataPin** and **clockPin** must already be configured as +outputs by a call to +`pinMode <http://arduino.cc/en/Reference/PinMode>`_\ (). + + + +**shiftOut** is currently written to output 1 byte (8 bits) so it +requires a two step operation to output values larger than 255. + +:: + + // Do this for MSBFIRST serial + int data = 500; + // shift out highbyte + shiftOut(dataPin, clock, MSBFIRST, (data >> 8)); + // shift out lowbyte + shiftOut(data, clock, MSBFIRST, data); + + // Or do this for LSBFIRST serial + data = 500; + // shift out lowbyte + shiftOut(dataPin, clock, LSBFIRST, data); + // shift out highbyte + shiftOut(dataPin, clock, LSBFIRST, (data >> 8)); + + + +Example +------- + +*For accompanying circuit, see the `tutorial on controlling a 74HC595 shift register <http://arduino.cc/en/Tutorial/ShiftOut>`_.* + + + +:: + + //**************************************************************// + // Name : shiftOutCode, Hello World // + // Author : Carlyn Maw,Tom Igoe // + // Date : 25 Oct, 2006 // + // Version : 1.0 // + // Notes : Code for using a 74HC595 Shift Register // + // : to count from 0 to 255 // + //**************************************************************** + + //Pin connected to ST_CP of 74HC595 + int latchPin = 8; + //Pin connected to SH_CP of 74HC595 + int clockPin = 12; + ////Pin connected to DS of 74HC595 + int dataPin = 11; + + void setup() { + //set pins to output because they are addressed in the main loop + pinMode(latchPin, OUTPUT); + pinMode(clockPin, OUTPUT); + pinMode(dataPin, OUTPUT); + } + + void loop() { + //count up routine + for (int j = 0; j < 256; j++) { + //ground latchPin and hold low for as long as you are transmitting + digitalWrite(latchPin, LOW); + shiftOut(dataPin, clockPin, LSBFIRST, j); + //return the latch pin high to signal chip that it + //no longer needs to listen for information + digitalWrite(latchPin, HIGH); + delay(1000); + } + } + + diff --git a/source/arduino/sin.rst b/source/arduino/sin.rst new file mode 100644 index 0000000..3a06a8f --- /dev/null +++ b/source/arduino/sin.rst @@ -0,0 +1,35 @@ +.. _arduino-sin: + +sin(rad) +======== + +Description +----------- + +Calculates the sine of an angle (in radians). The result will be +between -1 and 1. + + + +Parameters +---------- + +rad: the angle in radians (*float*) + + + +Returns +------- + +the sine of the angle (*double*) + + + +See also +-------- + + +- `cos <http://arduino.cc/en/Reference/Cos>`_\ () +- `tan <http://arduino.cc/en/Reference/Tan>`_\ () +- `float <http://arduino.cc/en/Reference/Float>`_ +- `double <http://arduino.cc/en/Reference/Double>`_ diff --git a/source/arduino/sizeof.rst b/source/arduino/sizeof.rst new file mode 100644 index 0000000..a95dfbf --- /dev/null +++ b/source/arduino/sizeof.rst @@ -0,0 +1,71 @@ +.. _arduino-sizeof: + +sizeof +====== + +Description +----------- + +The sizeof operator returns the number of bytes in a variable type, +or the number of bytes occupied by an array. + + + +Syntax +------ + +sizeof(variable) + + + +Parameters +---------- + +variable: any variable type or array (e.g. int, float, byte) + + + +Example code +------------ + +The sizeof operator is useful for dealing with arrays (such as +strings) where it is convenient to be able to change the size of +the array without breaking other parts of the program. + + + +This program prints out a text string one character at a time. Try +changing the text phrase. + + + +:: + + char myStr[] = "this is a test"; + int i; + + void setup(){ + Serial.begin(9600); + } + + void loop() { + for (i = 0; i < sizeof(myStr) - 1; i++){ + Serial.print(i, DEC); + Serial.print(" = "); + Serial.println(myStr[i], BYTE); + } + } + + +Note that sizeof returns the total number of bytes. So for larger +variable types such as ints, the for loop would look something like +this. + + + +:: + + for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { + // do something with myInts[i] + } + diff --git a/source/arduino/sqrt.rst b/source/arduino/sqrt.rst new file mode 100644 index 0000000..5b8a73e --- /dev/null +++ b/source/arduino/sqrt.rst @@ -0,0 +1,33 @@ +.. _arduino-sqrt: + +sqrt(x) +======= + +Description +----------- + +Calculates the square root of a number. + + + +Parameters +---------- + +x: the number, any data type + + + +Returns +------- + +double, the number's square root. + + + +See also +-------- + + +- `pow <http://arduino.cc/en/Reference/Pow>`_\ () +- `sq <http://arduino.cc/en/Reference/Sq>`_\ () + diff --git a/source/arduino/static.rst b/source/arduino/static.rst new file mode 100644 index 0000000..1c0340e --- /dev/null +++ b/source/arduino/static.rst @@ -0,0 +1,71 @@ +.. _arduino-static: + +Static +====== + +The static keyword is used to create variables that are visible to +only one function. However unlike local variables that get created +and destroyed every time a function is called, static variables +persist beyond the function call, preserving their data between +function calls. + + + +Variables declared as static will only be created and initialized +the first time a function is called. + + + +Example +------- + +:: + + + + /* RandomWalk + * Paul Badger 2007 + * RandomWalk wanders up and down randomly between two + * endpoints. The maximum move in one loop is governed by + * the parameter "stepsize". + * A static variable is moved up and down a random amount. + * This technique is also known as "pink noise" and "drunken walk". + */ + + #define randomWalkLowRange -20 + #define randomWalkHighRange 20 + int stepsize; + + int thisTime; + int total; + + void setup() + { + Serial.begin(9600); + } + + void loop() + { // tetst randomWalk function + stepsize = 5; + thisTime = randomWalk(stepsize); + Serial.println(thisTime); + delay(10); + } + + int randomWalk(int moveSize){ + static int place; // variable to store value in random walk - declared static so that it stores + // values in between function calls, but no other functions can change its value + + place = place + (random(-moveSize, moveSize + 1)); + + if (place < randomWalkLowRange){ // check lower and upper limits + place = place + (randomWalkLowRange - place); // reflect number back in positive direction + } + else if(place > randomWalkHighRange){ + place = place - (place - randomWalkHighRange); // reflect number back in negative direction + } + + return place; + } + + diff --git a/source/arduino/string.rst b/source/arduino/string.rst new file mode 100644 index 0000000..b841728 --- /dev/null +++ b/source/arduino/string.rst @@ -0,0 +1,158 @@ +.. _arduino-string: + +string +====== + +Description +----------- + +Text strings can be represented in two ways. you can use the String +data type, which is part of the core as of version 0019, or you can +make a string out of an array of type char and null-terminate it. +This page described the latter method. For more details on the +String object, which gives you more functionality at the cost of +more memory, see the +`String object <http://arduino.cc/en/Reference/StringObject>`_ +page. + + + +Examples +-------- + +All of the following are valid declarations for strings. + +:: + + char Str1[15]; + char Str2[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o'}; + char Str3[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o', '\0'}; + char Str4[ ] = "arduino"; + char Str5[8] = "arduino"; + char Str6[15] = "arduino"; + + + +**Possibilities for declaring strings** + + + + +- Declare an array of chars without initializing it as in Str1 +- Declare an array of chars (with one extra char) and the compiler + will add the required null character, as in Str2 +- Explicitly add the null character, Str3 +- Initialize with a string constant in quotation marks; the + compiler will size the array to fit the string constant and a + terminating null character, Str4 +- Initialize the array with an explicit size and string constant, + Str5 +- Initialize the array, leaving extra space for a larger string, + Str6 + + + +**Null termination** + + + +Generally, strings are terminated with a null character (ASCII code +0). This allows functions (like Serial.print()) to tell where the +end of a string is. Otherwise, they would continue reading +subsequent bytes of memory that aren't actually part of the +string. + + + +This means that your string needs to have space for one more +character than the text you want it to contain. That is why Str2 +and Str5 need to be eight characters, even though "arduino" is only +seven - the last position is automatically filled with a null +character. Str4 will be automatically sized to eight characters, +one for the extra null. In Str3, we've explicitly included the null +character (written '\\0') ourselves. + + + +Note that it's possible to have a string without a final null +character (e.g. if you had specified the length of Str2 as seven +instead of eight). This will break most functions that use strings, +so you shouldn't do it intentionally. If you notice something +behaving strangely (operating on characters not in the string), +however, this could be the problem. + + + +**Single quotes or double quotes?** + + + +Strings are always defined inside double quotes ("Abc") and +characters are always defined inside single quotes('A'). + + + +**Wrapping long strings** + + + +You can wrap long strings like this: + +:: + + char myString[] = "This is the first line" + " this is the second line" + " etcetera"; + + + +**Arrays of strings** + + + +It is often convenient, when working with large amounts of text, +such as a project with an LCD display, to setup an array of +strings. Because strings themselves are arrays, this is in actually +an example of a two-dimensional array. + + + +In the code below, the asterisk after the datatype char "char\*" +indicates that this is an array of "pointers". All array names are +actually pointers, so this is required to make an array of arrays. +Pointers are one of the more esoteric parts of C for beginners to +understand, but it isn't necessary to understand pointers in detail +to use them effectively here. + + + +Example +------- + +:: + + + char* myStrings[]={"This is string 1", "This is string 2", "This is string 3", + "This is string 4", "This is string 5","This is string 6"}; + + void setup(){ + Serial.begin(9600); + } + + void loop(){ + for (int i = 0; i < 6; i++){ + Serial.println(myStrings[i]); + delay(500); + } + } + + + +See Also +-------- + + +- `array <http://arduino.cc/en/Reference/Array>`_ +- `PROGMEM <http://arduino.cc/en/Reference/PROGMEM>`_ +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ + diff --git a/source/arduino/stringobject.rst b/source/arduino/stringobject.rst new file mode 100644 index 0000000..ffee295 --- /dev/null +++ b/source/arduino/stringobject.rst @@ -0,0 +1,88 @@ +.. _arduino-stringobject: + +String +====== + +Description +----------- + +The String class, part of the core as of version 0019, allows you +to use and manipulate strings of text in more complex ways than +`character arrays <http://arduino.cc/en/Reference/String>`_ do. You +can concatenate Strings, append to them, search for and replace +substrings, and more. It takes more memory than a simple character +array, but it is also more useful. + + + +For reference, character arrays are referred to as strings with a +small s, and instances of the String class are referred to as +Strings with a capital S. Note that constant strings, specified in +"double quotes" are treated as char arrays, not instances of the +String class. + + + +Functions +--------- + + +- `String <http://arduino.cc/en/Reference/StringConstructor>`_\ () +- `charAt <http://arduino.cc/en/Reference/StringCharAt>`_\ () +- `compareTo <http://arduino.cc/en/Reference/StringCompareTo>`_\ () +- `concat <http://arduino.cc/en/Reference/StringConcat>`_\ () +- `endsWith <http://arduino.cc/en/Reference/StringEndsWith>`_\ () +- `equals <http://arduino.cc/en/Reference/StringEquals>`_\ () +- `equalsIgnoreCase <http://arduino.cc/en/Reference/StringEqualsIgnoreCase>`_\ () +- `getBytes <http://arduino.cc/en/Reference/StringGetBytes>`_\ () +- `indexOf <http://arduino.cc/en/Reference/StringIndexOf>`_\ () +- `lastIndexOf <http://arduino.cc/en/Reference/StringLastIndexOf>`_\ () +- `length <http://arduino.cc/en/Reference/StringLength>`_\ () +- `replace <http://arduino.cc/en/Reference/StringReplace>`_\ () +- `setCharAt <http://arduino.cc/en/Reference/StringSetCharAt>`_\ () +- `startsWith <http://arduino.cc/en/Reference/StringStartsWith>`_\ () +- `substring <http://arduino.cc/en/Reference/StringSubstring>`_\ () +- `toCharArray <http://arduino.cc/en/Reference/StringToCharArray>`_\ () +- `toLowerCase <http://arduino.cc/en/Reference/StringToLowerCase>`_\ () +- `toUpperCase <http://arduino.cc/en/Reference/StringToUpperCase>`_\ () +- `trim <http://arduino.cc/en/Reference/StringTrim>`_\ () + + + +Operators +--------- + + +- `[] (element access) <http://arduino.cc/en/Reference/StringBrackets>`_ +- `+ (concatenation) <http://arduino.cc/en/Reference/StringPlus>`_ +- `== (comparison) <http://arduino.cc/en/Reference/StringComparison>`_ + + + +Examples +-------- + + +- `StringConstructors <http://arduino.cc/en/Tutorial/StringConstructors>`_ +- `StringAdditionOperator <http://arduino.cc/en/Tutorial/StringAdditionOperator>`_ +- `StringIndexOf <http://arduino.cc/en/Tutorial/StringIndexOf>`_ +- `StringAppendOperator <http://arduino.cc/en/Tutorial/StringAppendOperator>`_ +- `StringLengthTrim <http://arduino.cc/en/Tutorial/StringLengthTrim>`_ +- `StringCaseChanges <http://arduino.cc/en/Tutorial/StringCaseChanges>`_ +- `StringReplace <http://arduino.cc/en/Tutorial/StringReplace>`_ +- `StringCharacters <http://arduino.cc/en/Tutorial/StringCharacters>`_ +- `StringStartsWithEndsWith <http://arduino.cc/en/Tutorial/StringStartsWithEndsWith>`_ +- `StringComparisonOperators <http://arduino.cc/en/Tutorial/StringComparisonOperators>`_ +- `StringSubstring <http://arduino.cc/en/Tutorial/StringSubstring>`_ + + + +See Also +-------- + + +- `string <http://arduino.cc/en/Reference/String>`_: character + arrays +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ + + diff --git a/source/arduino/switchcase.rst b/source/arduino/switchcase.rst new file mode 100644 index 0000000..28791eb --- /dev/null +++ b/source/arduino/switchcase.rst @@ -0,0 +1,77 @@ +.. _arduino-switchcase: + +switch / case statements +======================== + +Like **if** statements, **switch...case** controls the flow of +programs by allowing programmers to specify different code that +should be executed in various conditions. In particular, a switch +statement compares the value of a variable to the values specified +in case statements. When a case statement is found whose value +matches that of the variable, the code in that case statement is +run. + + + +The **break** keyword exits the switch statement, and is typically +used at the end of each case. Without a break statement, the switch +statement will continue executing the following expressions +("falling-through") until a break, or the end of the switch +statement is reached. + + + +Example +~~~~~~~ + +:: + + switch (var) { + case 1: + //do something when var equals 1 + break; + case 2: + //do something when var equals 2 + break; + default: + // if nothing else matches, do the default + // default is optional + } + + + +Syntax +~~~~~~ + +:: + + switch (var) { + case label: + // statements + break; + case label: + // statements + break; + default: + // statements + } + + + +Parameters +~~~~~~~~~~ + +var: the variable whose value to compare to the various cases + + + +label: a value to compare the variable to + + + +See also: +--------- + +`if...else <http://arduino.cc/en/Reference/Else>`_ + + diff --git a/source/arduino/tan.rst b/source/arduino/tan.rst new file mode 100644 index 0000000..f31b357 --- /dev/null +++ b/source/arduino/tan.rst @@ -0,0 +1,35 @@ +.. _arduino-tan: + +tan(rad) +======== + +Description +----------- + +Calculates the tangent of an angle (in radians). The result will be +between negative infinity and infinity. + + + +Parameters +---------- + +rad: the angle in radians (*float*) + + + +Returns +------- + +The tangent of the angle (*double*) + + + +See also +-------- + + +- `sin <http://arduino.cc/en/Reference/Sin>`_\ () +- `cos <http://arduino.cc/en/Reference/Cos>`_\ () +- `float <http://arduino.cc/en/Reference/Float>`_ +- `double <http://arduino.cc/en/Reference/Double>`_ diff --git a/source/arduino/tone.rst b/source/arduino/tone.rst new file mode 100644 index 0000000..c7b1e44 --- /dev/null +++ b/source/arduino/tone.rst @@ -0,0 +1,78 @@ +.. _arduino-tone: + +tone() +====== + +Description +----------- + +Generates a square wave of the specified frequency (and 50% duty +cycle) on a pin. A duration can be specified, otherwise the wave +continues until a call to +`noTone <http://arduino.cc/en/Reference/NoTone>`_\ (). The pin can be +connected to a piezo buzzer or other speaker to play tones. + + + +Only one tone can be generated at a time. If a tone is already +playing on a different pin, the call to tone() will have no effect. +If the tone is playing on the same pin, the call will set its +frequency. + + + +Use of the tone() function will interfere with PWM output on pins 3 +and 11 (on boards other than the Mega). + + + +**NOTE:** if you want to play different pitches on multiple pins, +you need to call noTone() on one pin before calling tone() on the +next pin. + + + +Syntax +------ + +tone(pin, frequency) +tone(pin, frequency, duration) + + + +Parameters +---------- + +pin: the pin on which to generate the tone + + + +frequency: the frequency of the tone in hertz + + + +duration: the duration of the tone in milliseconds (optional) + + + +Returns +------- + +nothing + + + +See also +-------- + + +- `noTone <http://arduino.cc/en/Reference/NoTone>`_\ () +- `analogWrite <http://arduino.cc/en/Reference/AnalogWrite>`_\ () +- `Tutorial:Tone <http://arduino.cc/en/Tutorial/Tone>`_ +- `Tutorial:Pitch follower <http://arduino.cc/en/Tutorial/Tone2>`_ +- `Tutorial:Simple Keyboard <http://arduino.cc/en/Tutorial/Tone3>`_ +- `Tutorial: multiple tones <http://arduino.cc/en/Tutorial/Tone4>`_ + + +- `Tutorial: PWM <http://arduino.cc/en/Tutorial/PWM>`_ + diff --git a/source/arduino/unsignedchar.rst b/source/arduino/unsignedchar.rst new file mode 100644 index 0000000..f846105 --- /dev/null +++ b/source/arduino/unsignedchar.rst @@ -0,0 +1,41 @@ +.. _arduino-unsignedchar: + +unsigned char +============= + +Description +----------- + +An unsigned data type that occupies 1 byte of memory. Same as the +`byte <http://arduino.cc/en/Reference/Byte>`_ datatype. + + + +The unsigned char datatype encodes numbers from 0 to 255. + + + +For consistency of Arduino programming style, the *byte* data type +is to be preferred. + + + +Example +------- + +:: + + unsigned char myChar = 240; + + + +See also +-------- + + +- `byte <http://arduino.cc/en/Reference/Byte>`_ +- `int <http://arduino.cc/en/Reference/Int>`_ +- `array <http://arduino.cc/en/Reference/Array>`_ +- `Serial.println <http://arduino.cc/en/Serial/Println>`_ + + diff --git a/source/arduino/unsignedint.rst b/source/arduino/unsignedint.rst new file mode 100644 index 0000000..10835fe --- /dev/null +++ b/source/arduino/unsignedint.rst @@ -0,0 +1,77 @@ +.. _arduino-unsignedint: + +unsigned int +============ + +Description +----------- + +Unsigned ints (unsigned integers) are the same as ints in that they +store a 2 byte value. Instead of storing negative numbers however +they only store positive values, yielding a useful range of 0 to +65,535 (2^16) - 1). + + + +The difference between unsigned ints and (signed) ints, lies in the +way the highest bit, sometimes refered to as the "sign" bit, is +interpreted. In the Arduino int type (which is signed), if the high +bit is a "1", the number is interpreted as a negative number, and +the other 15 bits are interpreted with +`2's complement math. <http://en.wikipedia.org/wiki/2's_complement>`_ + + + +Example +------- + +:: + + unsigned int ledPin = 13; + + + +Syntax +------ + +:: + + unsigned int var = val; + + + + +- var - your unsigned int variable name +- val - the value you assign to that variable + + + +Coding Tip +---------- + +When variables are made to exceed their maximum capacity they "roll +over" back to their minimum capacitiy, note that this happens in +both directions + + + +:: + + unsigned int x + x = 0; + x = x - 1; // x now contains 65535 - rolls over in neg direction + x = x + 1; // x now contains 0 - rolls over + + + +See Also +-------- + + +- `byte <http://arduino.cc/en/Reference/Byte>`_ +- `int <http://arduino.cc/en/Reference/Int>`_ +- `long <http://arduino.cc/en/Reference/Long>`_ +- `unsigned long <http://arduino.cc/en/Reference/UnsignedLong>`_ +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ + + diff --git a/source/arduino/unsignedlong.rst b/source/arduino/unsignedlong.rst new file mode 100644 index 0000000..1bdb434 --- /dev/null +++ b/source/arduino/unsignedlong.rst @@ -0,0 +1,63 @@ +.. _arduino-unsignedlong: + +unsigned long +============= + +Description +----------- + +Unsigned long variables are extended size variables for number +storage, and store 32 bits (4 bytes). Unlike standard longs +unsigned longs won't store negative numbers, making their range +from 0 to 4,294,967,295 (2^32 - 1). + + + +Example +------- + +:: + + unsigned long time; + + void setup() + { + Serial.begin(9600); + } + + void loop() + { + Serial.print("Time: "); + time = millis(); + //prints time since program started + Serial.println(time); + // wait a second so as not to send massive amounts of data + delay(1000); + } + +Syntax +------ + +:: + + unsigned long var = val; + + + + +- var - your long variable name +- val - the value you assign to that variable + + + +See Also +-------- + + +- `byte <http://arduino.cc/en/Reference/Byte>`_ +- `int <http://arduino.cc/en/Reference/Int>`_ +- `unsigned int <http://arduino.cc/en/Reference/UnsignedInt>`_ +- `long <http://arduino.cc/en/Reference/Long>`_ +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ + + diff --git a/source/arduino/void.rst b/source/arduino/void.rst new file mode 100644 index 0000000..00166b6 --- /dev/null +++ b/source/arduino/void.rst @@ -0,0 +1,37 @@ +.. _arduino-void: + +void +==== + +The void keyword is used only in function declarations. It +indicates that the function is expected to return no information to +the function from which it was called. + + + +Example: +-------- + +:: + + // actions are performed in the functions "setup" and "loop" + // but no information is reported to the larger program + + void setup() + { + // ... + } + + void loop() + { + // ... + } + + + + +See also +-------- + +`function declaration <http://arduino.cc/en/Reference/FunctionDeclaration>`_ + diff --git a/source/arduino/volatile.rst b/source/arduino/volatile.rst new file mode 100644 index 0000000..4212ac5 --- /dev/null +++ b/source/arduino/volatile.rst @@ -0,0 +1,70 @@ +.. _arduino-volatile: + +volatile keyword +================ + +volatile is a keyword known as a variable *qualifier*, it is +usually used before the datatype of a variable, to modify the way +in which the compiler and subsequent program treats the variable. + + + +Declaring a variable volatile is a directive to the compiler. The +compiler is software which translates your C/C++ code into the +machine code, which are the real instructions for the Atmega chip +in the Arduino. + + + +Specifically, it directs the compiler to load the variable from RAM +and not from a storage register, which is a temporary memory +location where program variables are stored and manipulated. Under +certain conditions, the value for a variable stored in registers +can be inaccurate. + + + +A variable should be declared volatile whenever its value can be +changed by something beyond the control of the code section in +which it appears, such as a concurrently executing thread. In the +Arduino, the only place that this is likely to occur is in sections +of code associated with interrupts, called an interrupt service +routine. + + + +Example +------- + +:: + + // toggles LED when interrupt pin changes state + + int pin = 13; + volatile int state = LOW; + + void setup() + { + pinMode(pin, OUTPUT); + attachInterrupt(0, blink, CHANGE); + } + + void loop() + { + digitalWrite(pin, state); + } + + void blink() + { + state = !state; + } + + + +See also +-------- + + +- `AttachInterrupt <http://arduino.cc/en/Reference/AttachInterrupt>`_ + + diff --git a/source/arduino/while.rst b/source/arduino/while.rst new file mode 100644 index 0000000..5155f09 --- /dev/null +++ b/source/arduino/while.rst @@ -0,0 +1,46 @@ +.. _arduino-while: + +while loops +=========== + +Description +----------- + +**while** loops will loop continuously, and infinitely, until the +expression inside the parenthesis, () becomes false. Something must +change the tested variable, or the **while** loop will never exit. +This could be in your code, such as an incremented variable, or an +external condition, such as testing a sensor. + + + +Syntax +------ + +:: + + while(expression){ + // statement(s) + } + + + +Parameters +---------- + +expression - a (boolean) C statement that evaluates to true or +false + + + +Example +------- + +:: + + var = 0; + while(var < 200){ + // do something repetitive 200 times + var++; + } + diff --git a/source/arduino/word.rst b/source/arduino/word.rst new file mode 100644 index 0000000..39b3a0d --- /dev/null +++ b/source/arduino/word.rst @@ -0,0 +1,29 @@ +.. _arduino-word: + +word +==== + +Description +----------- + +A word stores a 16-bit unsigned number, from 0 to 65535. Same as an +unsigned int. + + + +Example +------- + +:: + + word w = 10000; + + + +See also +-------- + + +- `byte <http://arduino.cc/en/Reference/Byte>`_ +- `word <http://arduino.cc/en/Reference/WordCast>`_\ () + diff --git a/source/arduino/wordcast.rst b/source/arduino/wordcast.rst new file mode 100644 index 0000000..5ef821c --- /dev/null +++ b/source/arduino/wordcast.rst @@ -0,0 +1,51 @@ +.. _arduino-wordcast: + +word() +====== + +Description +----------- + +Convert a value to the +`word <http://arduino.cc/en/Reference/Word>`_ data type or create a +word from two bytes. + + + +Syntax +------ + +word(x) +word(h, l) + + + +Parameters +---------- + +x: a value of any type + + + +h: the high-order (leftmost) byte of the word + + + +l: the low-order (rightmost) byte of the word + + + +Returns +------- + +word + + + +See also +-------- + + +- `word <http://arduino.cc/en/Reference/Word>`_ + + diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst new file mode 100644 index 0000000..21379db --- /dev/null +++ b/source/arm-gcc.rst @@ -0,0 +1,13 @@ + +.. _arm-gcc: +.. _arm-gcc-attribute-flash: + +============ + GCC on ARM +============ + +Stub. + +Include special things, differences with AVR-GCC, using +``__attribute__`` to stick things in flash, etc. + diff --git a/source/conf.py b/source/conf.py index 26147fd..e1aa3a4 100644 --- a/source/conf.py +++ b/source/conf.py @@ -14,6 +14,7 @@ import sys, os + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. diff --git a/source/epilog.rst b/source/epilog.rst index 7805362..73aab6d 100644 --- a/source/epilog.rst +++ b/source/epilog.rst @@ -2,11 +2,19 @@ .. it's useful for common references, etc. .. Common URL references + .. _forum: http://forums.leaflabs.com .. _contact: http://leaflabs.com/contact/ +.. _stm32-all: http://www.st.com/mcu/devicedocs-STM32F103RB-110.html +.. _stm32-programming: http://www.st.com/stonline/products/literature/pm/15491.pdf +.. _stm32-adc-modes: http://www.st.com/stonline/products/literature/an/16840.pdf +.. _stm32-adc-oversampling: http://www.st.com/stonline/products/literature/an/14183.pdf +.. _full-manual: http://www.st.com/stonline/products/literature/rm/13902.pdf +.. _datasheet: http://www.st.com/stonline/products/literature/ds/13587.pdf .. Arduino built-in functions + .. _setup(): http://arduino.cc/en/Reference/Setup .. _loop(): http://arduino.cc/en/Reference/Loop diff --git a/source/foo.rst b/source/foo.rst new file mode 100644 index 0000000..d2ac4c6 --- /dev/null +++ b/source/foo.rst @@ -0,0 +1,114 @@ +.. _foo: + +================================== +[temporary] Converted Arduino docs +================================== + +This is the index of the imported Arduino docs. + +.. toctree:: + :maxdepth: 2 + + abs() <arduino/abs> + analogRead() <arduino/analogread> + pinMode() <arduino/pinmode> + Arithmetic <arduino/arithmetic> + Arrays <arduino/array> + Assignment <arduino/assignment> + +.. attachinterrupt <arduino-attachinterrupt> +.. bit <arduino-bit> +.. bitclear <arduino-bitclear> +.. bitread <arduino-bitread> +.. bitset <arduino-bitset> +.. bitshift <arduino-bitshift> +.. bitwiseand <arduino-bitwiseand> +.. bitwisecompound <arduino-bitwisecompound> +.. bitwisexornot <arduino-bitwisexornot> +.. bitwrite <arduino-bitwrite> +.. boolean <arduino-boolean> +.. booleanvariables <arduino-booleanvariables> +.. braces <arduino-braces> +.. break <arduino-break> +.. byte <arduino-byte> +.. bytecast <arduino-bytecast> +.. changes <arduino-changes> +.. char <arduino-char> +.. charcast <arduino-charcast> +.. comments <arduino-comments> +.. comparison <arduino-comparison> +.. const <arduino-const> +.. constants <arduino-constants> +.. constrain <arduino-constrain> +.. continue <arduino-continue> +.. cos <arduino-cos> +.. define <arduino-define> +.. delay <arduino-delay> +.. delaymicroseconds <arduino-delaymicroseconds> +.. detachinterrupt <arduino-detachinterrupt> +.. digitalread <arduino-digitalread> +.. digitalwrite <arduino-digitalwrite> +.. double <arduino-double> +.. dowhile <arduino-dowhile> +.. else <arduino-else> +.. float <arduino-float> +.. floatcast <arduino-floatcast> +.. for <arduino-for> +.. fpconstants <arduino-fpconstants> +.. goto <arduino-goto> +.. highbyte <arduino-highbyte> +.. homepage <arduino-homepage> +.. if <arduino-if> +.. include <arduino-include> +.. increment <arduino-increment> +.. incrementcompound <arduino-incrementcompound> +.. int <arduino-int> +.. intcast <arduino-intcast> +.. integerconstants <arduino-integerconstants> +.. interrupts <arduino-interrupts> +.. libraries <arduino-libraries> +.. long <arduino-long> +.. longcast <arduino-longcast> +.. loop <arduino-loop> +.. lowbyte <arduino-lowbyte> +.. map <arduino-map> +.. max <arduino-max> +.. micros <arduino-micros> +.. millis <arduino-millis> +.. min <arduino-min> +.. modulo <arduino-modulo> +.. nointerrupts <arduino-nointerrupts> +.. notone <arduino-notone> +.. pointer <arduino-pointer> +.. pow <arduino-pow> +.. pulsein <arduino-pulsein> +.. random <arduino-random> +.. randomseed <arduino-randomseed> +.. return <arduino-return> +.. scope <arduino-scope> +.. semicolon <arduino-semicolon> +.. serial <arduino-serial> +.. setup <arduino-setup> +.. shiftout <arduino-shiftout> +.. sin <arduino-sin> +.. sizeof <arduino-sizeof> +.. sqrt <arduino-sqrt> +.. static <arduino-static> +.. string <arduino-string> +.. stringobject <arduino-stringobject> +.. switchcase <arduino-switchcase> +.. tan <arduino-tan> +.. tone <arduino-tone> +.. unsignedchar <arduino-unsignedchar> +.. unsignedint <arduino-unsignedint> +.. unsignedlong <arduino-unsignedlong> +.. void <arduino-void> +.. volatile <arduino-volatile> +.. while <arduino-while> +.. word <arduino-word> +.. wordcast <arduino-wordcast> + +.. TODO later + +.. analogreference() <arduino/analogreference> +.. analogWrite() <arduino/analogwrite> diff --git a/source/gpio.rst b/source/gpio.rst index 9104fed..bd562a7 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -80,77 +80,18 @@ above). GPIO Modes ---------- -``OUTPUT`` - - Basic digital output: when the pin set high the voltage is held at - +3.3V (|vcc|) and when set low it is pulled down to ground. - -``OUTPUT_OPEN_DRAIN`` - - In open drain mode, the pin indicates "low" by accepting current - flow to ground and "high" by providing increased impedance. An - example use would be to connect a pin to a bus line (which is - pulled up to a positive voltage by a separate supply through a - large resistor). When the pin is high, not much current flows - through to ground and the line stays at positive voltage; when the - pin is low the bus "drains" to ground with a small amount of - current constantly flowing through the large resistor from the - external supply. In this mode no current is ever actually - *sourced* from the pin. - -``INPUT`` (or ``INPUT_FLOATING``) - - Basic digital input. The pin voltage is sampled; when it is closer - to 3.3V (|vcc|) the pin status is high, and when it is closer to - 0V (ground) it is low. If no external circuit is pulling the pin - voltage to high or low, it will tend to randomly oscillate and be - very sensitive to noise (e.g., a breath of air across the pin will - cause the state to flip). - -``INPUT_PULLUP`` - - The state of the pin in this mode is reported the same way as with - INPUT, but the pin voltage is gently "pulled up" towards - +3.3V. This means the state will be high unless an external device - is specifically pulling the pin down to ground, in which case the - "gentle" pull up will not effect the state of the input. - -``INPUT_PULLDOWN`` - - The state of the pin in this mode is reported the same way as with - INPUT, but the pin voltage is gently "pulled down" towards - 0V. This means the state will be low unless an external device is - specifically pulling the pin up to 3.3V, in which case the - "gentle" pull down will not effect the state of the input. - -``INPUT_ANALOG`` - - This is a special mode for when the pin will be used for analog - (not digital) reads. See the :ref:`ADC <adc>` page. - -``PWM`` - - This is a special mode for when the pin will be used for PWM - output (a special case of digital output). See the :ref:`PWM - <pwm>` page. - -.. TODO PWM_OPEN_DRAIN needs documentation +.. doxygenenum:: WiringMode Function Reference ------------------ -``pinMode(pin_number, MODE)`` - - Usually called from within `setup()`_ to configure the pin. MODE - is one of the set listed :ref:`above <gpio-modes>`. - -``digitalRead(pin_number)`` +.. doxygenfunction:: pinMode - Returns ``HIGH`` (|vcc|) or ``LOW`` (0V). +.. doxygenfunction:: digitalRead -``digitalWrite(pin_number, value)`` +.. doxygenfunction:: digitalWrite - Sets the pin to ``HIGH`` or ``LOW``. +.. doxygenfunction:: analogRead .. _gpio-recommended-reading: @@ -159,6 +100,6 @@ Recommended Reading STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) + * `All <stm32-all>`_ + * `Datasheet <datasheet>`_ (pdf) + * `Reference Manual <full-manual>`_ (pdf) diff --git a/source/i2c.rst b/source/i2c.rst index 564ca0e..764a342 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -80,13 +80,9 @@ Recommended Reading * `Arduino i2c/TWI reference <http://www.arduino.cc/playground/Learning/I2C>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet - <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ - (pdf) - * `Reference Manual - <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ - (pdf) + * `All <stm32-all>`_ + * `Datasheet <datasheet>`_ (pdf) + * `Reference Manual <full-manual>`_ (pdf) * `Application Note on Advanced I2C Usage <http://www.st.com/stonline/products/literature/an/15021.pdf>`_ (pdf) diff --git a/source/index.rst b/source/index.rst index e5af08f..3e72e85 100644 --- a/source/index.rst +++ b/source/index.rst @@ -27,11 +27,12 @@ Table of contents: Maple/Arduino Compatibility Reference <compatibility> Maple Language Reference <language> Maple Library Reference <libraries> - libmaple Documentation and APIs <libmaple> + libmaple Command-Line Tools and APIs <libmaple> Troubleshooting <troubleshooting> Hardware-Specific Documentation <hardware> Maple bootloader <bootloader> Known Problems <errata> + [Temporary] Arduino docs TOC <foo> Indices and tables ================== diff --git a/source/jtag.rst b/source/jtag.rst index 5301a18..4ef417d 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -66,6 +66,6 @@ Recommended Reading * `STM32/gdb/OpenOCD HOWTO <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet (pdf) <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ - * `Reference Manual (pdf) <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + * `All <stm32-all>`_ + * `Datasheet <datasheet>`_ (pdf) + * `Reference Manual <full-manual>`_ (pdf) diff --git a/source/language.rst b/source/language.rst index 36cb801..d3c7895 100644 --- a/source/language.rst +++ b/source/language.rst @@ -483,11 +483,8 @@ Recommended Reading * `newlib Documentation <http://sourceware.org/newlib/>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet (pdf) - <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ - * `Reference Manual (pdf) - <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ - * `Programming Manual (pdf) - <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ - (assembly language and register reference) + * `All documents <stm32-all>`_ + * `Datasheet <datasheet>`_ (pdf) + * `Reference Manual <full-manual>`_ (pdf) + * `Programming Manual <stm32-programming>`_ (assembly language and + register reference) diff --git a/source/pwm.rst b/source/pwm.rst index 8d3a8d9..0f77781 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -159,6 +159,6 @@ Recommended Reading * `So You Want To Use PWM, Eh? <http://www.arcfn.com/2009/07/secrets-of-arduino-pwm.html>`_ at Non-Lexical Vocables * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet (pdf) <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ - * `Reference Manual (pdf) <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + * `All <stm32-all>`_ + * `Datasheet <datasheet>`_ (pdf) + * `Reference Manual <full-manual>`_ (pdf) diff --git a/source/spi.rst b/source/spi.rst index 3c29b79..91c165a 100644 --- a/source/spi.rst +++ b/source/spi.rst @@ -63,9 +63,7 @@ Recommended Reading * `Hardcore SPI on Arduino <http://klk64.com/arduino-spi/>`_ by kik64 * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet (pdf) - <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ - * `Reference Manual (pdf) - <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + * `All <stm32-all>`_ + * `Datasheet <datasheet>`_ (pdf) + * `Reference Manual <full-manual>`_ (pdf) diff --git a/source/usart.rst b/source/usart.rst index 19b054f..d6343e6 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -94,6 +94,6 @@ Recommended Reading * `Arduino reference on Serial <http://arduino.cc/en/Reference/Serial>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) + * `All <stm32-all>`_ + * `Datasheet <datasheet>`_ (pdf) + * `Reference Manual <full-manual>`_ (pdf) diff --git a/source/usb.rst b/source/usb.rst index 1ce91f0..93d476e 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -185,7 +185,8 @@ Recommended Reading * Linux Kernel documentation for `USB ACM <http://www.kernel.org/doc/Documentation/usb/acm.txt>`_ and `USB Serial <http://www.kernel.org/doc/Documentation/usb/usb-serial.txt>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) - * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (pdf; assembly language and register reference) + * `All documents <stm32-all>`_ + * `Datasheet <datasheet>`_ (pdf) + * `Reference Manual <full-manual>`_ (pdf) + * `Programming Manual <stm32-programming>`_ (pdf; assembly + language and register reference) |