LeapFrog Pollux Platform: OpenLFConnect

From eLinux.org
Jump to: navigation, search

OpenLFConnect is a Python and sg3_utils command line based replacement application for the LeapFrog LFConnect program and more. For Explorer and LeapPad it can use their dftpdevice to upload firmware. It also manages uploading the surgeon.cbf file for USB boot recovery mode and is capable of enabling ftp/telnet on both devices. For Didj it can mount the USB drive, copy firmware over, and send the eject command that will attempt to start flashing the firmware. There are also extra functions for wrapping and unwrapping CBF files and extracting lf2/lfp packages.

The program deals with firmware/bootloader items. The update functions deal with those exclusively, for updating the offical LeapFrog user interfaces, games, movies, etc. You'll need to use the LFConnect program. Especially if you want those things to run as they should, since there is online functionality that is required for certain features.

WARNING: This program can flash new firmware, has the ability to make and delete, upload and download, files could be destroyed, firmware flashing could go wrong. There is no prompts for second chances. Make sure you understand what you're doing, and use fresh batteries or an A/C adapter during updating.


Downloads

https://github.com/jrspruitt/OpenLFConnect

Command Reference

https://github.com/jrspruitt/OpenLFConnect/blob/master/doc/command_reference.md

Install and Getting Started

https://github.com/jrspruitt/OpenLFConnect/blob/master/readme.md#install

Examples

There is basically four types of commands.

OpenLFConnect commands, debug on, set_host_ip, get_mount_point, these are some basic configuration settings used by the base application.

Client commands, dftp_connect, didj_mount, boot_surgeon didj_update, dftp_reboot, these are commands specific to the client that is running, and are checked to make sure their respective client is the currently running client.

Filesystem commands, ls, cd, cat, upload, download, these are your basic filesystem commands, for navigation or basic maintenance.

Utility commands, package_download, cbf_unwrap, jffs2_create_eroots, these commands are there to help facilitate creating updates. Either packaging, or opening up the stock firmware for modification.


Caution, there are no prompts to ask if you are sure. Uploading will over write a directory or file, deleting a directory will remove it regardless if there is anything in it, etc, etc. Also always make sure you are where you think you are, its easy to forget you switched to local or remote, and run a command thinking you are somewhere else. You've been warned, cwdl and cwdr are you're friends, they will tell you where each path is pointed to and pay attention to the prompt prefix.


Didj

The Didj is different than the LeapPad or Explorer in that it is not a networking enabled device. Once you mount the Didj, you will be given a remote prompt, in reality you are still on the local filesystem, you can still use all the same commands if you like however. The Didj client has a few specific commands, all prefixed with didj_.

The first thing you should do with your Didj, is back up the entire drive that gets mounted, archive it, and keep it somewhere safe. It will be needed if your Didj ever says it "needs repair."

A word of caution to prevent "needs repair" issues. Always make sure to safely eject the device, to allow the host OS to commit the changes. If you just pull the plug, it can cause data corruption.

Didj Command List

Filesystem Command List

General

Once Didj is plugged in and turned on, start the client and connect.

local>didj_mount
Mounted on /dev/Didj

This will obtain the location the Didj is mounted on. You should see a new window pop up with the contents, or it show up in your file browser, depending on the OS used. For general purpose looking around, its far easier to use the OS's file browser. But if you would like to run an update of the firmware or bootloader, OpenLFConnect can make it rather painless.

Send the eject command, to be gentle with your Didj or start firmware update.

didj_eject

Updates

Preperation

Didj is by far the easiest to mess up while updating, or transferring any files for that matter. Be sure you never pull the power or turn it off, before files have been synced/disk cache written. A partial write in the directory makes it 99.9% certain of file corruption, as fdsk is ran on boot, if it finds anything wrong, it panics. Which generally means formatting and replacing all the files.

Caution: Use and A/C adapter, or fresh batteries, a power outage during this will ruin your update, and could leave your device in need of repair.

More Information on firmware updating.

OpenLFConnect tries to make formatting your updates as easy as possible.

Firmware when running the didj_update, or didj_update_firmware commands it will first search the current directory, for the firmware-LF_LF1000 that the LeapFrog update comes in, if it finds it, it will update your Didj with its contents. If it can't find that particular directory, it will search the current directory for files with names matching 'erootfs' and 'kernel'. This means you could have custom-kernel.bin and erootfs-custom.jffs2 and it will pick those up for updating. It will then created the md5 files and firmware-LF_LF1000 directory on the Didj to place your files in. So you do not have to worry about creating the necessary support files and directory. One thing to mention, the update must include an erootfs.jffs2 and kernel.bin file, OpenLFConnect will fail if not both are not found, as Didj would refuse to update, if only one was available. There is a couple rules to follow, so OpenLFConnect does not pick the wrong update, do not keep your files in a directory with a firmware-LF_LF1000/ directory, as it will search that and use the files in it instead, and only have one set of update files in the directory, as it will cause issues if more than one is found.

Bootloader is almost exactly the same as firmware, with one difference, you can choose a specific lightning-boot.bin file to upload, as this is the only file required for a bootloader update. If you do not specify the file, giving only a directory, the same search pattern takes place as above, except for bootstrap-LF_LF1000 as the directory. This also creates the necessary support files for the update, directory, and md5 file.

Update both with change to directory.

local>cd /Didj

local>ls
bootloader-LF_LF1000
firmware-LF_LF1000

Update both.

local>didj_update

Update Firmware using the parent path.

local>didj_update_firmware Didj/

Update Bootloader with path to a file.

local>didj_update_bootloader Didj/my-bootloader/lightning-boot.bin

It will take a second for the command prompt to come back after the files have transferred and eject command sent. Once ejected the Didj screen should change, it will say "Learning new tricks" Then "Disconnect Now". Once you do it will shutdown. Turn it back on and plug it in. run:

local>didj_mount
local>didj_update_cleanup

This removes the update files to prevent unwanted firmware flashes if the eject command is sent again. If everything went okay your files will have been flashed to the Didj and you can now use it.

Needs Repair

This section is part warning, part remedy. With disk caching enabled, it is fairly easy to corrupt the Didj's drive. When ever possible, use safely remove options, which will flush the disk cache before removing. The Didj, when in good status, seems to hold up on the eject command until everything is synced, especially on Windows, for Linux OpenLFConnect will run the sync command prior to issuing the eject.

Needs Repairs and Download Failed

To fix it you'll first need your backup copy of the disks contents,Base/ Data/ and ProgramFiles/ at the very minimum Base/ is required, Data/ holds your user profile type stuff, ProgramFiles/ is for JetPackHeros. Then format the drive with FAT, when done copy over your backups then safely eject it, preferably use didj_eject. Most of the time this has worked for me in fixing any issue that arises.

If you want the be all to end all access for such issues check out serial console. In console if you just can't get anything going, cause it "brazenly refuses to mount /dev/mtdblock9" rmmod g_file_storage this disables usb storage and takes out the /flags/needs_repair that won't go away, as it is set by the usb driver.

Prevention

Always use safely remove, if you've uploaded data, especially with a Linux host PC as data corruption seems far more likely. On a Linux host, OpenLFConnect will run the sync command, before ejecting. Its actually a fairly good idea to use the didj_eject command each time. Windows, XP at least, seems more friendly in these regards, as didj_eject will hold up until files are written. It is still highly recommended to disable disk cache in Windows aka Quick Removal. As for Linux, mounting with the sync option is a good idea also. But getting this to work with automounting can be problematic. Manually running sync, safely removing, or running didj_eject should all take care of it.

LeapPad and Explorer

LeapPad and Explorer are both network connected and use the same DFTPdevice, as does both versions of Surgeon. There are a few client specific commands available, but mostly it is much like a basic ftp client. All DFTP commands are prefixed with dftp_.

DFTP Command List

Filesystem Command List

General

There are a few things worth doing with OpenLFConnect and your Explorer. You can send a surgeon.cbf file, or any kernel and or initramfs you want to test that has been converted to CBF Commands, Information. You can run firmware updates, there is a convenience function for enabling ftp, or you can use it like a basic ftp browser.

Once the device is turned on and plugged in.

Connect to it.

dftp_connect
prints device info...

Disconnect, device can be reconnected to with out unplugging or restarting application.

dftp_disconnect


Reboot the device and/or disconnect.(depends what you're running Surgeon, Explorer, LeapPad, as to if it reboots or not)

dftp_reboot

Starting FTP, Telnet and SSHD

When normally booted, FTP and Telnet are not running, while they will be if surgeon is running. SSHD is never enabled, but can be. These use the dftp RUN command, to upload a shell script, these can be found in files/Extras/Scripts/. All three will have the same log in.

Username:root
Password:[blank]

dftp_run_script Extras/Scripts/command.sh

On Linux you can install the service-discovery-applet which will automatically pick up the FTP and SSHD server announcing themselves. Look in Places>Network. In Windows it should show up in any Bonjour apps that display services.

USB Booting

There is a special mode called USB Boot mode, which can accept a Surgeon.cbf file. Both Explorer and LeapPad have it. You can access this mode using dftp_reboot_usbmode, or on the Explorer through holding both shoulder buttons and the ? while turning it on. As for LeapPad a hardware method is not known.

There are two versions of surgeon, one for LeapPad and one for Explorer. The DFTPdevice on the LeapPad version is better, disconnects do not reboot the device. As far as functionality, updating seems to work just as well also.

More Information

Put the device in USB boot mode.

OpenLFConnect with device connected and running normally.

remote>dftp_reboot_usbmode

Button presses.

Explorer: hold both shoulder buttons and the ? button while turning it on.

LeapPad: hold the right D-pad, home button, and volume down while turning it on.

Download Surgeon if you do not have it.

local>cd LX/
local>package_download explorer surgeon

Extract package file

local>package_extract LX_surgeon.1.3.4.2859.lfp
local>ls
 Surgeon/
cd Surgeon

Boot surgeon file. This will take about 30 seconds or so to return.

boot_surgeon surgeon.cbf

You can then connect to the DFTP server surgeon sets up.

local>dftp_connect
 ...device info...
remote>

Update

Update is determined by if fuse-flasher on LeapPad has created the /LF/fuse directory, if so, it tries a Fuse (LeapPad) style update if not a standard DFTP (Explorer) style. This allows you to run the LeapPad surgeon during updates also, as it will not create the fuse folder, falling back to a regular DFTP style update.

Caution: Use and A/C adapter, or fresh batteries, a power outage during this will ruin your update, and could leave your device in need of repair.

Update Files

dftp_update first looks for the official firmware directories in the directory specified, firmware/ (LeapPad) Firmware-Base/ (Explorer). Failing that, it looks for the files it would normally find inside those directories. If those are not found, it tries to match a list of keywords to the files in the current directory.

LeapPad: nfs, kernel, mbr2G, FIRST_Lpad
Explorer erootfs, kernel, FIRST

The first files it finds to match those, it will attempt to upload while translating to the proper path and file names.It is best to not have multiples, as its not guaranteed which one will be selected. Also any CBF file will be checked for a valid magic number and length before any upload takes place.

You may also specify a single file to upload, and it will translate it for you.


Boot Surgeon.cbf

You will also need a surgeon.cbf file, this will be sent to the device while its in USB boot mode, and establishes the necessary systems for the flashing process.

Once you got your firmware ready, put the device in USB boot mode and boot surgeon:

local>surgeon_boot /path/to/Explorer/surgeon.cbf


Run Update

Connect to the device

local>dftp_connect

It will take a few for the device to boot up, you will then have the command line back. And can start flashing your files.

remote>dftp_update /files/Explorer/Firmware-Base

Once done uploading reboot the device.

remote>dftp_reboot

You can now unplug the USB cord, or otherwise let it boot normally. You can connect again if you like, and browse around too.

Explorer File Names These file names must be prefixed as they are, as the name has significance to the flashing process. The first number is the NAND address in decimal to flash to, and the second is the size of the partition in packets, which the packet size is 131072. Check Explorer technical information for the partitions numbers.

1048576,8,FIRST.32.rle
2097152,64,kernel.cbf
10485760,688,erootfs.ubi