Getting started hacking the didj

Getting started with hacking on the leapfrog didj.

[Credits]

Claude

NullMoogleCable

Losinggeneration

JulsPower(some correction)

Add all the names of contributors to the Didj project here

[Contents]

1. What is the purpose of this document? 2. Why hack the didj? 3. Getting started 3.1 UART (serial) connection 3.2 Uploading the custom UART bootloader onto the Didj 3.3 Uploading a custom kernel to the Didj 3.4 Using the custom kernel 3.41 Uploading the OpenGL demo 3.42 Using g_ether to play mp3 files via a network 3.50 Setting up a working toolchain (programming environment) 3.51 Installing and configuring the virtual Image 3.6 Installing your own toolchain 4. Other stuff 4.1 Links

1. What is the purpose of this document?

To explain how to get started with hacking the didj, which software to use, which tools you might need and to try and add some extra context to all the hard work that has been done so far. At the end of this document you should have a custom linux kernel on your didj and a working toolchain which should allow you to write your own programs to take full advantage of this little handheld device.

2. Why hack the didj? ---

The didj whilst it is marketed as a childs learning tool hides a wealth of power inside the case, it has a 393Mhz arm9 cpu with a slew of multimedia chips and runs a custom linux kernel, add to that the fact that they have been sold en masse via places like woot for $20 and its easy to see that they make an ideal hacker target for cheap and relatively high power processing for game emulation or embedded projects.

For a full list of features check the main Didj page for more details.

3. Getting started

3.1 UART (serial) connection

So, You've got your didj and you want to start hacking it, the first thing that you will need to do is gain access to the didj, this is done via UART (Serial).

luckily for us Claude found out that you could access the didj's uart connection via a pair of pins on the game cartridge slot, [link to relevant wiki section] this was initially done by soldering directly to the cart slot pins, you can still use that method if you wish but these days most people buy a DJHI (did ja hack it?) cart designed and built by NullMoogleCable, this gives you a set of pins that can be used with an FTDI usb to serial cable or breakout board, (which you can purchase from SparkFun) or any other usb to serial adapter that uses 3.3V logic levels.

Another bonus on the DJHI cart is it has a microSD slot which gives you loads of storage space for anything you might want to use on the Didj.(don't say rom and music)

When you have your DJHI connected to the FTDI usb to serial breakout board, you can use any number of programs (cutecom, minicom, gtkterm) to connect to your DIDJ. The connection is 115200 baud, 8 bits, odd parity, 1 stopbit. Hardware Flow Control should be off. This connection will allow you to interact with the terminal on the Didj.

3.2 Uploading the custom UART bootloader onto the Didj

Once you have your uart connection you will need to get a custom bootloader onto the didj, The bootloader will allow you to boot the custom linux kernel with root(Full) access or access other features instead of bootloading the leapfrog software that the didj ships with.

There are 2 or 3 ways to do this, you can either uart load everything and as soon as you turn off the didj, it reverts back to the original firmware, no custom bootloader.(This method have 0 chance of briking your didj)

or you can do the uart load of lightning boot and uboot, then flash those to the didj, then you can either test custom kernels/software or flash them to the didj.

1. Using a djhi 2.0 or above, make sure D5 is grounded, have hyperterminal open and connected to your com port, 19200,8,n,1

2. turn on and hold the power button on the didj do not let go until you see the blue lightning boot screen

3. In hyperterminal click 'transfer' and select send txt file, set it to 'all files', select 'lightning-boot-1.4-UART.bin' and click open.

Djhi doesn't have a led, but my ftdi breakout does, you should be able to see some activity, once the led stops flashing a few seconds later the lightning boot blue screen should come up, you can now let go of the power button. (Should be around 30 Seconds)

4. Now that lightning boot is loaded you will need to put uboot onto the system. If you use the reset cpu command in uboot, you will need to power off the didj completely before you can use it again, reset doesn't do a reboot or shutdown :/

5. Remove the ground from D5. In hyperterminal disconnect, now go to file, properties and then click on configure, set the baud rate to 115200. Now click on the call menu and choose call, then click on the transfer menu, choose send a file, for protocol select 'Xmodem' and click on the browse button and select your uboot.bin file and click open, now on the didj select the 'upload using xmodem @ 115200' option and press the A button, (didj will send C on serial console) now back in hyperterminal click on the send button, Then press the A button again to start upload.

6. Once uboot has been sent there'll be a terminal prompt, you can either start uploading a non destructive kernel image(see below, takes 15 mins) or you can write the bootloaders permanently to the didj following these instructions:

Didj U Boot Flashing Primer (do step1a and Step3 onwards, we've effectively just done step 2).

3.3 Uploading a custom kernel to the Didj

Now we have the bootloader on the didj we can upload a kernel image to it. This will allow us to use the didj pretty much the same as any other linux handheld computer.

There are a few caveats, such as there is no USB Host on the Didj, leapfrog didn't connect the relevant pins, so you can't attach USB devices such as webcams etc. directly to the didj. However, you can use g_ether via USB for networking so it still has flexibility and of course there are unused GPIO pins that can be tapped so adding sensors etc. shouldn't be an issue and of course you can connect to all manner of devices via the UART connection.

Uploading a custom kernel via uart

with uboot loaded, if you want to upload a non destructive custom kernel enter the following at the terminal prompt:

setenv bootargs mem=18M init=/sbin/init console=ttyS0,115200 root=31:06 ro rootflags=noatime rootfstype=jffs2 ubi.mtd=Brio ubi.mtd=prg_Brio ubi.mtd=Cartridge ubi.mtd=EXT

setenv loadaddr 1800000

loadb

Next send the zImage file using Kermit method once finished there will be another terminal prompt, enter.

go 1800000

You should now see Should now see the linux kernel uncompressing then booting, if not you may need to set the baud rate on your com port to 115200.

3.4 Using the custom kernel

You should now be able to boot into the custom linux kernel, great but what now?

We are limited in what we can do but as the wiki project goals are reached this section or the links section will grow as features/software is added. For now though we can load losinggeneration's OpenGL port demo and mp3 playback via g_ether

3.41 Uploading the OpenGL demo

One of the aims of the didj project is to get game emulation working, however, OpenGL was broken on the didj kernel, OpenGL is a library that is used in for producing graphically intensive apps and games and would be a key feature that needed fixing, due to hard work by		 losinggeneration it now works :)		 losinggeneration has written a cube demo as a hello world, [link to download and instructions]

3.42 Using g_ether to play mp3 files via a network

3.5 Setting up a working toolchain (programming environment)

You've uploaded a bootloader, got your linux image onto the Didj, played some mp3s on it, seen the OpenGL demo by [losinggeneration, link] but what you really want to do is start programming or editing your kernel so that it starts to do what you want. To do this you're going to need a toolchain.

In this particular document, as I am running Windows, the toolchain consists of a virtual linux PC image that runs on the freely downloadable software VirtualBox. Once you have downloaded and installed VirtualBox you will need the toolchain image file.

You can find the VBox image file here [link to losinggenerations image http://losinggeneration.homelinux.org/wp-upload/VBox-Didj.tar.bz2 and instructions] (link is currently broken). This image has all of the software needed to write and compile your own programs/custom kernels for the Didj.

There are other prebuilt toolchains on the Didj Build Environment page, including one for Windows.

3.51 Installing and configuring the virtual Image

Before you can start using the build environment it will need unpacking and then you will need to configure a virtual machine in the Virtual Box software, for now you can unpack the image file into the folder you downloaded it to, leave the folder open for the next step.

Next we need to start the Virtual Box software you installed in the previous section. When the software is up and running Click on 'File' and choose 'Virtual Media Manager' In the window that opens you should be on the 'harddisks' Tab, click on the 'add' button you will now have a browse window open, go back to the folder that you unpacked the image to and either cut and paste or copy and paste the 2 folders (Harddisks, Machines) into the browse window, this will put your image files in the Virtual Box default folder, you can now go into the harddisks folder, select the file named 'Ubuntu-Didj.vdi' and click on the open button, then click on the OK button. This will allow you to use the virtual disk image(vdi) in Virtual Box.

Now that Virtual Box knows where the vdi is we can Configure ourselves a virtual machine to use it. To configure the virtual machine we will use the built in wizard, click on the blue 'New' icon in the top left corner of of the main window. In the window that opens click on the next button, give the wizard a name for your virtual machine 'ubuntu-didj' or something you will remember, then click on the dropdown for the Operating system and choose 'Linux', next click on the version dropdown and choose 'Ubuntu', then click next. Now we setup the virtual hardware, first up is the how much memory you want your virtual machine to have, it defaults to use 512MB of your system memory, I've got 6GB in my PC so I set mine to 1024MB. To set the memory, drag the slider left or right, when you are happy click the next button.

Next we tell the wizard to use the vdi file that we added into virtual box earlier on, click on the radio button next to 'Use existing Hard Disk', then click the folder icon to the right, in the virtual media manager window that opens make sure 'ubuntu-didj.vdi' selected in the list, then click on the select button, once that window has closed click on the next button, you should now see a summary of the virtual machines settings, once you click on the finish button a virtual machine will be created.

3.52 Extra configuration and installing 'Guest Additions' 

You can either start your virtual machine straight away (password: didj) or right click on the machine name in the list and change other settings, I won't go into too much detail but you can configure graphics memory allocation (I set mine to 128MB) and networking, shared folders amongst other things. At this point, it would be a good idea to install virtual box 'guest additions', this will allow you to change screen resolution and give you 3d acceleration on your guest machine. To install 'Guest Additions', start the virtual machine, then once logged in (password: didj) go to the top of the virtual box window and click on 'Devices', then click on 'Install guest additions', this will mount the guest additions ISO as a virtual CD, it may or may not autorun, if it doesn't go to your 'places' menu and then click on 'computer', then double click on the CD drive, then look for autorun.sh and double click that, wait for it to install and you should be done. log off and log back on and you should be able to change screen resolution and you should have 3d acceleration.

3.53 Start hacking

You can now start editing your custom didj kernel [insert wiki tutorials here] using your favourite Text/Code editor or IDE.

3.6 Other toolchains

If you want to roll your own toolchain you can follow one of these tutorials:


 * Creating a Kernel Build Scratchbox
 * Setting up a Cross Compiler Build Environment and Basic Usage
 * An alternate cross compiler, built with crosstool-NG

4. Other stuff and things to look at

With everything setup you should take a good look at whats on offer on the main wiki page, there are lots of excellent hardware and software hacks that you can do, sd card drivers, the sdl tutorial, TV-out, jtag, networking to name a few. There is also an IRC channel to hang out in, visit #didj on freenode.