Differences

This shows you the differences between two versions of the page.

--- simulat0r [2011/07/20 03:03] – created ray
+++ simulat0r [2011/12/25 02:15] (current) – ray
@@ Line 1: / Line 1: @@
 ====== Simulat0r ======
+{{:wiki:simulat0r.png}}
+<note>
+The simulat0r currently does not compile. We hope to push some fixes soon - up to then the easiest way possibly is to check out a git at camp-time...
+</note>
 <note tip>
 The simulat0r allows you to develop and test applications for the r0ket even without having the actual hardware
-</note>
+So write cool stuff now and bring it onto your badge right after you arrived at the Camp!
+</note>
 ===== 1. What is it? =====
 The simulat0r basically is a set of headerfiles and some C code which enables you to compile r0ket applications on x86 machines and run them using a qt GUI frontend. Currently only the LEDs, display and input button are supported, but that should be enough to develop simple games, a cool nickname-scroller firmware or similar stuff.
+File-IO and possibly even some RF-API-stuff might be added in the future...
+There are currently two different kinds of software for the r0ket - applications and l0dables. An application runs as main firmware on the r0ket while l0dables can be loaded from within the default firmware. It depends on your project what to choose, but for smaller stuff that many people are supposed to use a l0dable is the better way, for stand-alone stuff (like building the r0ket into your pedelec) an application would be the right thing.
+L0dables can also be built as single applications using the "l0dable" Application. This is what you will be doing when devel0ping l0dables in the simulat0r as the simulat0r can't run the main firmware and load l0dables.
 ===== 2. Installation =====
 Start in the [[build|build]] section and at least clone the git repository. We also recommend installing the ARM compiler - even though not needed for the simulat0r it helps you check if your code will at least compile for the real r0ket and code/memory sizes fit.
-You will also need the qt4-devel package of your distribution including cmake. We have successfully built the simulat0r on Fedora and Debian Linux as well as on FreeBSD.
+You will also need the qt4-devel package of your distribution and cmake. We have successfully built the simulat0r on Fedora and Debian Linux as well as on FreeBSD.
 ===== 3. Try it out =====
-After installation go to the simulat0r directory and built one of the sample applications:
+After installation go to the simulat0r directory and build one of the sample l0dables:
 <code>
-$ cd simulat0r
+r0ket/$ cd simulat0r
-$ make APP=spaceinvaders
+simulat0r/$ make APP=l0dable LAPP=nick_plain
 </code>
-If all needed libs are installed, the built should succeed and result in an executable, start it:
+If all needed libs are installed, the build should succeed and result in an executable, start it:
 <code>
-$ gui/build/qsimulat0r
+simulat0r/$ ./gui/build/qsimulat0r
 </code>
-and you should see a X window showing the display and the 4 LEDs in the corners.
+and you should see an X window showing the display and the 4 LEDs in the corners.
-The 5-way button is emulated using the cursor keys+space or 84562 on your number pad
+As you have built the "l0dable" app you will first see its start menu. Press space to start your l0dable.
+The 5-way button is emulated using the cursor keys+space or 84562 on your number pad.
+By the way: as tui/simulat0r also a text-mode application is built. This simply shows the display in ASCII, but currently doesn't support input, so its use is limited. A very small font is recommended...
 ===== 4. Start your own project =====
-...coming soon
+The easiest way to start your own l0dable is to use a sample as template. Even when developing in the simulat0r you should do this in the normal firmware/l0dable directory, so you can easily also compile it for the target platform from time to time.
+<code>
+r0ket/$ cp firmware/l0dable/pwgen.c firmware/l0dable/coolapp.c
+</code>
+If you want to build an application instead, do the same in the applications directory. For an application, after copying the source you have to rename the main_menutest function to main_coolapp to match your APP name.
+<code>
+r0ket/$ cp firmware/applications/menutest.c firmware/applications/coolapp.c
+r0ket/$ vi firmware/applications/coolapp.c
+</code>
+===== 5. Developing =====
+Now your normal cycle would be to edit the source in r0ket/firmware/l0dable/ and build the simulat0r like above. As said, from time to time you also should do a "normal" build in the standard firwmare:
+<code>
+r0ket/$ cd firmware/l0dable
+l0dable/$ make coolapp.c0d
+</code>
+to check if everything at least compiles. The resulting .c0d must be <2500 bytes to be able to be started in a normal firmware.
+You also should try to build your l0dable as "l0dable" APP for the real platform to see if there are any linker errors.
+Please always keep in mind: the x86 platform of the simulat0r is much more powerful than the real target device. You have to be very strict in your memory usage and also don't have a full blown C library at your hands. Also not all types are available.
+One advantage of this is that you can easily add debug output to stdout/err and even write logfiles from within your simulat0r application. Please put #ifdef SIMULATOR blocks around such code so it doesn't get included in the target build. On the other had, if you for some reason need to include ARM assembler code, put #ifdef <nowiki>__arm__</nowiki> around it (and possible replacement code like puts("would do ... here\n") in the corresponding #else part). Also keep in mind: your PC most probably is much faster than the r0ket (which can't pass the speed of light for legal reasons), so timing most probably will be different. Use delayms() to get predictable timing for animations etc.
+===== 6. Ideas for projects =====
+We don't want to limit your creativity, so surprise us. The current simulat0r mainly supports the development of display-centric applications like games and demos, so things like Tetris or a Blinkenlights viewer should be possible (and as far as I know nobody started those yet. Let us know if you do...).
+And don't worry - even if you start now there will be enough to code at the Camp, like make your game interact over RF with a second r0ket...
+===== 7. Questions =====
+If you have any questions regarding development you are welcome to visit our IRC channel, see the [[contact]] page.
+Please also contact us if you are building a cool application you would like to be part of the official firmware or at least have it included in our repository.