diff options
Diffstat (limited to 'docs')
36 files changed, 435 insertions, 383 deletions
diff --git a/docs/flibbit.py b/docs/flibbit.py deleted file mode 100644 index 5f149d4..0000000 --- a/docs/flibbit.py +++ /dev/null @@ -1,26 +0,0 @@ -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/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index bf05832..93547f0 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -1,6 +1,5 @@ {% extends "!layout.html" %} {% block rootrellink %} - <li><a href="http://leaflabs.com">LeafLabs</a> |</li> - <li><a href="index.html">Docs Home</a> |</li> + <li><a href="http://leaflabs.com/">LeafLabs</a> |</li> {{ super() }} {% endblock %} diff --git a/docs/source/errata.rst b/docs/source/errata.rst index a3bb66a..8feb6ea 100644 --- a/docs/source/errata.rst +++ b/docs/source/errata.rst @@ -10,22 +10,22 @@ but are easy ways to break or damage your board permanently. For a list of differences between the Maple and Arduinos, see the :ref:`compatibility reference <compatibility>`. +The errata are grouped by Maple version ("Rev"). Rev 5 is currently +on sale. If you are unsure which version you own, the :ref:`Maple +hardware page <maple-hardware-identify-rev>` has pictures and +descriptions of each version. + .. contents:: Contents :local: Maple Rev 5 ----------- -These boards went on sale in November 2010. They have white buttons, -and "r5" in small print near the "LeafLabs Maple" text next to the -"infinity-leaf" logo, among other changes: - -.. figure:: /_static/img/maple_rev5.png - :align: center - :alt: Maple Rev 5 - Known issues: +* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the + corresponding "AIN" is missing from its silkscreen. + * **GPIO 39-43 not configured**: this is really more of a software "TODO" item. Some of the JTAG header pins are numbered 39-43. These STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when the a @@ -43,13 +43,6 @@ Potential failure modes: Maple Rev 3 ----------- -This batch of boards went on sale beginning in May 2010. They have a -darker red silkscreen and the "infinity-leaf" logo: - -.. figure:: /_static/img/maple_rev3.png - :align: center - :alt: Maple Rev 3 - Known issues: * **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 @@ -106,13 +99,6 @@ Potential failure modes: Maple Rev 1 ----------- -This batch of 100 boards shipped in later 2009. They have a red -silkscreen and the logo is a single pixelated leaf: - -.. figure:: /_static/img/maple_rev1.png - :align: center - :alt: Maple Rev 1 - Known issues: * **ADC noise**: generally very high, in particular when the USB port diff --git a/docs/source/external-interrupts.rst b/docs/source/external-interrupts.rst index 5187ca4..b2cbbb1 100644 --- a/docs/source/external-interrupts.rst +++ b/docs/source/external-interrupts.rst @@ -84,14 +84,8 @@ The following table shows which pins can be used on which lines. Function Reference ------------------ -.. doxygenfunction:: attachInterrupt - -.. doxygenfunction:: detachInterrupt - -.. doxygenenum:: ExtIntTriggerMode - -.. doxygentypedef:: voidFuncPtr - +- :ref:`attachInterrupt() <lang-attachinterrupt>` +- :ref:`detachInterrupt() <lang-detachinterrupt>` Code example ------------ diff --git a/docs/source/hardware/maple-mini.rst b/docs/source/hardware/maple-mini.rst new file mode 100644 index 0000000..a8a4186 --- /dev/null +++ b/docs/source/hardware/maple-mini.rst @@ -0,0 +1,6 @@ +.. _hardware-maple-mini: + +Maple Mini +========== + +Stub. diff --git a/docs/source/hardware/maple-native.rst b/docs/source/hardware/maple-native.rst new file mode 100644 index 0000000..79115fc --- /dev/null +++ b/docs/source/hardware/maple-native.rst @@ -0,0 +1,6 @@ +.. _hardware-maple-native: + +Maple Native +============ + +Stub. diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst new file mode 100644 index 0000000..8350cc5 --- /dev/null +++ b/docs/source/hardware/maple.rst @@ -0,0 +1,104 @@ +.. highlight:: sh + +.. _hardware-maple: + +Maple +===== + +.. contents:: Contents + :local: + +.. _maple-hardware-identify-rev: + +Identifying your Rev +-------------------- + +We went through three versions ("Revs") of the Maple hardware: Rev 1, +Rev 3, and Rev 5 [#frev2_4]_; Rev 5, the final design, is currently on +sale. The following sections will help you to help you identify your +Rev. Known issues are listed in the :ref:`errata <errata>`. + +Rev 1 +^^^^^ + +A small number of Maple Rev 1 boards went on sale in late 2009. They +have a light red silkscreen and a single pixelated leaf as a logo. + +.. figure:: /_static/img/maple_rev1.png + :align: center + :alt: Maple Rev 1 + +.. rubric:: Footnotes + +.. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal + testing. + +Rev 3 +^^^^^ + +This batch of boards went on sale beginning in May 2010. They have a +darker red silkscreen and the "infinity leaf" logo. The Maple Rev 3 +was the first version which includes the built-in button, labeled BUT. +It also includes a built-in LiPo battery charger. + +.. figure:: /_static/img/maple_rev3.png + :align: center + :alt: Maple Rev 3 + +Rev 5 +^^^^^ + +These boards went on sale in November 2010. They have white buttons, +and "r5" in small print near the "LeafLabs Maple" text next to the +"infinity leaf" logo. The Maple Rev 5 repositioned the double header +on the right hand side to better fit 0.1 inch pitch breadboard. This +necessitated the removal of pins 21 and 22 from the double header; +they are still available, but don't have any headers installed on +them. + +.. figure:: /_static/img/maple_rev5.png + :align: center + :alt: Maple Rev 5 + +Powering the Maple +------------------ + +The Maple's power source is determined by the header to the left of +the "LeafLabs" label on the silkscreen. All versions of the Maple can +be powered from the barrel jack connector, USB, or a LiPo battery. We +ship the Maple with a jumper on the USB selector. In order to power +it off of an alternative source, unplug the Maple, then move the +jumper to the desired selector before reconnecting power. + +You can also power the Maple via the pin labeled "Vin" on the lower +header. However, don't do this while simultaneously powering the +Maple from another source, or you could damage the board. + +Using the Built-in Battery Charger +---------------------------------- + +Maples Rev 3 and Rev 5 also have a built-in LiPo battery charger. In +order to use it, put a jumper across the CHRG header on the power +selection header and across the USB, or EXT selectors, depending on +whether you're charging the battery via USB cable or barrel jack +connector. The LED labeled CHRG will light up while the battery is +being charged. When the battery is finished charging, the LED labeled +DONE will also light up. + +Hardware Design Files +--------------------- + +The hardware schematics and board layout files are available in the +`Maple github repository <https://github.com/leaflabs/maple>`_. The +design files for Rev 1, Rev 3, and Rev 5 are respectively in the +``maple-r1``, ``maple-r3``, and ``maple-r5`` subdirectories. A +schematic for a JTAG adapter suitable for use with Maple is available +in the ``jtagadapter`` directory. + +From the github repository main page, you can download the entire +repository by clicking the "Download" button. If you are familiar +with `git <http://git-scm.com/>`_, you can also clone the repository +at the command line with :: + + $ git clone git://github.com/leaflabs/maple.git + diff --git a/docs/source/index.rst b/docs/source/index.rst index 825ec81..5c1718f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,27 +16,26 @@ Have fun! **Usage Guides:** .. toctree:: - :maxdepth: 2 + :maxdepth: 1 Quickstart <maple-quickstart> IDE Installation <maple-ide-install> - IDE Anatomy <ide> + IDE Usage <ide> + Command-Line Toolchain <unix-toolchain> .. _index-maple-programming: **Maple Programming:** .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - Maple Language<language> - Maple Libraries <libraries> + Language <language> + Libraries <libraries> Arduino Compatibility <compatibility> + libmaple <libmaple> External Interrupts <external-interrupts> - Command-Line Tools & APIs <libmaple> Bootloader <bootloader> - - Troubleshooting <troubleshooting> Known Problems <errata> @@ -47,15 +46,32 @@ Have fun! .. toctree:: :maxdepth: 1 - i2c - pwm + adc gpio - usb + i2c jtag - adc + pwm spi - usart timers + usb + usart + +.. _index-schematics: + +**Board Hardware Documentation:** + +.. toctree:: + :maxdepth: 1 + + hardware/maple.rst + +.. TODO write/include these upon Mini and Native release + +.. toctree:: + :hidden: + + hardware/maple-mini.rst + hardware/maple-native.rst .. _index-reference: diff --git a/docs/source/lang/api/attachinterrupt.rst b/docs/source/lang/api/attachinterrupt.rst index 0b8907f..7c5a6c7 100644 --- a/docs/source/lang/api/attachinterrupt.rst +++ b/docs/source/lang/api/attachinterrupt.rst @@ -15,7 +15,28 @@ occurs. Library Documentation --------------------- -.. doxygenfunction:: attachInterrupt +.. FIXME once breathe knows how to get the correct attachInterupt +.. (right now it's copying from HardwareTimer), replace with a +.. doxygenfunction directive + +.. cpp:function:: void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode) + + Registers an interrupt handler on a pin. + + The interrupt will be triggered on a given transition on the pin, + as specified by the mode parameter. The handler runs in interrupt + context. The new handler will replace whatever handler is + currently registered for the pin, if any. + + *Parameters* + + - ``pin`` - Maple pin number + + - ``handler`` - Function to run upon external interrupt trigger. + The handler should take no arguments, and have void return type. + + - ``mode`` - Type of transition to trigger on, e.g. falling, + rising, etc. .. doxygenenum:: ExtIntTriggerMode @@ -34,7 +55,6 @@ There are a few constraints you should be aware of if you're using more than one interrupt at a time; the :ref:`external-interrupts` page has the details. - Using Interrupts ---------------- @@ -43,7 +63,6 @@ microcontroller programs, and can help solve timing problems. A good task for using an interrupt might be reading a rotary encoder, or 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 @@ -55,7 +74,6 @@ sensor that is trying to catch a click, or an infrared slot sensor situations, using an interrupt can free the microcontroller to get some other work done while not missing the doorbell. - Example ------- @@ -78,7 +96,6 @@ Example state = !state; } - Arduino Compatibility --------------------- @@ -89,14 +106,10 @@ additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 number goes with which pin -- just tell ``attachInterrupt()`` the pin you want. - See also -------- - - :ref:`detachInterrupt <lang-detachinterrupt>` - :ref:`external-interrupts` - - .. include:: cc-attribution.txt diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst index 4426293..72738b8 100644 --- a/docs/source/lang/api/constants.rst +++ b/docs/source/lang/api/constants.rst @@ -242,10 +242,18 @@ type, follow it with: For example, ``33U`` is an :ref:`unsigned int <lang-unsignedint>`. - an ``l`` or ``L`` to interpret the constant as a long value. For - example, ``100000L`` is a :ref:`long <lang-long>`. + example, ``100000L`` is a :ref:`long <lang-long>`. On the Maple, + ``long`` is just a synonym for ``int``. - a ``ul`` or ``UL`` to do both. For example, ``32767UL`` is an - :ref:`unsigned long <lang-unsignedlong>`. + :ref:`unsigned long <lang-unsignedlong>`. On the Maple, ``unsigned + long`` is just a synonym for ``unsigned int``. + +- an ``ll`` or ``LL`` to interpret the constant as a :ref:`long long + <lang-longlong>` value. + +- a ``ull`` or ``ULL`` to interpret the constant as an :ref:`unsigned + long long <lang-unsignedlonglong>`. .. _lang-constants-fp: @@ -321,6 +329,8 @@ See Also - :ref:`unsigned int <lang-unsignedint>` - :ref:`long <lang-long>` - :ref:`unsigned long <lang-unsignedlong>` +- :ref:`long long <lang-longlong>` +- :ref:`unsigned long long <lang-unsignedlonglong>` - :ref:`float <lang-float>` - :ref:`double <lang-double>` diff --git a/docs/source/lang/api/detachinterrupt.rst b/docs/source/lang/api/detachinterrupt.rst index adb2439..41642a7 100644 --- a/docs/source/lang/api/detachinterrupt.rst +++ b/docs/source/lang/api/detachinterrupt.rst @@ -6,11 +6,20 @@ detachInterrupt() Used to disable an interrupt specified with :ref:`lang-attachinterrupt`\ . - Library Documentation --------------------- -.. doxygenfunction:: detachInterrupt +.. FIXME once breathe knows how to get the correct detachInterupt +.. (right now it's copying from HardwareTimer), replace with a +.. doxygenfunction directive + +.. cpp:function:: void detachInterrupt(uint8 pin) + + Disable any registered external interrupt on the given pin. + + *Parameters* + + - ``pin`` Maple pin number Arduino Compatibility --------------------- @@ -31,7 +40,4 @@ See Also - :ref:`attachInterrupt() <lang-attachInterrupt>` - - - .. include:: cc-attribution.txt diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst index 258471b..3e5424c 100644 --- a/docs/source/lang/api/hardwaretimer.rst +++ b/docs/source/lang/api/hardwaretimer.rst @@ -317,6 +317,8 @@ For example, to set the prescale factor on timer 1 to 5, call The :ref:`setPeriod() <lang-hardwaretimer-setperiod>` method may also be used as a convenient alternative. +.. _lang-hardwaretimer-resume: + .. cpp:function:: void HardwareTimer::resume() Resume a paused timer, without affecting its configuration. diff --git a/docs/source/lang/api/millis.rst b/docs/source/lang/api/millis.rst index 54e4507..0288c56 100644 --- a/docs/source/lang/api/millis.rst +++ b/docs/source/lang/api/millis.rst @@ -40,7 +40,7 @@ Tip Since the return value for ``millis()`` is an :ref:`unsigned long <lang-unsignedlong>`, overflow errors may occur if you try to do math -with other data types, such as :ref:`ints <lang-int>`. +with other data types, such as :ref:`chars <lang-char>`. See Also -------- diff --git a/docs/source/lang/api/pwmwrite.rst b/docs/source/lang/api/pwmwrite.rst index 2c858ab..9d50077 100644 --- a/docs/source/lang/api/pwmwrite.rst +++ b/docs/source/lang/api/pwmwrite.rst @@ -33,21 +33,20 @@ Sets the output to the LED proportional to the value read from the potentiometer:: int analogPin = 3; // potentiometer connected to analog pin 3 - int val = 0; // variable to store the read value void setup() { pinMode(BOARD_LED_PIN, OUTPUT); // sets the LED pin as output - pinMode(analogPin, PWM); // sets the potentiometer pin as PWM - // output + pinMode(analogPin, INPUT_ANALOG); // sets the potentiometer pin as + // analog input } void loop() { - val = analogRead(analogPin); // read the input pin + int val = analogRead(analogPin); // read the input pin - analogWrite(BOARD_LED_PIN, val / 16); // analogRead values go from 0 - // to 4095, analogWrite values - // from 0 to 65535 + pwmWrite(BOARD_LED_PIN, val * 16); // analogRead values go from 0 + // to 4095, pwmWrite values + // from 0 to 65535, so scale roughly } See Also diff --git a/docs/source/lang/api/random.rst b/docs/source/lang/api/random.rst index f2a9762..dd8871d 100644 --- a/docs/source/lang/api/random.rst +++ b/docs/source/lang/api/random.rst @@ -7,13 +7,13 @@ random() The ``random()`` function generates pseudo-random numbers. -.. TODO keep tracking Sphinx/Breathe's ability to reference overloaded -.. functions so we can use doxygenfunction instead of manually -.. documenting this. - Library Documentation --------------------- +.. FIXME keep tracking Sphinx/Breathe's ability to reference +.. overloaded functions so we can use doxygenfunction instead of +.. manually documenting. + .. cpp:function:: random(long max) Same as a call to ``random(0, max)``. diff --git a/docs/source/lang/cpp/arithmetic.rst b/docs/source/lang/cpp/arithmetic.rst index 91fe22e..7e8c3fc 100644 --- a/docs/source/lang/cpp/arithmetic.rst +++ b/docs/source/lang/cpp/arithmetic.rst @@ -97,7 +97,7 @@ 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. The following table summarizes the sizes and -ranges of integer datatypes on the Maple (the ranges of long long +ranges of integer datatypes on the Maple (the ranges of ``long long`` types are approximate): .. _lang-arithmetic-int-sizes: diff --git a/docs/source/lang/cpp/assignment.rst b/docs/source/lang/cpp/assignment.rst index b6ad4d5..f9430b4 100644 --- a/docs/source/lang/cpp/assignment.rst +++ b/docs/source/lang/cpp/assignment.rst @@ -15,47 +15,38 @@ 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 - - + sensVal = 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 ) +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. - +Don't confuse the assignment operator ``=`` (single equal sign) with +the comparison operator ``==`` (double equal signs), which evaluates +whether two expressions are equal. Arduino Compatibility --------------------- Assignments on the Maple are identical to those on Arduino. - - 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>`_ - +- :ref:`if <lang-if>` +- :ref:`char <lang-char>` +- :ref:`int <lang-int>` +- :ref:`long long <lang-longlong>` .. rubric:: Footnotes @@ -66,5 +57,4 @@ See Also <http://icu-project.org/docs/papers/cpp_report/the_anatomy_of_the_assignment_operator.html>`_ for more information. - .. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/built-in-types.rst b/docs/source/lang/cpp/built-in-types.rst index 1323db8..a7349e6 100644 --- a/docs/source/lang/cpp/built-in-types.rst +++ b/docs/source/lang/cpp/built-in-types.rst @@ -33,7 +33,7 @@ Integral types .. cpp:type:: long - 64-bit integer value. + 32-bit integer value. .. cpp:type:: long long diff --git a/docs/source/lang/cpp/compoundbitwise.rst b/docs/source/lang/cpp/compoundbitwise.rst index a4bbb24..8231130 100644 --- a/docs/source/lang/cpp/compoundbitwise.rst +++ b/docs/source/lang/cpp/compoundbitwise.rst @@ -31,8 +31,8 @@ value of ``y``:: x &= y; // equivalent to x = x & y; You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any :ref:`integer value +``int``, ``char``, ``byte``, ``long long``, etc.). You can use either +an integer variable or any :ref:`integer value <lang-constants-integers>` (like ``3`` or ``0x20``) for ``y``. Before doing an example of ``&=``, let's first review the Bitwise AND @@ -115,9 +115,9 @@ its old value bitwise ORed with the value of ``y``:: x |= y; // equivalent to x = x | y; You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any integer value (like ``3`` or ``0x20``) for -``y``. (This works the same way as :ref:`compound bitwise AND +``int``, ``char``, ``long long`` etc.). You can use either an integer +variable or any integer value (like ``3`` or ``0x20``) for ``y``. +(This works the same way as :ref:`compound bitwise AND <lang-compoundbitwise-and>`\ , ``&=``). Before doing an example of ``|=``, let's first review the Bitwise OR @@ -178,12 +178,11 @@ will be equal to its old value bitwise XORed with the value of ``y``:: x ^= y; // equivalent to x = x ^ y; You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +``int``, ``char``, ``long long``, etc.). You can use either an integer variable or any integer value (like ``3`` or ``0x20``) for ``y``. (This works the same way as :ref:`&= -<lang-compoundbitwise-and>` and :ref:`\|= -<lang-compoundbitwise-or>`; in fact, these three operators all -work the same in this way). +<lang-compoundbitwise-and>` and :ref:`\|= <lang-compoundbitwise-or>`; +in fact, these three operators all work the same in this way). Before doing an example of ``^=``, let's first review the Bitwise XOR operator, ``^``:: diff --git a/docs/source/lang/cpp/doublecast.rst b/docs/source/lang/cpp/doublecast.rst index 511fe24..16a9907 100644 --- a/docs/source/lang/cpp/doublecast.rst +++ b/docs/source/lang/cpp/doublecast.rst @@ -12,7 +12,7 @@ data type. Here is an example:: double d = double(x); // d now holds 2.0, a double 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`` or ``long long``), you will get strange results. See the :ref:`double <lang-double>` reference for details about the precision and limitations of ``double`` values on the Maple. diff --git a/docs/source/lang/cpp/enum.rst b/docs/source/lang/cpp/enum.rst index ba82383..b6409eb 100644 --- a/docs/source/lang/cpp/enum.rst +++ b/docs/source/lang/cpp/enum.rst @@ -18,8 +18,7 @@ which has values ``HOT``, ``COMFY``, and ``COLD``:: enum weather {HOT, COMFY, COLD}; Once you've defined this type, you can create variables of type -``weather``, in the same way you would with an :ref:`int <lang-int>` -or a :ref:`long <lang-long>`:: +``weather``, in the same way you would with an :ref:`int <lang-int>`:: // create a weather variable named theWeather, with value COMFY: weather theWeather = COMFY; diff --git a/docs/source/lang/cpp/int.rst b/docs/source/lang/cpp/int.rst index ca75f75..3e96b69 100644 --- a/docs/source/lang/cpp/int.rst +++ b/docs/source/lang/cpp/int.rst @@ -24,6 +24,10 @@ arithmetic operations work mostly as you'd expect. There can be an dealing with the :ref:`bitshift right operator (>>) <lang-bitshift>`, however. +.. _lang-long: + +The ``long`` type is a synonym for ``int``. + Here is an example of declaring an ``int`` variable named ``ledPin``, then giving it value 13:: @@ -56,8 +60,8 @@ See Also - :ref:`unsigned int <lang-unsignedint>` - :ref:`char <lang-char>` - :ref:`unsigned char <lang-unsignedchar>` -- :ref:`long <lang-long>` -- :ref:`unsigned long <lang-unsignedlong>` +- :ref:`long long <lang-longlong>` +- :ref:`unsigned long long <lang-unsignedlonglong>` - :ref:`Integer Constants <lang-constants-integers>` - :ref:`Variables <lang-variables>` diff --git a/docs/source/lang/cpp/keywords.rst b/docs/source/lang/cpp/keywords.rst index e3bc20d..f21cd0d 100644 --- a/docs/source/lang/cpp/keywords.rst +++ b/docs/source/lang/cpp/keywords.rst @@ -89,11 +89,11 @@ Types The following keywords are used for built-in types. - :ref:`bool <lang-booleanvariables>` -- :ref:`lang-char` -- :ref:`lang-double` -- :ref:`lang-float` -- :ref:`lang-int` -- :ref:`lang-long` +- :ref:`char <lang-char>` +- :ref:`double <lang-double>` +- :ref:`float <lang-float>` +- :ref:`int <lang-int>` +- :ref:`long <lang-long>` - :ref:`short <lang-built-in-types-integral>` - :ref:`void <lang-void>` (not really a type, but used in the absence of one) @@ -109,8 +109,7 @@ Qualifiers variables; it has other uses not documented here. - ``unsigned`` is used to specify an unsigned integral type. - Examples: :ref:`lang-unsignedint`, :ref:`lang-unsignedchar`, - :ref:`lang-unsignedlong`. + Examples: :ref:`lang-unsignedint`, :ref:`lang-unsignedchar`. - :ref:`volatile <lang-volatile>` is useful when declaring variables that may be modified by external interrupts. diff --git a/docs/source/lang/cpp/long.rst b/docs/source/lang/cpp/long.rst deleted file mode 100644 index d8498c0..0000000 --- a/docs/source/lang/cpp/long.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. highlight:: cpp - -.. _lang-long: - -``long`` -======== - -The ``long`` data type stores extended size integer values. You can -use a ``long`` when your values are too large to fit into an :ref:`int -<lang-int>`. A ``long`` occupies 8 bytes of memory. This yields a -range of approximately -9.2×10^18 to 9.2×10^18 (that's 9.2 billion -billion, or about 92 million times the number of stars in the Milky -Way galaxy). The exact range of a ``long`` on the Maple is from --9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, or -2^63 to -(2^63-1). A ``long`` it is subject to the same :ref:`overflow issues -<lang-variables-rollover>` as any numeric data type. - -Here's an example of declaring a long (see :ref:`integer constants -<lang-constants-integers-u-l>` for an explanation of the "L" at the end of the -number):: - - // Speed of light in nanometers per second (approximate). - long c = 299792458000000000L; - -The general syntax for declaring an ``long`` variable named ``var``, -then giving it value ``val``, looks like:: - - long var = val; - -This is identical to the ``int`` syntax, with ``long`` replacing -``int``. - -Note that ``long`` values will still :ref:`overflow -<lang-int-overflow>`, just like ``int`` values, but their much -larger range makes this less likely to happen. - -The downside to using a ``long`` instead of an ``int`` (besides the -extra storage) is that :ref:`arithmetic <lang-arithmetic>` operations -on ``long``\ s will take slightly longer than on ``int``\ s. - -See Also --------- - -- :ref:`char <lang-char>` -- :ref:`unsigned char <lang-unsignedchar>` -- :ref:`int <lang-int>` -- :ref:`unsigned int <lang-unsignedint>` -- :ref:`unsigned long <lang-unsignedlong>` -- :ref:`Integer Constants <lang-constants-integers>` -- :ref:`Variables <lang-variables>` - -.. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/longcast.rst b/docs/source/lang/cpp/longcast.rst index 2b92345..f588fc6 100644 --- a/docs/source/lang/cpp/longcast.rst +++ b/docs/source/lang/cpp/longcast.rst @@ -21,7 +21,7 @@ precision and limitations of ``long`` variables on the Maple. See Also -------- -- :ref:`long <lang-long>` - +- :ref:`long <lang-long>` +- :ref:`long long <lang-longlong>` .. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/longlong.rst b/docs/source/lang/cpp/longlong.rst new file mode 100644 index 0000000..0ba56ed --- /dev/null +++ b/docs/source/lang/cpp/longlong.rst @@ -0,0 +1,56 @@ +.. highlight:: cpp + +.. _lang-longlong: + +``long long`` +============= + +The ``long long`` data type stores extended size integer values. You +can use a ``long long`` when your values are too large to fit into an +:ref:`int <lang-int>`. A ``long long`` occupies 8 bytes of memory. +This yields a range of approximately -9.2×10^18 to 9.2×10^18 (that's +9.2 billion billion, or about 92 million times the number of stars in +the Milky Way galaxy). The exact range of a ``long long`` on the +Maple is from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, +or -2^63 to (2^63-1). A ``long long`` it is subject to the same +:ref:`overflow issues <lang-variables-rollover>` as any numeric data +type. + +A synonym for the ``long long`` type is ``int64``. + +Here's an example of declaring a long long (see :ref:`integer +constants <lang-constants-integers-u-l>` for an explanation of the +"LL" at the end of the number):: + + // Speed of light in nanometers per second (approximate). + long long c = 299792458000000000LL; + +The general syntax for declaring an ``long long`` variable named ``var``, +then giving it value ``val``, looks like:: + + long long var = val; + +This is identical to the ``int`` syntax, with ``long long`` (or, at +your option, ``int64``) replacing ``int``. + +Note that ``long long`` values will still :ref:`overflow +<lang-int-overflow>`, just like ``int`` values, but their much larger +range makes this less likely to happen. + +The downside to using a ``long long`` instead of an ``int`` (besides +the extra storage) is that :ref:`arithmetic <lang-arithmetic>` +operations on ``long long``\ s will take slightly longer than on +``int``\ s. + +See Also +-------- + +- :ref:`char <lang-char>` +- :ref:`unsigned char <lang-unsignedchar>` +- :ref:`int <lang-int>` +- :ref:`unsigned int <lang-unsignedint>` +- :ref:`unsigned long long <lang-unsignedlonglong>` +- :ref:`Integer Constants <lang-constants-integers>` +- :ref:`Variables <lang-variables>` + +.. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/return.rst b/docs/source/lang/cpp/return.rst index 7b5039e..b4ef5fd 100644 --- a/docs/source/lang/cpp/return.rst +++ b/docs/source/lang/cpp/return.rst @@ -21,7 +21,7 @@ Syntax: In the second case, ``value`` should have a type which is the same as the return type of the function, or be convertible to it (like an -``int`` to a ``long``, etc.; see :ref:`this note +``int`` to a ``double``, etc.; see :ref:`this note <lang-arithmetic-typeconversion>` for some references). Examples: diff --git a/docs/source/lang/cpp/unsignedint.rst b/docs/source/lang/cpp/unsignedint.rst index f6311da..ad3e2f2 100644 --- a/docs/source/lang/cpp/unsignedint.rst +++ b/docs/source/lang/cpp/unsignedint.rst @@ -31,6 +31,10 @@ that an ``unsigned int`` will "underflow" at 0, and "overflow" at x--; // x now contains 4,294,967,295; rolled over "left to right" x++; // x now contains 0; rolled over "right to left" +.. _lang-unsignedlong: + +The ``unsigned long`` type is a synonym for ``unsigned int``. + Here is an example of declaring an ``unsigned int`` variable named ``ledPin``, then giving it value 13:: @@ -47,8 +51,8 @@ See Also - :ref:`int <lang-int>` - :ref:`char <lang-char>` - :ref:`unsigned char <lang-unsignedchar>` -- :ref:`long <lang-long>` -- :ref:`unsigned long <lang-unsignedlong>` +- :ref:`long long <lang-longlong>` +- :ref:`unsigned long long <lang-unsignedlonglong>` - :ref:`Integer Constants <lang-constants-integers>` - :ref:`Variables <lang-variables>` diff --git a/docs/source/lang/cpp/unsignedlong.rst b/docs/source/lang/cpp/unsignedlong.rst deleted file mode 100644 index 14a4fc3..0000000 --- a/docs/source/lang/cpp/unsignedlong.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. highlight:: cpp - -.. _lang-unsignedlong: - -``unsigned long`` -================= - -An unsigned version of the :ref:`long <lang-long>` data type. An -``unsigned long`` occupies 8 bytes of memory; it stores an integer -from 0 to 2^64-1, which is approximately 1.8×10^19 (18 quintillion, or -18 billion billion). - -Like an :ref:`unsigned int <lang-unsignedint>`, an ``unsigned long`` -won't store negative numbers; it is also subject to the same -:ref:`overflow issues <lang-int-overflow>` as any integral data type. - -Here is an example of declaring an ``unsigned long`` variable named -``c``, then giving it value 299,792,458,000,000,000 (see :ref:`integer -constants <lang-constants-integers-u-l>` for an explanation of the "L" -at the end of the number):: - - // Speed of light in nanometers per second (approximate). - unsigned long c = 299792458000000000L; - -The general syntax for declaring an ``unsigned long`` variable named -``var``, then giving it value ``val``, looks like:: - - unsigned long var = val; - -See Also --------- - -- :ref:`long <lang-long>` -- :ref:`int <lang-int>` -- :ref:`unsigned <lang-unsignedint>` -- :ref:`char <lang-char>` -- :ref:`unsigned char <lang-unsignedchar>` -- :ref:`Integer Constants <lang-constants-integers>` -- :ref:`Variables <lang-variables>` - -.. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/unsignedlonglong.rst b/docs/source/lang/cpp/unsignedlonglong.rst new file mode 100644 index 0000000..910b7e4 --- /dev/null +++ b/docs/source/lang/cpp/unsignedlonglong.rst @@ -0,0 +1,43 @@ +.. highlight:: cpp + +.. _lang-unsignedlonglong: + +``unsigned long long`` +====================== + +An unsigned version of the :ref:`long long <lang-longlong>` data type. +An ``unsigned long long`` occupies 8 bytes of memory; it stores an +integer from 0 to 2^64-1, which is approximately 1.8×10^19 (18 +quintillion, or 18 billion billion). + +A synonym for the ``unsigned long long`` type is ``uint64``. + +Like an :ref:`unsigned int <lang-unsignedint>`, an ``unsigned long +long`` won't store negative numbers; it is also subject to the same +:ref:`overflow issues <lang-int-overflow>` as any integral data type. + +Here is an example of declaring an ``unsigned long long`` variable +named ``c``, then giving it value 299,792,458,000,000,000 (see +:ref:`integer constants <lang-constants-integers-u-l>` for an +explanation of the "ULL" at the end of the number):: + + // Speed of light in nanometers per second (approximate). + unsigned long long c = 299792458000000000ULL; + +The general syntax for declaring an ``unsigned long long`` variable named +``var``, then giving it value ``val``, looks like:: + + unsigned long long var = val; + +See Also +-------- + +- :ref:`long long <lang-longlong>` +- :ref:`int <lang-int>` +- :ref:`unsigned <lang-unsignedint>` +- :ref:`char <lang-char>` +- :ref:`unsigned char <lang-unsignedchar>` +- :ref:`Integer Constants <lang-constants-integers>` +- :ref:`Variables <lang-variables>` + +.. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/variables.rst b/docs/source/lang/cpp/variables.rst index e6da0c9..336d5ab 100644 --- a/docs/source/lang/cpp/variables.rst +++ b/docs/source/lang/cpp/variables.rst @@ -44,7 +44,7 @@ Here are a few examples of declaring variables of different types:: int lightSensVal; char currentLetter; - unsigned long speedOfLight = 186000UL; + unsigned long long speedOfLight = 186000ULL; char errorMessage = {"choose another option"}; // see string Naming Variables diff --git a/docs/source/language.rst b/docs/source/language.rst index 018eb8c..2ebe03c 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -102,59 +102,59 @@ A more exhaustive index is available at the :ref:`language-index`. | |* :ref:`unsigned int <lang-unsignedint>` | | |* :ref:`#include <lang-include>` | (4 bytes) |* :ref:`micros() <lang-micros>` | | | | | -| |* :ref:`long <lang-long>` (8 bytes) |* :ref:`delay() <lang-delay>` | -|**Arithmetic Operators** | | | -| |* :ref:`unsigned long <lang-unsignedlong>` |* :ref:`delayMicroseconds() | -|* :ref:`= <lang-assignment>` | (8 bytes) | <lang-delaymicroseconds>` | -| (assignment operator) | | | -| |* :ref:`float <lang-float>` (4 bytes) | | -|* :ref:`+ <lang-arithmetic>` (addition) | |**Math** | -| |* :ref:`double <lang-double>` (8 bytes) | | -|* :ref:`- <lang-arithmetic>` | |* :ref:`min() <lang-min>` | -| (subtraction) |* :ref:`Strings <lang-string>` | | +| |* ``long`` (4 bytes), synonym for :ref:`int |* :ref:`delay() <lang-delay>` | +|**Arithmetic Operators** | <lang-int>` | | +| | |* :ref:`delayMicroseconds() | +|* :ref:`= <lang-assignment>` |* ``unsigned long`` (4 bytes), synonym for | <lang-delaymicroseconds>` | +| (assignment operator) | :ref:`unsigned int <lang-unsignedint>` | | +| | | | +|* :ref:`+ <lang-arithmetic>` (addition) |* :ref:`long long <lang-longlong>` (8 bytes) |**Math** | +| | | | +|* :ref:`- <lang-arithmetic>` |* :ref:`unsigned long |* :ref:`min() <lang-min>` | +| (subtraction) | long <lang-unsignedlonglong>` (8 bytes) | | | | |* :ref:`max() <lang-max>` | -|* :ref:`* <lang-arithmetic>` |* :ref:`Arrays <lang-array>` | | +|* :ref:`* <lang-arithmetic>` |* :ref:`float <lang-float>` (4 bytes) | | | (multiplication) | |* :ref:`abs() <lang-abs>` | -| |* :ref:`enum <lang-enum>` | | +| |* :ref:`double <lang-double>` (8 bytes) | | |* :ref:`/ <lang-arithmetic>` (division) | |* :ref:`constrain() <lang-constrain>` | -| |* :ref:`Numeric types <lang-built-in-types>` | | +| |* :ref:`strings <lang-string>` | | |* :ref:`% <lang-modulo>` (modulo) | |* :ref:`map() <lang-map>` | -| |**Conversion** | | +| |* :ref:`arrays <lang-array>` | | | | |* :ref:`pow() <lang-pow>` | -|**Comparison Operators** |* :ref:`char() <lang-charcast>` | | +|**Comparison Operators** |* :ref:`enum <lang-enum>` | | | | |* :ref:`sqrt() <lang-sqrt>` | -|* :ref:`== <lang-comparison>` (equal to) |* :ref:`byte() <lang-bytecast>` | | +|* :ref:`== <lang-comparison>` (equal to) |* :ref:`numeric types <lang-built-in-types>` | | | | | | -|* :ref:`\!= <lang-comparison>` |* :ref:`int() <lang-intcast>` |**Trigonometry** | +|* :ref:`\!= <lang-comparison>` |**Conversion** |**Trigonometry** | | (not equal to) | | | -| |* :ref:`long() <lang-longcast>` |* :ref:`sin() <lang-sin>` | +| |* :ref:`char() <lang-charcast>` |* :ref:`sin() <lang-sin>` | |* :ref:`< <lang-comparison>` (less than) | | | -| |* :ref:`float() <lang-floatcast>` |* :ref:`cos() <lang-cos>` | +| |* :ref:`byte() <lang-bytecast>` |* :ref:`cos() <lang-cos>` | |* :ref:`> <lang-comparison>` | | | -| (greater than) |* :ref:`double() <lang-doublecast>` |* :ref:`tan() <lang-tan>` | +| (greater than) |* :ref:`int() <lang-intcast>` |* :ref:`tan() <lang-tan>` | | | | | -|* :ref:`<= <lang-comparison>` | | | -| (less than or equal to) |**Variable Scope & Qualifiers** |**Random Numbers** | -| | | | -|* :ref:`>= <lang-comparison>` |* :ref:`variables <lang-variables>`, |* :ref:`randomSeed() <lang-randomseed>` | -| (greater than or equal to) | :ref:`scope <lang-variables-scope>` | | +|* :ref:`<= <lang-comparison>` |* :ref:`long() <lang-longcast>` | | +| (less than or equal to) | |**Random Numbers** | +| |* :ref:`float() <lang-floatcast>` | | +|* :ref:`>= <lang-comparison>` | |* :ref:`randomSeed() <lang-randomseed>` | +| (greater than or equal to) |* :ref:`double() <lang-doublecast>` | | | | |* :ref:`random() <lang-random>` | -| |* :ref:`static <lang-static>` | | -|**Boolean Operators** | | | -| |* :ref:`volatile <lang-volatile>` |**Bits and Bytes** | -|* :ref:`&& <lang-boolean-and>` (and) | | | -| |* :ref:`const <lang-const>` |* :ref:`lowByte() <lang-lowbyte>` | -|* :ref:`|| <lang-boolean-or>` (or) | | | -| | |* :ref:`highByte() <lang-highbyte>` is | -|* :ref:`\! <lang-boolean-not>` (not) |**Utilities** | provided, though its use is discouraged. | | | | | -| |* :ref:`sizeof() <lang-sizeof>` |* :ref:`bitRead() <lang-bitread>` | -|**Pointer Operators** | | | +|**Boolean Operators** |**Variable Scope & Qualifiers** | | +| | |**Bits and Bytes** | +|* :ref:`&& <lang-boolean-and>` (and) |* :ref:`variables <lang-variables>`, | | +| | :ref:`scope <lang-variables-scope>` |* :ref:`lowByte() <lang-lowbyte>` | +|* :ref:`|| <lang-boolean-or>` (or) | | | +| |* :ref:`static <lang-static>` |* :ref:`highByte() <lang-highbyte>` is | +|* :ref:`\! <lang-boolean-not>` (not) | | provided, though its use is discouraged. | +| |* :ref:`volatile <lang-volatile>` | | +| | |* :ref:`bitRead() <lang-bitread>` | +|**Pointer Operators** |* :ref:`const <lang-const>` | | | | |* :ref:`bitWrite() <lang-bitwrite>` | |* :ref:`* dereference operator | | | -| <lang-pointer>` | |* :ref:`bitSet() <lang-bitset>` | +| <lang-pointer>` |**Utilities** |* :ref:`bitSet() <lang-bitset>` | | | | | -|* :ref:`& reference operator | |* :ref:`bitClear() <lang-bitclear>` | +|* :ref:`& reference operator |* :ref:`sizeof() <lang-sizeof>` |* :ref:`bitClear() <lang-bitclear>` | | <lang-pointer>` | | | | | |* :ref:`bit() <lang-bit>` | | | | | diff --git a/docs/source/libmaple.rst b/docs/source/libmaple.rst index b76c7c8..8cc39a3 100644 --- a/docs/source/libmaple.rst +++ b/docs/source/libmaple.rst @@ -2,8 +2,8 @@ .. _libmaple: -``libmaple`` Reference -====================== +``libmaple`` +============ .. image:: /_static/img/libmaple-screenshot-small.png :align: center @@ -35,7 +35,6 @@ wrappers and code to imitate the Arduino programming library. .. toctree:: :maxdepth: 2 - Unix Toolchain Quickstart <unix-toolchain> Guide to using GCC's ARM target <arm-gcc> .. TODO LATER create, style, and host a pure Doxygen libmaple diff --git a/docs/source/maple-ide-install.rst b/docs/source/maple-ide-install.rst index ce50c49..92d1a96 100644 --- a/docs/source/maple-ide-install.rst +++ b/docs/source/maple-ide-install.rst @@ -61,6 +61,13 @@ First, extract all the files in the ZIP file to a suitable location on your system (like your Desktop folder). Next, you have to install some drivers. Sorry! +.. note:: Note that while these instructions work on Windows XP, + changes in Windows 7 mean that you won't be able to install the IDE + without disabling driver signing on your computer. We're working + on resolving this situation. For now, `users on the forum have + reported some workarounds + <http://forums.leaflabs.com/topic.php?id=73>`_. + First, install DFU drivers (for uploading code to your Maple) using the following steps. diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst index ca902f3..08fa5c1 100644 --- a/docs/source/maple-quickstart.rst +++ b/docs/source/maple-quickstart.rst @@ -6,7 +6,7 @@ Maple Quickstart Guide ======================== -You'll need a `Maple board <http://leaflabs.com/store/>`_, a `mini-b +You'll need a `Maple board <http://leaflabs.com/store/>`_, a `Mini-B USB cable <http://www.google.com/products?q=mini-b+usb+cable>`_, a functional computer, and possibly root (or "administrator") access to that computer. diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst index e6039a2..836f777 100644 --- a/docs/source/unix-toolchain.rst +++ b/docs/source/unix-toolchain.rst @@ -8,7 +8,7 @@ This is a tutorial for using the Maple with a standard Unix toolchain. It's not necessary to do this in order to program the Maple; you can -always use our `IDE <maple-ide-install>`_ instead. +always :ref:`install the Maple IDE <maple-ide-install>` instead. You'll need a Maple board, a mini-b USB cable, a functional computer, and root access to that computer. This guide assumes you've had @@ -16,10 +16,10 @@ success with the IDE on your machine and that you are fairly comfortable with the Unix command line; some previous experience with editing your shell startup script (.bashrc, .tcshrc, etc.) and using `make <http://www.gnu.org/software/make/>`_ is recommended. For -generic installation/setup issues, the `IDE install -<http://leaflabs.com/docs/libmaple/install/>`_ and -:ref:`troubleshooting` pages may be helpful. If all else fails, try -our `forum`_, or `contact us directly`_\ ! +generic installation/setup issues, the :ref:`IDE installation +<maple-ide-install>` and :ref:`troubleshooting` pages may be +helpful. If all else fails, try our `forum`_, or `contact us +directly`_\ ! We currently have instructions for 32- and 64-bit Linux and OS X Snow Leopard. If you're on another Unix platform, Windows, or an earlier @@ -28,7 +28,7 @@ directions on your own. As a jumping off point, you might want to begin with these `stripped down distributions <http://static.leaflabs.com/pub/codesourcery/>`_ of the `CodeSourcery GCC compiler tools <http://www.codesourcery.com/sgpp/features.html>`_ -(including win32 versions). If you do have success on other platforms, +(including Win32 versions). If you do have success on other platforms, please post in the forums, so we can fold your tips into this document! @@ -55,7 +55,7 @@ First I'll give the commands to run, then explain:: You'll want to install a bunch of developer "basics" like :command:`make`, :command:`tar`, etc. A good catch-all for these -tools is the "build-essential" meta-package on most debian platforms: +tools is the "build-essential" meta-package on most Debian platforms: installing this fake package will pull in dozens of useful tools without bogging your system down too much. ``git-core`` is the name of the git package; `Git <http://git-scm.com/>`_ is a distributed code @@ -90,7 +90,7 @@ package; this could also be installed with `easy_install $ 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 + $ tar xvf gcc-arm-none-eabi-latest-linux32.tar.gz $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up This step is fairly straightforward: do a git clone of the `libmaple @@ -104,6 +104,9 @@ where you put the toolchain, make sure to preserve its internal directory layout, as the binaries make relative path calls and references. +After you're done, you'll probably want to update your shell startup +script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. + .. _toolchain-udev: **3. Install udev Rules** @@ -136,15 +139,11 @@ stated previously, this document assumes a general level of Unix aptitude on the part of the reader; if you're uncomfortable using Terminal (or if you don't know what that means), then you should probably stick with using the `Maple IDE -<http://leaflabs.com/docs/maple-ide/>`_ to develop programs. Some of -these software packages might be available on `MacPorts -<http://www.macports.org/>`_. The author had some bad experiences with -MacPorts a few years ago, though, and hasn't touched it since. Of -course, your mileage may vary. +<http://leaflabs.com/docs/maple-ide/>`_ to develop programs. **1. Collect and Install Tools** -You will need the following tools to get started: +You will need the following tools\ [#fmacports]_ to get started: 1. `XCode <http://developer.apple.com/technologies/xcode.html>`_: If you're reading this, you've probably already got this. Provides @@ -326,7 +325,7 @@ something like :file:`/dev/ttyACMXXX` on Linux or :file:`/dev/tty.usbmodemXXX` on OS X, but it might have a slightly different name on your system. To open up a session, run :: - $ screen /dev/tty-whatever-it-is + $ screen /dev/ttyXXX If the interactive test program built and uploaded correctly, you should be able to connect without any errors reported by @@ -335,20 +334,25 @@ there are a number of commands which demonstrate Maple peripheral features. As of October 2010, the HardwareSerial library is blocking, so using any commands which would write to the USART Serial ports will cause the program to hang. To exit the screen session, type :kbd:`C-a -C-\\` (control-a, followed by control-backslash), and type ``y`` when -prompted if you're sure. +C-\\` (control-a, followed by control-backslash) on Mac, or :kbd:`C-a +k` (control-a k) on Linux, and type ``y`` when prompted if you're +sure. -Using :command:`screen` in this way sometimes messes up your session. -If your shell starts acting up after you exit screen, you should be -able to fix it with :: +.. note:: - $ reset && clear + Using :command:`screen` in this way sometimes messes up your + terminal session on OS X. If your shell starts acting up after you + exit screen, you should be able to fix it with :: + + $ reset && clear .. _toolchain-projects: Starting your own projects -------------------------- +.. TODO fix the build-targets.mk mess, note the "library" target + So everything worked, and you want to start your own project? Great! It's easy. Just set the environment variable ``LIB_MAPLE_HOME`` in your shell startup script to point to the libmaple repository you @@ -402,87 +406,6 @@ TODO. For now see `this great guide <http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se, and the ``jtag`` Makefile target. -.. _toolchain-codeblocks: - -Do it all with Code::Blocks ---------------------------- - -.. TODO this really should reflect the new, more pleasant build system - -Optional. `Code::Blocks <http://www.codeblocks.org/>`_ is a generic -cross platform IDE. We don't personally use it for development, so we -haven't worked out all the kinks (e.g., debugging isn't integrated), -but it might be helpful for people who are allergic to `vim -<http://www.vim.org/>`_ and/or `Emacs -<http://www.gnu.org/software/emacs/>`_. The simple configuration -described here just calls down to the :file:`Makefile`, so follow the -above directions to get the command line tools configured (you'll -definitely need the arm-none-eabi-* tools on your ``PATH``), then -`install Code::Blocks <http://www.codeblocks.org/downloads/26>`_. You -can do this on Linux with:: - - $ 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 -"projects" file to the libmaple repository: you can try using that one -by copying it from :file:`support/codeblocks/libmaple.cbp` to the top -level directory, but no promises (it might be missing new source files -etc). It's probably worth reading through these instructions as well -to get a feel for how it all works. - -To create your own "libmaple" project, start with an "Empty Project" -with the "Folder to create project in" set to your -``LIB_MAPLE_HOME``. Make sure that the "Resulting filename" is in the -top level directory as well. - -.. image:: /_static/img/codeblocks_newproject.png - :align: center - :alt: Code::Blocks new project wizard - -Select the "GNU GCC Compiler" (it won't be used, anyway) and disable -the "Debug" configuration in the next window. Now you should have a -project with no files; add files by right clicking on the project in -the left panel file hierarchy and "Add files recursively". Import both -the :file:`wirish` and :file:`libmaple` directories recursively, then -add :file:`main.cpp` separately. - -.. image:: /_static/img/codeblocks_makefile.png - :align: center - :alt: Code::Blocks targets options - -Next we have to configure the Makefile targets. Go to the -"Properties..." menu under "Project" and check the "This is a custom -Makefile" box. Then go to the "Build targets" tab and create "ram" and -"flash" targets, both of type "Console application" and without the -Auto-generated filename prefixes or extensions. Set the Output -filename to :file:`support/codeblocks/program_flash.sh` and -:file:`support/codeblocks/program_ram.sh` respectively; these scripts -just call the program_ram/program_flash make targets and are a hack to -get the "run" button to upload code to the Maple. The IDE will warn -that these files will be overwritten, but they won't be. For both the -"flash" and "ram" targets, click the "Build options..." button (below -"Virtual targets..." etc) and go to the far right tab ("'Make' -commands"). Edit the Clean project/target line so it's just "clean" -(not "clean$target"), and set the "Build project/target" and "Compile -single file" commands to ``$make -f $makefile MAPLE_TARGET=$target`` -and ``$make -f $makefile MAPLE_TARGET=$target $file``, respectively. - -.. image:: /_static/img/codeblocks_maketargets.png - :align: center - :alt: Code::Blocks make targets - -Save all these changes, go back to the main IDE window, and try to -build/run. "Build" will compile everything, "Run" will run the upload -script in a terminal window (if there are problems they will flash by -very quickly; you can start Code::Blocks in a terminal window and -check the output in that base window if necessary), and "Rebuild" will -clean before rebuilding. - -.. image:: /_static/img/codeblocks_build.png - :align: center - :alt: Success! - .. _toolchain-exuberantly: Go forth exuberantly! @@ -491,3 +414,10 @@ Go forth exuberantly! Let us know what you come up with! Use #leaflabs on Twitter, post in the `forum`_, track us down in the real world, whatever. We love projects! + +.. rubric:: Footnotes + +.. [#fmacports] Some of these software packages might be available on + `MacPorts <http://www.macports.org/>`_. The author had some bad + experiences with MacPorts a few years ago, though, and hasn't + touched it since. Of course, your mileage may vary. |