Rockbox UI Simulator

---

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

This incompatibility extends to voice/speech files as well; you will need a simulator-specific voice file for your target.

---

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.

However, unofficial (but trusted) pre-compiled Windows versions of the simulators can be found here: https://marcrosoft.dk/rockbox/simulators/

---

Simulated APIs

• File I/O (open, close, read, filesize, etc)
• Directories (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 "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.

---

Building

1. Get Sources

The the very latest sources off the Git server.

Git details can be found here: UsingGit

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 the questions ]
 
        [ Makefile created, simdisk subdirectory created ]
 
        $ make
        $ make fullinstall
        $ ./rockboxui
 

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.

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 git-client someone skilled should check if this is the command to get git 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.15.tar.gz
tar xvzf SDL-1.2.15.tar.gz
cd SDL-1.2.15
./configure --host=i586-mingw32msvc --prefix=${HOME}/mingw32-sdl
make && make install

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

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

---

If you're getting this message during configuring: '*** Your compiler (/usr/bin/gcc) does not produce Win32 executables!', try doing this:

CC=/usr/bin/i586-mingw32msvc-gcc CXX=/usr/bin/i586-mingw32msvc-gcc ./configure --host=i586-mingw32msvc --prefix=${HOME}/mingw32-sdl

(with the right paths to i586-mingw32msvc-gcc)

---

Building Windows sim in Windows

MSYS/MinGW

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.

WSL/MinGW

You can build a Windows simulator on Windows 10 using the Windows Subsystem for Linux as described here: Windows10CrossCompiler

---

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

Mappings:

Generic Archos:

Rockbox/sim	Keyboard
ON	+
UP	8
DOWN	2
LEFT	4
RIGHT	6
Toggle USB connect	U

Archos Recorder only:

Rockbox/sim	Keyboard
OFF	Enter
PLAY	5
F1	/
F2	*
F3	-

Archos Player only:

Rockbox/sim	Keyboard
MENU	Enter
PLAY (there's no separation between PLAY and RIGHT)	6

iAudio X5:

Rockbox/sim	Keyboard (numpad)	alternate keys
LEFT	4	Left
RIGHT	6	Right
UP	8	Up
DOWN	2	Down
SELECT	5	Space
PLAY	+	F8
OFF	Enter	Esc, a
RECORD	/	F1
Toggle USB connect	U	none
Toggle Hold	H	none
Toggle Hold on remote	J	none

iPod

Rockbox/sim	Keyboard (numpad)	alternate keys
Menu	.	Insert
Select	5	Space
Play	+	F8
Left	4	Left Arrow
Right	6	Right Arrow
Scroll Back	8	Up Arrow
Scroll Forward	2	Down Arrow
Toggle Hold	H	none

iRiver H1xx/H3xx:

Rockbox/sim	Keyboard (numpad)	alternate keys
LEFT	4	Left
RIGHT	6	Right
UP	8	Up
DOWN	2	Down
SELECT	5	Space
ON	+	Q
OFF	Enter	A
MODE	.	INS
RECORD	/	F1
Toggle USB connect	U	none
Toggle Hold	H	none
Toggle Hold on remote	J	none

iRiver H10:

Rockbox/sim	Keyboard (numpad)	alternate keys
<-	4	Left
O	6	Right
UP	8	Up
DOWN	2	Down
PLAY	5	Space
REW	/	F1
FF	*	F2
POWER	+	Escape/F8
Toggle USB connect	U	none
Toggle Hold	H	none
Toggle Hold on remote	J	none

Sansa e200:

Rockbox/sim	Keyboard (numpad)	alternate keys
Left	4	Left
Right	6	Right
Scroll Up	8	Up
Scroll Down	2	Down
Select	5	Space
Play	9	Page Up
Submenu	3	Page Down
Power	1	Home
Rec	7	End
Toggle USB connect	U	none
Toggle Hold	H	none