FreeCalypso > hg > freecalypso-citrine

annotate doc/Freerunner-Howto @ 37:5487db285025

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LICENSE explanatory file added
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 26 Nov 2016 01:03:01 +0000
parents cb00b90edaff
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
28
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 How to play with FreeCalypso GSM firmware on a Neo Freerunner
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 =============================================================
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 We have two entirely different firmware offerings for the Freerunner:
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 1. Leo2moko fw produced back in 2013-10: this is the only one suitable for
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 end users. We also have leo2moko-debug which is a slightly hacked-up
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 version of leo2moko with some additional debug features for developers;
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 this version is for developers only; end users should stick with the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 original leo2moko-r1 aka moko12 from 2013-10.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 2. The work-in-progress full-source gcc-built FreeCalypso Citrine fw
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 you are looking at can be built for multiple targets, and the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 gtamodem target is one of them - the original one, in fact.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 The flash+SRAM chip which FIC/Openmoko populated in their modems provides
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 plenty enough RAM for the firmware's data space requirements, but not enough
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 to run a complete firmware code image entirely from RAM, hence whichever fw
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 version you would like to exercise, you need to flash it. There are two ways
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 to flash modem firmware images in these smartphones: from inside the phone
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 (from the application processor) or externally through a special serial cable
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 inserted into the analog headset jack. The internal method is intended only
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 for end users flashing released production-quality images; developers and
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 tinkerers are expected to use the serial cable method.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 The serial cable wiring requirements for the GTA02 are the same as for Mot C1xx
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 phones, thus the same cable can be used for both. The FreeCalypso project has
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 endorsed UberWaves as our official vendor for serial cables; George at
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 UberWaves now makes serial cables that are specifically certified for use with
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 FreeCalypso. If you would like to order one, email uberwaves@gmail.com.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 Please see the Current_Status write-up for the current status of the present
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 Citrine firmware. As you can read there, this fw is currently nowhere near
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 being able to replace leo2moko. Therefore, if you are going to flash Citrine
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 into your FR's modem, we expect that you are using your FR as a poor man's
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 substitute for the not-yet-built FCDEV3B (a board we seek to build specifically
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 for developers and not for end users), and are NOT expecting this experimental
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 work-in-progress modem fw to work together with user-oriented application
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 processor software like QtMoko or SHR.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 If you would like to play with our experimental Citrine fw using a GTA02 modem
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 as the hw platform, here are the instructions:
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 1. Build the firmware in the gtamodem-gsm configuration - see the Compiling
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 document for more details;
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 2. You should get a flashImage.bin image built; now you need to flash it into
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 your FR's modem. The serial cable method is highly recommended: the only
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 thing you'll be able to do with our current not-fully-functional firmware is
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 play with it and observe the debug output, and the serial cable will be
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 needed for the latter part anyway.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 3. Run fc-loadtool the same way you would if you were flashing leo2moko;
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 4. The actual flash programming commands are a little different because the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 image is smaller and in a different format:
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 flash erase 0 0x160000
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 flash program-bin 0 finlink/flashImage.bin
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 The second number in the flash erase command needs to be the size of
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 flashImage.bin rounded up to a multiple of 64 KiB (the flash sector size in the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 GTA02 modem); 0x160000 is correct for the fw image size as of this writing, but
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 please double-check it yourself before flashing. The 0 argument in the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 flash program-bin command is the flash offset at which the image should be
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 programmed: it will always be 0 for FreeCalypso flashable fw images for gtamodem
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 and other targets that have the Calypso boot ROM enabled in the hardware.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 Once you have flashed our experimental fw into your modem, you can power-cycle
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 the modem and see the new fw boot. You should have the serial cable connected,
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 the serial channel enabled from the Freerunner's AP side and either rvtdump or
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 rvinterf running on your PC or other development machine when you first power
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 your modem up with the experimental fw in it: this way you will see the debug
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 output as the firmware boots up.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 Once the firmware has booted, it needs to be controlled via AT commands. The
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 present fw presents its AT command interface on two channels on this target: on
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 the MODEM UART going to the Freerunner's application processor and via RVTMUX.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 At the present stage of development, we highly recommend that you avoid running
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 any GSM-driving software on the AP and exercise our work-in-progress fw solely
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 through the external serial interface on the headset jack, using rvinterf and
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 fc-shell. The standard AT command interface on the dedicated MODEM UART is a
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 feature which we plan to address properly only when we build our planned FCDEV3B
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 hardware, which will bring both UARTs out to the external host.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 Assuming that you already have rvinterf running in a terminal window (you should
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 have started it before you gave the modem power-on command from the AP side),
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 to exercise our firmware further, you will need to open another terminal window
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 on your driving PC/laptop and run fc-shell. This program will connect to the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 already running rvinterf process via a local socket, and it will enable you to
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 send various commands to the running fw on the target, the most important ones
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 being standard AT commands. Send the following sequence of AT commands to
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 bring up GSM functionality:
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 AT+CMEE=2 -- enable verbose error responses
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 AT+CFUN=1 -- enable radio and SIM interfaces
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 AT+COPS=0 -- register to the default GSM network
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 To reflash your modem back to stable and working leo2moko aka moko12, execute
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 the following fc-loadtool commands:
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 flash erase 0 0x230000
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 flash program-m0 leo2moko.m0
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 (Whichever firmware image you are flashing, the flash erase command needs to
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 cover the range of flash sectors this image will occupy. You can erase more
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 sectors up to 0x300000, the "natural" boundary of the flash area where fw
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 images live, but I prefer to erase only the needed number of sectors: it is
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 both faster and imposes less wear on the flash.)