Introduction

The Rockbox UI simulator is a version of Rockbox compiled to run on a host PC. It is known to work on Linux, Mac OS X and Windows, and should be able to run on any Unix-like operating system where SDL is available.

It was originally designed by the Rockbox developers as a platform to make developing and testing code easier - removing the need to repeatedly install on the target device, and even to own a particular target, and also allowing easier debugging. It is also useful to WPS/theme authors for similar reasons.

A Rockbox simulator is specific to a target device - i.e. when building it, you select the combination of the target device and "Simulator", and it will build a simulator for that device, replacing the low-level drivers in Rockbox with their SDL or host operating system equivalents.

It is important to note that the simulator is NOT an emulator - this means that you can't take (for example) .rock files compiled to run on a target device and use them in the simulator - simulator ".rock" files contain code compiled to run on the host PC's processor (e.g. Intel x86), and the target device .rock files contain code for that device (e.g. ARM, Coldfire or SH).

Download

Because it is mainly aimed at developers, there are no official downloads of ready-to-run Rockbox UI simulators.

The simulator source code is part of the Rockbox source download, or can be retreived via Git. See below for instructions to compile it.

Simulated APIs

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 "simdisk" as a simulated root dir. LCD operations should operate in a window on your screen and buttons should be usable.

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.

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

Note that the simulator uses a local subdirectory named 'simdisk' as "root directory" for the simulated 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 fullinstall". That step actually copies the rockbox code into ./simdisk/.rockbox/, where it's found when the simulator runs.

"make fullinstall" includes all the rockbox fonts, a faster way to install is "make install" which skips the fonts but once you have made a full install there is no reason to copy all the fonts every time you build.

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.

You can change the argument to --prefix to wherever you want the mingw32 version of SDL installed, but you really should set a prefix, since the sdl-config will overwrite your native sdl-config otherwise.

Then you need to put the path to the mingw32 sdl-config in your path (eg. by putting PATH=$PATH:$HOME/mingw32-sdl/bin/ into $HOME/.bashrc)

Now, just compile as normal, selecting the (A)dvanced build option and selecting (S)imulator and (W)in32 crosscompile.

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):

Building Windows sim in Windows

It is possible to build a Windows simulator in Windows using MSYS and MingW.

Requirements:

MingW & MSYS

SDL

upgrade MSYS make to 3.81

zip/unzip for Windows

perl

mingw-crypto

Note: UIsimulator build is currently broken for MS Windows. Here is a possible workaround.

3. Run UIsimulator

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

Then type ./rockboxui to run UIsimulator. To get a list and a description of available switches, type ./rockboxui --help.

Note: if you build the simulator on cygwin or MingW 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.

Running Windows sim in Linux

An alternative for testing purposes under Linux you can use WINE for a Windows environment that will execute the various Win Emulator Binaries.

Target Keypad Equivalents

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

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

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

Note: on touchscreen targets, you can switch between simulated buttons and real touch screen by pressing F4

Note: mappings not explained here can be found by looking in the simulator keymaps files