Batman

batman is a Forth script for the OLPC firmware which is used for advanced diagnostics and repair of the laptop battery. It is available from http://dev.laptop.org/pub/firmware/scripts/batman.fth and certain parts are included in recent firmware versions.

NOTE: batman is incompatible with XO-1.75. Any repairs done with batman must be performed on a XO-1 or XO-1.5 laptop.

Usage

Batman is invoked from an Open Firmware (OFW) ok prompt. This usually requires a developer key.

Internal version

batman's functionality tends to get pulled into the official OLPC firmware releases at irregular intervals. If you are running a recent firmware, you may well already have the functionality available at you fingertips. Try running the procedure you wish to run, e.g.

ok batman-start

External version

The external batman.fth file tends to be more up-to-date than the one included in the firmware; new additions and changes may only appear in the external version. To use:

1. Place batman.fth on a USB key
2. Insert the USB key into the laptop XO (while it is turned off)
3. Start the laptop
4. Go to the ok prompt by pushing the ESC key while the laptop is starting up.
5. At the prompt, type:

fload u:\batman.fth

The batman script may be stored on devices other than a USB key. It is loaded with the 'fload' command, which must specify the storage device where bathman.fth is located:

USB disk:
 fload usb:\batman.fth
SD card:
 fload sd:\batman.fth
NAND flash (root directory):
 fload nand:\batman.fth

Once loaded you run the commands in the script just like any other OpenFirmware command. If you turn off the laptop, you have to repeat the loading process.

Key tools in batman.fth

The following is a list of useful tools in batman.fth with a brief note how to use them. Some of these commands require that the EC be put into reset prior to running them so that the EC battery management system is disabled. The 1w-init command does this. After the 1w-init command is used all keyboard, touchpad and button activity is disabled. Including the power button. Any command requiring a 1w-init will require that any further commands be invoked using the processor serial port. To power off the laptop afterwards, you will have to remove both external power and the battery. (note: if you came here from LiFePO4 Recovery Procedure you only need to run the bat-recover command)

• batman-start

Put the EC in reset and prepare the system so that Open Firmware can talk directly to the gas gauge chip in the battery. Newer firmware only suspends the battery interface and leaves the keyboard working. Required prior to some of the other commands.

ok batman-start

• batman-stop

undoes what batman-start did.

ok batman-stop

• see-bstate

Continually prints the EC 1-wire communication state machine index. Useful for determining if the EC can talk to the battery gas gauge.

ok see-bstate

• bat-recover

Does PWM on the charge enable line resulting in a psuedo-current limited charge of the battery. Streams the battery temperature, currrent, voltage and accumulated charge register (ACR) to the screen.

Automatically runs batman-start.

Remove the battery to cause bat-recover to exit (with an error message).

ok bat-recover

• bat-set-low

Zeros out various values in the battery's gas gauge EEPROM forcing the EC to resync with the state of the battery. Useful if your battery is marked as full when it really is not.

Needs batman-start.

ok batman-start bat-set-low