diff options
Diffstat (limited to 'freedom-maker/README.freedom-maker')
| -rw-r--r-- | freedom-maker/README.freedom-maker | 418 |
1 files changed, 418 insertions, 0 deletions
diff --git a/freedom-maker/README.freedom-maker b/freedom-maker/README.freedom-maker new file mode 100644 index 0000000..6039861 --- /dev/null +++ b/freedom-maker/README.freedom-maker @@ -0,0 +1,418 @@ +Freedom-Maker - Bdale's building tools for the FreedomBox project + +Welcome to the FreedomBox! This project is the central hub of the FreedomBox +project, it builds and installs the file-system image that turns any computer +into a FreedomBox. + +There are a couple ways to use this system: + +1. If you just want to use a FreedomBox and don't care about changing how it + works or mucking about in its insides (if you're like most people), you + should get a pre-built image from someone and copy it to an SD card or USB + drive. If you don't have a JTAG or don't know what one is, make sure to ask + for the SD card image. + +2. If you want to change and build on it, you can use: + + A. A USB stick. This requires a JTAG, but doesn't require opening up the + DreamPlug, or, + + B. A microSD card and adapter. You can use the one from inside the + DreamPlug. You won't need a JTAG, but you will need to open the DreamPlug + and void the warranty. + +*** +*** Warning! There are no "training wheels" here .. read the scripts and +*** understand what they're going to do before you run them... +*** + +# Recent Firmware Necessary! + +Modern kernels need a relatively recent version of the u-boot firmware. If +you still use old firmware (including what Global Scale ships on the units by +default), then you need to update, which requires having the JTAG dongle (to +gain console serial port access). One way to know you've got old firmware +is if booting a Linux kernel results in errors about corrupt gzip data and +a failure to launch the kernel. + +Note that re-flashing firmware will erase all configuration variables. If +preserving your exising boot config is important, use printenv and make notes +before proceeding. Also note that any time you're re-flashing boot firmware, +there is a slight chance you could 'brick' your device leaving it unbootable. +If that happens, the JTAG interface can be used to recover. + +The instructions for updating firmaware go something like this (thanks to +Ian Campbell for his notes): + + Using 2012.04.01-2 which is current Wheezy. Prep by mounting a USB stick. + + wget http://http.debian.net/debian/pool/main/u/u-boot/u-boot_2012.04.01-2_armel.deb + dpkg-deb -x u-boot_2012.04.01-2_armel.deb u-boot_2012.04.01-2_armel + cp u-boot_2012.04.01-2_armel/usr/lib/u-boot/dreamplug/* /media/usbdisk + + Move the USB stick to your DreamPlug. Flash the new firmare: + + usb start + fatload usb 2 0x6400000 u-boot.kwb + sf probe 0 + sf erase 0x0 0x80000 + sf write 0x6400000 0x0 0x${filesize} + + (You must, of course, fill in the size of the file you're loading in hex) + +At this point, you should be able to reset the DreamPlug and have it boot to +a serial console prompt. If that fails, you'll need real JTAG magic to try +again. + +Note that if you use the 'make usb' target to create a bootable USB stick +image, we include the required firmware in /boot/dreamplug, so the above +fatload command might be replaced with: + + fatload usb 2 0x6400000 dreamplug/u-boot.kwb + +# To Use It + +You'll need to copy the image to the memory card or USB stick: + +1. Figure out which device your card actually is. + + A. Unplug your card. + + B. Run "df" to show you the list of devices your computer actually knows + about. + + C. Plug your card in. + + D. Run "df" again, your computer should know about a new device or two: your + memory card. It's probably "/dev/sd(someletter)". It *won't be* + /dev/sda. + +2. Decompress the image: + + $ tar -xjvf freedombox-unstable_*.tar.bz2 + +3. Copy the image to your card. Whatever you do, make sure you don't copy it to + /dev/sda. That'll break your system. + + # dd bs=1M if=freedombox-unstable_*.img of=/dev/sd(thesameletter) + + When picking a device, use the drive-letter destination, like /dev/sdb, not a + numbered destination, like /dev/sdb1. The device-without-a-number refers to + the entire device, while the device-with-a-number refers to a specific + partition. We want to use the whole device. + +Now, what you need to do depends on whether you're using the microSD card or USB +stick method: + +- USB drive: You'll hook the JTAG up to the DreamPlug before booting and use the + JTAG to control the boot process, so we can boot from the USB drive. + +- microSD card: You'll put the microSD card into the DreamPlug's internal + microSD card slot and boot the DreamPlug. It'll restart once to finish the + install process, then it's ready to use. + +## Running from a microSD Card + +When DD has finished, take the microSD card out of your computer and plug it +into your DreamPlug. If you have a JTAG, you can watch it boot. You'll see it +restart once during the boot process. If you don't have a JTAG, wait a while (5 +minutes or less) and it'll be available over SSH (port 22). You might need to +use nmap to find it: + + $ nmap -p 22 --open -sV 192.168.0.0/24 + + ... + Interesting ports on 192.168.0.13: + PORT STATE SERVICE VERSION + 22/tcp open ssh OpenSSH 6.0p1 Debian 2 (protocol 2.0) + Service Info: OS: Linux + ... + +Once you've found it, SSH into the box: + + $ ssh root@192.168.0.13 + +## Running from a USB Stick + +Move the USB stick to the DreamPlug, obtain a serial console, and hit reset. A +good way to access the serial console (actually USB serial emulation provided by +the optional JTAG dongle), is to use 'screen', like so: + + screen /dev/ttyUSB0 115200 + +Interrupt the boot by pressing a key during the autoboot countdown, and type the +following to boot from the USB stick: + + setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;' + setenv x_bootcmd_kernel fatload usb 2 0x6400000 uImage + setenv x_bootcmd_initrd fatload usb 2 0x6900000 uInitrd + setenv x_bootargs_root root=/dev/sdc2 rootdelay=10 + boot + +The system should boot to a login prompt, using only the bits on the stick. + +The default root password is 'freedom'. The normal user is "fbx" and the +password is "frdm". + +- - - - - + +To set things up to boot from the internal microSD card, once you're logged into +the system booted from root on USB stick you can use: + + /sbin/copy2dream + +Note that if you don't have a reasonable system date and time set in the +DreamPlug before running this command, you may see a long stream of warnings +from tar about timestamps being in the future. It is safe to ignore these. + +On reboot, you may want to interrupt the boot and type the following to ensure +you boot from the internal microSD by default. This bootcmd line elides the +time-consuming attempts to boot grom gigE, which makes boot go much faster: + + setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;' + setenv x_bootcmd_kernel fatload usb 0 0x6400000 uImage + setenv x_bootcmd_initrd fatload usb 0 0x6900000 uInitrd + setenv x_bootargs_root root=/dev/sda2 rootdelay=10 + saveenv + reset + +# To Make It + +If you want to build your own image yourself, you're more than welcome to. +Whether you're using a USB drive or a microSD card, you'll need to ensure that +it's at least 2 GB in size and that it has two partitons: + +1. The stick must start with a 128 MB FAT partition for the boot directory. + +2. The rest of the stick is an EXT2 partition, for the main installation. + +The rest of the steps you need to follow depend on whether you're using a USB +stick or a microSD card. + +## Building on a USB Stick + +Partition a USB stick to have a small FAT partition and large ext2 partition, +create a /media/freedom mount point, and add entries to /etc/fstab like: + + /dev/sdb1 /media/freedom/boot vfat user,noauto 0 0 + /dev/sdb2 /media/freedom ext2 user,noauto 0 0 + +This will allow the Makefile to mount and unmount the stick at will. + +If you have a favorite Debian mirror, update the file fbx-base.conf setting the +source= line. + +To populate the stick with bits for a DreamPlug, just plug it in to your +computer and type: + + make + +This will build a file tree under build/dreamplug, representing the contents of +a root file system, then that content will be copied to the stick. + +## Building it on a microSD card. + +Changing the image and building your own is a simple 18 step process! Lots of +thanks to Nick Hardiman for putting these instructions together. + +### Get Ready + +1. Start your workstation. + +2. Use a Debian OS, the version doesn't matter. A virtual image, such + as a VirtualBox image, is fine. Usually. + +3. Use the root account. + +### Prepare an SD Card + +4. Find a microSD card with SD card holder. It must be at least 2GB + in size. + +5. Insert the card into your workstation. + +6. Install a partition editor. Install parted if you are a masochist. + + # apt-get install parted + +7. Create 2 partitions. Use cfdisk, parted, gparted or similar. + + # cfdisk /dev/sdb + + a. First partition: 128meg (no smaller or the kernel copy will run + out of room and make - see below - will end with an error). + + b. Second partition: The rest of the card (anything over 600 MB + should work). + +8. Make a note of the SD card’s device name. Mine is /dev/sdb (my + workstation’s layout is simple: one disk called /dev/sda and + nothing else defined). + +9. Format the two partitions. + + a. First partition: FAT + + # mkdosfs /dev/sdb1 + + b. Second partition: ext3 + + # mkfs.ext3 /dev/sdb2 + +10. Create the mountpoints on your workstation. + + # mkdir -p /media/freedom/boot + +11. Mount the second partition. + + # mount /dev/sdb2 /media/freedom/ + +12. Mount the first partition. + + # mount /dev/sdb1 /media/freedom/boot/ + +13. Check your work. + + # mount + + sysfs on /sys type sysfs (rw,nosuid,nodev,noexec,relatime) + ... + /dev/sdb2 on /media/freedom type ext3 + (rw,relatime,errors=continue,barrier=1,data=ordered) + /dev/sdb1 on /media/freedom/boot type vfat + (rw,relatime,fmask=0022,dmask=0022,codepage=cp437,iocharset=utf8,shortname=mixed,errors=remount-ro) + +### Clone the Git Repository + +14. Install git. + + # apt-get install git + + Reading package lists... Done + ... + After this operation, 15.3 MB of additional disk space will be used. + Do you want to continue [Y/n]? + ... + +15. Clone Nick Daly’s repository. + + $ git clone https://github.com/NickDaly/freedom-maker.git + + Cloning into 'freedom-maker'... + + +### Create the Debian OS. + +16. Change to the new directory. + + $ cd ~/freedom-maker/ + +17. Kick off: + + $ make weekly-card + +18. Enter your password when asked by "sudo". If that fails, run: + + $ su -c "make weekly-card" + +If you do that, you'll need to enter the root password to build the image. + +The next part took about an hour, but required no input from me. Packages were +downloaded. Lots of commands were run. Many harmless errors were ignored: + + sysvinit: restarting...init: timeout opening/writing control channel /run/initctl + .init: timeout opening/writing control channel /run/initctl + ... + +There was good news: + + Multistrap system installed successfully... + Copying the source directory to the FreedomBox root. + +There was an enormous amount of this: + + bin/bash + 818092 100% 7.07MB/s 0:00:00 (xfer#1, to-check=1102/1123) + bin/cat + 42736 100% 362.91kB/s 0:00:00 (xfer#2, to-check=1101/1123) + bin/chgrp + 54996 100% 383.62kB/s 0:00:00 (xfer#3, to-check=1100/1123) + ... + +Finally an image is copied and zipped up for redistribution: + + dd if=/dev/sdb of="freedombox-unstable_`date +%Y.%m%d`.img" bs=1M + 3781+1 records in + 3781+1 records out + 3965190144 bytes (4.0 GB) copied, 266.174 s, 14.9 MB/s + Image copied. The microSD card may now be removed. + tar -cjvf "freedombox-unstable_`date +%Y.%m%d`.tar.bz2" + "freedombox-unstable_`date +%Y.%m%d`.img" + freedombox-unstable_2012.0705.img + +The end. Hooray! The SD card is ready for the DreamPlug. + +# To Understand It + +Be aware that this is a *very* imcomplete solution for now, suitable only +for developers .. you will want to at least do things like create unique +ssh host keys for your device! + +Digging into the code should be fairly straightforward. There are only six +files you need to be aware of: + +- /Makefile: The makefile that describes and builds the system. +- /mk_dreamplug_rootfs: Builds the DreamPlug's root file-system. +- /bin/projects: The place for external projects to hook into and customize + themselves before they're copied to the image. +- /bin/finalize: Finalizes and prepares the build for booting. +- /source: The root file system. +- /source/install.sh: Pre-boot configuration that needs to be run on the device + itself (from within a chroot). + +## Makefile + +There are three major targets to be aware of: + +- dreamstick: The default target. This loads an image to a USB drive that can + be used to install the FreedomBox without opening up your DreamPlug and + voiding the warranty. You'll need a JTAG, though. +- weekly-card: The target used to produce the weekly FreedomBox test release. + This will copy the image to a card that can be popped directly into the + microSD card slot in the DreamPlug. The DreamPlug will boot happily without + needing a JTAG. +- stamp-dreamplug-rootfs: The root file system itself. It doesn't get installed + anywhere (that's done by the other two targets), but is a good way to test + whether the image will actually build, without waiting for all that pesky + hardware I/O. + +## mk_dreamplug_rootfs + +Starts building the system by creating all the destination directories and +installing the base system. + +## /bin/projects + +Where projects that want to integrate into the FreedomBox should hook into. +Keep in mind, we aren't in a chroot at this point. The only environment +variables you'll probably need are: + +- user: The non-root user's name (uid = 1000). +- homedir: The non-root user's home-directory. + +## /bin/finalize + +Getting the system ready for boot, doing the things that don't need to be done +inside a chroot. You probably don't need to change this. + +## /source + +The root file system on the DreamPlug. Modify this, and you're modifying what +ends up on the FreedomBox. + +## /source/install.sh + +This is executed from a chroot during the build process to do configuration that +needs to be done on the device itself. You shouldn't need to modify this. If +you're installing a project that needs to change how the system configures +itself, you're probably doing something wrong. |