This program (including documentation) is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License version 3 (GPLv3; http://www.gnu.org/licenses/gpl-3.0.html ) for more details.

If you don't know what you are doing, think twice before using this guide. I take absolutely no responsibility for any damage(s) that you might cause to your hard- and/or software-environment by following the descriptions below!

Pogoplug_V3_Emdebian_Debian

Scripts to create a bootable Emdebian or Debian drive for the Pogoplug V3 devices. Emdebian is (mostly) binary compatible to the same Debian versions. However Emdebian is size optimized, by removing documentation etc. .
Hint: Emdebian is far better suited for a NAND install!

ATTENTION:

• The original ARCH Linux kernel 2.6.31.6, that is flashed to NAND per default, is too old to run Debian/Emdebian Wheezy or anything newer!
  
• If you want to run Wheezy, or anything newer, you will have to update the kernel FIRST! Otherwise the system won't boot!
  
• A SERIAL CONNECTION to the Pogoplug is HIGHLY RECOMMENDED for this procedure.
  Debugging is more or less impossible without it!


• Most of the descriptions below assume that you are able to connect to the Pogoplug via serial connection!!!


• A working INTERNET CONNECTION is mandatory and must be available RIGHT AWAY when running the script! So please make sure to be connected before starting the script.

Otherwise you will simply get an error message right away, stating the lack of a connection.

---

HOWTO: Emdebian or Debian on the Pogoplug V3 (Classic and/or Pro)

Step-by-step description on how to get Emdebian runnning on your Pogogplug V3:

1. Boot your Pogoplug V3 and install Arch Linux, like explained here: http://archlinuxarm.org/platforms/armv6/pogoplug-provideov3
2. Then get your Debian or Ubuntu Host machine ready and get the scipts via git or download them as a zip file: 'git clone git://github.com/ingmar-k/Pogoplug_V3_Emdebian_Debian.git' OR https://github.com/ingmar-k/Pogoplug_V3_Emdebian_Debian/archive/master.zip
3. Make the file build_emdebian_debian_system.sh executable, by running 'chmod +x build_emdebian_debian_system.sh'
4. VERY IMPORTANT: Edit the file general_settings.sh to exactly represent your host system, Pogoplug-device and network environment.
5. Run the script with root privileges (su or sudo!) by typing './build_emdebian_system.sh'
6. When the script is done, boot your Pogoplug Classic/Pro with the newly created USB-drive attached.
7. If everything went well, the Plug should boot fine and be accessible via SSH (if you installed the package and the network settings are correct --> general_settings.sh ).

DEBUGGING:

There are several log files that get created while running the script. The main one, log.txt can be found under ${output_dir}/log.txt, where ${output_dir} is a variable that you set in the file general_settings.sh.

Several other log and error-log files get created in the root directory of the target-rootfs (the root filesystem that the script creates). If you need to find an error, have a look there, too. If the script comes that far, you can find the files in the output-archive (hint: ${output_dir}/${output_filename}, as set in general_settings.sh ) that the script creates.
If the error occurs before the creation of the output-archive, you might want to set the option clean_tmp_files in the general_settings.sh to no. This will cause the script to KEEP the temporary image file that is used for the rootfs creation. In order to debug you can then mount that very image file via loop, after the script failed.

Running the script with call parameters (special functions)

The script at the moment accepts three main call parameters. These are "build", "install". and "clean".

Descriptions:

build : This only runs the script's functions to build a new rootfs including kernel, but does not create a bootable USB drive (drive). It is meant for those creating rootfs-archives for others to use, with known-to-work configurations.

install : Opposite of "build"! It will just download/copy/link a prebuilt rootfs-archive + bootloader and will create a bootable USB drive using these files. This is meant for people not familiar with the build specifics who just want to create a SD-card with known-to-work rootfs configurations. The "install" parameter, however REQUIRES a valid second parameter, to work properly. You need to pass the complete path+filename of a compressed (.tar.gz or .tar.bz2) rootfs-archive of your choice on to the script. The archive can be located online (for example 'http://www.tester.com/rootfs.tar.bz2' ) or on your local storage (for example '/home/tester/rootfs.tar.bz2' ). The script should be able to handle both cases just fine.

clean : Cleanup the build directory This option is used to delete either the files located in the cache or build directories, or even in both. As the script knows caching of apt-packages, it might sometimes be necessary to delete the old cache files before starting a new build. That's what --clean cache would be for. Respectively, --clean build would only delete the files and folders in the build directory and --clean all would do both.

Usage examples:

sudo ./build_emdebian_system.sh --build will run only the scripts build funtions to create a rootfs-archive according to your settings (NO USB drive creation!).

sudo ./build_emdebian_system.sh --install http://www.tester.com/rootfs.tar.bz2 will download the named rootfs-archive and create a bootable USB drive with it.

sudo ./build_emdebian_system.sh --install /local/path/to/rootfs.tar.bz2 will create a bootable USB drive, using the local rootfs-archive that you set.

sudo ./build_emdebian_system.sh --build will run only the scripts build funtions to create a rootfs-archive according to your settings.

sudo ./build_emdebian_system.sh --clean all will delete both the files in the build and cache directories.

sudo ./build_emdebian_system.sh --clean cache will only delete the files in the cache directory.

sudo ./build_emdebian_system.sh --clean build will only delete the files in the build directory.

Any wrong parameter leads to an error message and a short help text, explaining the valid usage options.

Booting directly from SATA

The PLX 7821, aka OXNAS 820, CPU support booting directly from SATA, without even needing NAND. The scrips are able to create a drive that is ready to boot directly, when connected to the internal SATA port of the Pogoplug V3 device.
In order to create a drive in such a manner, you have to do the follwoing:

In the file general_settings.sh you need to set the option boot_directly_via_sata to yes.
Finally you need to specifically check that the settings for the following variables are OK:

• std_kernel_pkg
• sata_boot_stage1
• sata_uboot

Besides that you just run the scripts, like described for USB booting.

Flashing and testing a new kernel

If you want to use a new/newer kernel, you need to replace the original (Arch Linux-)Kernel in NAND.

Here is how to do that:

1. Boot your pogoplug and get (through USB, wget etc. ) the new uImage and kernel modules.
2. Make sure to place the new kernels modules directory into /lib/modules !
3. Then run '/usr/sbin/flash_erase /dev/mtd1 0xB00000 24' to delete the backup image in flash.
4. By running '/usr/sbin/nandwrite -p -s 0xB00000 /dev/mtd1 /path/to/new/uImage' you write the newer uImage to flash.
5. Reboot the Pogoplug and interrupt the boot process at the Uboot prompt( CE>> ).
6. In order to boot the backup kernel image directly, instead of the main image, run 'run load_custom_nand2 boot' (as found in the second half of the boot_custom command, shown by running 'printenv' )
7. This will boot the backup kernel image for one time only. At the next reboot, the default command will be run again.
8. Extensively (!!!) test the kernel before thinking about making it your default kernel!
9. To make this new kernel the default, repeat steps 3. and 4. with the hex adress 0x500000, INSTEAD OF 0xB00000.
10. The Pogoplug will then boot to the new kernel by default.

Root-filesystem in NAND

Now that the Pogoplug boots Emdebian (Debian will probably be way too big for NAND) from USB, the next possible (but optional) step is putting the rootfs into NAND.

1. First, shut down your Pogoplug, remove the USB drive and attach it to your desktop system that was used to create the Emdebian rootfs.

2. Create a new directory on the USB drive (for example named nand_rootfs).

3. Extract the created rootfs archive (by default emdebian_rootfs_pogoplug_v3.tar.bz2 file) into the newly created directory.

4. Open the filesystem-table used for mounting the Rootfs ( ./nand_rootfs/etc/fstab ) with an editor (for example nano).

5. Remove the 2 lines '/dev/root / ext3/ext4 defaults,noatime 0 1' and '/dev/sda2 none swap defaults 0 0', replace them with '/dev/root / ubifs defaults,noatime 0 0' and save the file.

6. Make absolutely sure that the nand_rootfs-directory includes the needed kernel modules in /lib/modules !

7. To delete the contents of the old rootfs in nand, run the command 'flash_eraseall /dev/mtd2' ( with mtd2 being the rootfs partition according to 'cat /proc/mtd' ).

8. Change into a different directory, that is not part of the nand_rootfs dir !!!

9. Create a file called ubinize.cfg, with the following content:

   [ubifs]
   mode=ubi
   image=ubifs.img
   vol_id=0
   vol_size=100MiB
   vol_type=dynamic
   vol_name=rootfs
   vol_alignment=1
   vol_flags=autoresize

10. Check your boot log (or via dmesg) for the UBI entry called UBI: available PEBs: and memorize or write down the number ( should be something like '897' ).

11. Run 'mkfs.ubifs -r /nand_rootfs -m 2048 -e 129024 -c 897 -x zlib -o ubifs.img' with the parameters fitting your system (very important, the number after '-c' is the one you memorized). Check the other parameters, too, to be sure.

12. Then run 'ubinize -o ubi.img -m 2048 -p 128KiB -s 512 ubinize.cfg' to create the final image, ready to flash.

13. To flash that image to NAND, you first need to detach second the partition (mtd2) from UBI, by running 'ubidetach /dev/ubi_ctrl -m 2' .

14. Finally flash the created image to NAND by running 'ubiformat /dev/mtd2 -f ubi.img' .

15. Reboot the Pogoplug and again interrupt the boot process at the Uboot prompt.

16. To boot the system from NAND, run the commmand 'setenv bootargs $bootargs_stock' , followed by 'run boot_custom'.

17. This change again is only temporary until the next reboot.

18. To make the Pogoplug boot from NAND by default, run 'setenv bootargs $bootargs_stock' at the Uboot prompt again, followed followed by running 'saveenv' .

19. Now the Pogoplug should boot to NAND by default.