LeapFrog Pollux Platform: OpenLFConnect

From eLinux.org
Revision as of 00:17, 26 January 2012 by Jrspruitt (talk | contribs)
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.

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

Requirements

Windows or Linux compatible

Python 2.6 - No special modules needed. Windows or Linux

sg3_utils

  • Included for Windows, common on many Linux distros

Windows

  • LeapFrog Ethernet Driver
  • If LFConnect is installed, or previously was, this is already installed.
  • If not, when it prompts you for a driver, use the Windows update service.

Bonjour For auto device IP discovery

  • If LFConnect is installed, or previously was, this is already installed.


Install

Extract archive or clone git repo to a location of your choice.

Windows

If LFConnect is installed you may want to make sure Monitor.exe is disabled, which can be done via Task Manager, before plugging a device in, this is the program that auto starts LFConnect. Or permanently stop it by deleting the regkey:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run\Monitor

Didj

You'll need to assign the Didj' USB Disk a drive letter as LFConnect will have assigned it another mount point instead. The letter you pick doesn't matter, as long as it doesn't conflict with something else. Plug your Didj in and then go to Disk Management, depending on what version of Windows it should be something like:

Administrative Tools > Computer Management > Disk Management

Right click the drive, and select Change Drive Letters and Paths click Add and assign the letter.

LeapPad and Explorer

Windows will default to a zeroconfig address, if you like you can just let it do that. But it takes a bit over a minute for it to do it. Static IP will greatly speed up the process.

Plug your device in and turn it on. You should see an icon in the Start Bar about trying to connect, if not go to Network Connections, right click and choose status. Then properties, scroll down to TCP/IP click on its properties, and make sure to set a static IP. Unless your device is set to a non standard IP, it will be on the 169.254. subnet. Windows will actually default to an address on this subnet, it takes a little over a minute from first turn on though, static IP is much faster.

Static IP: 169.254.0.1
Broadcast Mask: 255.255.0.0

Linux

Extract archive or clone git repo to a location of your choice.

You'll have to decide if you want to run OpenLFConnect.py with sudo or not. If you do not want to, you will need to copy the OpenLFConnect/src/udev_rules files to /etc/udev/rules.d/ The Mass_Storage rules are for all 3 devices. Didj in normal use and LeapPad, Explorer in USB Boot mode. The create a persistent generic SCSI device name /dev/leapfrog that is set to allow regular users permission to use.

Make sure the rule is owned by root:root and set to permission 644.

Didj

Other than the udev rules there is nothing to configure for Didj. One issue that may arise on your system, is Linux won't unmount when the didj_eject command is run. Didj will get the command, but you will have to unmount the drive in Nautilus or the command line for it to happen. The didj_umount command fails to work at all on Linux because of this.

LeapPad and Explorer

Plug your device in and turn it on, then check

System > Preferences > Network Connections

If you see Auto Eth1 open up its properties and go to the IPv4 tab, on the Methods drop down pick Link Local.

If you do not see the Auto Eth1 or something similar, you can copy the udev rules for Net to /etc/udev/rules.d/ This will trigger avahi-autoipd on plug in, and assign an IP address to the interface. This is basically what Network Manager does when set to Link Local.

Make sure the rule is owned by root:root and set to permission 644.


Usage

There is basically three types of commands. OpenLFConnect commands, such as manually configuring the host IP before a connection is made, debug settings, remote, or local. There are client commands, for DFTP and Didj, dftp_connect or didj_mount both start their respective clients and connections and each have various commands to run once started. Then there is filesystem commands, ls, cd, cat, upload, upload_dir, etc. Client commands are only available while the client is running, filesystem commands, are the same remote or local, obviously if no remote client is running, there is no where to upload something to though.

A word of 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.

Getting Started

From a terminal or the command prompt run OpenLFConnect.py this will bring up the python command line. In windows you can also double click on the file.

To get a full list of commands type

local>help

For help on a specific command

local>help command

Commands with an option in [] means its optional, commands with an option <> means it is mandatory.


Basic Commands

The basics are very similar to the Linux command line, and when first started, you will be able to navigate around the local filesystem. Some examples.

This changes the directory

local>cd files/LX

This lists a directory's contents.

local>ls files/Didj
bootloader-LF_LF1000/
firmware-LF_LF1000/

Connect to the device

local>dftp_connect
Device:		Explorer
Firmware Version:	1.3.4-2044
IP:			169.254.3.208
DFTP Version: 		1.8
remote>

Make a directory and list its contents.

remote>cd /tmp
remote>mkdir NewDir
remote>ls
NewDir/
temp.socket
temp.file


Download takes a remote path argument to a file, and will download it to the current local directory.

Upload takes a local path argument to a file, and will upload it to the current remote directory.

Set the remote directory to where the file you want to download resides in, switch back to local and navigate to where you want to save it. Then download.

remote>cd etc/
remote>local
local>cd LX/temp
local>download vsftpd.conf
local>ls
vsftpd.conf

Set your remote directory to where you want the file to be put, then upload a local file using the path argument.

remote>cd ../etc/avahi/
remote>upload ../../user/scripts/avahi-autoipd.action
remote>ls
avahi-autopid.action


Remote/Local Locations

Once a remote client is running, you can navigate both the local and remote filesystems. On Didj, remote just means it starts at the mounting point as technically they are both local.

This means you are on the host computer and the commands will take action on it.

local> command arg

This indicates you are about to run a command on the device.

remote> command arg

Change to remote device

local>remote
remote>

Change to local from remote

remote>local
local>

The are a few exceptions to this, Upload/Download commands don't care, as Upload wants a local path to upload to the current remote directory, and Download wants a remote path, to the current local directory, the location is taken care of behind the scenes. Commands that do not deal with a path, or connecting a client, generally do not care either.

The current directory is maintained on an individual basis. So you can switch between remote and local, and you will stay in the same place. The only exception is if the device is disconnected, this will reset both paths. The cwdl and cwdr commands Current Working Directory Local and Current Working Directory Remote respectively, can be used to check what that path is, regardless of the command lines current location.


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 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."

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.

Updates

Preperation

OpenLFConnect comes with a directory called files/, inside you'll find the Didj/ directory, its a convenient place to keep your firmwares.

More Information on firmware updating.

Bootloader

Make a directory called bootloader-LF_LF1000. Put your lightning-boot.bin and bootflags.jffs2 (optional) into it.

Firmware

Make a directory called firmware-LF_LF1000. Put your kernel.bin and erootfs.jffs2 files into it.

In OpenLFConnect navigate to the location of these files. You can be one above, or just inside the one you want to update. If you are going to do both, you must be in the parent directory of both of them.

Depending on what you want to do, update just the bootloader, just firmware, or both, there is a command for each.

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 path to parent.

local>didj_update_firmware Didj/

Update Bootloader with path a to files.

local>didj_update_bootloader Didj/bootloader-LF_LF1000

It will take a second for the command prompt to come back after the files have transferred and eject command sent. If on Linux eject the device now. 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 file 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.

If your Didj needs repair, this can get complicated, as the USB storage that gets mounted becomes corrupted. I seemed to have decent luck formating it as FAT, and reinstalling the Base/ and Data/ directories with backups I made. This is where having a serial console comes in very handy.

LeapPad and Explorer

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 CBF Information. You can run firmware updates, there is a convenience function for enabling ftp, or you can use it like a basic ftp browser.

Enable FTP and Telnet

!!! Has not been actually tested on a LeapPad yet. Should work fine, but be prepared, if this fails, you will require a USB boot to fix it.!!!

This command will patch the /etc/init.d/rcS file, to turn FTP and Telnet on during device boot up.

Turn the device on and plug in the USB cable.

local>dftp_connect
... device info ...
remote>dftp_enable_ftp_telnet
remote>dftp_reboot

If your device does not reboot, go ahead and switch it off, then back on. Once booted, you should be able to connect through telnet or ftp to the device.

Username:root
Password:[blank]

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


Explorer

Update

Preparation Create a directory called Firmware-Base/ and load it with the firmware files. These files must be named 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 [Leapster_Explorer#Technical_Information] for the partitions numbers.

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

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

Once you got your firmware ready, plug in the device hold down both shoulder buttons and the ? button while turning it on, then run:

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

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 /path/to//Firmware-Base

It will print out the file its uploading and say when its done, it will say it skipped any files that were not present, like if only kernel.bin was in your directory.

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.

LeapPad

!!!I don't have a LeapPad to test on, so this section, minus the generic stuff, is theoretical If someone is willing to risk it, please let me know if it worked or not, so this feature can be less theoretical and more confirmed. But be warned, it could do some SERIOUS damage. So if you know what you are doing, maybe this can be of some assistance in getting there!!!

Another hurdle, is getting the LeapPad into USB Boot mode. I'm not exactly sure how to do this, as the device is missing the buttons used on the Explorer to trigger it.

Update

Preparation The LeapPad is vary similar to the Explorer, but it uses a different structure and flash system for its firmware. The update will look for the files in certain directories and place them in /LF/fuse/firmware/sd/* as needed. The structure looks like this

firmware/sd/raw/1/FIRST_Lpad.cbf
firmware/sd/raw/2/kernel.cbf
firmware/sd/ext4/3/rfs

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

Once you got your firmware ready, plug in the device hold down both shoulder buttons and the ? button while turning it on, then run:

local>boot_surgeon /path/to/LeapPad/surgeon.cbf

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 /path/to/firmware

It will print out the file its uploading and say when its done, it will say it skipped any files that were not present, like if only kernel.bin was in your directory.

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.

Command List

General

debug_on

Usage:
   debug_on

Setting this prevents updates from actually happening, instead printing the files that would have been uploaded.


debug_off

Usage:
   debug_off

Turns off debugging mode. Updates will be attempted.


get_device_id

Usage:
   get_dev_id

Returns the currently configured device id.


get_mount_point

Usage:
   get_mount_point

Returns the currently configured mount point to use when creating a new mount client client.


set_mount_point

Usage:
   set_mount_point <mount point>

Set the mount point to use when creating a new mount client. 
The mount point, ex. Linux /media/didj, or Windows D:\
To reset to auto determine leave input blank.


get_device_ip

Usage:
   get_device_ip

Returns currently configured device IP to use when creating a new network client.


set_device_ip

Usage:
   set_device_ip <IP>

Set the device IP address to use when creating a new network client.
ex. 169.254.123.123
To reset to auto determine leave input blank.


get_host_ip

Usage:
   get_host_ip

Returns currently configured host IP to use when creating a new network client.


set_host_ip

Usage:
   set_host_ip <IP>

Set the host IP address to use when creating a new network client.
ex. 169.254.123.123
To reset to auto determine leave input blank.


remote

Usage:
   remote

Set to remote device for filesystem navigation.


local

Usage:
   local

Set to prompt to local host for filesystem navigation.


FileSystem

cwdr

Usage:
   cwdr

Print current remote directory path.


cwdl

Usage:
   cwdl

Print current local directory path.


exit

Usage:
   exit

Exit OpenLFConnect

ls

Usage:
   ls [path]

List directory contents. Where depends on which is set, remote or local


cd

Usage:
   cd <path>

Change directories. Where depends on which is set, remote or local


mkdir

Usage:
   mkdir <path>

Create directory. Where depends on which is set, remote or local


rmdir

Usage:
   rmd <path>

Delete directory. Where depends on which is set, remote or local


rm

Usage:
   rm <file>

Delete file. Where depends on which is set, remote or local


upload

Usage:
   upload <local file>

Upload the specified local file to the current remote directory, Will overwrite with out prompt.


upload_dir

Usage:
   upload_dir <local directory>

Upload the specified local directory into the current remote directory, Will overwrite with out prompt.


download

Usage:
   download <remote file>

Download the specified remote file to the current local directory, will over write with out prompt.


download_dir

Usage:
   download_dir <remote directory>

Download the specified remote directory into the current local directory, will over write with out prompt.


cat

Usage:
   cat <path>

Prints the contents of a file to the screen.
Doesn't care what kind or how big of a file.


Didj

didj_mount

Usage:
   didj_mount [mount name]

Unlock Didj to allow it to mount on host system.


didj_umount

Usage:
   didj_umount

Lock Didj which will un mount on host system. Only seems to work in Windows.


didj_eject

Usage:
   didj_eject
Eject the Didj which will unmount on host system, if the firmware updates are 
on the Didj, an update will be triggered. If they are not, it will ask you to unplug it. For
Linux hosts, you'll also have to eject it from the system.


didj_device_info

Usage:
   didj_device_info

Returns various information about device and mount.


didj_update

Usage:
   didj_update <path>

CAUTION:
!!Attempts to flash firmware, could potentially be harmful.!!
!!Make sure Battery's are Fresh, or A/C adpater is used!!

Update Didj firmware and bootloader. Files must be in bootloader-LF_LF1000 and firmware-LF_LF1000 directories.
Searches from the current local directory for the top level directory of the firmware, local path can be directly inside the top level directory or  one above it.
MD5 files will be created automatically.


didj_update_firmware

Usage:
   didj_update_firmware <path>

CAUTION:
!!Attempts to flash firmware, could potentially be harmful.!!
!!Make sure Battery's are Fresh, or A/C adpater is used!!

Update Didj firmware. Files must be in firmware-LF_LF1000 directory.
Searches from the current local directory for the top level directory of the firmware, local path can be directly inside the top level directory or  one above it.
MD5 files will be created automatically.


didj_update_bootloader

Usage:
   didj_update_bootloader <path>
CAUTION:
!!Attempts to flash firmware, could potentially be harmful.!!
!!Make sure Battery's are Fresh, or A/C adpater is used!!

Update Didj bootloader. Files must be in bootloader-LF_LF1000 directory.
Searches from the current local directory for the top level directory of the firmware, local path can be directly inside the top level directory or  one above it.
MD5 files will be created automatically.


didj_update_cleanup

Usage:
   didj_update_cleaup

Remove Didj firmware and bootloader from device.


DFTP

Used for LeapPad and Explorer.

dftp_connect

Usage:
   dftp_connect

Connect to device for dftp session.
Will attempt to configure IPs as needed.
This could take a minute or so, if you just booted the device.


dftp_disconnect

Usage:
   dftp_disconnect

Disconnect DFTP client.
This will cause the DFTP server to start announcing its IP again, except Explorer's surgeon.cbf version,   which will reboot the device


dftp_server_version

Usage
   dftp_server_version [number]

Sets the version number of the dftp server. Or retrieves if none specified
OpenLFConnect checks for version 1.12 for surgeon running before a firmware update.
Set this to 1.12 if getting complaints, or surgeon has its dftp version updated.


dftp_device_info

Usage:
   dftp_device_info

Returns various information about the device, and connection.
Note: Device name is guessed from board id.


dftp_update

Usage:
   update <local path>

CAUTION:
!!Attempts to flash firmware, could potentially be harmful.!!
!!Make sure Battery's are Fresh, or A/C adpater is used!!
Uploads and flashes to NAND the files in <local path>.
Note: Files must conform to LF naming conventions. Explorer in a Firmware-Base/* directory, LeapPad in  firmware/sd/*
Searches from the current local directory for the top level directory of the firmware, local path can be  directly inside the top level directory or one above it.
What firmware it to tries to upload depends on the board id.
LeaPad > 10
Explorer <= 10
Caution: Has not been tested on LeapPad, theoretically it should work though, please confirm to author yes or no if you get the chance.


dftp_reboot

Usage:
    update_reboot
After running update, run this to trigger a reboot


send

Usage:
   send <raw command>
Advanced use only, don't know, probably shouldn't.


dftp_enable_ftp_telnet

       """
Usage:
   dftp_enable_ftp_telnet
   
This patches the /etc/init.d/rcS file, to run Telnet and FTP on start up.
Username:root
Password:<blank>

Caution:
This will double check everything went okay, if it fails, it will save the original copy to files/rcS.
You will then have the ability to upload it, if this file is corrupt or missing, your device will
have to be recovered with Surgeon and a firmware update.

USB Boot

boot_surgeon

Usage:
   boot_surgeon <path to surgeon.cbf>

Uploads a Surgeon.cbf file to a device in USB Boot mode. 
File can be any name, but must conform to CBF standards.


Firmware

Explorer

lx_rename_firmware

Usage:
   lx_rename_firmware [path]

Renames a the current or specified directory of files, with first, kernel, and or erootfs in the file names.
Prepends the proper number prefix to each file.
Will rename all files in the directory that match.


LF2/LFP Packages

package_extract

Usage:
   package_extract [path]

Extracts LF Package files (lfp ,lfp2)
Takes a file path, or will extract all packages in a directory.


CBF Files

cbf_unwrap

Usage:
   cbf_unwrap <file path>

Removes the CBF wrapper and prints a summary.
CBF is used on kernels and surgeon, to wrap a zImage or Image file.
Saves the image file to the same directory the cbf file was in.
If image file already exists will fail.


cbf_wrap_surgeon

Usage:
   cbf_wrap_surgeon <file path>

Creates the CBF wrapper named surgeon.cbf and prints a summary.
CBF is used on kernels and surgeon, to wrap a zImage or Image file.
Saves the image file to the same directory the kernel file was in.
Kernel should be a zImage or Image file.
If cbf file already exists will fail.


cbf_wrap_kernel

Usage:
   cbf_wrap_kernel <file path>

Creates the CBF wrapper named kernel.cbf and prints a summary.
CBF is used on kernels and surgeon, to wrap a zImage or Image file.
Saves the image file to the same directory the kernel file was in.
Kernel should be a zImage or Image file.
If cbf file already exists will fail.


cbf_summary

Usage:
   cbf_summary <file path>

Display the CBF wrapper summary.
CBF is used on kernels and surgeon, to wrap a zImage or Image file.