**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 use one of the pre-built systems we've already
   put together.

   If you don't have a DreamPlug or don't know what one is, make sure
   to ask for a copy of the VirtualBox image.  If you do have a
   DreamPlug, then 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 (not the
   USB) version.

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.  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.

## Updating DreamPlug's U-Boot

MAKE SURE YOU READ AND UNDERSTAND THIS SECTION IN ITS ENTIRETY BEFORE STARTING.

You can also review these instructions online:

    http://wiki.debian.org/FreedomBox/Firmware

These instructions are from Ian Campbell, using uboot version 2012.04.01-2,
which is the current version in Debian's Wheezy release (as of December 12,
2012).

First, prepare your system::

    # 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 -r u-boot_2012.04.01-2_armel/usr/lib/u-boot/dreamplug /mnt

Move the USB drive to your DreamPlug, and connect to your system via the JTAG
dongle.  Connect the UART DreamPlug port to the JTAG Board's UART port or
connect the JTAG DreamPlug port to the JTAG Board's JTAG port.  Next, plug the
USB cord into your main system and access the serial port with::

    # screen /dev/ttyUSB0 115200

Now, interrupt the boot process so you can flash it from within the bootloader,
before the GNU/Linux system takes over so you can actually write the new uBoot
file.  If you get to the "sf erase" step, *make sure to complete the "sf write"
step before turning off your plug.* If you turn off your plug before finishing
the write step, your plug will be unbootable.

Load and write the new bootloader::

    > usb start
    > fatload usb 2 0x6400000 dreamplug/u-boot.kwb
    > sf probe 0
    > sf erase 0x0 0x80000
    > sf write 0x6400000 0x0 0xFILESIZE

You must, of course, fill in the size of u-boot.kwb file you're loading in hex.
Use this chart to determine what size to use for the last line:

    | File Size | Code Line                      |
    |-----------+--------------------------------|
    |    196076 | sf write 0x6400000 0x0 0x2FDEC |

If your u-boot.kwb was 196076 bytes, the last command would look like:

    > sf write 0x6400000 0x0 0x2FDEC

### My File Size Isn't Listed!

If your file size isn't listed, we'll need to figure out what should go in the
last line manually.  To convert the file's size to hex, try entering the file
size in bytes (which you can get from running `ls -l u-boot.kwb` at a command
prompt) into the following search:

    https://duckduckgo.com/?q=10 in hex

This handy table lists the file sizes for all versions we know of:

    | Modification Date   | File Size | Hex Size | md5sum |
    |---------------------+-----------+----------+--------|
    | May 31, 2012, 21:19 |    196076 |    2FDEC | 4312c71b98049eab73332a3f283a1c5c

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 freedom-maker now includes DreamPlug firmware in the FAT partition on
USB stick targets.  To use a freedom-maker USB stick to update your u-boot,
ignore the instructions above about how to wget and extract the firmware, and
just connect to the DreamPlug and follow the bootloader instructions.

## Unbricking a DreamPlug

These instructions were copied and edited from:

https://www.newit.co.uk/forum/index.php?PHPSESSID=t9b8s83gen1h10m65p0s3q4md6&topic=2835.0

These instructions should get you from a Bricked DreamPlug to getting uboot
running in RAM ready to restore your system from USB/TFTP.  They should be used
if you erased your DreamPlug's bootloader and shut it off before writing the new
bootloader.

0. Edit your /etc/apt/sources.list to make sure you're using Wheezy or later.

1. First, install the required packages:

    $ sudo apt-get install openocd telnet screen

2. Connect & Power up your device with the mini usb cable and JTAG.

3. Open a terminal session and connect to the plug console:

   $ sudo screen /dev/ttyUSB0 115200

4. Open a 2nd terminal session.

    $ wget http://www.downloadsnewit.co.uk/u-boot/recovery/dreamplug/u-boot.elf
    $ sudo openocd -f /usr/share/openocd/scripts/board/sheevaplug.cfg -s /usr/share/openocd/scripts

5. You should see output similar to this:

    Open On-Chip Debugger 0.4.0 (2010-10-08-15:52)
    Licensed under GNU GPL v2
    For bug reports, read
       http://openocd.berlios.de/doc/doxygen/bugs.html
    2000 kHz
    trst_and_srst separate srst_gates_jtag trst_push_pull srst_open_drain
    jtag_nsrst_delay: 200
    jtag_ntrst_delay: 200
    dcc downloads are enabled
    Warn : use 'feroceon.cpu' as target identifier, not '0'
    Info : clock speed 2000 kHz
    Info : JTAG tap: feroceon.cpu tap/device found: 0x20a023d3 (mfg: 0x1e9, part: 0x0a02, ver: 0x2)
    Info : Embedded ICE version 0
    Info : feroceon.cpu: hardware has 1 breakpoint/watchpoint unit

6. If you are using a JTAG and getting errors at this point replug or even swap
   JTAG cables and retry.

7. Next open a 3rd terminal session.

    $ telnet localhost 4444

8. Output should look like this:

    Trying ::1...
    Trying 127.0.0.1...
    Connected to localhost.
    Escape character is '^]'.
    Open On-Chip Debugger
    >

9. Then, in that third seesion, run:

    reset;sheevaplug_init;load_image u-boot.elf;resume 0x00600000

10. Now you should see Uboot starting to run in the 1st terminal session and you
    are ready to start restoring your plug.

11. DON'T turn off your DreamPlug.  Follow the "Updating the DreamPlug's U-Boot"
    instructions.

# 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 DESTINATION=usb plugserver-image

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

   If you don't hate yourself, use GParted, click through the relevant
   bits and skip on to step 10.

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 800 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-image

18. Enter your password when asked by "sudo".  If that fails, run:

    $ su -c "make weekly-image"

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.
- /bin/mk_dreamplug_rootfs: Builds the DreamPlug's root file-system.
- /bin/mk_virtualbox_image: Builds the VirtualBox image.
- /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:

- plugserver-image: 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-image: 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.
- 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.

## /bin/mk_dreamplug_rootfs

Starts building the DreamPlug system image by creating all the destination
directories and installing the base system.

## /bin/mk_virtualbox_image

Starts building the VirtualBox system image 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.