aboutsummaryrefslogtreecommitdiffstats
path: root/source/maple-quickstart.rst
blob: a4bc55a8e91da32610e0a4d5be17941408a55b48 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
.. 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 <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:`troubleshooting page
<troubleshooting>` 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 <maple-ide-install>` 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
<maple-powering>` 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 <troubleshooting-throb>` 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
   <troubleshooting-perpetual-bootloader>`, 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 <http://everything2.com/title/Velvet+Elvis>`_.

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
<unix-toolchain>` 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
<http://twitter.com/#!/leaflabs>`_ on Twitter, post in the `forum`_,
post on `our wiki's Projects page
<http://wiki.leaflabs.com/index.php?title=Projects>`_, track us down
in the real world, whatever. We love projects!