Rockbox UI Simulator

Goal

To enable Rockbox application and plugin developers to test and debug their code and concepts on a host PC as a complement to running on target.

Simulated APIs

• file I/O (open, close, read, filesize etc)
• dir (opendir, readdir, etc)
• lcd (lcd_puts(), lcd_update, etc) * buttons (button_get() etc)
• plugins (plugins are loadable and the most of the plugin API is supported)

File and dir operations are redirected to use the local directory named "archos" as a simulated root dir. LCD operations should operate in a window on your screen and buttons should be usable. The exact button mapping simulator => target keypad should be documented but currently isn't.

How It Works

When building a simulated Rockbox, the simulated functions are simply redirected to use the alternative versions provided in the uisimulator/ source tree. The simulator tries to use as many Rockbox functions as possible, putting the simulated layer as "low-level" as possible.

Code in firmware/ and apps/ are subject to get simulated (the goal is of course to make everything in apps/ totally ignorant about simulation or not, but we're not quite there yet).

Code in uisimulator/ is for doing the simulation. This code may never include files that are present in firmware/include.

Building

1. Get Sources

The the very latest sources off the SVN server. Get the 'tools' dir, 'firmware' dir, the 'apps' dir and the 'uisimulator' dir on the same dir level, to make it easier to build things (some of the files assume this hierarchy).

SVN details can be found here: UsingSVN

2. Build Uisimulator

(Note: you do not need any target-specific CrossCompiler to build the simulators.)

(Note: under linux, you need the libsdl-dev package installed)

(Note: ensure the complete path (especially your username in the home directory) has no spaces, otherwise you will get errors compiling)

Create a new directory and run the 'tools/configure' script in there. Select target to simulate and select simulation. The script will then generate a Makefile for you:

        $ mkdir build-dir
        $ cd build-dir
        $ ../tools/configure
 
        [ answer to questions ]
 
        [ Choose simulator type:

           SDL - the preferred version for all platforms
           (The Win32 and X11 versions have now been depreciated in favour of the SDL version)        
        ]

        [ Makefile created, archos subdirectory created ]
 
        $ make
        $ make install
        $ ./rockboxui
 

Run "../tools/configure --help" for more informations, including argument line options.

Note that the simulator uses a local subdirectory named 'archos' as "root directory" for the simulated box. It will use this name even if the unit being simulated isn't an Archos box. Copy a bunch of mp3 files into that directory, create subdirectories and do all sorts of things you want to be able to browse when you fire up the simulator.

Don't forget to do the "make install". That step actually copies the rockbox code into ./archos/.rockbox/, where it's found when the simulator runs.

3. Run Uisimulator

First, populate the 'archos' directory with a bunch of test files/directories to create a simulated disk drive for the simulator to see.

Then type ./rockboxui or ./rockboxui --background to run Uisimulator. The --background switch displays a helpful image of the target selected in the configure stage. To get a list and a description of available switches, type ./rockboxui --help.

Note: if you build the simulator on cygwin and want to be able to start it by clicking, you need to copy the SDL DLL from /usr/local/bin/ to \windows or similar.

Linux note: you may see ALSA error messages printed to the console such as "ALSA lib conf.c:xxxx:(snd_config_hooks): id of field i is not and integer". This may affect actual sound output but the rest of the sim should run normally.

4. Target Keypad Equivalents

The keyboard's numerical keypad is used to simulate the native device keypads. Mappings:

Generic Archos:

Archos Recorder only:

Archos Player only:

iRiver H1xx/H3xx:

iRiver H10:

iAudio X5:

Sansa e200:

Note: to make a screenshot in the simulator press F5 or NUM0. Screenshots are saved in the archos directory named dump*.bmp

Note: USB connection can be simulated on all targets by pressing u

Note: mappings not explained here can be found by looking in the \uisimulator\sdl\button.c file

Download precompiled simulators for Windows

This might be useful if you are not able or willing to compile the simulators by yourself:

Get recent pre-built simulators from Rasher: http://rasher.dk/rockbox/simulator/

Building on Mac OS X 10.4

The simulator will build and run on Mac OS X, linked with libSDL 1.2.9. There are still problems with sound output.

Building in the XWindow environment on Mac OS X 10.4

• install the XCode package that comes on the OSX install CD.
• install the most recent binary off the download page at the Fink project
• start up FinkCommander.app
• use FinkCommander to install sdl, which automatically installs all dependencies. (sdl, sdl-image, sdl-image-, sdl-mixer, sdl-mixer-, sdl-shlibs, sdl-ttf, sdl-ttf-shlibs, smpeg-shlibs)
• use FinkCommander to install svn-client
• follow directions 1, 2, and 3 from the Building section above from within Terminal.app

Building Windows sim in Linux

It is possible to build a Windows simulator from Linux. You will need the Mingw32 compiler environment (Debian package mingw32).

First, download and build SDL:

wget http://www.libsdl.org/release/SDL-1.2.12.tar.gz
tar xvzf SDL-1.2.12.tar.gz
cd SDL-1.2.12
./configure --host=i586-mingw32msvc --prefix=${HOME}/mingw32-sdl
make && make install

Now, just compile as normal, with the path to the mingw32 sdl-config in your path:

PATH=${HOME}/mingw32-sdl/bin:${PATH} ../tools/configure
make && make install

The resulting binaries will be rather large, and most plugins will not run, including codecs. Running i586-mingw32msvc-strip on the files will make them usable (but will no longer let you run the binary in GDB):

find -name "*rock"         -exec i586-mingw32msvc-strip "{}" ";"
find -name "*codec"        -exec i586-mingw32msvc-strip "{}" ";"
find -name "rockboxui.exe" -exec i586-mingw32msvc-strip "{}" ";"