rescueOS/documentation.txt

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)
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. But should have existed
anyway, correct? 

-Charging the battery (when maemo is dead).

-Modification of the EMMC partitions and partition table.

-Backing up & Restoring maemo rootfs.

-fsck file system checks

-and more...

Booting the initrd
~~~~~~~~~~~~~~~
Note: You can not store persistent data in / as everything happens in RAM. Of
course, it becomes possible when you mount the EMMC or sd card on the
corresponding mountpoint.  

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

flasher-3.5 -k 2.6.37 -n initrd.img -l -b"rootdelay root=/dev/ram0"

wait for "suitable device not found..." and connect the N900 to your 
Linux box through USB.


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

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.

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

How to transfer files
=====================
It asks you on boot whether an FTP Server should be started. 
This will have anonymous up and download permissions 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).