FreeCalypso > hg > freecalypso-citrine

comparison doc/Freerunner-Howto @ 28:cb00b90edaff

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