diff options
Diffstat (limited to 'docs/source/maple-quickstart.rst')
| -rw-r--r-- | docs/source/maple-quickstart.rst | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst new file mode 100644 index 0000000..8184772 --- /dev/null +++ b/docs/source/maple-quickstart.rst @@ -0,0 +1,256 @@ +.. highlight:: sh + +.. _maple-quickstart: + +======================== + Maple Quickstart Guide +======================== + +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. + +If you have trouble along the way try the :ref:`install page +<maple-ide-install>` for more detailed download and installation +instructions, and the :ref:`troubleshooting page <troubleshooting>` +for help with some common problems. If all else fails, try our `forum +<http://forums.leaflabs.com>`_, or `contact us directly +<http://leaflabs.com/contact>`_! + +The major steps are: + +* :ref:`Download and install the IDE <maple-quickstart-download>` + +* :ref:`(Windows) Resolve driver issues <maple-ide-install-windows-drivers>` + +* :ref:`Run the IDE <maple-quickstart-run-ide>`, then :ref:`compile + and upload a simple Blink program <maple-quickstart-compile-blinky>` + +* Test the USB serial connection with a HelloWorld + +.. _maple-quickstart-download: + +1. Download the IDE +------------------- + +Choose the correct version for your operating system: + +.. list-table:: + :widths: 15 30 50 + :header-rows: 1 + + * - Platform + - Status + - IDE Package + * - Windows + - Tested on 32bit Windows XP + - `maple-ide-LATEST-windowsxp32.zip <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-windowsxp32.zip>`_ (about 75mb) + * - Linux + - Tested on Ubuntu 9.10 (64bit) and 10.04 (32bit) + - `maple-ide-LATEST-linux32.tgz <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-linux32.tgz>`_ (about 30mb) + + `maple-ide-LATEST-linux64.tgz <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-linux64.tgz>`_ (about 30mb) + * - Mac OSX + - Tested on Snow Leopard 10.6 (64bit and 32bit) + - `maple-ide-LATEST-macosx-10_6.dmg <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-macosx-10_6.dmg>`_ (about 40mb) + +.. note:: + + The Linux release requires that you have a Java runtime (JRE) + installed. If you're on Linux, don't have a JRE, and don't know how + to install one, see the :ref:`installation page + <maple-ide-install-java>`. + +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 <http://fsf.org/>`_; we are grateful to the `Arduino +<http://arduino.cc/>`_, `CodeSourcery +<http://www.codesourcery.com/>`_, `GNU <http://gnu.org/>`_, and +`OpenMoko <http://openmoko.com/>`_ developers, as well as many others, +who allow us to reuse their software. + +2. Install the IDE +------------------ + +**Windows:** + +First, extract all the files in the ZIP file to a suitable location on +your system (like your Desktop folder). + +Next, you'll have to install drivers; see the :ref:`installation page +<maple-ide-install-windows-drivers>` for more details. Sorry! + +**Linux:** + +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. For instructions +on installing a JRE, try the :ref:`installation page +<maple-ide-install-java>` or searching the package manager for your +distribution. + +Next, run the script :file:`install-udev-rules.sh` in the extracted +IDE directory. It will ask for root permissions. You now need to +restart udev:: + + sudo /etc/init.d/udev restart + +This will grant members of the group ``plugdev`` read/write access to +Maple devices over USB. Make sure that you are in that group. (For +more information on why this is part of the install process, see the +:ref:`Unix toolchain quickstart <toolchain-udev>`). + +**OS X:** + +Double-click on the :file:`.dmg` file you downloaded in :ref:`Step 1 +<maple-quickstart-download>`. + +Next, drag and drop the Maple IDE icon into your computer's +Applications folder. + +.. _maple-quickstart-run-ide: + +3. Run the IDE +-------------- + +**Windows:** + +Double-click on the :command:`maple-ide` program from within the +extracted IDE directory. + +**Linux:** + +Run :file:`maple-ide` from the shell, or double click on it if your +window system supports it. + +**OS X:** + +Double-click the :command:`Maple IDE` application you dragged into +your computer's :file:`Applications` folder. + +.. _maple-quickstart-compile-blinky: + +4. 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": + +.. image:: /_static/img/blinky-to-flash.png + :align: center + :alt: Upload to FLASH + +.. note:: + + You have the option between RAM and FLASH programming: FLASH saves + the program into permanent memory so the program will be run every + time the Maple is reset, while RAM simply injects the compiled + program into the processor's memory. + + Programming to RAM is faster to upload and a buggy program can be + wiped away with a simple reset, while FLASH memory is larger and is + the only option for permanently uploading a program. + +.. image:: /_static/img/verify_button.png + :align: left + :alt: Verify button + +Now press the "verify" button (furthest to the left with a "play" +arrow) 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. + +5. Upload that program! +----------------------- + +Now it's (finally!) time to plug in your Maple. Use a mini-b cable, +making sure that the power source jumper is on the USB header +first. + +The Maple should blink a short pattern on the blue status LED every +time it is plugged in, reset, or reprogrammed, just to let you know +it's there. If it ever starts throbbing in a slow, smooth pattern that +means you've got a problem: see the troubleshooting page. + +On OS X, a modem setup dialog will pop up every time you plug in the +Maple. If you go to System Preferences Network Settings and accept +the default ("unconfigured") settings, the dialog won't pop up and +everything will work fine. + +If all systems are go, select the Board type and Serial Port +(something like /dev/ttyACM0, /dev/cu.usbmodem5d21, or COM3 depending +on your platform) from the Tools menu. Then press the "upload" button +(right arrow to a bunch of dots) to upload your program to the +Maple. You should see some text and a progress bar flash by in the +status window of the IDE, then some blinky patterns on the Maple, and +then a constant blink with whatever time period you programmed in +above. + +Go ahead and modify the file a little bit: if you change the +'delay(1000);' numbers to a different value the speed of the blink +will change. The value 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. + +.. warning:: + + This 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 + <troubleshooting-perpetual-bootloader>`, or restarting the + IDE. + + Please report any problems in the forums. If we don't know it's + broken, we can't fix it! + +6. 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 Maple +back to the IDE over the USB connection. From File select Examples, +Stubs, HelloWorld, and make sure the correct board and serial port +targets are selected from the Tools pull-down. And of course you could +change the text to be printed out; make sure you leave the double +quotes around it though or you'll get a compile error. + +Open the serial monitor window (button on the far right) and make sure +the 9600 baud speed is selected. Then go back to the code editing +window and upload your program (upload will recompile your code +automatically if there's been any change since the last "verify"). You +should get text spit at you over the serial monitor right after the +program is uploaded. Shout back! We can hear you! + +7. Go forth exuberantly! +------------------------ + +We really hope you got this far and didn't frown or make a bitter +lemon face too often 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 and has more than a 100 lines of vim or emacs +customization and doesn't even have a mouse plugged into your computer +you may want to look at the Unix Toolchain quickstart guide to getting +working with your old friends make, jtag, and gcc. + +Let us know what you come up with! Tag internet content with +#leaflabs, post in the forums, track us down in the real world, +whatever. We love projects! |