altos: Add EasyMega v2.0 to default build
[fw/altos] / doc / updating-firmware.inc
1 [appendix]
2 == Updating Device Firmware
3
4         ifdef::telemega[]
5         TeleMega, TeleMetrum v2, EasyMega, EasyMini and TeleDongle v3
6         are all
7         endif::telemega[]
8         ifndef::telemega[]
9         EasyMini is
10         endif::telemega[]
11         programmed directly over their USB connectors (self
12         programming).
13         ifdef::telemega[]
14         TeleMetrum v1, TeleMini v1.0 and TeleDongle v0.2 are
15         all programmed by using another device as a programmer (pair
16         programming). It's important to recognize which kind of devices
17         you have before trying to reprogram them.
18         endif::telemega[]
19
20         You may wish to begin by ensuring you have current firmware
21         images.  These are distributed as part of the AltOS software
22         bundle that also includes the AltosUI ground station program.
23         Newer ground station versions typically work fine with older
24         firmware versions, so you don't need to update your devices
25         just to try out new software features.  You can always
26         download the most recent version from
27         http://www.altusmetrum.org/AltOS/
28
29         ifdef::telemega[]
30         === Updating TeleMega, TeleMetrum v2, EasyMega, EasyMini or TeleDongle v3 Firmware
31         endif::telemega[]
32         ifndef::telemega[]
33         === Updating EasyMini Firmware
34         endif::telemega[]
35
36                 Self-programmable devices are reprogrammed by
37                 connecting them to your computer over USB.
38
39                 . Attach a battery if necessary and power switch to
40                   the target device. Power up the device.
41
42                 . Using a Micro USB cable, connect the target device to your
43                   computer's USB socket.
44
45                 . Run AltosUI, and select 'Flash Image' from the File menu.
46
47                 . Select the target device in the Device Selection dialog.
48
49                 . Select the image you want to flash to the device,
50                   which should have a name in the form
51                   <product>-v<product-version>-<software-version>.ihx,
52                   such as EasyMini-v1.0-1.6.0.ihx.
53
54                 . Make sure the configuration parameters are
55                   reasonable looking. If the serial number and/or RF
56                   configuration values aren't right, you'll need to
57                   change them.
58
59                 . Hit the 'OK' button and the software should proceed
60                   to flash the device with new firmware, showing a
61                   progress bar.
62
63                 . Verify that the device is working by using the
64                   'Configure Altimeter' or 'Configure Groundstation'
65                   item to check over the configuration.
66
67                 ==== Recovering From Self-Flashing Failure
68
69                         If the firmware loading fails, it can leave the device
70                         unable to boot. Not to worry, you can force the device to
71                         start the boot loader instead, which will let you try to
72                         flash the device again.
73
74                         On each device, connecting two pins from one of the exposed
75                         connectors will force the boot loader to start, even if the
76                         regular operating system has been corrupted in some way.
77
78                         ifdef::telemega[]
79                         TeleMega::
80
81                         Connect pin 6 and pin 1 of the companion
82                         connector. Pin 1 can be identified by the square pad
83                         around it, and then the pins could sequentially across
84                         the board. Be very careful to *not* short pin 8 to
85                         anything as that is connected directly to the
86                         battery. Pin 7 carries 3.3V and the board will crash
87                         if that is connected to pin 1, but shouldn't damage
88                         the board.
89                         endif::telemega[]
90
91                         ifdef::easymega[]
92                         EasyMega::
93
94                         Connect pin 6 and pin 1 of the companion
95                         connector. Pin 1 can be identified by the square pad
96                         around it, and then the pins could sequentially across
97                         the board. Be very careful to *not* short pin 8 to
98                         anything as that is connected directly to the
99                         battery. Pin 7 carries 3.3V and the board will crash
100                         if that is connected to pin 1, but shouldn't damage
101                         the board.
102                         endif::easymega[]
103
104                         ifdef::telemetrum[]
105                         TeleMetrum v2::
106
107                         Connect pin 6 and pin 1 of the companion
108                         connector. Pin 1 can be identified by the square pad
109                         around it, and then the pins could sequentially across
110                         the board. Be very careful to *not* short pin 8 to
111                         anything as that is connected directly to the
112                         battery. Pin 7 carries 3.3V and the board will crash
113                         if that is connected to pin 1, but shouldn't damage
114                         the board.
115                         endif::telemetrum[]
116
117                         ifdef::easymini[]
118                         EasyMini::
119
120                         Connect pin 6 and pin 1 of the debug connector, which
121                         is the six holes next to the beeper. Pin 1 can be
122                         identified by the square pad around it, and then the
123                         pins could sequentially across the board, making Pin 6
124                         the one on the other end of the row.
125                         endif::easymini[]
126
127                         ifdef::telemetrum[]
128                         TeleDongle v3::
129
130                         Connect pin 32 on the CPU to ground. Pin 32 is closest
131                         to the USB wires on the row of pins towards the center
132                         of the board. Ground is available on the capacitor
133                         next to it, on the end towards the USB wires.
134                         
135                         TeleBT v4::
136
137                         Connect pin 30 on the CPU to ground. Pin 30 is the 6th
138                         pin from the right on the top when the unit is oriented
139                         such that the SMA is at the top.
140                         endif::telemetrum[]
141
142                         Once you've located the right pins:
143
144                         . Turn the altimeter power off.
145
146                         . Connect a battery.
147
148                         . Connect the indicated terminals together with a
149                           short piece of wire. Take care not to accidentally
150                           connect anything else.
151
152                         . Connect USB
153
154                         . Turn the board power on.
155
156                         The board should now be visible over USB as
157                         'AltosFlash' and be ready to receive firmware.  Once
158                         the board has been powered up, you can remove the
159                         piece of wire.
160
161         ifdef::telemetrum,telemini[]
162         === Pair Programming
163
164                 The big concept to understand is that you have to use
165                 a TeleMetrum v1.0, TeleBT v1.0 or TeleDongle v0.2 as a
166                 programmer to update a pair programmed device. Due to
167                 limited memory resources in the cc1111, we don't
168                 support programming directly over USB for these
169                 devices.
170
171                 If you need to update the firmware on a TeleDongle
172                 v0.2, we recommend updating the altimeter first,
173                 before updating TeleDongle.  However, note that
174                 TeleDongle rarely need to be updated.  Any firmware
175                 version 1.0.1 or later will work, version 1.2.1 may
176                 have improved receiver performance slightly.
177
178                 ==== Updating TeleMetrum v1.x Firmware
179
180                         . Find the 'programming cable' that you got as
181                           part of the starter kit, that has a red
182                           8-pin MicroMaTch connector on one end and a
183                           red 4-pin MicroMaTch connector on the other
184                           end.
185
186                         . Take the 2 screws out of the TeleDongle v0.2
187                           or TeleBT v1.0 case to get access to the
188                           circuit board.
189
190                         . Plug the 8-pin end of the programming cable
191                           to the matching connector on the TeleDongle
192                           v0.2 or TeleBT v1.0, and the 4-pin end to
193                           the matching connector on the TeleMetrum.
194                           Note that each MicroMaTch connector has an
195                           alignment pin that goes through a hole in
196                           the PC board when you have the cable
197                           oriented correctly.
198
199                         . Attach a battery to the TeleMetrum board.
200
201                         . Plug the TeleDongle v0.2 or TeleBT v1.0 into
202                           your computer's USB port, and power up the
203                           TeleMetrum.
204
205                         . Run AltosUI, and select 'Flash Image' from
206                           the File menu.
207
208                         . Pick the TeleDongle v0.2 or TeleBT v1.0
209                           device from the list, identifying it as the
210                           programming device.
211
212                         . Select the image you want put on the
213                           TeleMetrum, which should have a name in the
214                           form telemetrum-v1.2-1.0.0.ihx.  It should
215                           be visible in the default directory, if not
216                           you may have to poke around your system to
217                           find it.
218
219                         . Make sure the configuration parameters are
220                           reasonable looking. If the serial number
221                           and/or RF configuration values aren't right,
222                           you'll need to change them.
223
224                         . Hit the 'OK' button and the software should
225                           proceed to flash the TeleMetrum with new
226                           firmware, showing a progress bar.
227
228                         . Confirm that the TeleMetrum board seems to
229                           have updated OK, which you can do by
230                           plugging in to it over USB and using a
231                           terminal program to connect to the board and
232                           issue the 'v' command to check the version,
233                           etc.
234
235                         If something goes wrong, give it another try.
236
237                 ==== Updating TeleMini v1.0 Firmware
238
239                         You'll need a special 'programming cable' to
240                         reprogram the TeleMini v1.0.  You can make your own
241                         using an 8-pin MicroMaTch connector on one end
242                         and a set of four pins on the other.
243
244                         . Take the 2 screws out of the TeleDongle v0.2
245                           or TeleBT v1.0 case to get access to the
246                           circuit board.
247
248                         . Plug the 8-pin end of the programming cable
249                           to the matching connector on the TeleDongle
250                           v0.2 or TeleBT v1.0, and the 4-pins into the
251                           holes in the TeleMini v1.0 circuit board.  Note
252                           that the MicroMaTch connector has an
253                           alignment pin that goes through a hole in
254                           the PC board when you have the cable
255                           oriented correctly, and that pin 1 on the
256                           TeleMini v1.0 board is marked with a square pad
257                           while the other pins have round pads.
258
259                         . Attach a battery to the TeleMini v1.0 board.
260
261                         . Plug the TeleDongle v0.2 or TeleBT v1.0 into
262                           your computer's USB port, and power up the
263                           TeleMini v1.0
264
265                         . Run AltosUI, and select 'Flash Image' from
266                           the File menu.
267
268                         . Pick the TeleDongle v0.2 or TeleBT v1.0
269                           device from the list, identifying it as the
270                           programming device.
271
272                         . Select the image you want put on the
273                           TeleMini v1.0, which should have a name in the
274                           form telemini-v1.0-1.0.0.ihx.  It should be
275                           visible in the default directory, if not you
276                           may have to poke around your system to find
277                           it.
278
279                         . Make sure the configuration parameters are
280                           reasonable looking. If the serial number
281                           and/or RF configuration values aren't right,
282                           you'll need to change them.
283
284                         . Hit the 'OK' button and the software should
285                           proceed to flash the TeleMini v1.0 with new
286                           firmware, showing a progress bar.
287
288                         . Confirm that the TeleMini v1.0 board seems to
289                           have updated OK, which you can do by
290                           configuring it over the radio link through
291                           the TeleDongle, or letting it come up in
292                           “flight” mode and listening for telemetry.
293
294                         If something goes wrong, give it another try.
295
296                 ==== Updating TeleDongle v0.2 Firmware
297
298                 Updating TeleDongle v0.2 firmware is just like
299                 updating TeleMetrum v1.x or TeleMini v1.0 firmware, but you
300                 use either a TeleMetrum v1.x, TeleDongle v0.2 or
301                 TeleBT v1.0 as the programmer.
302
303                 . Find the 'programming cable' that you got as part of
304                   the starter kit, that has a red 8-pin MicroMaTch
305                   connector on one end and a red 4-pin MicroMaTch
306                   connector on the other end.
307
308                 . Find the USB cable that you got as part of the
309                   starter kit, and plug the “mini” end in to the
310                   mating connector on TeleMetrum v1.x, TeleDongle v0.2
311                   or TeleBT v1.0.
312
313                 . Take the 2 screws out of the TeleDongle v0.2 or
314                   TeleBT v1.0 case to get access to the circuit board.
315
316                 . Plug the 8-pin end of the programming cable to the
317                   matching connector on the programmer, and the 4-pin
318                   end to the matching connector on the TeleDongle
319                   v0.2.  Note that each MicroMaTch connector has an
320                   alignment pin that goes through a hole in the PC
321                   board when you have the cable oriented correctly.
322
323                 . Attach a battery to the TeleMetrum v1.x board if
324                   you're using one.
325
326                 . Plug both the programmer and the TeleDongle into
327                   your computer's USB ports, and power up the
328                   programmer.
329
330                 . Run AltosUI, and select 'Flash Image' from the File
331                   menu.
332
333                 . Pick the programmer device from the list,
334                   identifying it as the programming device.
335
336
337                 . Select the image you want put on the TeleDongle
338                   v0.2, which should have a name in the form
339                   teledongle-v0.2-1.0.0.ihx.  It should be visible in
340                   the default directory, if not you may have to poke
341                   around your system to find it.
342
343                 . Make sure the configuration parameters are
344                   reasonable looking. If the serial number and/or RF
345                   configuration values aren't right, you'll need to
346                   change them.  The TeleDongle v0.2 serial number is
347                   on the “bottom” of the circuit board, and can
348                   usually be read through the translucent blue plastic
349                   case without needing to remove the board from the
350                   case.
351
352                 . Hit the 'OK' button and the software should proceed
353                   to flash the TeleDongle v0.2 with new firmware,
354                   showing a progress bar.
355
356                 . Confirm that the TeleDongle v0.2 board seems to have
357                   updated OK, which you can do by plugging in to it
358                   over USB and using a terminal program to connect to
359                   the board and issue the 'v' command to check the
360                   version, etc.  Once you're happy, remove the
361                   programming cable and put the cover back on the
362                   TeleDongle v0.2.
363
364                 If something goes wrong, give it another try.
365
366                 Be careful removing the programming cable from the
367                 locking 8-pin connector on TeleMetrum.  You'll need a
368                 fingernail or perhaps a thin screwdriver or knife
369                 blade to gently pry the locking ears out slightly to
370                 extract the connector.  We used a locking connector on
371                 TeleMetrum to help ensure that the cabling to
372                 companion boards used in a rocket don't ever come
373                 loose accidentally in flight.
374         endif::telemetrum,telemini[]