From 19e8336afbc827378216aca2b1af45ef89a108ab Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 21 Nov 2010 01:40:37 -0500 Subject: updated serial bootloader spec; other improvements --- docs/source/arduino/arithmetic.rst | 4 +- docs/source/arduino/bitwisemath.rst | 4 +- docs/source/arduino/boolean.rst | 8 +- docs/source/arduino/braces.rst | 8 +- docs/source/arduino/break.rst | 8 +- docs/source/arduino/bytecast.rst | 14 +- docs/source/arduino/comments.rst | 10 +- docs/source/arduino/const.rst | 10 +- docs/source/arduino/constants.rst | 24 +- docs/source/arduino/continue.rst | 18 +- docs/source/arduino/delaymicroseconds.rst | 12 +- docs/source/arduino/floatcast.rst | 12 +- docs/source/arduino/goto.rst | 4 +- docs/source/arduino/highbyte.rst | 8 +- docs/source/arduino/millis.rst | 4 +- docs/source/arduino/setup.rst | 8 +- docs/source/arduino/sizeof.rst | 45 ++- docs/source/arduino/static.rst | 6 +- docs/source/arduino/switchcase.rst | 96 ++++-- docs/source/arduino/unsignedchar.rst | 2 +- docs/source/arduino/variables.rst | 16 +- docs/source/arduino/void.rst | 8 +- docs/source/arduino/volatile.rst | 10 +- docs/source/bootloader.rst | 400 +++++++++++++++---------- docs/source/external-interrupts.rst | 2 +- docs/source/foo.rst | 3 +- docs/source/index.rst | 20 +- docs/source/language.rst | 469 +++++++++++++----------------- docs/source/unix-toolchain.rst | 42 ++- docs/source/wirish.rst | 1 + docs/source/wirish/pwmwrite.rst | 13 +- 31 files changed, 675 insertions(+), 614 deletions(-) diff --git a/docs/source/arduino/arithmetic.rst b/docs/source/arduino/arithmetic.rst index 412a0be..69cf166 100644 --- a/docs/source/arduino/arithmetic.rst +++ b/docs/source/arduino/arithmetic.rst @@ -14,7 +14,7 @@ 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. +since 9 and 4 are :ref:`int variables `. 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 @@ -126,4 +126,4 @@ See Also - :ref:`sizeof `\ () -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/bitwisemath.rst b/docs/source/arduino/bitwisemath.rst index 196cc2c..40c3d7a 100644 --- a/docs/source/arduino/bitwisemath.rst +++ b/docs/source/arduino/bitwisemath.rst @@ -120,7 +120,7 @@ program to blink digital pin 13 (the LED pin on Maple):: void setup(){ pinMode(led_pin, OUTPUT); } - + void loop(){ toggle = toggle ^ 1; digitalWrite(led_pin, toggle); @@ -183,4 +183,4 @@ See Also ``|=``, ``^=``). -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/boolean.rst b/docs/source/arduino/boolean.rst index 8106520..1d834d3 100644 --- a/docs/source/arduino/boolean.rst +++ b/docs/source/arduino/boolean.rst @@ -6,7 +6,8 @@ Boolean Operators ================= These can be used inside the condition of an :ref:`if ` -statement. +statement. Evaluate to :ref:`true ` or +:ref:`false `. .. contents:: Contents :local: @@ -45,6 +46,7 @@ True if either operand is true. For example:: is true if either ``x`` or ``y`` is greater than 0. +.. _arduino-boolean-not: ! (logical not) --------------- @@ -55,7 +57,7 @@ True if the operand is false. For example:: // ... } -is true if ``x`` is false (i.e. if ``x`` equals zero). +is true if ``x`` is false (i.e. if ``x`` is zero). Some Advice ----------- @@ -86,4 +88,4 @@ See Also - :ref:`if statement ` -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/braces.rst b/docs/source/arduino/braces.rst index 38018fe..04518b3 100644 --- a/docs/source/arduino/braces.rst +++ b/docs/source/arduino/braces.rst @@ -59,10 +59,10 @@ pages for more information):: while (boolean expression) { // code inside the loop goes here } - + for (initialisation; termination condition; incrementing expr) { // code inside the loop goes here - } + } do { // code inside the loop goes here @@ -80,7 +80,7 @@ reference page for more information):: } else if (boolean expression) { // code inside the "else if" - } + } else { // code inside the "else" } @@ -94,4 +94,4 @@ reference page for more information):: out. -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/break.rst b/docs/source/arduino/break.rst index 8c0478a..3e1e9ee 100644 --- a/docs/source/arduino/break.rst +++ b/docs/source/arduino/break.rst @@ -19,17 +19,17 @@ Example for (x = 0; x < 255; x ++) { digitalWrite(PWMpin, x); - sens = analogRead(sensorPin); + sens = analogRead(sensorPin); if (sens > threshold){ // bail out on sensor detect x = 0; // this line of code means that we'll immediately exit // from the "for" loop: break; - } + } delay(50); } - -.. include:: cc-attribution.txt \ No newline at end of file + +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/bytecast.rst b/docs/source/arduino/bytecast.rst index 38aec36..348c9fb 100644 --- a/docs/source/arduino/bytecast.rst +++ b/docs/source/arduino/bytecast.rst @@ -10,17 +10,17 @@ Description Converts a value to the :ref:`byte ` data type. -.. warning:: +.. note:: Casting to the byte type is provided for compatibility with - Arduino. However, ``byte`` is a non-standard type. The standard - C++ type for storing an 8-bit unsigned integer is ``unsigned - char``, and we recommend using that instead. + Arduino. However, the recommended Maple type for storing an 8-bit + unsigned integer is ``uint8``. (C and C++ programmers: ``stdint.h`` + is also available). - In order to cast a variable ``x`` to an ``unsigned char``, the + In order to cast a variable ``x`` to a ``uint8``, the following syntax can be used:: - (unsigned char)(x); + uint8(x); Syntax ------ @@ -50,4 +50,4 @@ See Also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/comments.rst b/docs/source/arduino/comments.rst index e46fc48..b50aa0f 100644 --- a/docs/source/arduino/comments.rst +++ b/docs/source/arduino/comments.rst @@ -14,19 +14,23 @@ One use for comments is to help you understand (or remember) how your program works, or to inform others how your program works. There are two different ways of making comments. +.. _arduino-comments-singleline: + **Single line comment**: Anything following two slashes, ``//``, until the end of the line, is a comment:: x = 5; // the rest of this line is a comment +.. _arduino-comments-multiline: + **Multi-line comment**: Anything in between a pair of ``/*`` and ``*/`` is a comment:: - + /* <-- a slash-star begins a multi-line comment all of this in the multi-line comment - you can use it to comment out whole blocks of code - + if (gwb == 0){ // single line comment is OK inside a multi-line comment x = 3; } @@ -60,4 +64,4 @@ is cryptic or unhelpful. -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/const.rst b/docs/source/arduino/const.rst index eb2b07b..b008144 100644 --- a/docs/source/arduino/const.rst +++ b/docs/source/arduino/const.rst @@ -26,13 +26,13 @@ Example // this defines a variable called "pi", which cannot be changed: const float pi = 3.14; float x; - + // .... - + x = pi * 2; // it's fine to find the value of a const variable - + pi = 7; // illegal - you can't write to (modify) a constant - + **#define** or **const** ------------------------ @@ -49,4 +49,4 @@ See Also - :ref:`volatile ` -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/constants.rst b/docs/source/arduino/constants.rst index 3a819b3..e841c9b 100644 --- a/docs/source/arduino/constants.rst +++ b/docs/source/arduino/constants.rst @@ -103,7 +103,7 @@ 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. - +.. _arduino-constants-input: Pins Configured as Inputs ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -115,7 +115,7 @@ 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. - +.. _arduino-constants-output: Pins Configured as Outputs ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -132,7 +132,7 @@ of current provided by an Atmega pin is also not enough to power most relays or motors, and some interface circuitry will be required. -.. _arduino-fpconstants: +.. _arduino-constants-fp: Floating-Point Constants ------------------------ @@ -141,28 +141,26 @@ 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. +.. TODO explain that floating point literals are doubles +.. _arduino-constants-fp-f: -Examples: - +.. TODO f modifiers +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 - + constant + 10.0 10 2.34E5 2.34 * 10^5 234000 67e-12 67.0 * 10^-12 .000000000067 @@ -301,4 +299,4 @@ See also - `unsigned long `_ -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/continue.rst b/docs/source/arduino/continue.rst index 31af3a5..bda1c95 100644 --- a/docs/source/arduino/continue.rst +++ b/docs/source/arduino/continue.rst @@ -2,8 +2,9 @@ .. _arduino-continue: -continue -======== +========== + continue +========== The ``continue`` keyword skips the rest of the current iteration of a :ref:`while `\ , :ref:`for `\ , or @@ -13,22 +14,21 @@ iterations. Example -------- +======= :: - - for (x = 0; x < 255; x ++) - { - if (x > 40 && x < 120){ // create jump in values + + for (x = 0; x < 255; x ++) { + if (x > 40 && x < 120) { // create jump in values continue; // skips the next two lines and goes to the // beginning of the loop, with the next value of x } - + digitalWrite(PWMpin, x); delay(50); } -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/delaymicroseconds.rst b/docs/source/arduino/delaymicroseconds.rst index 10f3a1b..d1016f1 100644 --- a/docs/source/arduino/delaymicroseconds.rst +++ b/docs/source/arduino/delaymicroseconds.rst @@ -21,18 +21,18 @@ Example The following example configures pin number 8 to work as an output pin, and sends a train of pulses with a period of roughly 100 microseconds:: - + int outPin = 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 + delayMicroseconds(50); // pauses for 50 microseconds digitalWrite(outPin, LOW); // sets the pin off - delayMicroseconds(50); // pauses for 50 microseconds + delayMicroseconds(50); // pauses for 50 microseconds } @@ -62,4 +62,4 @@ See Also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/floatcast.rst b/docs/source/arduino/floatcast.rst index 6a2e799..a8d1113 100644 --- a/docs/source/arduino/floatcast.rst +++ b/docs/source/arduino/floatcast.rst @@ -9,13 +9,14 @@ Description ----------- Converts a value to the :ref:`float ` data type. Here -is an example:: +is an example (see the :ref:`constants reference +` for an explanation of the "2.0f"):: int x = 2; - float f = float(x); // f now holds "2.0", a floating point value + float f = float(x); // f now holds 2.0f, a float value The value ``x`` can be of any type. However, if ``x`` is not a number -(like an ``int`` or ``long``), you will get strange results. +(like an ``int``), you will get strange results. See the :ref:`float ` reference for details about the precision and limitations of ``float`` values on the Maple. @@ -24,6 +25,7 @@ See Also -------- - :ref:`float ` +- :ref:`double ` +- :ref:`double() ` - -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/goto.rst b/docs/source/arduino/goto.rst index e683c98..2901913 100644 --- a/docs/source/arduino/goto.rst +++ b/docs/source/arduino/goto.rst @@ -95,7 +95,7 @@ Here's an example:: if (analogRead(0) > 250) { goto bailout; } - // more statements ... + // more statements ... } // innermost loop ends here } @@ -127,4 +127,4 @@ See Also - Knuth, Donald. `Structured Programming with go to Statements `_ (PDF) -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/highbyte.rst b/docs/source/arduino/highbyte.rst index 74717c1..5b1c24e 100644 --- a/docs/source/arduino/highbyte.rst +++ b/docs/source/arduino/highbyte.rst @@ -6,9 +6,9 @@ highByte(x) .. warning:: This macro is provided for compatibility with Arduino only. It returns the second-least significant byte in an integral value. It makes sense to call this the "high" byte on a 16-bit - microcontroller like the Atmel chips on Arduinos, but it makes no - sense at all on a 32-bit microcontroller like the STM32s in the - Maple line. + ``int`` microcontroller like the Atmel chips on Arduinos, but it + makes no sense at all on a 32-bit microcontroller like the STM32s + in the Maple line. In short: we provide this so that existing Arduino code works as expected, but **strongly discourage its use** in new programs. @@ -50,4 +50,4 @@ See Also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/millis.rst b/docs/source/arduino/millis.rst index 12f5d8d..f52d396 100644 --- a/docs/source/arduino/millis.rst +++ b/docs/source/arduino/millis.rst @@ -32,7 +32,7 @@ Example :: unsigned long time; - + void setup(){ Serial.begin(9600); } @@ -67,4 +67,4 @@ See also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/setup.rst b/docs/source/arduino/setup.rst index 79c9527..9cc96d4 100644 --- a/docs/source/arduino/setup.rst +++ b/docs/source/arduino/setup.rst @@ -15,15 +15,15 @@ Example :: - + int buttonPin = 3; - + void setup() { Serial.begin(9600); pinMode(buttonPin, INPUT); } - + void loop() { // ... @@ -31,4 +31,4 @@ Example -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/sizeof.rst b/docs/source/arduino/sizeof.rst index 8513e9d..7c31809 100644 --- a/docs/source/arduino/sizeof.rst +++ b/docs/source/arduino/sizeof.rst @@ -5,28 +5,20 @@ sizeof() ======== -Syntax ------- +The ``sizeof`` operator on the Maple returns the number of bytes +needed to store a value of a given type\ [#fcharsize]_. This can be +an ordinary numeric type, like ``int``. It can be something more +complicated, like a ``struct`` or ``union``. If the argument to +``sizeof`` is an array, it returns the total number of bytes occupied +by the array. -:: +The general syntax looks like this:: sizeof(type) sizeof(var) - - -Description ------------ - -The ``sizeof`` operator returns the number of bytes needed to store a -value of a given type. This can be an ordinary numeric type, like -``int``. It can be something more complicated, like a ``struct`` or -``union``. If the argument to ``sizeof`` is an array, it returns the -total number of bytes occupied by the array. - - -Examplec --------- +Example +------- 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 @@ -51,15 +43,22 @@ changing the text phrase:: } -Note that ``sizeof`` returns the total number of bytes; this is equal -to the number of ``char``\ s only because the C++ standard guarantees -that ``sizeof(char) == 1``. So for larger variable types such as -``int``, the :ref:`for loop ` would look something like -this:: +Note that ``sizeof`` returns the total number of bytes. So for larger +variable types such as ``int``, the :ref:`for loop ` +would look something like this:: for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { // do something with myInts[i] } +.. rubric:: Footnotes + +.. [#fcharsize] Technically (and pedantically) speaking, ``sizeof`` + returns a multiple of the number of bits a ``char`` occupies in + memory. However, on the Maple (this goes for most C++ + implementations), a ``char`` occupies 8 bits = 1 byte. All the C++ + standard guarantees, however, is that a ``char`` occupies at + *least* 8 bits. + +.. include:: cc-attribution.txt -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/docs/source/arduino/static.rst b/docs/source/arduino/static.rst index 76bf949..01f3dbf 100644 --- a/docs/source/arduino/static.rst +++ b/docs/source/arduino/static.rst @@ -15,8 +15,8 @@ Variables declared as ``static`` will only be created and initialized the first time a function is called. .. note:: This is only one use of the ``static`` keyword in C++. It - has some other important uses that are outside the scope of this - documentation; consult a reliable C++ reference for details. + has some other important uses that are not documented here; consult + a reliable C++ reference for details. Example ------- @@ -54,4 +54,4 @@ it was declared ``static``. Thus, ``numSensorReadings`` is a count of the number of times that ``readSensors()`` has been called. -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/switchcase.rst b/docs/source/arduino/switchcase.rst index 2ca2793..9f66d0a 100644 --- a/docs/source/arduino/switchcase.rst +++ b/docs/source/arduino/switchcase.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-switchcase: switch / case statements @@ -7,10 +9,7 @@ Like :ref:`if/else ` blocks, A ``switch`` statement controls program flow by allowing you to specify different code that should be executed under various cases. -Syntax ------- - -:: +The general syntax looks like this:: switch (var) { case val1: @@ -28,6 +27,7 @@ Where ``var`` is a variable whose value to investigate, and the ``val1``, ``val2`` after each ``case`` are constant values that ``var`` might be. + Description ----------- @@ -36,46 +36,82 @@ 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``, the ``switch`` -statement will continue executing the following ``case`` expressions -("falling-through") until a ``break`` (or the end of the switch -statement) is reached. +Here's a more concrete example:: -Writing ``default:`` instead of a ``case`` statement allows you to -specify what to do if none of the ``case`` statements matches. Having -a ``default:`` is optional (you can leave it out), but if you have -one, it must appear after all of the ``case`` statements, as shown -above. + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + } + afterTheSwitch(); -``switch`` statements are often used with an ``enum`` value as the -variable to compare. In this case, you can write down all of the -values the ``enum`` takes as ``case`` statements, and be sure you've -covered all the possibilities. +In the above example, if ``var == 1``, then the code beginning on the +line after ``case 1:`` gets executed. That is, if ``var`` is one, +``doThing1()`` gets called first, and then the ``break`` statement +gets executed. + +The ``break`` keyword exits the ``switch`` statement, and is typically +used at the end of each ``case``. Since there is a ``break`` at the +end of ``case 1:``, the ``switch`` statement gets exited, and the next +line to be run is the one which calls ``afterTheSwitch()``. + +Without a ``break``, the ``switch`` statement will continue executing +the following ``case`` expressions ("falling-through") until a +``break`` (or the end of the switch statement) is reached. Let's +pretend the ``switch`` looked like this instead:: -Example -------- + switch (var) { + case 1: + doThing1(); + // no break statement anymore + case 2: + doThing2(); + break; + } + afterTheSwitch(); + +Now, if ``var`` is one, ``doThing1()`` gets executed like before. +However, without a ``break``, the code would continue to be executed +line-by-line, so ``doThing2()`` would be called next. At this point, +a ``break`` has been reached, so the program continues by calling +``afterTheSwitch()``. This is usually not what you want, which is why +each ``case`` usually has a ``break`` at the end. -:: +Writing "``default:``" instead of a ``case`` statement allows you to +specify what to do if none of the ``case`` statements matches. Having +a ``default`` is optional (you can leave it out), but if you have one, +it must appear after all of the ``case`` statements. Let's add a +``default`` to the ``switch`` we've been discussing:: switch (var) { case 1: - //do something when var equals 1 + doThing1(); break; case 2: - //do something when var equals 2 + doThing2(); break; default: - // if nothing else matches, do the default - // default is optional + doSomethingElse(); } + afterTheSwitch(); -See also: ---------- - -`if...else `_ +If ``var`` is one, then ``doThing1()`` gets called. If ``var`` is +two, ``doThing2()`` gets called. If ``var`` is anything else, +``doSomethingElse()`` gets called. As stated above, a ``default`` is +optional. If you're missing one and none of the ``case`` statements +match, the ``switch`` does nothing at all, as if it wasn't there. +``switch`` statements are often used with an ``enum`` value as the +variable to compare. In this case, you can write down all of the +values the ``enum`` takes as ``case`` statements, and be sure you've +covered all the possibilities. +See also: +--------- +- :ref:`if...else ` -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/unsignedchar.rst b/docs/source/arduino/unsignedchar.rst index 1fd7a1c..5c26d17 100644 --- a/docs/source/arduino/unsignedchar.rst +++ b/docs/source/arduino/unsignedchar.rst @@ -41,4 +41,4 @@ See also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/variables.rst b/docs/source/arduino/variables.rst index bedb86b..0720041 100644 --- a/docs/source/arduino/variables.rst +++ b/docs/source/arduino/variables.rst @@ -9,7 +9,7 @@ A variable is a way of naming and storing a value for later use by the program, such as data from a sensor or an intermediate value used in a calculation. - +.. _arduino-variables-declaring: Declaring Variables ^^^^^^^^^^^^^^^^^^^ @@ -34,7 +34,7 @@ store in choosing variable types. Variables will `roll over <#VariableRollover>`_ when the value stored exceeds the space assigned to store it. See below for an example. - +.. _arduino-variables-scope: Variable Scope ^^^^^^^^^^^^^^ @@ -45,7 +45,7 @@ influences how various functions in a program will *see* the variable. This is called variable `scope `_. - +.. _arduino-variables-initializing: Initializing Variables ^^^^^^^^^^^^^^^^^^^^^^ @@ -63,7 +63,7 @@ Example: int calibrationVal = 17; // declare calibrationVal and set initial value - +.. _arduino-variables-rollover: Variable Rollover ^^^^^^^^^^^^^^^^^ @@ -104,7 +104,7 @@ variable on the left side. :: inputVariable1 = 7; // sets the variable named inputVariable1 to 7 - inputVariable2 = analogRead(2); // sets the variable named inputVariable2 to the + inputVariable2 = analogRead(2); // sets the variable named inputVariable2 to the // (digitized) input voltage read from analog pin #2 @@ -117,7 +117,7 @@ Examples int lightSensVal; char currentLetter; unsigned long speedOfLight = 186000UL; - char errorMessage = {"choose another option"}; // see string + char errorMessage = {"choose another option"}; // see string @@ -135,7 +135,7 @@ inputVariable2 which is a minimum of 100: { inputVariable2 = 100; } - + delay(inputVariable2); @@ -188,4 +188,4 @@ Variable Scope -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/void.rst b/docs/source/arduino/void.rst index 1d3bf8e..82f9606 100644 --- a/docs/source/arduino/void.rst +++ b/docs/source/arduino/void.rst @@ -16,17 +16,17 @@ Example: // actions are performed in the functions "setup" and "loop" // but no information is reported to the larger program - + void setup() { // ... } - + void loop() { // ... } - + @@ -37,4 +37,4 @@ See also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/arduino/volatile.rst b/docs/source/arduino/volatile.rst index 9516db0..fc02081 100644 --- a/docs/source/arduino/volatile.rst +++ b/docs/source/arduino/volatile.rst @@ -39,21 +39,21 @@ 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; @@ -70,4 +70,4 @@ See also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst index 2cacb5a..4be8e93 100644 --- a/docs/source/bootloader.rst +++ b/docs/source/bootloader.rst @@ -4,7 +4,7 @@ Maple Bootloader(s) ===================== -.. TODO: [Stub] add a section on flashing your own bootloader +.. TODO: add a section on flashing your own bootloader The firmware which allows the Maple to be reprogrammed via a USB connection. Every Maple board comes programmed with this by default, @@ -20,43 +20,46 @@ Flash memory and only runs when the chip is reset). .. contents:: Contents :local: -Bootloader Schemes Explained! ------------------------------ - -Maple Rev 3 and Rev 5 (the version currently shipping) represents a -drastic remake of the core library as well as the upload process. Some -of these changes are aesthetic, refactoring and reorganization. Some -are performance minded. The changes to the bootloader, however, were -implemented to solve some really gritty cross platform issues. Before -delving in to how the Rev 1 bootloader worked and how the Rev 3 -bootloader works now, lets look at the features common to both of them -and touch a bit on the Arduino setup. This is a fairly involved -explanation, with a lot of details that are likely only interesting to -a few. If you just want to get the rough idea, skim this article. If -you want to start hacking on the bootloader, get in touch with us to -get even more info on how this all works. Of course, you can always -`check out the code at github `_! +Bootloader Schemes Explained +---------------------------- + +Maple Rev 3 and Rev 5 (Rev 5 is the version currently shipping) +represents a drastic remake of the core library as well as the upload +process. Thes changes to the bootloader, were implemented to resolve +platform-specific issues on Windows. Before delving into how the Rev +1 bootloader worked and how the Rev 5 bootloader works now, we'll +discuss the features common to each and touch a bit on the Arduino +setup. + +This is a fairly involved explanation, with a lot of details that are +likely only interesting to a few. If you just want to get the rough +idea, skim this article. If you want to start hacking on the +bootloader, get in touch with us to get even more info on how this all +works. And finally, you can always `check out the code at github +`_! Arduino ------- -Arduino is based off of AVR series micro controllers, most of which +Arduino is based off of AVR series microcontrollers, most of which lack USB support. Thus, boards like the Duemilanove add USB capability -via an FTDI USB to Serial converter chip. This chip interfaces with -the AVR over…serial. When you plug an Arduino into a computer, only an -FTDI driver is needed. Since the FTDI chip is separate from the AVR, -you can reset the Arduino without closing this USB connection with the -FTDI chip. To program an Arduino, the host machine sends a command -over the USB pipe (reset DTR) which in turn resets the AVR. The AVR -will boot into a bootloader, which waits for a second for any upload -commands over serial. The host machine can either send those commands, -or do nothing. In which case the AVR will quickly jump to user code +via an FTDI USB-to-Serial converter chip. This chip interfaces with +the AVR over an RS-232 serial interface. When you plug an Arduino into +a computer, only an FTDI driver is needed. Since the FTDI chip is +separate from the AVR, you can reset the Arduino without closing this +USB connection with the FTDI chip. + +To program an Arduino, the host machine sends a command over the USB +pipe (reset DTR) which in turn resets the AVR. The AVR will boot into +a bootloader, which waits for a second for any upload commands over +serial. The host machine can either send those commands, or do +nothing. If it does nothing, the AVR will quickly jump to user code and off you go. The whole process is quick, the bootloader doesn’t live for very long, and will exit almost immediately if no upload commands are received. -Maple Rev 1: The Horror... ---------------------------- +Maple Rev 1 +----------- Maple is based off the STM32 (ARM cortex M3) series chips, which do have embedded USB support. Thus, Maple doesn’t need the extra FTDI @@ -140,101 +143,132 @@ bringing up the USB serial. Maple Rev6 - The Serial Bootloader (Tentative) ---------------------------------------------- -The bootloader in Rev3/Rev5 works quite well in linux, it works OK in -Mac, but in windows we had a few major issues. First off, unlike the -other operating systems, Windows needed to be manually pointed to both -the driver to use for programming (DFU, via libusb) and the driver to -use for serial communication (usbser.sys, built in to windows). Maple -operates in only one of these modes at a time, installation has been -quite tricky, involving getting Maple into the right mode and then -installing the driver/inf file during the windows prompt. Furthermore, -because libusb is not bundled with Windows, and its driver is not -signed, users of Windows 7 have been forced to laboriously disable -driver signing checks. Finally, the constant switching of the device -between Serial and DFU modes (during programming) really confuses -windows, often reprompting users to install drivers that are alrady -installed or generally not working well. We have therefore decided to -simplify things greatly, by simply abandoning DFU. In this new -bootloader scheme, Maple is, simply, a serial device. Windows comes -bundled with usbser.sys, so no driver signing is required. The -installation process will be greatly simplified, there will be no more -siwtching back and forth between "modes" and we get the chance to -build in a lot of new functionality that were outside the DFU spec. +The bootloader in Rev3/Rev5 works well on Linux, acceptably on Mac, +but was unsatisfactory on Windows. Unlike the other operating systems, +Windows needed to be manually pointed to both the driver to use for +programming (DFU, via `libusb `_) and the +driver to use for serial communication (usbser.sys, built in to +Windows). Since Maple operates in only one of these modes at a time, +driver installation was unnecessarily complicated. It was necessary to +bring Maple into the correct mode before installing each of the +drivers. Furthermore, because libusb is not bundled with Windows, and +its driver is not signed, Windows 7 users have been forced to +laboriously disable driver signing checks. Finally, Windows hates the +constant switching of the device between Serial and DFU modes (during +programming), and often prompts users to install drivers that are +already installed. We have therefore decided to abandon DFU. + +In our new bootloader scheme, Maple is simply a serial device. +Windows comes bundled with usbser.sys, so no driver signing is +required. The IDE installation process is greatly simplified, there +is no more switching back and forth between "modes", and we can build +in new functionality outside the DFU spec. The first incarnation of this serial-only bootloader leaves libmaple and user code untouched. However, during programming, instead of -calling dfu-util to upload code we will now call a newly written -utility script similar to avr-dude used by arduino. The high level +calling :command:`dfu-util` to upload code we will now call a newly +written utility script similar to `avr-dude +`_. The high level operation of the bootloader will remain the same - come on at startup, -wait for an upload operation or timeout and jump to user code. The -second version of this bootloader will eliminate this dependence on -resetting and timing out by having the bootloader run in the -background all the time, and owning the serial port. In this scheme, +wait for an upload operation or timeout, and jump to user code. + +The second version of this bootloader will eliminate this dependence +on resetting and timing out by having the bootloader run in the +background. It will additionally own the serial port. In this scheme, sending data over the COM port while DTR is pulled low results in that packet being captured by the bootloader and interpreted as a bootloader command. When the user uploads a new program, the bootloader will overwrite the old one, reset the various peripheral -registers, and jump to user code. All of this will occur without every +registers, and jump to user code. All of this will occur without resetting the chip and thus causing Maple to connect and disconnect -from your computer (which seems to cause many problems). The finaly -version of this new bootloader scheme will actually involve a separate +from your computer (which seems to cause many problems). + +The final version of this bootloader scheme will involve a separate microcontroller, whose responsibilities are to drive the USB port, program the main processor, and offer some amount of debugging -capability. This will allow user sketches to run on the "bare metal" -of the main processor, without any bootloader hiding underneath your -programs. This approach is similar to the approaches taken by mBed and -the new Arduino UNO. +capability. This will allow user sketches to run on the bare metal of +the main processor, without any bootloader hiding underneath. This +approach is similar to the approaches taken by mbed and the Arduino +Uno. Regardless of which generation of the new serial bootloader you are working with, the command interface is the same. The low level communication protocol is inspired by STK-500, the protocol used to -program Arduino's and many other AVR based development boards. The -protocol is a packetized query-response scheme. The host PC initiates -every transaction, and for every query sent to the bootloader, a -single response will be returned (or the system times out). Data is +program many AVR-based development boards. The protocol is a +packetized query-response scheme. The host PC initiates every +transaction, and for every query sent to the bootloader, a single +response will be returned (or the system times out). Data is transmitted over 115.2kbps, 8 data bits, 1 stop bit, no parity bit. Every query or response follows the same packet format that looks like this: .. _bootloader-packet-structure: -The Packet -^^^^^^^^^^ -.. csv-table:: - :header: Field, length (Bytes), value, description +Packet Structure +^^^^^^^^^^^^^^^^ + +A bootloader packet is composed of a sequence of fields, as follows. + +.. list-table:: + :header-rows: 1 + + * - Field + - Length (bytes) + - Value + - Description - START, 2, 0x7EAF, A magic constant that indicates this is a - bootloader packet + * - START + - 2 + - 0x7EAF + - Magic constant, indicates bootloader packet - SEQUENCE_NUM, 1, 0-255, Every response must have the same sequence - number as its query + * - SEQUENCE_NUM + - 1 + - 0--255 + - Queries and responses must have the same sequence number; rolls + over to 0 after 255. - MESSAGE_SIZE, 2, 0-65535, Size of the message body\, currently - messages must be <= 512 Bytes + * - MESSAGE_SIZE + - 2 + - 0--65,535 + - Size of message body, currently limited to a 512B maximum - MESSAGE_BODY, 0-65535, DATA, Self explanatory + * - MESSAGE_BODY + - Variable, determined by MESSAGE_SIZE field + - Command query or response + - See next section - CHECKSUM, 4, VAL, The XOR of all bytes in the packet except the - checksum byte + * - CHECKSUM + - 4 + - XOR of all other bytes in packet + - .. _bootloader-commands: Commands ^^^^^^^^ -The packet structure is really just overhead. The actual queries and -responses are transacted inside of the message body. Again following -in the footsteps of STK-500, each query or response begins with the -single byte CMD field. For each query, the resultant response must -begin with the same CMD byte. For each type of CMD, the structure of -queries and responses are well formed and of fixed size. Like STK-500, -fields longer than 1 byte are transmitted MSB first (big -endian). However, READ and WRITE commands operate bytewise (not word -wise), it is up to the host PC to ensure that alignment and ordering -issues are taken care of when appropriate (Maple uses a little endian -processor, LSB first). - -.. list-table:: GET_INFO Query +The packet structure overhead is for reliability. The actual queries +and responses are transacted inside of the message body. Following in +the footsteps of the STK-500 protocol, each query or response begins +with the single byte CMD field. For each query, the resultant response +must begin with the same CMD byte. For each type of CMD, the structure +of queries and responses are of fixed size. As in STK-500, fields +longer than 1 byte are transmitted MSB first (big endian). However, +READ and WRITE commands operate byte-wise (not word-wise); it is up to +the host PC to ensure that alignment and ordering issues are handled +appropriately. + +.. _bootloader-get-info: + +GET_INFO +"""""""" + +Used to query device characteristics. + +GET_INFO Query: + +.. list-table:: :header-rows: 1 * - Field @@ -243,11 +277,13 @@ processor, LSB first). * - GET_INFO - 1 - - -\ + - Value 0 + +GET_INFO Response: -.. list-table:: GET_INFO Response +.. list-table:: :header-rows: 1 + :widths: 4 2 10 * - Field - Bytes @@ -255,19 +291,25 @@ processor, LSB first). * - GET_INFO - 1 - - + - Value 0 + + * - Endianness + - 1 + - 0 indicates little-endian, 1 indicates big-endian. + (Currently returns 0; this field allows for future + expansion). * - Available Ram - 4 - - + - In bytes * - Available Flash - 4 - - + - In bytes * - Flash Page Size - 2 - - + - In bytes * - Starting Address (FLASH) - 4 @@ -281,11 +323,18 @@ processor, LSB first). - 4 - Current version 0x00060000 (MAJ,MIN) -\ -\ +.. _bootloader-erase-page: -.. list-table:: ERASE_PAGE Query +ERASE_PAGE +"""""""""" + +Used to erase flash pages. + +ERASE_PAGE query: + +.. list-table:: :header-rows: 1 + :widths: 4 2 10 * - Field - Bytes @@ -293,16 +342,17 @@ processor, LSB first). * - ERASE_PAGE - 1 - - \ + - Value 1 * - ADDRESS - 4 - Will erase whichever page contains ADDRESS -\ +ERASE_PAGE response: -.. list-table:: ERASE_PAGE Response +.. list-table:: :header-rows: 1 + :widths: 3 2 10 * - Field - Bytes @@ -310,17 +360,22 @@ processor, LSB first). * - ERASE_PAGE - 1 - - - - * - SUCCESS? + - Value 1 + + * - SUCCESS - 1 - - Either 0 or 1, (FAILED and OK) + - Either 0 (failure) or 1 (success) + +WRITE_BYTES +""""""""""" -\ -\ +Used to write to RAM or flash. -.. list-table:: ERASE_PAGE Response +WRITE_BYTES query: + +.. list-table:: :header-rows: 1 + :widths: 4 4 10 * - Field - Bytes @@ -328,20 +383,22 @@ processor, LSB first). * - WRITE_BYTES - 1 - - + - Value 2 * - Starting Address - 4 - - Can only write to RAM or addresses on cleared FLASH pages! + - Can address arbitrary RAM, or :ref:`cleared + ` flash pages. * - DATA - - Message Size - 5 - - + - MESSAGE_SIZE - 5 + - See :ref:`Packet Structure ` -\ +WRITE_BYTES response: -.. list-table:: WRITE_BYTES Response +.. list-table:: :header-rows: 1 + :widths: 2 2 10 * - Field - Bytes @@ -349,38 +406,47 @@ processor, LSB first). * - WRITE_BYTES - 1 - - - - * - SUCCESS? + - Value 2 + + * - SUCCESS - 1 - - Either 0 or 1 (FAILED, OK). Will fail if writes were made to uncleared pages, does not clean up failed writes (memory in unknown state) + - Either 0 (failure) or 1 (success). Will fail if writes were + made to uncleared pages. Does not clean up failed writes + (memory will be left in an undefined state). -\ -\ +READ_BYTES +"""""""""" -.. list-table:: READ_BYTES Query +Used to read from RAM or flash. + +READ_BYTES query: + +.. list-table:: :header-rows: 1 + :widths: 2 2 10 * - Field - Bytes - Comments - + * - READ_BYTES - 1 - - - + - Value 3 + * - ADDRESS - 4 - - Start of block to read, must be a multiple of 4 (4 byte alignment) + - Start of block to read. Must be a multiple of 4. * - LENGTH - 2 - - Number of Bytes to Read (currently 512 byte max, must be a multiple of 4) + - Maximum number of bytes to read (currently, this may be at most + 512). Must be a multiple of 4. -\ +READ_BYTES response: -.. list-table:: READ_BYTES Response +.. list-table:: :header-rows: 1 + :widths: 2 2 10 * - Field - Bytes @@ -388,17 +454,26 @@ processor, LSB first). * - READ_BYTES - 1 - - + - Value 3 * - DATA - - Message Size - 1 - - Returns data, if this section is of length 0, this should be interpreted as a read failure + - MESSAGE_SIZE - 1 + - Contains read bytes. The actual number of bytes read may be + less than the LENGTH field of the corresponding READ_BYTES + query. If this section is of length 0, this should be + interpreted as a read failure. See + :ref:`bootloader-packet-structure`. + +JUMP_TO_USER +"""""""""""" + +Causes the bootloader to jump to user code's starting address. -\ -\ +JUMP_TO_USER query: -.. list-table:: JUMP_TO_USER Query +.. list-table:: :header-rows: 1 + :widths: 2 1 10 * - Field - Bytes @@ -406,12 +481,19 @@ processor, LSB first). * - JUMP_TO_USER - 1 - - + - Value 4 + + * - Location + - 1 + - 0 means jump to flash starting address, 1 means jump to RAM + starting address. See the :ref:`bootloader-get-info` command + for more information. -\ +JUMP_TO_USER response: -.. list-table:: JUMP_TO_USER Response +.. list-table:: :header-rows: 1 + :widths: 2 1 10 * - Field - Bytes @@ -419,17 +501,26 @@ processor, LSB first). * - JUMP_TO_USER - 1 - - + - Value 4 * - SUCCESS - 1 - - Either 0 or 1 (FAILED,OK). Will end this bootloader session and jump to user + - Either 0 (failure) or 1 (success). If successful, after the + response is sent, the bootloader ends this session and jumps to + the user code in flash or RAM as specified in the query's + Location field. + + +SOFT_RESET +"""""""""" -\ -\ - -.. list-table:: SOFT_RESET Query +Engages a full software reset. + +SOFT_RESET query: + +.. list-table:: :header-rows: 1 + :widths: 2 1 10 * - Field - Bytes @@ -437,12 +528,13 @@ processor, LSB first). * - SOFT_RESET - 1 - - Will engage a full software reset + - Value 5 -\ +SOFT_RESET response: -.. list-table:: SOFT_RESET Response +.. list-table:: :header-rows: 1 + :widths: 2 1 10 * - Field - Bytes @@ -450,11 +542,9 @@ processor, LSB first). * - SOFT_RESET - 1 - - Will engage a full software + - Value 5 * - SUCCESS - 1 - - Either 0 or 1 (FAILED,OK). Will end this bootloader session and reset the processor - -\ -\ + - Either 0 or 1 (FAILED and OK, respectively). Will end this + bootloader session and reset the processor. diff --git a/docs/source/external-interrupts.rst b/docs/source/external-interrupts.rst index bc9d6cd..39828e3 100644 --- a/docs/source/external-interrupts.rst +++ b/docs/source/external-interrupts.rst @@ -123,4 +123,4 @@ Recommended Reading * `All `_ * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/docs/source/foo.rst b/docs/source/foo.rst index 5631922..1da021c 100644 --- a/docs/source/foo.rst +++ b/docs/source/foo.rst @@ -46,6 +46,7 @@ Finished: arduino/detachinterrupt arduino/digitalread arduino/double + arduino/doublecast arduino/dowhile arduino/else arduino/float @@ -77,7 +78,7 @@ Finished: arduino/sq arduino/static arduino/string - + Unfinished; straightforward to convert: .. toctree:: diff --git a/docs/source/index.rst b/docs/source/index.rst index fdaf801..ac91c4f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,19 +15,19 @@ Table of contents: .. TODO: be more Pythonic with a "parts of the documentation" thing .. toctree:: - :maxdepth: 2 - - Maple Quickstart Guide - Maple IDE Installation Guide - Maple IDE Documentation - Maple/Arduino Compatibility Reference - Maple Language Reference - Maple Library Reference - libmaple Command-Line Tools and APIs + :maxdepth: 1 + + Quickstart Guide + IDE Installation Guide + IDE Documentation + Language Reference + Arduino Compatibility Reference + Library Reference + Command-Line Tools and APIs Troubleshooting Hardware-Specific Documentation External Interrupts - Maple bootloader + Bootloader Known Problems [Temporary] Arduino docs TOC [Temporary] Wirish-only docs TOC diff --git a/docs/source/language.rst b/docs/source/language.rst index b2ef017..bbdbf90 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -9,16 +9,6 @@ The Maple can be programmed in the `Wiring `_ language, which is the same language used to program the `Arduino `_ boards. -Please see the extensive `language reference -`_ on the Arduino webpage for -more information, or follow a direct link below. - -.. warning:: - - The Arduino boards have different sizes for data types, so don't - trust their documentation for how many bytes an ``int``, ``long``, - etc. take up. The sizes of each data type on the Maple are given - in the :ref:`table below `. C or C++ programmers curious about the differences between the Wiring language and C++ may wish to skip to the @@ -59,268 +49,207 @@ Unique Maple Additions .. _language-arduino-docs: -Arduino Documentation Links ---------------------------- - -(This table was copied from http://arduino.cc/en/Reference/Extended). - -+------------------------------------+------------------------------------+-----------------------------------------+ -| Structure | Variables | Functions | -| | | | -+====================================+====================================+=========================================+ -| |**Constants** |**Digital I/O** | -|* `setup()`_ | | | -| |* `HIGH`_ | `LOW`_ |* `pinMode()`_ | -|* `loop()`_ | | | -| |* `INPUT`_ | `OUTPUT`_ |* `digitalWrite()`_ | -| | | | -|**Control Structures** |* `true`_ | `false`_ |* `digitalRead()`_ | -| | | | -|* `if`_ |* `integer constants`_ | | -| | |**Analog I/O** | -|* `if...else`_ |* `floating point constants`_ | | -| | |* `analogReference()`_ | -|* `for`_ | | | -| |**Data Types** |* `analogRead()`_ | -|* `switch/case`_ | | | -| |Primitive data types on the Maple |* `analogWrite()`_ - PWM | -|* `while`_ |have different sizes than on the | | -| |Arduino, since the Maple has a full | | -|* `do...while`_ |32-bit processor. The size of each |**Advanced I/O** | -| |such type on the Maple is given | | -|* `break`_ |below. |* `tone()`_ | -| | | | -|* `continue`_ |The ``word`` type is (deliberately) |* `noTone()`_ | -| |:ref:`not supported | | -|* `return`_ |`. |* `shiftOut()`_ | -| | | | -|* `goto`_ |* `void`_ |* `pulseIn()`_ | -| | | | -| |* `boolean`_ (1 byte) | | -|**Further syntax** | |**Time** | -| |* `char`_ (1 byte) | | -|* `;`_ (semicolon) | |* `millis()`_ | -| |* `unsigned char`_ (1 byte) | | -|* `{}`_ (curly braces) | |* `micros()`_ | -| |* `byte`_ (1 byte) | | -|* `//`_ (single line comment) | |* `delay()`_ | -| |* `int`_ (4 bytes) | | -|* `/\* \*/`_ (multi-line comment) | |* `delayMicroseconds()`_ | -| |* `unsigned int`_ (4 bytes) | | -|* `#define`_ | | | -| |* `long`_ (8 bytes) |**Math** | -|* `#include`_ | | | -| |* `unsigned long`_ (8 bytes) |* `min()`_ | -| | | | -|**Arithmetic Operators** |* `float`_ (4 bytes) |* `max()`_ | -| | | | -|* `=`_ (assignment operator) |* `double`_ (8 bytes) |* `abs()`_ | -| | | | -|* `+`_ (addition) |* `string`_ |* `constrain()`_ | -| | | | -|* `-`_ (subtraction) |* `array`_ |* `map()`_ | -| | | | -|* `*`_ (multiplication) | |* `pow()`_ | -| |**Conversion** | | -|* `/`_ (division) | |* `sqrt()`_ | -| |* `char()`_ | | -|* `%`_ (modulo) | | | -| |* `byte()`_ |**Trigonometry** | -| | | | -|**Comparison Operators** |* `int()`_ |* `sin()`_ | -| | | | -|* `==`_ (equal to) |* `word()`_ |* `cos()`_ | -| | | | -|* `!=`_ (not equal to) |* `long()`_ |* `tan()`_ | -| | | | -|* `<`_ (less than) |* `float()`_ | | -| | |**Random Numbers** | -|* `>`_ (greater than) | | | -| |**Variable Scope & Qualifiers** |* `randomSeed()`_ | -|* `<=`_ (less than or equal to) | | | -| |* `variable scope`_ |* `random()`_ | -|* `>=`_ (greater than or equal to) | | | -| |* `static`_ | | -| | |**Bits and Bytes** | -|**Boolean Operators** |* `volatile`_ | | -| | |* `lowByte()`_ | -|* `&&`_ (and) |* `const`_ | | -| | |* `highByte()`_ | -|* `||`_ (or) | | | -| |**Utilities** |* `bitRead()`_ | -|* `!`_ (not) | | | -| |* `sizeof()`_ (sizeof operator) |* `bitWrite()`_ | -| | | | -|**Pointer Access Operators** | |* `bitSet()`_ | -| | | | -|* `* dereference operator`_ | |* `bitClear()`_ | -| | | | -|* `& reference operator`_ | |* `bit()`_ | -| | | | -| | | | -|**Bitwise Operators** | |**External Interrupts** | -| | | | -|* `&`_ (bitwise and) | |For more information on external | -| | |interrupts on Maple, see | -|* `|`_ (bitwise or) | |`our reference page`_. | -| | | | -|* `^`_ (bitwise xor) | | | -| | |* `attachInterrupt()`_ | -|* `~`_ (bitwise not) | | | -| | |* `detachInterrupt()`_ | -|* `<<`_ (shift left) | | | -| | | | -|* `>>`_ (shift right) | |**Interrupts** | -| | | | -| | |* `interrupts()`_ | -|**Compound Operators** | | | -| | |* `noInterrupts()`_ | -|* `++`_ (increment) | | | -| | | | -|* `- -`_ (decrement) | |**Communication** | -| | | | -|* `+=`_ (compound addition) | |* `Serial`_ | -| | | | -|* `-=`_ (compound subtraction) | |**Looking for something else?** | -| | | | -|* `*=`_ (compound multiplication) | |See the :ref:`libraries` page for | -| | |interfacing with particular types of | -|* `/=`_ (compound division) | |hardware. Try the list of | -| | |`community-contributed code`_. Maple | -|* `&=`_ (compound bitwise and) | |links against `newlib`_ and allows the | -| | |use of any of its functions; see its | -|* `|=`_ (compound bitwise or) | |documentation for more details. | -| | | | -+------------------------------------+------------------------------------+-----------------------------------------+ +Maple Language Reference +------------------------ + ++-------------------------------------------------+----------------------------------------------+---------------------------------------------------+ +| Structure | Variables | Functions | +| | | | ++=================================================+==============================================+===================================================+ +|* :ref:`setup() ` |**Constants** |**Digital I/O** | +| | | | +|* :ref:`loop() ` |* :ref:`HIGH ` | |* :ref:`pinMode() ` | +| | :ref:`LOW ` | | +| | |* :ref:`digitalWrite() ` | +|**Control Structures** |* :ref:`INPUT ` | | | +| | :ref:`OUTPUT ` |* :ref:`digitalRead() ` | +|* :ref:`if ` | | | +| |* :ref:`true ` | | | +|* :ref:`if...else ` | :ref:`false ` |**Analog I/O** | +| | | | +|* :ref:`for ` |* :ref:`integer constants |* :ref:`analogRead() ` | +| | ` | | +|* :ref:`switch/case ` | |* :ref:`pwmWrite() ` | +| |* :ref:`floating point constants | (:ref:`analogWrite() ` is | +|* :ref:`while ` | ` | also available, though its use is discouraged) | +| | | | +|* :ref:`do...while ` | | | +| |**Data Types** |**Advanced I/O** | +|* :ref:`break ` | | | +| | The size of each datatype, in bytes, is |* tone(): TODO | +|* :ref:`continue ` | given in parentheses where appropriate. | | +| | |* noTone(): TODO | +|* :ref:`return ` | *Note*: The ``word`` type is (deliberately) | | +| | :ref:`not supported `. |* shiftOut(): TODO | +|* :ref:`goto ` | | | +| |* :ref:`void ` |* pulseIn(): TODO | +| | | | +|**Further syntax** |* :ref:`boolean ` (1 byte) | | +| | |**Time** | +|* :ref:`; ` (semicolon) |* :ref:`char ` (1 byte) | | +| | |* :ref:`millis() ` | +|* :ref:`{} ` (curly braces) |* :ref:`unsigned char | | +| | ` (1 byte) |* :ref:`micros() ` | +|* :ref:`// ` | | | +| (single line comment) |* :ref:`byte ` (1 byte) |* :ref:`delay() ` | +| | | | +|* :ref:`/\* \*/ |* :ref:`int ` (4 bytes) |* :ref:`delayMicroseconds() | +| ` | | ` | +| (multi-line comment) |* :ref:`unsigned int ` | | +| | (4 bytes) | | +|* :ref:`#define ` | |**Math** | +| |* :ref:`long ` (8 bytes) | | +|* :ref:`#include ` | |* :ref:`min() ` | +| |* :ref:`unsigned long ` | | +| | (8 bytes) |* :ref:`max() ` | +|**Arithmetic Operators** | | | +| |* :ref:`float ` (4 bytes) |* :ref:`abs() ` | +|* :ref:`= ` | | | +| (assignment operator) |* :ref:`double ` (8 bytes) |* :ref:`constrain() ` | +| | | | +|* :ref:`+ ` (addition) |* :ref:`string ` |* :ref:`map() ` | +| | | | +|* :ref:`- ` |* :ref:`array ` |* :ref:`pow() ` | +| (subtraction) | | | +| |* Also provided: ``int8``, ``int16``, |* :ref:`sqrt() ` | +|* :ref:`* ` | ``int32``, ``int64``, and their unsigned | | +| (multiplication) | counterparts ``uint8``, ``uint16``, | | +| | ``uint32``, ``uint64``. |**Trigonometry** | +|* :ref:`/ ` (division) | | | +| | |* :ref:`sin() ` | +|* :ref:`% ` (modulo) |**Conversion** | | +| | |* :ref:`cos() ` | +| |* :ref:`char() ` | | +|**Comparison Operators** | |* :ref:`tan() ` | +| |* :ref:`byte() ` | | +|* :ref:`== ` (equal to) | | | +| |* :ref:`int() ` |**Random Numbers** | +|* :ref:`\!= ` | | | +| (not equal to) |* :ref:`long() ` |* :ref:`randomSeed() ` | +| | | | +|* :ref:`< ` (less than) |* :ref:`float() ` |* :ref:`random() ` | +| | | | +|* :ref:`> ` |* :ref:`double() ` | | +| (greater than) | |**Bits and Bytes** | +| | | | +|* :ref:`<= ` |**Variable Scope & Qualifiers** |* :ref:`lowByte() ` | +| (less than or equal to) | | | +| |* :ref:`variables `, |* :ref:`highByte() ` is | +|* :ref:`>= ` | :ref:`scope ` | provided, though its use is discouraged. | +| (greater than or equal to) | | | +| |* :ref:`static ` |* :ref:`bitRead() ` | +| | | | +|**Boolean Operators** |* :ref:`volatile ` |* :ref:`bitWrite() ` | +| | | | +|* :ref:`&& ` (and) |* :ref:`const ` |* :ref:`bitSet() ` | +| | | | +|* :ref:`|| ` (or) | |* :ref:`bitClear() ` | +| |**Utilities** | | +|* :ref:`\! ` (not) | |* :ref:`bit() ` | +| |* :ref:`sizeof() ` | | +| | (``sizeof`` operator) | | +|**Pointer Access Operators** | |**External Interrupts** | +| | | | +|* :ref:`* dereference operator | |* :ref:`Reference Page ` | +| ` | | | +| | |* :ref:`attachInterrupt() | +|* :ref:`& reference operator | | ` | +| ` | | | +| | |* :ref:`detachInterrupt() | +| | | ` | +|**Bitwise Operators** | | | +| | | | +|* :ref:`& ` | |**Interrupts** | +| (bitwise and) | | | +| | |* interrupts(): TODO | +|* :ref:`| ` | | | +| (bitwise or) | |* noInterrupts(): TODO | +| | | | +|* :ref:`^ ` | | | +| (bitwise xor) | |**Communication** | +| | | | +|* :ref:`~ ` | |* :ref:`SerialUSB ` | +| (bitwise not) | | | +| | |* :ref:`Serial ` | +|* :ref:`\<\< ` | | | +| (shift left) | |**Looking for something else?** | +| | | | +|* :ref:`>> ` | | See the :ref:`libraries` page for interfacing with| +| (shift right) | | particular types of hardware. Try the list of | +| | | `community-contributed code` . Maple links | +| | | against `newlib` and allows the use of any of its | +|**Compound Operators** | | functions; see its documentation for more details.| +| | | | +|* :ref:`++ ` | | | +| (increment) | | | +| | | | +|* :ref:`- - ` | | | +| (decrement) | | | +| | | | +|* :ref:`+= ` | | | +| (compound add) | | | +| | | | +|* :ref:`-= | | | +| ` (compound | | | +| subtract) | | | +| | | | +|* :ref:`*= | | | +| ` (compound | | | +| multiply) | | | +| | | | +|* :ref:`/= | | | +| ` (compound | | | +| divide) | | | +| | | | +|* :ref:`&= | | | +| ` (compound | | | +| bitwise and) | | | +| | | | +|* :ref:`|= | | | +| ` (compound | | | +| bitwise or) | | | +| | | | ++-------------------------------------------------+----------------------------------------------+---------------------------------------------------+ .. _language-missing-features: -Stub TODO: fill in other missing features, like analogReference() - -.. note:: - - The ``word`` data type is not supported on the Maple. This is by - choice. - - We decided not to include it because, while the Maple has 32-bit - words, the word size on an Arduino board is only 16 bits, and code - that uses the ``word`` type is likely to rely on that fact. - - By not supporting ``word``, you'll get a compile error when porting - Arduino code to your Maple instead of potentially weird, - hard-to-debug runtime behavior. - - If you're porting over Arduino code and really want ``word``, you - can put the following at the top of the file you're porting:: - - typedef uint16 word; - -.. _if: http://arduino.cc/en/Reference/If -.. _if...else: http://arduino.cc/en/Reference/Else -.. _for: http://arduino.cc/en/Reference/For -.. _switch/case: http://arduino.cc/en/Reference/SwitchCase -.. _while: http://arduino.cc/en/Reference/While -.. _do...while: http://arduino.cc/en/Reference/DoWhile -.. _break: http://arduino.cc/en/Reference/Break -.. _continue: http://arduino.cc/en/Reference/Continue -.. _return: http://arduino.cc/en/Reference/Return -.. _goto: http://arduino.cc/en/Reference/Goto - -.. _;: http://arduino.cc/en/Reference/SemiColon -.. _{}: http://arduino.cc/en/Reference/Braces -.. _//: http://arduino.cc/en/Reference/Comments -.. _/\* \*/: http://arduino.cc/en/Reference/Comments -.. _#define: http://arduino.cc/en/Reference/Define -.. _#include: http://arduino.cc/en/Reference/Include - -.. _=: http://arduino.cc/en/Reference/Assignment -.. _+: http://arduino.cc/en/Reference/Arithmetic -.. _-: http://arduino.cc/en/Reference/Arithmetic -.. _*: http://arduino.cc/en/Reference/Arithmetic -.. _/: http://arduino.cc/en/Reference/Arithmetic -.. _%: http://arduino.cc/en/Reference/Modulo - -.. _==: http://arduino.cc/en/Reference/If -.. _!=: http://arduino.cc/en/Reference/If -.. _<: http://arduino.cc/en/Reference/If -.. _>: http://arduino.cc/en/Reference/If -.. _<=: http://arduino.cc/en/Reference/If -.. _>=: http://arduino.cc/en/Reference/If - -.. _&&: http://arduino.cc/en/Reference/Boolean -.. _||: http://arduino.cc/en/Reference/Boolean -.. _!: http://arduino.cc/en/Reference/Boolean - -.. _* dereference operator: http://arduino.cc/en/Reference/Pointer -.. _& reference operator: http://arduino.cc/en/Reference/Pointer - -.. _&: http://arduino.cc/en/Reference/BitwiseAnd -.. _|: http://arduino.cc/en/Reference/BitwiseAnd -.. _^: http://arduino.cc/en/Reference/BitwiseAnd -.. _~: http://arduino.cc/en/Reference/BitwiseXorNot -.. _<<: http://arduino.cc/en/Reference/Bitshift -.. _>>: http://arduino.cc/en/Reference/Bitshift - -.. _++: http://arduino.cc/en/Reference/Increment -.. FIXME can't freaking get two hyphens to show up! sphinx turns "--" -.. into an endash, whatever, fine, try to escape like "\-\-", that -.. ALSO becomes endash (!@#$), damn, well, maybe someone else is -.. eating my slash, try "\\-\\-", nope, that turns into a motherfing -.. \-\-. i hate everything. -.. _- -: http://arduino.cc/en/Reference/Increment -.. _+=: http://arduino.cc/en/Reference/IncrementCompound -.. _-=: http://arduino.cc/en/Reference/IncrementCompound -.. _*=: http://arduino.cc/en/Reference/IncrementCompound -.. _/=: http://arduino.cc/en/Reference/IncrementCompound -.. _&=: http://arduino.cc/en/Reference/BitwiseCompound -.. _|=: http://arduino.cc/en/Reference/BitwiseCompound - -.. _HIGH: http://arduino.cc/en/Reference/Constants -.. _LOW: http://arduino.cc/en/Reference/Constants -.. _INPUT: http://arduino.cc/en/Reference/Constants -.. _OUTPUT: http://arduino.cc/en/Reference/Constants -.. _true: http://arduino.cc/en/Reference/Constants -.. _false: http://arduino.cc/en/Reference/Constants -.. _integer constants: http://arduino.cc/en/Reference/IntegerConstants -.. _floating point constants: http://arduino.cc/en/Reference/Fpconstants - -.. _void: http://arduino.cc/en/Reference/Void -.. _boolean: http://arduino.cc/en/Reference/BooleanVariables -.. _char: http://arduino.cc/en/Reference/Char -.. _unsigned char: http://arduino.cc/en/Reference/UnsignedChar -.. _byte: http://arduino.cc/en/Reference/Byte -.. _int: http://arduino.cc/en/Reference/Int -.. _unsigned int: http://arduino.cc/en/Reference/UnsignedInt -.. _word: http://arduino.cc/en/Reference/Word -.. _long: http://arduino.cc/en/Reference/Long -.. _unsigned long: http://arduino.cc/en/Reference/UnsignedLong -.. _float: http://arduino.cc/en/Reference/Float -.. _double: http://arduino.cc/en/Reference/Double -.. _string: http://arduino.cc/en/Reference/String -.. _array: http://arduino.cc/en/Reference/Array - -.. _char(): http://arduino.cc/en/Reference/CharCast -.. _byte(): http://arduino.cc/en/Reference/ByteCast -.. _int(): http://arduino.cc/en/Reference/IntCast -.. _word(): http://arduino.cc/en/Reference/WordCast -.. _long(): http://arduino.cc/en/Reference/LongCast -.. _float(): http://arduino.cc/en/Reference/FloatCast - -.. _variable scope: http://arduino.cc/en/Reference/Scope -.. _static: http://arduino.cc/en/Reference/Static -.. _volatile: http://arduino.cc/en/Reference/Volatile -.. _const: http://arduino.cc/en/Reference/Const -.. _sizeof(): http://arduino.cc/en/Reference/Sizeof - -.. Links for the standard Arduino built-in functions are included as -.. part of the standard epilog. +Missing Arduino Features +------------------------ + +Stub TODO: fill in other missing features + +**analogReference()** + + It is not possible to implement this function on the Maple + hardware. It will be possible on the upcoming Maple Native. + +.. _language-no-word: + +**word** + + Readers familiar with the Arduino environment may notice that the + ``word`` datatype is missing from the above table's list of data + types. We chose **not to provide** the ``word`` data type on the + Maple. If you want a 16-bit unsigned integer, use the ``uint16`` + type instead. + + While the Maple has 32-bit words, the word size on an Arduino + board is only 16 bits, and code that uses the ``word`` type is + likely to rely on that fact. + + By not supporting ``word``, you'll get a compile error when + porting Arduino code to the Maple instead of potentially weird, + hard-to-debug runtime behavior. + + If you really must have ``word``, you can include the following + ``typedef`` in your program:: + + typedef uint16 word; + .. _our reference page: http://leaflabs.com/docs/external-interrupts/ -.. _Serial: http://arduino.cc/en/Reference/Serial -.. _community-contributed code: http://www.arduino.cc/playground/Main/GeneralCodeLibrary .. _newlib: http://sourceware.org/newlib/ - .. _arduino_c_for_c_hackers: Note for C/C++ Programmers @@ -331,7 +260,11 @@ you C programmers should remember that `C++ is not a superset of C `_) who want a better understanding of the differences between C++ and the Wiring language. The good news is that the differences are relatively -few. +few; Wiring is just a thin wrapper around C++. + +Some potentially better news is that the Maple can be programmed using +a :ref:`standard Unix toolchain `, so if you'd rather +stick with :command:`gcc`, :command:`make`, and friends, you can. A *sketch* is the IDE's notion of a project; it consists of one or more files written in the Wiring language, which is mostly the same as @@ -361,8 +294,8 @@ The Wiring language also does not require you to define your own are required to define two functions, ``setup`` and ``loop``, with type signatures :: - void setup(void) - void loop(void) + void setup(void); + void loop(void); Once a sketch is uploaded to a Maple and begins to run, ``setup()`` is called once, and then ``loop()`` is called repeatedly. The IDE diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst index b595f70..2bb584a 100644 --- a/docs/source/unix-toolchain.rst +++ b/docs/source/unix-toolchain.rst @@ -32,20 +32,16 @@ GCC compiler tools `_ please post in the forums, so we can fold your tips into this document! -* :ref:`Linux setup ` -* :ref:`OS X setup ` -* :ref:`Test compilation ` -* :ref:`Upload a program ` -* :ref:`Communicate over USB-serial interface ` -* :ref:`Starting your own projects ` -* :ref:`Debug with OpenOCD ` -* :ref:`Do it all with Code::Blocks ` -* :ref:`Go forth exuberantly! ` +.. contents:: Contents + :local: .. _toolchain-linux-setup: -Linux Setup ------------ +Setup +----- + +Linux +^^^^^ These instructions are oriented towards Linux users using a contemporary Debian-based distribution. @@ -55,7 +51,7 @@ contemporary Debian-based distribution. First I'll give the commands to run, then explain:: $ sudo aptitude install build-essential git-core wget screen dfu-util \ - openocd python python-serial + openocd python python-serial You'll want to install a bunch of developer "basics" like :command:`make`, :command:`tar`, etc. A good catch-all for these @@ -90,12 +86,12 @@ package; this could also be installed with `easy_install **2. Fetch libmaple and Compiler Toolchain** :: - $ cd ~ - $ git clone git://github.com/leaflabs/libmaple.git libmaple - $ cd libmaple + $ cd ~ + $ git clone git://github.com/leaflabs/libmaple.git libmaple + $ cd libmaple $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz $ tar xvf arm-*-linux32.tar.gz - $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up + $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up This step is fairly straightforward: do a git clone of the `libmaple repository `_ to some directory, @@ -114,9 +110,9 @@ relative path calls and references. From the libmaple directory, :: - $ groups # make sure it includes plugdev; if not add, yourself to it - $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules - $ sudo /etc/init.d/udev restart + $ groups # make sure it includes plugdev; if not add, yourself to it + $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules + $ sudo /etc/init.d/udev restart As a security precaution on linux, unknown USB devices can only be accessed by the superuser. This udev script identifies the Maple based @@ -132,8 +128,8 @@ Great! Test your setup by :ref:`compiling a sample program .. _toolchain-osx-setup: -OS X Setup ----------- +OS X +^^^^ These instructions have been tested successfully on OS X 10.6.4. As stated previously, this document assumes a general level of Unix @@ -185,7 +181,7 @@ You will need the following tools to get started: $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \ /somewhere/on/your/PATH/dfu-util - .. note:: + .. note:: Just copying the binary somewhere doesn't work, as it relies on dynamically linked libraries found elsewhere in the .app bundle. It's possible to pull just the relevant pieces out of the @@ -426,7 +422,7 @@ then `install Code::Blocks `_. You can do this on Linux with:: - $ sudo aptitude install codeblocks + $ sudo aptitude install codeblocks The first time it runs you'll maybe want to disable all the glitzy "Getting Started" crap (when will they learn?). We've added a .cbp diff --git a/docs/source/wirish.rst b/docs/source/wirish.rst index 2773e24..e8e608e 100644 --- a/docs/source/wirish.rst +++ b/docs/source/wirish.rst @@ -7,3 +7,4 @@ wirish/pwmwrite wirish/types + wirish/serialusb diff --git a/docs/source/wirish/pwmwrite.rst b/docs/source/wirish/pwmwrite.rst index b1f0515..7667a72 100644 --- a/docs/source/wirish/pwmwrite.rst +++ b/docs/source/wirish/pwmwrite.rst @@ -24,26 +24,25 @@ Example Sets the output to the LED proportional to the value read from the potentiometer (adapted for Maple from the Arduino `analogWrite() -reference `_\ ):: +reference `_):: - - int ledPin = 13; // LED connected to pin 13 (Maple-specific) + + int ledPin = 13; // LED connected to pin 13 (Maple) 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 LED pin as output pinMode(analogPin, PWM); // sets the potentiometer pin as PWM - // output (Maple-specific) + // output } - + void loop() { val = analogRead(analogPin); // read the input pin analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095, // analogWrite values from 0 to 65535 - // (Maple-specific) } See Also -- cgit v1.2.3