Documentation of rescueOS
=========================
rescueOS is a rescue solution for the Nokia N900, distributed
as an initrd image. It has several features, most
notable:

mounting maemo /
EMMC access(can mount maemo home and MyDocs partition)
Lock code reset
WiFi support
USB mass-storage mode
USB networking
Battery charging

Users must be familiar with the Linux console.

This project is _NOT_ the meego rescue initrd.


How does it work?
~~~~~~~~~~~~~~~~~
The flasher utility loads rescueOS. This makes it unnecessary 
to modify the bootloader or maemo's /sbin/preinit like other solutions do. 

By using the "-l" option, we do not flash the kernel or initrd image.
It only loads the kernel into RAM. No modification on
the NAND or bootloader happens.


Use cases
~~~~~~~~~
In fact, most users do not need it. Either way, possible use cases:

-Changing typos in bootscripts which prevent an operation system
(e.g. maemo) to boot. 

-Creating a backup of files before starting a reflash. 

-Charging the battery (when maemo is dead).

-Modification of the EMMC partitions and partition table.

-Backing up & Restoring maemo rootfs.

-fsck file system checks

-Resetting the lock code (without reflashing)

-and more...


Booting rescueOS with flasher
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note: You can not store persistent data in /. Of
course, it becomes possible on the mount points you mount the EMMC or sd card
to.

Note: It comes without any promises and without any warranty. Therefore you
are doing everything at your own risk. 

To load rescueOS onto an N900, you'll need a USB data cable, a PC, and one of
the following flashers:

- 0xFFFF - the Open Free Fiasco Firmware Flasher
  Free/open source, but only runs on GNU/Linux.
  Packaged for Ubuntu and Debian as '0xffff':
    http://packages.ubuntu.com/source/0xffff
    https://packages.debian.org/sid/0xffff
  Discussion:  http://talk.maemo.org/showthread.php?t=87996
  Source repo: https://github.com/pali/0xFFFF

- maemo_flasher v3.5 - the original proprietary flasher from Nokia
  Windows, MacOS, GNU/Linux
  Official distribution site is gone.  Archive copies at:
    https://web.archive.org/web/20131117084237/http://skeiron.org/tablets-dev/maemo_dev_env_downloads/
  Documentation:
    http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Development_Environment/Maemo_Flasher-3.5

Switch the N900 completely off.  If it is plugged into a charger, a PC, or
anything else by its USB port, unplug it and wait about 10 seconds to give the
charger software time to shut down.  Don't connect it to the PC just yet.

Startup the flasher and get it ready to load rescueOS.  For 0xFFFF, the
incantation is:

  0xFFFF -m kernel:rescueOS_n900_kernel_1.3.zImage -m initfs:rescueOS-1.3.img -l -b 'rootdelay root=/dev/ram0'

For maemo_flasher, it's:

  flasher-3.5 -k rescueOS_n900_kernel_1.3.zImage -n rescueOS-1.3.img -l -b"rootdelay root=/dev/ram0"

You'll get a message like "suitable device not found...", but the flasher
should block and wait.  Now connect the N900 to the PC with the data cable; the
flasher should detect the device, upload rescueOS, launch it, and then exit.


Booting rescueOS with U-Boot from SD card
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use this method if you have installed U-Boot (https://talk.maemo.org/showthread.php?t=81613)
and battery is so depleted, that flashing doesn't work.

You'll need "mkimage" command from "u-boot-tools" package.

Preparing required files:

mkimage -A arm -O linux -T kernel -C none -a 80008000 -e 80008000 -n kernel -d rescueOS_n900_kernel_1.3.zImage rescueOS_n900_kernel_1.3.uImage
mkimage -A arm -O linux -T ramdisk -C none -a 0 -e 0 -n initrd -d rescueOS-1.3.img rescueOS-1.3.uimg
cat >boot.cmd <<EOF
setenv bootargs rootdelay root=/dev/ram0;
setenv setup_omap_atag 1;
setenv mmckernfile rescueOS_n900_kernel_1.3.uImage;
setenv mmcinitrdfile rescueOS-1.3.uimg;
setenv mmcscriptfile;
run trymmckerninitrdboot;
EOF
mkimage -c none -A arm -T script -d boot.cmd boot.scr

Preparing SD card:
Your SD card needs to have the first partition formatted as ext2/3/4 or FAT.
Put generated files (without boot.cmd) in the root directory.

Now you should be able to boot rescueOS with generic "External SD card" option from U-Boot.


~~~~~~~~~~~~~~~
How to use it
~~~~~~~~~~~~~~~
It boots and you get a bash shell.

The folder /rescueOS/ contains some scripts for various tasks. Not all of them 
are completed yet. They help you with the usual stuff, e.g. mass-storage
mode, maemo root mounting, usbnetworking, WiFi setup etc.

Mounting maemo root
-------------------
/rescueOS/mount-maemo-root.sh
This scripts mounts the maemo root to /mnt/maemo. 

/rescueOS/umount-maemo-root.sh

Lock code reset
---------------
code_reset
# This will set the lock code back to the default ('12345').

USB Networking
--------------
/rescueOS/usbnetworking-enable.sh
Sets up USB networking in the following way:
ifconfig usb0 192.168.2.15 up
ifconfig usb0 netmask 255.255.255.0
route add 192.168.2.14 usb0

To disable it: /rescueOS/usbnetworking-disable.sh

USB Mass-Storage mode
--------------------
/rescueOS/mass-storage-enable.sh
Makes the first 2 EMMC partitions available for the mass-storage
mode. Known as /home/ and /home/user/MyDocs inside maemo.  

/rescueOS/mass-storage-disable.sh: Deactivates mass-storage mode.
Please unmount on your PC first. 

WiFi support
------------
It has wpa_supplicant, but without EAP support. This should be ok for
most home networks which use a PSK.

Give the following a try:

wpa_passphrase [essid] [password] > /run/wlan.conf
sh /rescueOS/setup-wpa-wifi.sh

For DHCP:

udhcpc -i wlan0.

Battery charging
----------------
By using ShadowJK's charge21 script. Use it only with the wallcharger,
as it pulls 950 mA, and USB is not designed for that 
(some ports can do it though, don't try if in doubt.)
 
/rescueOS/charge21.bash

Shutdown
--------
poweroff 

Root password
-------------
rootme

Shortcuts
---------
The following shortcuts are available to avoid unnecessary typing on the N900
keyboard. 
mmr -> mount maemo root
ummr -> umount maemo root
enftp -> enable ftp (anon upload/download everywhere)
mse -> enable mass-storage mode
msd -> disable mass-storage mode
usbne -> enable usb networking
usbnd -> disable usb networking
chargebat -> start battery charging
telnetd -> start telnetd. only necessary if you have closed it explicitly,
since it starts on boot.

Tab: Shift + Space
ESC: Fn (Arrow) + Ctrl


File transfer
----------------------
Enable the FTP server with "enftp". 
It will have anonymous up and download enabled everywhere.
Then you can connect to it once USB networking or a WLAN connection 
has been established, using any FTP client. For downloads, most browsers
can be used. 

Alternatively, use mass-storage mode.

Contributions and suggestions are welcome. Write to me (NIN101 on freenode or TMO. E-Mail: n900-rescueOS at quitesimple period org).