                        nxtOSEK (formerly LEJOS OSEK)

                                                               Takashi Chikamasa
================================================================================


What's new in 2.05 (December 2008)
=============================
- Support for TOPPERS/JSP as an RTOS kernel in addtion to TOPPERS/ATK(OSEK)
(TOPPERS/JSP is complied with Japan original RTOS specification "u(micro)ITRON")
Special thanks to Masaaki Muranaka san
Note that nxtOSEK C++ API uses some OSEK specific features, so it can't be used
with TOPPERS/JSP 
- Refactored makefiles and replaced lejos_osek.tmf with ecrobot.mak
(lejos_osek.tmf is still supported for backward compatibility)

What's new in 2.04 (November 2008)
=============================
- Support for C malloc/free (but not thread safe)
- Support for C++ new/delete, Boost smart pointer (but not thread safe)
Special thanks to Jon C. Martin

What's new in 2.03 (October 2008)
=============================
- Added NXTway-GS C API(see new NXTway-GS sample)
- Added mindsensors PSPNx C++ API
Special thanks to Jon C. Martin
- Support for multiple HiTechnic Acceleration Sensors on a NXT
- Fixed a bug in ecrobot_RUN_button_pressed/ecrobot_ENTER_button_pressed API
- Added biped robot sample using LATTEBOX NXTe/LSC (via I2C interface API)
- Added LATTEBOX LSC-22 sample
- Removed NXTway-DS sample

What's new in 2.02 (June 2008)
=============================
- Support for enhanced LEGO standard firmware (see #168 for more detailed information)
Special thanks to Sivan Toredo and John Hansen. <http://www.tau.ac.il/~stoledo/lego/nxt-native/>
- Added LATTEBOX NXTe RC servo controller sample (see samples/nxte)
Special thanks to Yu Yang san.

What's new in 2.01 (May 2008)
=============================
- Changed the project name from LEJOS OSEK to nxtOSEK. 
This change is not due to legal issue. However, LEJOS(leJOS) sometimes seems to make
people misunderstand LEJOS OSEK as "an alternative Java VM" or "an add-on of leJOS NXJ".
Therefore, we have changed the name, but, it would not affect the backward compatibility
of APIs and existing users applications.
- Support for BMP file format for LCD graphics (see samples/bmptest, anime)
- Support for WAV file format for sound generation. (see samples/wavtest)
- Added USB API (see samples/usbtest)
- Added I2C API
- Support Bluetooth run-time connection (see samples/btmaster, btslave)
- User customizable BMP file based splash screen
- No functionality changes in NXT BIOS (you don't need to update NXT BIOS)

What's new in 2.00 (April 2008)
===============================
Until LEJOS OSEK 1.10, LEJOS OSEK program had to be uploaded into SRAM of AT91SAM7S256 
in the NXT due to Flash endurance. This used to be a big restriction of LEJOS OSEK 
compared to other NXT firmwares and programming environments. But now...
The new LEJOS OSEK provides: 
 - Execution of LEJOS OSEK application in Flash/SRAM.
 - NXT BIOS supports LEJOS OSEK application flash WITHOUT touching the lock bits of AT91SAM7S.
 - 224Kbytes Flash and appx. 50Kbytes SRAM for user application and LEJOS OSEK in Flash.
 - New splash screen and main screen with status bar.
 - Speed up compilation time by archiving LEJOS OSEK application independent part.


Installation and Set up
=======================
Installation and set up for nxtOSEK is here:
http://lejos-osek.sourceforge.net/installation.htm


How to upload a program to the NXT
==================================
nxtOSEK application program can be uploaded either Flash or SRAM.
In case of uploading a program into Flash, it needs to upload NXT BIOS
and nxtOSEK application.
http://lejos-osek.sourceforge.net/howtoupload.htm

Upload NXT BIOS into Flash
--------------------------
STEP-1: Reset the NXT
 - To go into firmware update mode, press the reset button 
   (at the back of the NXT, upper left corner beneath the USB connector) 
   for more than 5 seconds. 
   The NXT will audibly tick when it is in firmware update mode. 

STEP-2: Upload NXT BIOS
 - Connect PC and the NXT by USB cable. 
 - Change to lejos_osek/bin directory.
 - Type "./biosflash.exe"
   After a few seconds, NXT BIOS screen comes up in the LCD.
   +------------------+
   | NXT BIOS 1.00    |
   | ================ |
   | BATT:80          | <- battery voltage (80 = 8.0V)
   | UPLOAD: READY    | <- upload is ready
   |                  |
   |                  |
   |                  |
   |                  |
   +------------------+
<NOTE>
When uploading NXT BIOS to the NXT at the first time, NXT BIOS screen may not be
appeared or battery voltage (BATT:) may be displayed as 0. 
In this case, remove the battery for five seconds and insert it again.

Upload nxtOSEK application program into Flash
--------------------------------------------------
STEP-1: Build and upload a nxtOSEK application into Flash
 - Change to a project directory (e.g. lejos_osek/samples/helloworld)
 - Type "make all" to build helloworld_app_rom.bin and upload scripts.
 - Connect PC and the NXT by USB cable.
 - Type "./appflash.sh". 
   While program upload is in progress, progress bar is displayed.
   After a few seconds, LCD screen should be changed like the following:
   +------------------+
   | NXT BIOS 1.00    |
   | ================ |
   | BATT:80          |
   | UPLOAD: FINISHED | <- upload is finished
   |                  |
   |                  |
   |                  |
   |                  |
   +------------------+
 - Press EXIT button to turn off the NXT.
 - Press ENTR button to start the application.
 - New splash screen and nxtOSEK main screen come up. 
   +------------------+
   |                  |
   |                  |
   |                  |
   | BATT:80          | <- battery voltage (80 = 8.0V)
   | [F][BT]          | <- status bar
   | ================ |
   | <STP  ENTR  RUN> |
   |       EXIT       |
   +------------------+
   [F]: program is executed in [F]lash
   [BT]: Bluetooth connection is established (in case of Bluetooth in use)
   STP(STOP): left triangle button
   ENTR(ENTER): orange colored rectangle button
   RUN: right triangle button
   EXIT: gray colored rectangle button

STEP-2: Upload a new nxtOSEK application program
 - While nxtOSEK main screen is displayed, press STOP + ENTR
   buttons for more than 1 second, then the NXT is turned off.
 - Press ENTR button to start the NXT and NXT BIOS screen comes up.
 - Perform from STEP-1.

<NOTE>
Way of uploading LEJOS SOEK application into Flash is the same as other NXT
Firmwares (e.g. LEGO standard fw/leJOS NXJ...). AT91SAM7S lock bit is NOT 
locked/un-locked during the flash.

Upload a nxtOSEK application program into SRAM
-------------------------------------------------
STEP-1: Reset the NXT
 Only when LEGO standard or other firmware was installed in Flash, this STEP-1 is needed.
 - To go into firmware update mode, press the reset button
   (at the back of the NXT, upper left corner beneath the USB connector) 
   for more than 5 seconds. 
   The NXT will audibly tick when it is in firmware update mode.

STEP-2: Build and upload a nxtOSEK application into SRAM
 - Change to a project directory (e.g. lejos_osek/samples/helloworld)
 - Type "make all" to build helloworld_samba_ram.bin and upload scripts.
 - Connect PC and the NXT by USB cable.
 - Press ENTR button.
 - Type "./ramboot.sh"
   After a few seconds, the new splash screen and nxtOSEK main screen come up.
   If you press EXIT button, the program in SRAM is gone.
   +------------------+
   |                  |
   |                  |
   |                  |
   | BATT:80          |
   | [R]              | <- program executed in S[R]AM
   | ================ |
   | <STP  ENTR  RUN> |
   |       EXIT       |
   +------------------+

STEP-3: Upload a new nxtOSEK application program
 - Perform from STEP2 (STEP-1 is not needed).

<NOTE>
During uploading a program into SRAM, if you encounterd an issue which any buttons
do not work, remove the battery for five seconds, and insert it again.

Upload a nxtOSEK application program into the enhanced LEGO standard firmware
-----------------------------------------------------------------------------
STEP-1: Install John Hansen's enhanced standard firmware.
http://bricxcc.sourceforge.net/lms_arm_jch.zip
NOTE that any version numbered 106 or later includes the native-invocation feature
Replace default LEGO standard firmware with the enhanced firmware.

STEP-2: Install John Hansens's NeXTTool.
http://bricxcc.sourceforge.net/utilities.html
NeXTTool requires NXT-G or LEGO MINDSTORMS NXT Driver v1.02 in your PC.
<http://mindstorms.lego.com/Support/Updates/>

STEP-3: Specify the path to NeXTTool.exe in nxtOSEK/ecrobot/tool_gcc.mak
For example:
# specify NeXTTool root directory
NEXTTOOL_ROOT = /cygdrive/C/cygwin/nexttool

STEP-4: Build a RXE file for nxtOSEK application.
 - Change to a project directory (e.g. lejos_osek/samples/helloworld)
 - Type "make all" to build helloworld_rxe.rxe and upload scripts.
 - Connect PC and the NXT by USB cable.
 - Type "./rxeflash.sh" to upload a nxtOSEK application to the NXT.
 - You can treat a nxtOSEK application as a file of LEGO standard firmware
   except for program termination.
(when you shut down a nxtOSEK application, NXT is turned off.
 So it needs to turn on the NXT to start again. An workaround is that you press
left triangle button to re-start nxtOSEK without turning off the NXT)

<NOTE>
nxtOSEK application is stored in Flash, but it copied and executed from RAM. 
Once nxtOSEK is executed, NXT is fully controlled by nxtOSEK application, 
so there is no difference between nxtOSEK in ramboot and nxtOSEK in the enhanced firmware. 
There are several benefits in case of using the enhanced LEGO standard firmware:
 - You can use NXT-G, NXC/NBC and nxtOSEK without replacing the firmware.
 - Support for Windows Vista (LibUsb seems to have some issues in the Vista)
 - You can upload multiple nxtOSEK applications to a NXT.


Memory layout
=============
Below is the flash memory layout for NXT BIOS and user application.
 - 224Kbytes (0x108000 - 0x140000) preserved for user application.
 - 32Kbytes  (0x100000 - 0x108000) preserved for NXT BIOS.
   +------------+
   |  0x140000  | Flash memory end address (256kbytes)
   +------------+
   |            |
   +------------+
   |  0x108000  | Flash start page address for user application
   +------------+
   | 256 bytes  | Flash record page (end of NXT BIOS)
   +------------+
   | 256 bytes  | Flash request page
   +------------+
   |            |
   +------------+
   |  0x100000  | Flash memory start address (start of NXT BIOS)
   +------------+

Program sequence is very simple:
 - By pressing ENTR button, NXT BIOS is executed.
 - If there is no flash record/a flash request, flash loader is executed.
 - If it is not in the above cases, the program jumps to the start address of user application.


There should be more sophiscated and smarter way to split flash loader and
application. Sorry, that's all my best.

Enjoy it!
