Enable non-free for cubietruck.
[freedombox/freedom-maker.git] / README
1 # Freedom-Maker - Bdale's Building Tools for the FreedomBox Project
2
3 Welcome to the FreedomBox!  This project is the central hub of the FreedomBox
4 project, it builds and installs the file-system image that turns any computer
5 into a FreedomBox.
6
7 There are a couple ways to use this system:
8
9 1. Get a pre-built image via https://wiki.debian.org/FreedomBox
10    There are images available for virtualbox, raspberry and dreamplug.
11    You also find the setup instructions in the Wiki.
12
13 2. Create a VirtualBox image on your own: The "To Make It" section of this
14    document is all you need.
15
16 3. Create an image for the dreamplug (or similar devices):
17    Read this document. You can use
18
19    A. A USB stick.  This requires a JTAG, but doesn't require opening up the
20       DreamPlug, or,
21
22    B. A microSD card and adapter.  You can use the one from inside the
23       DreamPlug.  You won't need a JTAG, but you will need to open the DreamPlug
24       and void the warranty.
25
26 # Warning!
27
28 There are no training wheels.  Read the scripts and understand what
29 they're going to do before you run them.
30
31 # Recent Firmware Necessary!
32
33 If you received your DreamPlug from GlobalScale during or after fall of 2012,
34 you probably don't need to reflash your DreamPlug and can try skipping directly
35 to the *To Use It* section.
36
37 Modern kernels need a relatively recent version of the u-boot firmware.  If
38 you still use old firmware (including what Global Scale ships on the units by
39 default), then you need to update, which requires having the JTAG dongle (to
40 gain console serial port access).  One way to know you've got old firmware
41 is if booting a Linux kernel results in errors about corrupt gzip data and
42 a failure to launch the kernel.
43
44 Note that re-flashing firmware will erase all configuration variables.  If
45 preserving your exising boot config is important, use printenv and make notes
46 before proceeding.  Also note that any time you're re-flashing boot firmware,
47 there is a slight chance you could 'brick' your device leaving it unbootable.
48 If that happens, the JTAG interface can be used to recover.  See the *Errors* ->
49 *Unbricking a DreamPlug* section of this document.
50
51 ## Updating DreamPlug's U-Boot
52
53 MAKE SURE YOU READ AND UNDERSTAND THIS SECTION IN ITS ENTIRETY BEFORE STARTING.
54
55 You can also review these instructions online:
56
57     http://wiki.debian.org/FreedomBox/Firmware
58
59 These instructions are from Ian Campbell, using uboot version 2012.04.01-2,
60 which is the current version in Debian's Wheezy release (as of December 12,
61 2012).
62
63 First, prepare your system::
64
65     # wget http://http.debian.net/debian/pool/main/u/u-boot/u-boot_2012.04.01-2_armel.deb
66     # dpkg-deb -x u-boot_2012.04.01-2_armel.deb u-boot_2012.04.01-2_armel
67     # cp -r u-boot_2012.04.01-2_armel/usr/lib/u-boot/dreamplug /mnt
68
69 Move the USB drive to your DreamPlug, and connect to your system via the JTAG
70 dongle.  Connect the UART DreamPlug port to the JTAG Board's UART port or
71 connect the JTAG DreamPlug port to the JTAG Board's JTAG port.  Next, plug the
72 USB cord into your main system and access the serial port with::
73
74     # screen /dev/ttyUSB0 115200
75
76 Now, interrupt the boot process.  You'll need to save your DreamPlug's Ethernet
77 interface MAC addresses because they'll be erased during the update and we'll
78 need to restore them at the end of the process.  If you don't save the MAC
79 addresses, the FreedomBox will automatically create random MAC addresses during
80 the box's first boot.  Letting the box set a random MAC address should be a last
81 resort, because those MAC addresses are unusual and can easily identify your
82 system as a FreedomBox.
83
84 To find the current MAC addresses, run:
85
86     > printenv
87
88 The MAC addresses will be on lines like these.  Save the whole line:
89
90     > ethaddr=F0:AD:4E:00:00:00
91     > eth1addr=F0:AD:4E:00:00:01
92
93 Now that you've recorded the MAC addresses for each interface, you need to write
94 the new uBoot file.  If you get to the "sf erase" step, *make sure to complete
95 the "sf write" step before turning off your plug.* If you turn off your plug
96 before finishing the write step, your plug will be unbootable.
97
98 Load and write the new bootloader:
99
100     > usb start
101     > fatload usb 2 0x6400000 dreamplug/u-boot.kwb
102     > sf probe 0
103     > sf erase 0x0 0x80000
104     > sf write 0x6400000 0x0 0xFILESIZE
105
106 You must, of course, fill in the size of u-boot.kwb file you're loading in hex.
107 Use this chart to determine what size to use for the last line:
108
109     | File Size | Code Line                      |
110     |-----------+--------------------------------|
111     |    196076 | sf write 0x6400000 0x0 0x2FDEC |
112
113 If your u-boot.kwb was 196076 bytes, the last command would look like:
114
115     > sf write 0x6400000 0x0 0x2FDEC
116
117 ### My File Size Isn't Listed!
118
119 If your file size isn't listed, we'll need to figure out what should go in the
120 last line manually.  To convert the file's size to hex, try entering the file
121 size in bytes (which you can get from running `ls -l u-boot.kwb` at a command
122 prompt) into the following search:
123
124     https://duckduckgo.com/?q=10 in hex
125
126 This handy table lists the file sizes for all versions we know of:
127
128     | Modification Date   | File Size | Hex Size | md5sum |
129     |---------------------+-----------+----------+--------|
130     | May 31, 2012, 21:19 |    196076 |    2FDEC | 4312c71b98049eab73332a3f283a1c5c
131
132 At this point, you should be able to reset the DreamPlug and have it boot to a
133 serial console prompt.  If that fails, you'll need real JTAG magic to try again.
134 That JTAG magic is described in the *Errors* -> *Unbricking a DreamPlug* section
135 at the end of this document.
136
137 Note that freedom-maker now includes DreamPlug firmware in the FAT partition on
138 USB stick targets.  To use a freedom-maker USB stick to update your u-boot,
139 ignore the instructions above about how to wget and extract the firmware, and
140 just connect to the DreamPlug and follow the bootloader instructions.
141
142 After you restore your microSD card to the DreamPlug, you should try booting it.
143 If the boot fails because of an "Invalid boot device", you'll need to interrupt
144 the boot process again to update the firmware with the settings described in the
145 *Errors* -> *Unbricking a DreamPlug* section, at the end of this document.
146
147 # To Use It
148
149 You'll need to copy the image to the memory card or USB stick:
150
151 1. Figure out which device your card actually is.
152
153    A. Unplug your card.
154
155    B. Run "df" to show you the list of devices your computer actually knows
156       about.
157
158    C. Plug your card in.
159
160    D. Run "df" again, your computer should know about a new device or two: your
161       memory card.  It's probably "/dev/sd(someletter)".  It *won't be*
162       /dev/sda.
163
164 2. Decompress the image:
165
166         $ tar -xjvf freedombox-unstable_*.tar.bz2
167
168 3. Copy the image to your card.  Whatever you do, make sure you don't copy it to
169    /dev/sda.  That'll break your system.
170
171         # dd bs=1M if=freedombox-unstable_*.img of=/dev/sd(thesameletter)
172
173    When picking a device, use the drive-letter destination, like /dev/sdb, not a
174    numbered destination, like /dev/sdb1.  The device-without-a-number refers to
175    the entire device, while the device-with-a-number refers to a specific
176    partition.  We want to use the whole device.
177
178 Now, what you need to do depends on whether you're using the microSD card or USB
179 stick method:
180
181 - USB drive: You'll hook the JTAG up to the DreamPlug before booting and use the
182   JTAG to control the boot process, so we can boot from the USB drive.
183
184 - microSD card: You'll put the microSD card into the DreamPlug's internal
185   microSD card slot and boot the DreamPlug.  It'll restart once to finish the
186   install process, then it's ready to use.
187
188 ## Running from a microSD Card
189
190 When DD has finished, take the microSD card out of your computer and plug it
191 into your DreamPlug.  If you have a JTAG, you can connect directly to the box to
192 watch it boot by running:
193
194     $ sudo screen /dev/ttyUSB0 115200
195
196 You'll see the DreamPlug restart once during the boot process.  If you don't
197 have a JTAG, wait a while (5 minutes or less) and it'll be available over SSH
198 (port 22).  You might need to use nmap to find it:
199
200     $ nmap -p 22 --open -sV 192.168.0.0/24
201
202     ...
203     Interesting ports on 192.168.0.13:
204     PORT   STATE SERVICE VERSION
205     22/tcp open  ssh     OpenSSH 6.0p1 Debian 2 (protocol 2.0)
206     Service Info: OS: Linux
207     ...
208
209 Once you've found it, SSH into the box:
210
211     $ ssh root@192.168.0.13
212
213 ## Running from a USB Stick
214
215 Move the USB stick to the DreamPlug, obtain a serial console, and hit reset.  A
216 good way to access the serial console (actually USB serial emulation provided by
217 the optional JTAG dongle), is to use 'screen', like so:
218
219     # sudo screen /dev/ttyUSB0 115200
220
221 If ``screen`` fails, see the *Errors* -> *Troubleshooting Screen* section at the
222 end of this document.
223
224 Interrupt the boot by pressing a key during the autoboot countdown, and type the
225 following to boot from the USB stick:
226
227     setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;'
228     setenv x_bootcmd_kernel fatload usb 2 0x6400000 uImage
229     setenv x_bootcmd_initrd fatload usb 2 0x6900000 uInitrd
230     setenv x_bootargs console=ttyS0,115200
231     setenv x_bootargs_root root=/dev/sdc2 rootdelay=10 rootflags=subvol=@
232     boot
233
234 The system should boot to a login prompt, using only the bits on the stick.
235
236 The default root password is 'freedom'.  The normal user is "fbx" and the
237 password is "frdm".
238
239 - - - - -
240
241 If booting from the USB stick fails because u-boot in the Dreamplug doesn't
242 recognize the FAT partition on your stick, it may be because the partition
243 type code isn't one of the FAT variants that u-boot recognizes.  It's not
244 clear what the root cause is yet, but if this happens, plug the USB stick
245 into a Linux machine and use your favorite partition editor (fdisk works)
246 to change the type of partition 1 to something like '6' which is simple
247 FAT16, then write the change.  This won't change the *contents* of the
248 partition, but it may allow u-boot to recognize it.
249
250 - - - - -
251
252 To set things up to boot from the internal microSD card, once you're logged into
253 the system booted from root on USB stick you can use:
254
255     /usr/sbin/copy2dream
256
257 Note that if you don't have a reasonable system date and time set in the
258 DreamPlug before running this command, you may see a long stream of warnings
259 from tar about timestamps being in the future.  It is safe to ignore these.
260
261 After copy2dream completes, you may need to update /etc/fstab by hand since
262 copy2dream does not yet understand UUIDs in that file.
263
264 On reboot, you may want to interrupt the boot and type the following to ensure
265 you boot from the internal microSD by default.  This bootcmd line elides the
266 time-consuming attempts to boot from gigE, which makes boot go much faster.  If
267 you flashed the bootloader, you'll need to replace the *ethaddr* and *eth1addr*
268 lines with the MAC addresses you previously recorded.  If you didn't record MAC
269 addresses, completely exclude those two lines.
270
271     setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;'
272     setenv x_bootcmd_kernel fatload usb 0 0x6400000 uImage
273     setenv x_bootcmd_initrd fatload usb 0 0x6900000 uInitrd
274     setenv x_bootargs console=ttyS0,115200
275     setenv x_bootargs_root root=/dev/sda2 rootdelay=10 rootflags=subvol=@
276     setenv ethaddr=F0:AD:4E:00:00:00
277     setenv eth1addr=F0:AD:4E:00:00:01
278     saveenv
279     reset
280
281 Congratulations, you're done!  To connect your DreamPlug to the Internet, plug
282 an Ethernet cord from the box's *eth0* port into your router.  The *eth0* port
283 is the inner Ethernet port.  To connect to the Internet through your DreamPlug,
284 plug your computer's Ethernet port into the box's eth1 port.  The *eth1* port is
285 the outer Ethernet port.
286
287 # To Make It
288
289 To build the image, download and install the dependencies for each of the images
290 you want to build.
291
292 Required for all images:
293
294     # apt-get -y install git python-docutils mktorrent vmdebootstrap \
295                  dosfstools btrfs-tools
296
297 Required for VirtualBox:
298
299     # apt-get -y install extlinux virtualbox
300
301 Required for RaspberryPi:
302
303     # apt-get -y install qemu-user-static binfmt-support
304
305 Required for DreamPlug:
306
307     # apt-get -y install qemu-user-static binfmt-support u-boot-tools
308
309 Now, fetch the git source of freedom-maker and build the image you want:
310
311     $ git clone http://anonscm.debian.org/git/freedombox/freedom-maker.git freedom-maker
312     $ make -C freedom-maker dreamplug raspberry virtualbox
313
314 If you only want one of the possible images of DreamPlug, RaspberryPi and
315 VirtualBox, remove the rest from the make command line.  The images will show up
316 in freedom-maker/build/.
317
318 *dd* the images to the SD card (for DreamPlug and RaspberryPi), or create a new
319 VM for the VirtualBox hard drive file, and boot the client.
320
321 # To Understand It
322
323 Be aware that this is a *very* imcomplete solution for now, suitable only
324 for developers .. you will want to at least do things like create unique
325 ssh host keys for your device!
326
327 Digging into the code should be fairly straightforward.  There are only six
328 files you need to be aware of:
329
330 - /Makefile: The makefile that describes and builds the system.
331 - /bin/mk_dreamplug_rootfs: Builds the DreamPlug's root file-system.
332 - /bin/mk_virtualbox_image: Builds the VirtualBox image.
333 - /source: The root file system.
334
335 ## Makefile
336
337 There are three major targets to be aware of:
338
339 - dreamplug-image: This builds an image for the DreamPlug's internal SD card.
340 - raspberry-image: This builds an image for the RasbperryPi's SD card.
341 - virtualbox-image: This builds an image for the VirtualBox virtualization tool.
342
343 ## /bin/mk_freedombox_image
344
345 Starts building the image by running vmdebootstrap.
346
347 ## /bin/mk_virtualbox_image
348
349 Adds FreedomBox specific customizations to the image.
350
351 # Errors
352
353 This section documents known errors with the process and what you can do about
354 them.
355
356 ## Invalid boot device
357
358 If, while booting your DreamPlug, you receive this error message:
359
360     2 Storage Device(s) found
361
362     ** Invalid boot device **
363
364     ** Invalid boot device **
365     Wrong Image Format for bootm command
366     ERROR: can't get kernel image!
367
368 Make sure you've updated your DreamPlug to boot from the internal microSD card.
369 You'll need to plug in the JTAG and interrupt the boot process to paste in these
370 commands:
371
372     setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;'
373     setenv x_bootcmd_kernel fatload usb 0 0x6400000 uImage
374     setenv x_bootcmd_initrd fatload usb 0 0x6900000 uInitrd
375     setenv x_bootargs console=ttyS0,115200
376     setenv x_bootargs_root root=/dev/sda2 rootdelay=10 rootflags=subvol=@
377     saveenv
378     reset
379
380 ## Troubleshooting Screen
381
382 If screen fails when you're running:
383
384     $ sudo screen /dev/ttyUSB0 115200
385
386 First, verify that the ``usbserial`` module is loaded:
387
388     $ sudo modprobe usbserial
389     $ sudo lsmod | grep usbserial
390
391 Then, make sure your JTAG is plugged into both your DreamPlug and USB ports and
392 verify that you can access the ``/dev/ttyUSB0`` device:
393
394     $ sudo tail -f /dev/ttyUSB0
395
396 If that fails, you can try creating the device:
397
398     $ sudo mknod /dev/ttyUSB0 c 188 0
399
400 You may then be able to access the device via tail or screen.  If not, then
401 [DIYF](https://duckduckgo.com).
402
403 ## Unbricking a DreamPlug
404
405 You should first try to follow the
406 [simpler instructions from GlobalScale](https://code.google.com/p/dreamplug/downloads/detail?name=DreamPlug-Reflash%20uboot%20guide_%20Aug-28-2012.pdf&can=2&q=).
407 Search for the
408 "[Reflash uboot guide](https://code.google.com/p/dreamplug/downloads/list)" if
409 the link doesn't work.
410
411 If those instructions don't work, you should then try these instructions.
412
413 These instructions were copied and edited from:
414
415     https://www.newit.co.uk/forum/index.php?PHPSESSID=t9b8s83gen1h10m65p0s3q4md6&topic=2835.0
416
417 These instructions should get you from a Bricked DreamPlug to getting uboot
418 running in RAM ready to restore your system from USB/TFTP.  They should be used
419 if you erased your DreamPlug's bootloader and shut it off before writing the new
420 bootloader.
421
422 1. Edit your /etc/apt/sources.list to make sure you're using Wheezy or later.
423
424 2. First, install the required packages:
425
426         $ sudo apt-get install openocd telnet screen
427
428 3. Connect & Power up your device with the mini usb cable and JTAG.
429
430 4. Open a terminal session and connect to the plug console:
431
432         $ sudo screen /dev/ttyUSB0 115200
433
434 5. Open a 2nd terminal session.
435
436         $ wget http://www.downloadsnewit.co.uk/u-boot/recovery/dreamplug/u-boot.elf
437         $ sudo openocd -f /usr/share/openocd/scripts/board/sheevaplug.cfg -s /usr/share/openocd/scripts
438
439 6. You should see output similar to this:
440
441         Open On-Chip Debugger 0.4.0 (2010-10-08-15:52)
442         Licensed under GNU GPL v2
443         For bug reports, read
444            http://openocd.berlios.de/doc/doxygen/bugs.html
445         2000 kHz
446         trst_and_srst separate srst_gates_jtag trst_push_pull srst_open_drain
447         jtag_nsrst_delay: 200
448         jtag_ntrst_delay: 200
449         dcc downloads are enabled
450         Warn : use 'feroceon.cpu' as target identifier, not '0'
451         Info : clock speed 2000 kHz
452         Info : JTAG tap: feroceon.cpu tap/device found: 0x20a023d3 (mfg: 0x1e9, part: 0x0a02, ver: 0x2)
453         Info : Embedded ICE version 0
454         Info : feroceon.cpu: hardware has 1 breakpoint/watchpoint unit
455
456 7. If you are using a JTAG and getting errors at this point replug or even swap
457    JTAG cables and retry.
458
459 8. Next open a 3rd terminal session.
460
461         $ telnet localhost 4444
462
463 9. Output should look like this:
464
465         Trying ::1...
466         Trying 127.0.0.1...
467         Connected to localhost.
468         Escape character is '^]'.
469         Open On-Chip Debugger
470         >
471
472 10. Then, in that third seesion, run:
473
474         reset;sheevaplug_init;load_image u-boot.elf;resume 0x00600000
475
476 11. Now you should see Uboot starting to run in the 1st terminal session and you
477     are ready to start restoring your plug.
478
479 12. **DON'T turn off your DreamPlug.**  Follow the "Updating the DreamPlug's
480     U-Boot" instructions.