Open Recovery v1.37 [08/23/2010]

Open Recovery
Version: 1.37
Credit for mankind (from alldroid) for the CustomUpdate, on which this recovery is based,
credit for poseidon (also from alldroid) for ADBRecovery,
credit for koush for mtd-utils and nandroid (uses script based on it),
credit for nadlabak for keyboard layout change script.

!!!ATTENTION!!!
New backup format is used since 1.30. The recovery supports restoring the backups in the old format.
The backups in old format (there is a file "nandroid.md5" file in the folder) go to folder /sdcard/nandroid/adbrecovery/.
The backups in new format (there is a file "*.md5" file for each partition) go to folder /sdcard/nandroid/openrecovery/.

!!!IMPORTANT WARNING!!!
The md5 checksum files in the new nandroid in version 1.30 to 1.36 (fixed in 1.37) are not generated. The backups will restore normally, but there might be potential corruption.


Themes suplied -> OpenRecovery, Stock ...
Also Squirtle theme supplied (not on the screenshot).


Open Recovery on-phone console (only for Milestone).


Lite / Full concept on the XT701. The lite version is very much like the stock recovery but automatically changes to full version. Lite version shows only if error occurs.

Features:
- on-phone console (limited) - MILESTONE ONLY!
- rooting the phone from menu (using ChainsDD su and SuperUser.apk (version 2.2.2))
- nandroid backup/restore from menu
- apply update *.zip files from menu (located in OpenRecovery/updates folder under the sdcard root folder, there is a sample one (just unpacks a file named "babble" to /system), no signatures are needed
- special format of update.zip (noted lower)
- wipe data (factory reset)
- wipe cache
- wipe dalvik-cache
- adb in recovery, using bash shell
- run a script located in /sdcard/OpenRecovery/scripts folder under the sdcard root folder, the script can interactively prompt for a menu (sample included)
- recovery options for applications

Download & Installation (MILESTONE):
1) You need to have the vulnerable recovery with exploit, see this thread how to flash it: [You must be registered and logged in to see this link.]
2) Download the archive [You must be registered and logged in to see this link.] and unpack it to the root folder of the sdcard.

Usage (MILESTONE):
1) Reboot into recovery (hold 'X' button on bootloader 90.78, on others hold camera button; until you see triangle; then press camera + volume up)
2) Apply the update.zip
3) You are now in Open Recovery

Download & Installation (XT701):
1) Download the archive [You must be registered and logged in to see this link.] and Unpack it.
2) Either flash the sbf file using RSD Lite (preffered, recommended version 4.6+), or flash using the flash_image the *.img file to recovery partition.
3) Unpack the "OpenRecovery" folder and "OpenRecovery.zip" to the root folder of the sdcard.

Usage (XT701):
1) Reboot into recovery (hold camera button; until you see triangle; then press camera + volume up)
2) If no error occurs, you're now in Open Recovery. If error occurs you're in Open Recovery Lite.

NOTES

Console (MILESTONE ONLY):
- MENU key is CTRL, pressing MENU + ALT + C forcibly quits the console
- scrolling (pressing volume keys by a row (or eight rows if ALT is pressed))
- don't forget to select correct keyboard layout (under settings menu)
- search key is tab
- Alt+A prints "|" instead of Euro, Alt+F prints "$" instead of Pound
- limited support for escape characters but allowing to use "clear" and "ls" coloured

Changing a theme:
On /sdcard/OpenRecovery, the current theme is in "res" subfolder. The other two included are under "res.stock" or "res.squirtle". To change to another theme, let's say stock theme, rename the current "res" folder to "res.or" and "res.stock" to "res".

OR update.zip format:
- the update.zip is extracted to "/sdcard/OpenRecovery/tmp/update"
- shell script, located in the archive in "META-INF/update-or.sh" is called; under env. variable PACKAGE is the root folder of the extraction: "/sdcard/OpenRecovery/tmp/update"
- the script can do the very same as script called from the menu (can call imenu)
- progress bar is not supported in this format

ui.prop file:
This file sets the colors for the theme. It's located right under the "res" folder.
color3.LED=#100 <- led diode color (3-bit RGB, use only 0 or 1)
color32.background=#000000A0 <- recovery background color
color32.menu=#FF3705FF <- recovery menu color
color32.selection=#FFFFFFFF <- recovery selected item color
color32.script=#FFFF00FF <- recovery script color

#Console color properties
color24.console.header=#FFFF00 <- console header color
color24.console.background=#000000 <- console background color
color24.console.front=#E5E5E5 <- console foreground color

(The example values are used by default when the property is not found.)

Lite vs. Full version (XT701 ONLY):
- The recovery image contains Lite version, with minimal options (moreless only difference from stock recovery is the GUI and applying update.zip doesn't need any signatures.)
- When booting into recovery, the Lite version is started. It will automatically switch to full version by applying the OpenRecovery.zip).

CHANGELOG

Version 1.37
Bugfixes
- fixed nandroid restore not properly restoring yaffs2 partitions in old format
- fixed nandroid restore not restoring compressed backups
- fixed nandroid backup not taking md5 checksums

Changes
- console buffers up to 1000 lats printed lines (extended from 200)

Version 1.36
Bugfixes
- fixed nandroid when doing "Backup All" and not having apps2sd; which would fail complaining that /sddata could not be mounted
(Ticking all partitions in the menu and selecting "Backup Selected" was working properly and the backup has been done correctly.)
- fixed console cursor blinking
- squirtle theme fixed

Version 1.35
Features
- update.zip can be in new OR format using a shell script (described lower, there are samples of each one)
- console has now signalling implemented (menu key = CTRL)
- console has arrow keys implemented
- console has support for displaying front colors; thus it is no longer needed to disable bash colors
- console supports calling clear

Changes
- recovery binary will exit if not run by init (to prevent running it from adb or console)
- scripts in scripts folder are dos2unixed (on -FuFu- advice)
- switch files (.nobashcolors, .kdb_qwertz, etc.) are now located in /etc
- manual settings of the timezone (/etc/timezone), applied if the env. variable TZ doesn't exist
- update.zip no longer need to have the "update-binary", a default one is used if not found

Bugfixes
- fixed unyaffs not restoring sticky bit / suid / sgid
- fixed displaying long menus (it will not be truncated, instead a scrollbar appears)
- fixed error in switch.sh for XT701
- fixed color24.console.front in the themes -> default is supposed to be #E5E5E5

Version 1.32
Features
- pressing MENU + ALT + C forcibly quits the console

Changes
- ui.prop contains more options
- when applying any update.zip package, there is a confirmation menu
- cursor in console blinks

Bugfixes
- Error message when ext2 partition on sdcard doesn't exist fixed
- fixed the bug with imenu when ran more than once in one script

Version 1.30a
Bugfixes
- Console layout for QWERTZ / AZERTY fixed

Version 1.30
Features
- on-phone console
- keyboard layout changer included
- new nandroid, with support of backing up and restoring ext2 partition on sdcard (Note: uses new format of the backup, new backups are located in /sdcard/nandroid/openrecovery, there is a backwards compatibility to restore the old backups)
- ability to create compressed backups (and autoreboot when done)
- better nandroid menu
- menus wrap around
- theming for the recovery (3 themes included, to apply just rename the "res.*" folder to "res"); color settings can be manipulated in the ui.prop file under the res folder)
- new commands for menu (tag, label, break)
- scripts (command "shell") are able to show menu interactively when requesting user feedback (sample included)

Changes
- the OpenRecovery folder is same for all supported phones
- only 10 MB stock update file is used
- Logo, Cdrom and Linux bootloader can be backed up / restored with nandroid
- keyboard is lit
- mountable partitions are mounted by default

Bugfixes
- nandroid fixed
- fixed likely crash, when scripts prints '%', like '%s'
- menus don't blink when navigating from one to another
- LED diode blinking enhanced

Version 1.14
Changes
- UI
- switch.sh is separated (menu creation is in init_recovery.sh and called later by the recovery)
- Volume keys and Camera key can be used to navigate in Open Recovery

Version 1.12d
Bugfixes
- wipe commands working properly

Changes
- Bash Settings menu, to enable/disable coloured output (preset to disabled), this is persistent settings, it will last through reboots

Features
- ability to wipe dalvik-cache only (via script)

Version 1.12c
Bugfixes
- reboot command is working properly
- the content of the sdcard is no longer changed when running, everything is being copied into the ramdisk
- minor fixes

Changes
- removed the 'init' command, instead uses 'scripted_menu'
- adbd uses bash (interactively) instead of sh
- payload installs also bash and toolbox
- different the menu system (deprecated 'init' command), each menu must be generated from a script (notes later)
- added init folder, scripts (with extension *.sh) are ran there on startup of the open recovery.
- the diode is blinking in blue instead of red.

Features
- the recovery prints the output of the scripts / programs (prints their stdout)
- application menu (described later)
- new su and SuperUser.apk by ChainsDD
- if sdcard has ext2 partition, it is noted in fstab under "/sddata" (the module is inserted automatically)

Version 1.05
Bugfixes
- fixed a bug in payload making it dependant on the system
- there is now nothing in the /system folder when unmounted
- toolbox linked statically
- busybox now installs symlinks, instead of copying itself
- fixed a bug in adb about the shell being in /sbin/sh instead of /system/bin/sh
- cleaned up, removed unnecessary libraries and binaries
- switch.sh now initializes the Open Recovery completely, no other script is used for initialization
- permissions set correctly

Features
- added option to wipe
- menu's now have header (the menu file structure has been changed)
- added the possibility to run scripts, with .*sh extension located in scripts folder under OpenRecovery folder (shell is /sbin/sh or /sbin/bash)

Version 1.02
- fixed root installation

Version 1.01
- initial release

============================================================================================================================

DEVELOPER NOTES

Principle of switching:

The recovery contains an update.zip with payload, which doesn't do anything else than restarts to the open recovery. All the files for OpenRecovery are under the OpenRecovery folder under the root of the sdcard. The payload installs busybox to /sbin runs the "switch.sh" under the bin folder in open recovery.

Menu system:

The menu for the Open Recovery is created dynamically. The files must be created inside "/menu" folder by scripts, which can either be specified (if the menu is scripted_menu) or created by a *.sh script in /sdcard/OpenRecovery/init where the scripts are executed at startup. A menu creating script has to create a *.menu file inside the /menu folder. If the menu is supposed to be created on startup and not modified, place the script into /init folder, otherwise use "scripted_menu" item, where the script is ran right before the menu is created. sdcard, system and data partitions are mounted when the scripts are ran. A typical example for "scripted_menu" item is under the tutorial for application menu. For application menu see lower section. The structure of the menu file is different from the CustomUpdate by mankind:
First line is the menu name (normal string), then use the following structure:
"item name:type:argument"
- item name is what is seen in the menu
- type: type of the command (described later)
- argument: argument passed to the command (file, or anything else; if empty, put "*" there, otherwise the item will be discarded)

Commands:

- reboot: reboots the phone
- shell: calls a file specified in arguments (default path is to /bin, if not specified)
- menu: opens another menu file (specified in argument), if the argument is "..", it returns to up one level meu
- scripted_menu: argument is in format "menu file:menu script", the menu script is called with variable MENU_FILE containing the menu name (default path for the script is to /bin, if not specified)
- tag: if ticked, file "tags/.argument" is created
- break: unselectable item, argument is ignored (use "*") and creates a menu item like "---- name ----"; using "*" as name will create just "--------------"
- label: unselectable item, argument is ignored (use "*") and creates normal menu item "name "
- update: applies an update *.zip file, specified in argument (format SDCARD:$path_to_the_file_in_sdcard)
- wipe_data: factory reset
- wipe_cahce: wipe cache

The menu is refreshed (the script is called if the menu is scripted) on a menu change, applying an update or running a script. Whenever a script is ran, system, data and sdcard is mounted

Application menu:

Application menu is designed for anything that is run on the startup and can malfunction under any circumstances. Here is one example - suppose you have a mount on font in the startup. You'll have something like this in your startup script:

Code:


mount -o bind /system/myfonts/segoeui.ttf /system/fonts/DroidSans.ttf
mount -o bind /system/myfonts/segoeuib.ttf /system/fonts/DroidSans-Bold.ttf


Well the idea is that you add a condition to the script, to run only under some circumstances, like:

Code:


if [ ! -f /system/switch/.nocustomfont ]; then
   mount -o bind /system/myfonts/segoeui.ttf /system/fonts/DroidSans.ttf
   mount -o bind /system/myfonts/segoeuib.ttf /system/fonts/DroidSans-Bold.ttf
fi


which mounts the font only when /system/switch/.nocustomfont is not existing. If you want this controlable from the recovery, you register in into the application menu this way: all *.sh scripts in /app (where /sdcard/OpenRecovery/app is copied) are called at startup. They are passed variable "APP_MENU_FILE", which is the name of the used menu file (preinitalized). The script will look like this:

Code:


#!/sbin/sh

#create the menu item
echo "Custom Font:scripted_menu:custfont.menu:/app/custfont/menu.sh" >> "APP_MENU_FILE"


Note: yes there is a '$' before the APP_MENU_FILE, dunno why the vBulletin fails to show that in code.


Since the scripts are in /app and not /bin, use absolute path. This will add an item to the applications menu, now we need a menu when it is selected, which is the "/app/custfont/menu.sh":

Code:


#!/sbin/sh

if [ -f /system/switch/.nocustomfont ]; then
   # menu name - custom font is disabled
   echo "Custom Font (Disabled)" > "MENU_FILE"
   # go to upper level menu
   echo "Go Back:menu:.." >> "MENU_FILE"
   # enable it
   echo "Enable:shell:/app/custfont/enable.sh" >> "MENU_FILE"
else
   # menu name - custom font is enabled
   echo "Custom Font (Enabled)" > "MENU_FILE"
   # go to upper level menu
   echo "Go Back:menu:.." >> "MENU_FILE"
   # disable it
   echo "Disable:shell:/app/custfont/disable.sh" >> "MENU_FILE"
fi


Note: yes there is a '$' before each MENU_FILE, dunno why the vBulletin fails to show that in code.

Notice the shells are in /sbin, so use /sbin/sh (or /sbin/bash). The script checks if the switch is on or off and generates the menu accordingly. Since the menu is refreshed each time the script is run, it will always submit the correct option. The "enable.sh" simply touches the file and "disable.sh" just deletes it.

Source (v1.37):
[You must be registered and logged in to see this link.]

(The module name is "open_recovery_SHOLS", it can coexist next to the stock one.)

Note:
Don't forget that it uses bash to call all the scipts. (or edit the recovery.c "#define PHONE_SHELL" to go for sh)