# 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. Get a pre-built image via https://wiki.debian.org/FreedomBox
   There are images available for virtualbox, raspberry and dreamplug.
   You also find the setup instructions in the Wiki.

2. Create a VirtualBox image on your own: The "To Make It" section of this
   document is all you need.

3. Create an image for the dreamplug (or similar devices):
   Read this document. 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!

If you received your DreamPlug from GlobalScale during or after fall of 2012,
you probably don't need to reflash your DreamPlug and can try skipping directly
to the *To Use It* section.

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.  See the *Errors* ->
*Unbricking a DreamPlug* section of this document.

## 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.  You'll need to save your DreamPlug's Ethernet
interface MAC addresses because they'll be erased during the update and we'll
need to restore them at the end of the process.  If you don't save the MAC
addresses, the FreedomBox will automatically create random MAC addresses during
the box's first boot.  Letting the box set a random MAC address should be a last
resort, because those MAC addresses are unusual and can easily identify your
system as a FreedomBox.

To find the current MAC addresses, run:

    > printenv

The MAC addresses will be on lines like these.  Save the whole line:

    > ethaddr=F0:AD:4E:00:00:00
    > eth1addr=F0:AD:4E:00:00:01

Now that you've recorded the MAC addresses for each interface, you need to 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.
That JTAG magic is described in the *Errors* -> *Unbricking a DreamPlug* section
at the end of this document.

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.

After you restore your microSD card to the DreamPlug, you should try booting it.
If the boot fails because of an "Invalid boot device", you'll need to interrupt
the boot process again to update the firmware with the settings described in the
*Errors* -> *Unbricking a DreamPlug* section, at the end of this document.

# 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 connect directly to the box to
watch it boot by running:

    $ sudo screen /dev/ttyUSB0 115200

You'll see the DreamPlug 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:

    # sudo screen /dev/ttyUSB0 115200

If ``screen`` fails, see the *Errors* -> *Troubleshooting Screen* section at the
end of this document.

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 console=ttyS0,115200
    setenv x_bootargs_root root=/dev/sdc2 rootdelay=10 rootflags=subvol=@
    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".

- - - - -

If booting from the USB stick fails because u-boot in the Dreamplug doesn't
recognize the FAT partition on your stick, it may be because the partition
type code isn't one of the FAT variants that u-boot recognizes.  It's not
clear what the root cause is yet, but if this happens, plug the USB stick
into a Linux machine and use your favorite partition editor (fdisk works)
to change the type of partition 1 to something like '6' which is simple
FAT16, then write the change.  This won't change the *contents* of the
partition, but it may allow u-boot to recognize it.

- - - - -

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:

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

After copy2dream completes, you may need to update /etc/fstab by hand since
copy2dream does not yet understand UUIDs in that file.

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 from gigE, which makes boot go much faster.  If
you flashed the bootloader, you'll need to replace the *ethaddr* and *eth1addr*
lines with the MAC addresses you previously recorded.  If you didn't record MAC
addresses, completely exclude those two lines.

    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 console=ttyS0,115200
    setenv x_bootargs_root root=/dev/sda2 rootdelay=10 rootflags=subvol=@
    setenv ethaddr=F0:AD:4E:00:00:00
    setenv eth1addr=F0:AD:4E:00:00:01
    saveenv
    reset

Congratulations, you're done!  To connect your DreamPlug to the Internet, plug
an Ethernet cord from the box's *eth0* port into your router.  The *eth0* port
is the inner Ethernet port.  To connect to the Internet through your DreamPlug,
plug your computer's Ethernet port into the box's eth1 port.  The *eth1* port is
the outer Ethernet port.

# To Make It

To build the image, download and install the dependencies for each of the images
you want to build.

Required for all images:

    # apt-get -y install git python-docutils mktorrent vmdebootstrap \
                 dosfstools btrfs-tools

Required for VirtualBox:

    # apt-get -y install extlinux virtualbox

Required for RaspberryPi:

    # apt-get -y install qemu-user-static binfmt-support

Required for DreamPlug:

    # apt-get -y install qemu-user-static binfmt-support u-boot-tools

Now, fetch the git source of freedom-maker and build the image you want:

    $ git clone http://anonscm.debian.org/git/freedombox/freedom-maker.git freedom-maker
    $ make -C freedom-maker dreamplug raspberry virtualbox

If you only want one of the possible images of DreamPlug, RaspberryPi and
VirtualBox, remove the rest from the make command line.  The images will show up
in freedom-maker/build/.

*dd* the images to the SD card (for DreamPlug and RaspberryPi), or create a new
VM for the VirtualBox hard drive file, and boot the client.

# 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.
- /source: The root file system.

## Makefile

There are three major targets to be aware of:

- dreamplug-image: This builds an image for the DreamPlug's internal SD card.
- raspberry-image: This builds an image for the RasbperryPi's SD card.
- virtualbox-image: This builds an image for the VirtualBox virtualization tool.

## /bin/mk_freedombox_image

Starts building the image by running vmdebootstrap.

## /bin/mk_virtualbox_image

Adds FreedomBox specific customizations to the image.

# Errors

This section documents known errors with the process and what you can do about
them.

## Invalid boot device

If, while booting your DreamPlug, you receive this error message:

    2 Storage Device(s) found

    ** Invalid boot device **

    ** Invalid boot device **
    Wrong Image Format for bootm command
    ERROR: can't get kernel image!

Make sure you've updated your DreamPlug to boot from the internal microSD card.
You'll need to plug in the JTAG and interrupt the boot process to paste in these
commands:

    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 console=ttyS0,115200
    setenv x_bootargs_root root=/dev/sda2 rootdelay=10 rootflags=subvol=@
    saveenv
    reset

## Troubleshooting Screen

If screen fails when you're running:

    $ sudo screen /dev/ttyUSB0 115200

First, verify that the ``usbserial`` module is loaded:

    $ sudo modprobe usbserial
    $ sudo lsmod | grep usbserial

Then, make sure your JTAG is plugged into both your DreamPlug and USB ports and
verify that you can access the ``/dev/ttyUSB0`` device:

    $ sudo tail -f /dev/ttyUSB0

If that fails, you can try creating the device:

    $ sudo mknod /dev/ttyUSB0 c 188 0

You may then be able to access the device via tail or screen.  If not, then
[DIYF](https://duckduckgo.com).

## Unbricking a DreamPlug

You should first try to follow the
[simpler instructions from GlobalScale](https://code.google.com/p/dreamplug/downloads/detail?name=DreamPlug-Reflash%20uboot%20guide_%20Aug-28-2012.pdf&can=2&q=).
Search for the
"[Reflash uboot guide](https://code.google.com/p/dreamplug/downloads/list)" if
the link doesn't work.

If those instructions don't work, you should then try these instructions.

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.

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

2. First, install the required packages:

        $ sudo apt-get install openocd telnet screen

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

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

        $ sudo screen /dev/ttyUSB0 115200

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

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

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

8. Next open a 3rd terminal session.

        $ telnet localhost 4444

9. Output should look like this:

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

10. Then, in that third seesion, run:

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

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

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