From 239f77ce49fb0a11c6ef2b59825c7e772ebad11e Mon Sep 17 00:00:00 2001 From: bnewbold Date: Wed, 27 Aug 2014 18:15:33 -0400 Subject: docs: first pass removal of Maple IDE info --- docs/copy-to-ide | 9 -- docs/source/_templates/indexcontent.html | 9 +- docs/source/adc.rst | 2 - docs/source/arm-gcc.rst | 13 +- docs/source/bootloader.rst | 11 +- docs/source/contents.rst | 3 - docs/source/gpio.rst | 2 +- docs/source/ide.rst | 166 ------------------------ docs/source/lang/api/random.rst | 3 +- docs/source/lang/api/randomseed.rst | 3 +- docs/source/lang/cpp/goto.rst | 2 +- docs/source/lang/cpp/scope.rst | 5 +- docs/source/libmaple.rst | 8 +- docs/source/libraries.rst | 4 +- docs/source/libs/servo.rst | 3 - docs/source/libs/wire.rst | 4 +- docs/source/maple-ide-install.rst | 176 -------------------------- docs/source/maple-quickstart.rst | 210 ------------------------------- docs/source/troubleshooting.rst | 23 +--- docs/source/unix-toolchain.rst | 20 +-- docs/source/usb.rst | 8 +- docs/source/whats-new.rst | 2 +- 22 files changed, 34 insertions(+), 652 deletions(-) delete mode 100755 docs/copy-to-ide delete mode 100644 docs/source/ide.rst delete mode 100644 docs/source/maple-ide-install.rst delete mode 100644 docs/source/maple-quickstart.rst (limited to 'docs') diff --git a/docs/copy-to-ide b/docs/copy-to-ide deleted file mode 100755 index 6cd4bdd..0000000 --- a/docs/copy-to-ide +++ /dev/null @@ -1,9 +0,0 @@ -#!/bin/sh - -IDE_DIRECTORY=$1 - -REFERENCE=$IDE_DIRECTORY/build/shared/reference - -echo copying built docs... -cp -R build/html/* $REFERENCE -echo done diff --git a/docs/source/_templates/indexcontent.html b/docs/source/_templates/indexcontent.html index a043f8a..6724303 100644 --- a/docs/source/_templates/indexcontent.html +++ b/docs/source/_templates/indexcontent.html @@ -21,8 +21,7 @@ release }}.

Read This First

-

Just getting started? Try the Quickstart. Having problems? Check +Having problems? Check out Troubleshooting and the FAQ. Can't find what you want here? Look on the LeafLabs @@ -38,12 +37,6 @@ changes that are new in {{ release }}.

Getting Started

 diff --git a/docs/source/adc.rst b/docs/source/adc.rst index 937b178..70417ea 100644 --- a/docs/source/adc.rst +++ b/docs/source/adc.rst @@ -15,8 +15,6 @@ ADC On Maple ------------ Doing analog-to-digital conversion on the Maple is simple. -:ref:`Maple IDE ` contains a basic example. To see it, choose -Analog > AnalogInSerial from the :ref:`examples menu `. In order to set up your board for conversion, first connect the wire (potentiometer, etc.) with the voltage you want to measure to a diff --git a/docs/source/arm-gcc.rst b/docs/source/arm-gcc.rst index 30667a2..959f5c3 100644 --- a/docs/source/arm-gcc.rst +++ b/docs/source/arm-gcc.rst @@ -16,9 +16,6 @@ not intended as a reference manual for GCC; such manuals are available Obtaining ``arm-none-eabi-gcc`` ------------------------------- -Recent versions of ``arm-none-eabi-gcc`` and associated tools are -included with the :ref:`Maple IDE `. - Users who wish to use ``arm-none-eabi-gcc`` directly, along with a standard Unix Make-based toolchain, should read the :ref:`unix-toolchain`, which describes how to set up such an @@ -35,10 +32,9 @@ Compiler Flags Used by libmaple ------------------------------- This section documents the flags passed to ``arm-none-eabi-gcc`` by -the :ref:`Maple IDE ` and the default Makefile provided with the -:ref:`Unix toolchain `. The information in this -section is subject to change between :ref:`libmaple ` -releases. +the default Makefile provided with the :ref:`Unix toolchain `. +The information in this section is subject to change between :ref:`libmaple +` releases. .. highlight:: sh @@ -63,8 +59,7 @@ The following flags are among those passed to the assembler:: Using the C Standard Library ---------------------------- -By default (under both the :ref:`Maple IDE ` and the :ref:`Unix -toolchain `), ``arm-none-eabi-gcc`` is configured to +By default, ``arm-none-eabi-gcc`` is configured to link against `newlib `_, a C standard library intended for use with embedded applications. You are free to include of any of its headers. diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst index 23b0448..a4ab5c9 100644 --- a/docs/source/bootloader.rst +++ b/docs/source/bootloader.rst @@ -586,8 +586,8 @@ Flashing A Custom Bootloader .. warning:: This section is for users who want to put a fresh or custom bootloader on their board. It's possible to make a mistake - in this process and e.g. render your Maple unable to communicate - with the IDE. Know what you're doing, and proceed with caution. + in this process and e.g. render your Maple unable to communicate. + Know what you're doing, and proceed with caution. The STM32 microprocessor on the Maple comes with a built-in serial bootloader that can be used to flash a new (software) bootloader onto @@ -721,13 +721,6 @@ You can also run the following to get usage information:: If all goes well, you'll see a bunch of output, then "Verification OK". Your board now has a fresh bootloader installed. -The first time you upload a program after installing a new bootloader, -there is no need to select a serial port in the :ref:`IDE ` -[#fbootser]_. Perform this first upload with no serial port selected. -The IDE will emit a warning about not finding a serial port, but the -upload will still succeed. In subsequent uploads, select a serial -port as you normally would. - If something goes wrong, the `forum`_ is probably your best bet for obtaining help, with IRC (server irc.freenode.net, channel #leafblowers) being another option. If all else fails, you can always diff --git a/docs/source/contents.rst b/docs/source/contents.rst index 7be7aec..0738d28 100644 --- a/docs/source/contents.rst +++ b/docs/source/contents.rst @@ -10,9 +10,6 @@ Contents in Full .. toctree:: :maxdepth: 2 - maple-quickstart - maple-ide-install - ide unix-toolchain unix-toolchain-linux-setup unix-toolchain-osx-setup diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst index caaae3d..929173e 100644 --- a/docs/source/gpio.rst +++ b/docs/source/gpio.rst @@ -62,7 +62,7 @@ letter and bit number. For instance, "PA4" is GPIO port A, bit 4. Pin Maps -------- -Part of :ref:`Maple IDE's ` job is to convert normal pin numbers +Part of the library's job is to convert normal pin numbers into the corresponding GPIO port and bit when you call functions like :ref:`lang-pinmode`. It does this using a *pin map*, which lists the GPIO port and bit for each pin number. The GPIO documentation for diff --git a/docs/source/ide.rst b/docs/source/ide.rst deleted file mode 100644 index e6d49fc..0000000 --- a/docs/source/ide.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. _ide: - -Using Maple IDE -=============== - -This page documents the basic functionality of the Maple IDE. -Specifically, it describes the operation of the buttons on the main -toolbar. It is expected to become more comprehensive over time. - -If you're new to Maple, you should begin with the :ref:`Maple -Quickstart `. - -If you need to install the IDE for the first time, see the -:ref:`maple-ide-install` page. - -.. contents:: Contents - :local: - -IDE Windows ------------ - -The following screenshot shows the appearance of a Maple IDE window: - -.. figure:: /_static/img/ide-blinky.png - :align: center - :alt: Maple IDE - -Note the toolbar buttons at the top; they're the icons with circles or -squares around them. You can program your board mostly through the -use of these buttons, which are described in the next section. - -Toolbar Buttons ---------------- - -.. _ide-verify: - -Verify -~~~~~~ - -.. image:: /_static/img/button-verify.png - :align: left - -Click Verify to compile the current sketch. This will process your -program and produce an executable which can run on your board. - -.. _ide-stop: - -Stop -~~~~ - -.. image:: /_static/img/button-stop.png - :align: left - -Click Stop to cancel a compilation. Longer programs may take a while -to compile. Clicking Stop will let you go back to writing code -without having to wait for compilation to finish. - -.. _ide-new: - -New -~~~ - -.. image:: /_static/img/button-new.png - :align: left - -Click New to make a fresh sketch. - -.. _ide-open: - -Open -~~~~ - -.. image:: /_static/img/button-open.png - :align: left - -Click Open to open an existing sketch. Maple IDE will first look for -the sketch in your *sketchbook*, which is a folder on your computer -that contains your sketches. The sketchbook is stored in different -places depending on your operating system. You can change its -location in the IDE's preferences. - -.. _ide-save: - -Save -~~~~ - -.. image:: /_static/img/button-save.png - :align: left - -Click Save to save the currently opened sketch. This will save all -open tabs, not just the one you're currently looking at. - -.. _ide-upload: - -Upload -~~~~~~ - -.. image:: /_static/img/button-upload.png - :align: left - -Click Upload to send the compiled sketch to your Maple to run. Before -you click Upload, you must have a memory location and serial port -selected. - -The memory location, either Flash or RAM, determines whether the -compiled sketch binary will be stored on the Maple. You can choose -this using the Tools > Board menu. - -The serial port corresponds to the :ref:`SerialUSB ` -connection the Maple establishes with your computer. This looks like -"COM1", "COM2", etc. on Windows, "/dev/tty.usbmodemXXX" on Mac (where -"XXX" is some sequence of letters and numbers), or "/dev/ttyACMXXX" on -Linux (again, where "XXX" is some sequence of letters and numbers). -You can choose a serial port using the Tools > Serial Port menu. - -If you're trying to upload and are unsuccessful, make sure you've made -choices for both board and serial port. More help on uploading -(including screenshots) is available in the :ref:`quickstart -`. - -If all else fails, try putting your Maple in :ref:`perpetual -bootloader mode ` before -uploading. You can always find us on the `forum`_ or `contact us -directly`_ for help on any problems you're having. - -.. _ide-serial-monitor: - -Serial Monitor -~~~~~~~~~~~~~~ - -.. image:: /_static/img/button-serial-monitor.png - :align: left - -Click Serial Monitor to open up a communication channel between your -PC and the Maple's :ref:`SerialUSB ` virtual serial -port. - -If the serial monitor is open, any information sent to the computer -(for example, using :ref:`SerialUSB.println() -`) will be displayed in the large text area. -You can send data to the Maple by typing into the small text box and -either hitting the Enter key or pressing the Send button. (The Maple -can read the data you send with :ref:`SerialUSB.read() -`). - -Here is an example serial monitor session with the InteractiveTest -sketch (which you can load in the IDE by choosing menu item File > -Examples > Maple > InteractiveTest): - -.. image:: /_static/img/serial-monitor.png - -This is the result of typing "?" in the text box and clicking Send. - -.. note:: You cannot upload a sketch while the serial monitor is open. - If you click :ref:`Upload ` while the serial monitor is - open, the IDE will close it for you before proceeding with the - upload. - -.. _ide-examples: - -Example Code ------------- - -Maple IDE comes with a variety of sample code you can use to help you -get started writing your own programs. To load an example in a new -Maple IDE window, choose one from the submenus under File > Examples. diff --git a/docs/source/lang/api/random.rst b/docs/source/lang/api/random.rst index 9875ee6..42b0112 100644 --- a/docs/source/lang/api/random.rst +++ b/docs/source/lang/api/random.rst @@ -46,8 +46,7 @@ Example The following sketch initializes the random seed based on an :ref:`ADC ` reading of pin 0. If this pin is unconnected, the Sketch -should print different values to the :ref:`serial monitor -` each time it is run:: +should print different values to the serial port monitor each time it is run:: long randNumber; diff --git a/docs/source/lang/api/randomseed.rst b/docs/source/lang/api/randomseed.rst index ca7b75f..86a4088 100644 --- a/docs/source/lang/api/randomseed.rst +++ b/docs/source/lang/api/randomseed.rst @@ -35,8 +35,7 @@ Example The following sketch initializes the random seed based on an :ref:`ADC ` reading of pin 0. If this pin is unconnected, the Sketch -should print different values to the :ref:`serial monitor -` each time it is run:: +should print different values to the serial port monitor each time it is run:: long randNumber; diff --git a/docs/source/lang/cpp/goto.rst b/docs/source/lang/cpp/goto.rst index 2c0b3b0..73dce80 100644 --- a/docs/source/lang/cpp/goto.rst +++ b/docs/source/lang/cpp/goto.rst @@ -44,7 +44,7 @@ be a label. Let's say that we wanted to print ``x`` only if it was very large, say at least 2000. We might want to do this just so anybody watching on a -:ref:`serial monitor ` would know they were in for +serial port monitor would know they were in for a longer wait than usual. We can accomplish this through the use of a ``goto`` statement that skips the printing if ``x`` is less than 2000:: diff --git a/docs/source/lang/cpp/scope.rst b/docs/source/lang/cpp/scope.rst index a270428..20e139f 100644 --- a/docs/source/lang/cpp/scope.rst +++ b/docs/source/lang/cpp/scope.rst @@ -19,7 +19,7 @@ Global and Local Variables -------------------------- A global variable is one that can be "seen" by every function in a -program. In the :ref:`Maple IDE `, any variable declared outside +program. In Wirish, any variable declared outside of a function (like :ref:`setup() ` and :ref:`loop() `) is a global variable. @@ -43,8 +43,7 @@ Example Here is an example sketch (which you can copy into the Maple IDE and run on your Maple) that illustrates the use of global and local variables, as well as declaring variables inside of a ``for`` loop. -Be sure to open a :ref:`serial monitor ` after you -:ref:`verify ` and :ref:`upload ` the sketch:: +Be sure to open a serial port monitor after you upload the sketch:: int globalVar; // any function will see this variable diff --git a/docs/source/libmaple.rst b/docs/source/libmaple.rst index 458241e..88c5d6b 100644 --- a/docs/source/libmaple.rst +++ b/docs/source/libmaple.rst @@ -32,12 +32,8 @@ AVR libraries written for the `Arduino `_ and available. :ref:`Wirish libraries ` are documented separately. -libmaple is bundled with the :ref:`Maple IDE `. However, we -develop it separately, and :ref:`release it standalone -` for users who might chafe at the "sketch" -programming model of the IDE. The following pages document libmaple -proper. As such, they're intended for advanced users who know how to -write C. +The following pages document libmaple. They are intended for advanced users who +know how to write C. .. toctree:: :maxdepth: 1 diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst index 1ae0e87..e4e8549 100644 --- a/docs/source/libraries.rst +++ b/docs/source/libraries.rst @@ -10,8 +10,8 @@ .. Note: if you port an Arduino library and document it here, be sure .. to update compatibility.rst to reflect that fact. -This page lists the extra libraries that are part of the :ref:`Maple -IDE ` (along with the rest of :ref:`libmaple `). You +This page lists the extra libraries that are part of +:ref:`libmaple `. You can use a library from within a sketch by going to Sketch > Import Library... from within the IDE, then choosing the library you want. diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst index 80288c6..549e86f 100644 --- a/docs/source/libs/servo.rst +++ b/docs/source/libs/servo.rst @@ -9,9 +9,6 @@ This documents the Servo library for controlling RC servomotors. It is implemented as a thin layer over the built-in :ref:`timer peripherals `. -You can use this library in the :ref:`IDE ` by choosing the Servo -item under the Sketch > Import Library... menu. - If you are using the :ref:`Unix toolchain `, the library is located in the ``/libraries/Servo/`` :ref:`libmaple` directory. diff --git a/docs/source/libs/wire.rst b/docs/source/libs/wire.rst index 2c5bed9..2b79e7c 100644 --- a/docs/source/libs/wire.rst +++ b/docs/source/libs/wire.rst @@ -7,9 +7,7 @@ Wire .. TODO [0.1.0] Format this correctly, using Breathe -This page documents the Wire library for the :ref:`i2c` protocol. You -can use this library in the :ref:`Maple IDE ` by choosing the -Wire item under the Sketch > Import Library... menu. +This page documents the Wire library for the :ref:`i2c` protocol. If you are using the :ref:`Unix toolchain `, the library is located in the ``/libraries/Wire/`` :ref:`libmaple` diff --git a/docs/source/maple-ide-install.rst b/docs/source/maple-ide-install.rst deleted file mode 100644 index 7e9bfa2..0000000 --- a/docs/source/maple-ide-install.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. highlight:: c++ - -.. _maple-ide-install: - -======================== - Maple IDE Installation -======================== - -If you still can't get the IDE installed after reading this page, -check the :ref:`troubleshooting page ` for help with -some common problems. If all else fails, try our `forum`_, or `contact -us directly`_\ ! - -.. contents:: Contents - :local: - -Download --------- - -.. FIXME [RELEASE] Update this for the release. - -This documentation was built from a development version of libmaple. -See the formally released `LeafLabs documentation -`_ for more information about the current -Maple IDE release. - -.. Choose the correct version for your operating system: - -.. .. list-table:: -.. :widths: 15 30 -.. :header-rows: 1 - -.. * - Platform -.. - Status -.. - IDE Package -.. * - `Windows XP `_ -.. - Tested on Debian Wheezy (64-bit) and Mint 14.1 (64-bit) -.. * - `Linux `_ -.. - Tested on Ubuntu 10.04 (32-bit) -.. * - `Mac OS X `_ -.. - Tested on Snow Leopard (10.6) - -The package bundles together a compiler, an upload utility, a software -library, and a simple GUI text editor. All this software is `free and -open `_; we are grateful to the `Arduino -`_, `CodeSourcery -`_, `GNU `_, and -`OpenMoko `_ developers, as well as many others, -who allow us to reuse their software. - -**Looking for something older?** `Source archives and binaries -`_ are available -for previously-released versions. - -Installation ------------- - -* :ref:`Windows ` -* :ref:`Linux ` -* :ref:`OS X ` - -.. _maple-ide-install-windows: - -Windows XP (Legacy Only) -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. note:: Note that while these instructions work on Windows XP, - changes in Windows 7 (and later) mean that you won't be able to install the - IDE without disabling driver signing on your computer. - `Users on the forum have reported a workaround - `_, but we - only officially support the IDE on 32-bit Windows XP. - -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! - -.. _maple-ide-install-windows-drivers: - - -First, install DFU drivers (for uploading code to your Maple) using -the following steps. - -1. Plug your Maple into the USB port. - -2. Hit the reset button on your Maple (it's the small button at the - bottom left, labeled RESET). Notice that it blinks quickly 6 times, - then blinks slowly a few more times. - -3. Hit reset again, and this time push and hold the other button - during the 6 fast blinks (the button is on the top right; it is - labeled BUT). You can release it once the slow blinks start. - -4. Your Maple is now in :ref:`perpetual bootloader mode - `. This should give you a - chance to install the DFU drivers. - -5. Windows should now prompt you for some drivers. In the top level - directory of the Maple IDE, point Windows to - :file:`drivers/mapleDrv/dfu/`. - -Next, install serial drivers (for communicating with your Maple using -serial over USB). - -1. Reset your Maple and allow it to exit the bootloader (wait for the - slow blinking to stop). The Maple will next start running whatever - program was uploaded to it last. (New Maples will start running the - test program we upload to them before shipping them to you). - -2. Once Maple is running some user code, Windows should prompt you for - more drivers. Point windows to :file:`driver/mapleDrv/serial`. - -You can now run the Maple IDE by double-clicking on the -:command:`maple-ide` program from within the extracted IDE directory. - -.. _maple-ide-install-linux: - -Linux -^^^^^ - -.. _maple-ide-install-java: -.. note:: - - The IDE is written in Java and requires a compatible runtime (JRE). - - If you don't have one, they're usually pretty easy to install. - Oracle Java 1.6 and OpenJDK 1.6 are known to work, and runtimes - mostly compatible with Oracle Java 1.5+ should probably get the job - done. - - To install Java, try using your distribution's software packaging - tool and search for "JRE" or "java". On Debian-based systems - (including Ubuntu) you can try to install the OpenJDK 1.6 JRE - with:: - - $ sudo aptitude install openjdk-6-jre - -Extract the tarball to an appropriate location (like your home -directory or desktop). - -Make sure you have a Java runtime (JRE) installed; if you can run -:command:`java` from the shell, you should be fine. - -Next, run the script :file:`install-udev-rules.sh` in the extracted -IDE directory. It will ask for root permissions (you will be prompted -with something along the lines of ``[sudo] password for -:``). You now need to restart udev:: - - $ sudo restart udev - -This will grant members of the group ``plugdev`` read/write access to -Maple devices over USB. Make sure that you are in that group by -running ``$ sudo adduser plugdev`` (which will ensure -access to the Maple, but may report that you are already a member of -that group). (For more information on why this is part of the install -process, see the :ref:`Unix toolchain quickstart `). - -To run the Maple IDE, run :command:`maple-ide` from the shell, or -double-click on it if your window system supports it. - -Feel free to put the IDE directory wherever you want. As long as you -leave its internal structure unchanged, things should be fine. - -.. _maple-ide-install-osx: - -OS X -^^^^ - -Double-click on the :file:`.dmg` file you downloaded to mount the disk -image. From the mounted image, drag and drop the Maple IDE icon into -your computer's Applications folder. - -To run the Maple IDE, double-click the :command:`Maple IDE` -application you dragged into your computer's :file:`Applications` -folder. - diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst deleted file mode 100644 index a4bc55a..0000000 --- a/docs/source/maple-quickstart.rst +++ /dev/null @@ -1,210 +0,0 @@ -.. highlight:: sh - -.. _maple-quickstart: - -======================== - Maple Quickstart Guide -======================== - -.. TODO [0.0.13]: Update the images; e.g., "to FLASH" is now "to Flash" -.. -.. Consider putting the images as a bundle somewhere under -.. static.leaflabs.com that gets downloaded and unpacked if they are -.. not present, but don't get crazy. - -You'll need a `Maple board `_, a `Mini-B -USB cable `_, a -functional computer, and possibly root (or "administrator") access to -that computer. - -If you have trouble along the way, try the :ref:`troubleshooting page -` for help with some common problems. If all else -fails, try our `forum`_, or `contact`_ us directly! - -.. contents:: Contents - :local: - -.. _maple-quickstart-get-ide: - -Install and run the IDE ------------------------ - -See the :ref:`IDE installation page ` for instructions. - -.. _maple-quickstart-compile-blinky: - -Compile a program! ------------------- - -Let's load up a simple example program that blinks the status LED. -From the File menu, select Examples > Digital > Blink: - -.. image:: /_static/img/blinky.png - :align: center - :alt: Click "Blink" - -Next, select Tools > Board > "LeafLabs Maple ... to Flash", where -"..." depends on the board you're using. - -.. image:: /_static/img/blinky-to-flash.png - :align: center - :alt: Upload to Flash - -.. note:: - - You have the choice between Flash and RAM programming. Flash saves - the program into permanent Flash memory. RAM simply puts the - compiled program into the processor's built-in RAM. - - Flash memory is larger, and is the only option for permanently - uploading a program. Programming to RAM is faster to upload, and a - buggy program can be wiped away with a simple reset. - -.. image:: /_static/img/verify_button.png - :align: left - :alt: Verify button - -Now press the "Verify" button (the "play" symbol; see image at left) -to compile the code. Some output should scroll by in the bottom -window, and then a confirmation message will appear: - -.. image:: /_static/img/verify-success.png - :align: center - :alt: Code verified successfully. - -.. _maple-quickstart-upload: - -Upload that program! --------------------- - -Now it's time to plug in your Maple. Use a USB Mini-B cable (mini, -not micro). - -On the Maple, make sure that the :ref:`power source jumper -` is on the USB header first (the same goes for Maple -Native). We ship Maples with the power source jumper configured that -way, so you shouldn't have to do anything. For reference, it should -look like this (don't worry if a jumper is hanging half off of the -CHRG header): - -.. image:: /_static/img/plugged-in-maple.png - :align: center - :alt: Correctly plugged in Maple - -.. note:: - - On OS X, a network interface dialog will pop up every time you plug in - the board. - - .. image:: /_static/img/osx-unconfigured-popup.png - :align: center - :alt: Unconfigured modem popup - - If you click "Network Preferences..." and accept the default ("Not - Configured"), the dialog won't pop up and everything will work fine. - That is, from this window, click "Apply": - - .. image:: /_static/img/osx-network-prefs-unconfigured.png - :align: center - :scale: 75% - :alt: Click "Apply" - -If all systems are go, select your board's serial port in the Tools > -Serial Port menu. It will appear as something like :file:`COMx`, -:file:`/dev/ttyACMx`, or :file:`/dev/tty.usbmodemxxxxx`, depending on -your platform, like so: - -Windows XP: - -.. image:: /_static/img/serial-port-win.png - :align: center - :alt: Board type and serial port for Windows XP - -Linux: - -.. image:: /_static/img/serial-port-ubuntu.png - :align: center - :alt: Board type and serial port for Linux - -OS X: - -.. image:: /_static/img/serial-port-mac.png - :align: center - :alt: Board type and serial port for the OS X - -Then press the "Upload" button to upload your program over USB. - -.. image:: /_static/img/upload-button.png - :align: center - :alt: Click the "Upload" button - -You should see some text and a progress bar flash by in the status -window of the IDE, then some quick blinking patterns, followed a -constant blinking on and off. Congratulations! You've successfully -uploaded your first program to your Maple. - -The built-in status LED should blink in a short pattern every time the -board is plugged in, reset, or reprogrammed. If it ever starts -throbbing in a smooth, even pattern, then you've got a problem; see -this :ref:`troubleshooting item ` for help. - -Next, go ahead and modify the file a little bit. If you change the -number in the ``delay(1000);`` lines, the speed of the blink will -change. The number is a time in milliseconds to pause before -continuing with the program, so by default, the LED will be on for 1 -second, then off for 1 second, etc. Any time you make any changes, go -through the same Verify and Upload process to upload the new version -of your program to your Maple. - -.. warning:: - - The uploading step is the most common source of problems, - especially on Windows. - - The situation is much improved over the past, but if you have - trouble, try doing things again, unplugging your Maple and plugging - it back in, using :ref:`perpetual bootloader mode - `, or restarting the - IDE. - - If nothing works, please report the problem in the `forum`_. - -.. _maple-quickstart-serial-port: - -Use the serial port monitor! ----------------------------- - -As a last step to make sure everything has been configured correctly, -let's upload a "Hello, world!" program that will send text from the -board back to the IDE over the USB connection. - -From the File menu, select Examples > Stubs > HelloWorld (similarly to -how you selected the Blink program), and make sure the correct board -and serial port targets are selected from the Tools menu. - -Open the Serial Monitor window (on the far right of the toolbar). Then -go back to the code editing window and upload your program. You should -get text spit at you over the serial monitor right after the program -is uploaded. Shout back! We can hear you! - -Go forth exuberantly! ---------------------- - -We really hope you got this far and didn't frown or make a bitter -lemon face getting here. Where you go now is up to you: perhaps you've -got some crazy project cooking, or a longer tutorial to work through, -or maybe now is a good time for a trip to the kitchen for a delicious -`sandwich `_. - -If you blew through this guide and are the kind of person who drinks -their coffee straight, has more than a 100 lines of vim or emacs -customization, and doesn't even have a mouse plugged into their -computer, you may want to look at the :ref:`Unix toolchain quickstart -` guide. It's the tutorial for getting working with -your old friends :command:`make`, :command:`gcc`, and :command:`jtag`. - -Let us know what you come up with! Reach us at `leaflabs -`_ on Twitter, post in the `forum`_, -post on `our wiki's Projects page -`_, track us down -in the real world, whatever. We love projects! diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 4d7cbb0..181c3d4 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -45,8 +45,7 @@ My board is bricked! I can't upload via the bootloader no matter what! ---------------------------------------------------------------------- Don't panic. First, make sure that the board is plugged in correctly -for program upload, using the instructions given in the -:ref:`quickstart `. If that doesn't work, +for program upload. If that doesn't work, try using :ref:`perpetual bootloader mode `. @@ -94,21 +93,10 @@ the serial bootloader, but we haven't tried. ------------------------- There is probably a simple way to get autoconfiguration working with -devfs; in the meantime, you could try running the entire IDE as root. +devfs; in the meantime, you could try running the programmer as root. .. TODO: be more helpful -.. _troubleshooting-ide-usage: - -============== - IDE problems -============== - -[Mac OS X] The "Board" and "Serial Port" menu items are missing! ----------------------------------------------------------------- - -Sometimes this happens if you try to compile or upload without having -a board selected. The work-around is to restart the IDE. Mysterious! .. _troubleshooting-compilation: @@ -130,9 +118,8 @@ found by the compiler. Your program must include both ``void setup()`` and ``void loop()`` functions; they don't have to do anything, but they **must** be there. -You can start with an example program (to see one in the IDE, click on -File > Examples > Stubs > BareMinimum) to get the basic structure. -See also the :ref:`language ` documentation. +You can start with an example program (``./examples``) to get the basic +structure. See also the :ref:`language ` documentation. This is a common error when your entire sketch is blank. @@ -176,7 +163,7 @@ This can also happen if you disable the USB peripheral, e.g. using I have multiple boards plugged in; how do I know which one will get programmed? ------------------------------------------------------------------------------- -Because the Maple IDE uses DFU to upload programs, you can't select a +Because the programmer uses DFU to upload programs, you can't select a particular board to upload to. There's no solution to this problem for now: you'll have to just plug in your boards one at a time. If this is a real problem, let us know, and we'll see if we can come up diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst index 769b8ec..6e20218 100644 --- a/docs/source/unix-toolchain.rst +++ b/docs/source/unix-toolchain.rst @@ -8,8 +8,7 @@ This is a tutorial for using a standard Unix toolchain (``make``, ``gcc``, etc.) with Maple. It's intended for C and C++ programmers -who want to use :ref:`libmaple` directly. If you're just beginning, we -recommend installing :ref:`Maple IDE ` instead. +who want to use :ref:`libmaple` directly. .. contents:: Contents :local: @@ -17,9 +16,7 @@ recommend installing :ref:`Maple IDE ` instead. Requirements ------------ -We assume you've had success with the :ref:`Maple IDE ` (this is -important on Windows, as this document doesn't cover :ref:`driver -installation `). +For Windows, you will somehow need to install drivers. At a minimum, you need: @@ -182,8 +179,7 @@ over a :ref:`USB serial port `. * Linux: you need udev rules set up :ref:`as described in the setup doc `. -* Windows: you need to :ref:`install the Maple's device drivers - `. +* Windows: you need to somehow install drivers. * OS X: everything Just Works for you. Aren't you special? @@ -229,8 +225,7 @@ To open up a session on Linux or OS X, run :: $ screen /dev/ttyXXX -(On Windows, you will need to use a separate program, such as Maple -IDE's serial console or `PuTTY +(On Windows, you will need to use a separate program, such as `PuTTY `_.) ``screen`` will present you an empty terminal. Your board is waiting @@ -318,11 +313,8 @@ We do our best to keep the master libmaple branch on GitHub free from broken or half-finished code, so don't be too scared running the latest and greatest. If you do, please report any bugs or regressions! -We keep releases of libmaple and the Maple IDE in lockstep, so any IDE -updates will have corresponding library updates. Our `blog -`_ is the place to watch for major -releases; an `RSS feed `_ is -available. +Our `blog `_ is the place to watch for major +releases; an `RSS feed `_ is available. You can sign up for a free `GitHub `_ account and `watch libmaple diff --git a/docs/source/usb.rst b/docs/source/usb.rst index 80c40ca..70ca92e 100644 --- a/docs/source/usb.rst +++ b/docs/source/usb.rst @@ -9,9 +9,9 @@ The STM32 microprocessors include a dedicated USB peripheral which can be configured to act as a general USB slave device with transfer rates up to 12Mbps. (It unfortunately can't be configured as a host or on-the-go device). By default, the peripheral is configured for two -uses: first, to receive sketch/program uploads from the :ref:`IDE -`, and second, to emulate a regular serial port for use as a -terminal (text read/write). +uses: first, to receive sketch/program uploads from the programming utility, +and second, to emulate a regular serial port for use as a terminal (text +read/write). The emulated terminal is relatively slow and inefficient; it is best for transferring data at regular serial speeds (kilobaud). Library @@ -22,7 +22,7 @@ The SerialUSB channel is used with the :ref:`Maple bootloader ` to reprogram the board: a :ref:`magic sequence of control line toggles and transmitted data ` causes a Maple to reset itself and enter bootloader mode. As an unfortunate -consequence, the auto-reset will not work if the IDE can not access +consequence, the auto-reset will not work if the programmer can not access the serial port, either due to a conflict with another program (serial monitor) or because the interface has been disabled from the Maple side (through :ref:`SerialUSB.end() `). A diff --git a/docs/source/whats-new.rst b/docs/source/whats-new.rst index c7d10c5..02127d9 100644 --- a/docs/source/whats-new.rst +++ b/docs/source/whats-new.rst @@ -5,7 +5,7 @@ What's New .. FIXME [RELEASE] finish. -This page tracks updates to libmaple and MapleIDE. +This page tracks updates to libmaple. .. contents:: :local: -- cgit v1.2.3