=========================================================================== RELEASE NOTE: Series 60 MIDP SDK 1.2.1 for Symbian OS, Nokia edition (04.08.2003) =========================================================================== What's new compared to 2.7.2003 =============================== - Direct HTTP connection support - HTTP Proxy support Supported Platforms =================== The emulator has been tested on Windows NT 4 (SP6), Windows 2000(SP2) and Windows XP(SP1). These are currently the only supported operating systems, others may work, but have not been used in testing. The following tool setups can be used: - Nokia Developer's Suite for J2ME(TM) - Borland JBuilder (tested with JBuilder 8 + MobileSet 3.01 and JBuilder 9) - J2ME(TM) Wireless Toolkit (tested with version 1.0.4) - Sun ONE Studio 4, Mobile edition Update 1 - Command line development tools Supported Platforms in UEI mode =============================== - Sun ONE Studio 4, Mobile edition - Borland JBuilder IDE Usage from JBuilder 8 and JBuilder 9 ============================================= Installation and configuration ------------------------------ Follow the instructions of MobileSet Guide under JBuilder's help menu to configure this emulator as a JDK to be used in application development. JBuilder automaticly recognize this emulator as a UEI emulator. If you want to run this emulator in non UEI mode, the file bin/emulator.exe has to be renamed. The JDK directory to select is the root directory of this emulator. Note that the emulator must be installed into a directory, where the full absolute directory name does NOT contain spaces. Development ----------- This emulator is only able to run applications packaged into a MIDlet Suite as specified in MIDP specification. This means that both a JAD file (Java Application Descriptor) and a JAR file need to be created before the application can run. For general instructions on creating MIDlet Suites see the MobileSet Guide in JBuilder. Users of JBuilder Personal Edition need to use the Nokia Developer's Suite for J2ME(TM) to create the JAD and JAR files. In addition you need to make sure the following is done before attempting to run the application: (1) Select Project->Project Properties...->Paths(tab) and select the correct JDK to be used for building and running the application. If you change this setting, you need to close the window by pressing OK before proceeding to the next step. (2) Select Project->Project Properties...->Run(tab)->MIDlet(tab) and select the created JAD file as the 'entry point' for the application. (3) In the same window, add optional command line options, such as tracing flags into the "Emulator paramaters" field if necessary and accept the settings by pressing OK. If you are using Professional or Enterprise Edition of JBuilder and the Achive builder (JAR tool) that comes with those, the JAR file is automatically updated in the build process. With JBuilder Personal Edition and Nokia Developer's Suite for J2ME(TM), it is important to 'Recreate' the JAD and JAR files after building and before running the application. Otherwise the emulator will run the old version of these files instead of using the newly compiled classes. Tips & troubleshooting ---------------------- (1) If you get the following error message with JBuilder: JamGetAppDescFromFile - error converting descriptor content Uncaught exception com/symbian/midp/compatibility/runtime/MIDletException The reason may be that there are some extra JAR packages included in the current JBuilder JDK definition. You need configure the JDK again and remove the application JAR packages from the JDK definition. (2) If during debugging the IDE/debugger seems to get frozen or unresponsive, it often helps to switch to the emulator window and press a long press on the menu key followed by selecting the MIDlet process. This will swith the MIDlet into foreground and ensure it will get executed in the emulator. This symptom mostly happens during MIDlet startup and may be related to switching between Displayables. Usage from Sun's J2ME(TM) Wireless Toolkit ======================================= Installation and configuration ------------------------------ The emulator will appear in Wireless Toolkit's device list if it has been installed into directory \wtklib\devices. Note that the emulator must be installed into a directory, where the full absolute directory name does NOT contain spaces. Development ----------- Wireless Toolkit has the following features that affect application buidling and running procedure: (1) Building uses class library from the previously selected device before Run button is pressed. Only after attempting to run the application, the build process will start using the correct library until the device selection is changed again. Relevant for some old WTK version. (2) Building does not automatically refresh the MIDlet JAR-package after building the application. Project->Package command from the menu must be given to do that before running the application. For these reasons: - After device selection, press Run before attempting to Build. (It does not matter if running fails in this phase.) - After building, select Project->Package command before attempting to Run. About Preferences window: The emulator uses and supports the default Preferences UI in J2ME WTK with the following exceptions: - Security server address has no effect, since HTTPS is not supported. - The heap size setting has no effect, since the device has a dynamically growing Java heap. About Utilities window: The clean database utility in J2MEWTK has no effect with this emulator. The only way to clean up the RMS database of the emulator is to manually delete the file rms.db from emulator's C-drive. This directory is located in \bin\\epoc32\wins\c\tmp\midp. Usage from Sun ONE Studio 4, Mobile edition =============================================================== Installation and configuration ------------------------------ The emulator integrates into Sun ONE Studio either via J2ME(TM) Wireless Toolkit or via UEI. WTK must be installed to integrate with SUn ONE Studio and the emulator directory must be installed into directory \wtklib\devices. Via UEI, emulator must be configured as a new emulator. Please refer Sun ONE Studio Help. Note that the emulator must be installed into a directory, where the full absolute directory name does NOT contain spaces. Usage from command Line: ======================== The emulator can be also be used from command line. The KVM debug proxy, that is required for source level debugging will be started automatically by the emulator when the emulator is started in debug mode from command line. Usage: java -classpath -Demulator.home= com.nokia.phone.sdk.Emulator [options] -Xdescriptor where: -help Shows emulator help text. -version Shows emulator version. -debugger Runs the application with debugging enabled. -dbg_port Specifies the TCP/IP port number to be used between debugger and debug proxy. By default, the emulator assigns the first unallocated port starting from 2810. -port TCP/IP port number between VM and debug proxy. By default, the emulator assigns the first unallocated port starting from 2810. -classpath Specifies the directories and JAR files to be searched for classes. May include both library and application class directories and JAR packages. -Xdescriptor | -jad Specifies the name of the JAD file to use for finding the JAR to execute. The option must always be supplied. JAR will be searched for using these rules: (1) If JAD contains the entry for MIDlet-Jar-URL, and (1.1) If URL is a relative file URL, look for JAR using location of JAD file as reference. (1.2) If URL is an absolute file URL, look for JAR using the absolute path. (2) If JAD does not contain the entry for MIDlet-Jar-URL, search from the classpath. Tracing options: -traceallocation -tracegc -tracegcverbose -traceclassloading -traceclassloadingverbose -traceverifier -tracestackmaps -tracebytecodes -tracemethods -tracemethodsverbose -tracestackchunks -traceframes -traceexceptions -traceevents -tracemonitors -tracethreading -tracenetworking -traceall Other notes about the emulator ============================== Installation directory ---------------------- Note that the emulator must be installed into a directory, where the full absolute directory name does NOT contain spaces. Bluetooth configuration ----------------------- Please note that the Bluetooth card should not be installed with its own, commercial drivers on the laptop because after that you cannot setup the Bluetooth development and testing environment. Install the Bluetooth card as a COM port using Windows serial communications driver. For further information on suitable Bluetooth cards and on the installation, please download a document 'Setting_Up_and_Using_Bluetooth_Testing_Env_v1_3.pdf' from http://www.forum.nokia.com/main/1,,1_43_40,00.html. Note that document is written to c++ SDK but you could use same configuration with MIDP SDK and test first with document instructions that bluetooth is working correctly. Note also that the emulator starts indexing from zero, thus the port number in bt.esk file (mentioned in the document) must be one less than the COM port number for the card. Common problems and solutions ----------------------------- o MIDlet does not appear after startup, especially in debug mode. - Press long on the menu key until a list of running applications appears. Then select the running Java application with up and down keys and select. o If during debugging the IDE/debugger seems to get frozen or unresponsive - It often helps to switch to the emulator window and press a long press on the menu key followed by selecting the MIDlet process. This will swith the MIDlet into foreground and ensure it will get executed in the emulator. This symptom mostly happens during MIDlet startup and may be related to switching between Displayables. o Error message: Classpath is not set. Defaulting to "." - Check the command line parameters. This error message is sometimes given when there are unrecognised parameters on the command line. - Check that emulator installation directory does not contain spaces. o If emulator doesn't start - check JRE path from \bin emulator.cfg file. Spaces are not allowed in JRE path. - Solving: reinstall your JRE to the folder without spaces and change paths in emulator.cfg file. - Please make sure that you have JAD and JAR files. I.e. emulator canīt be started with pure MIDlet class. JAD/JAR checking ---------------- Real devices will perform MIDlet installation time checks to ensure consistency between the JAD file and the JAR file. Especially the manifest file in JAR needs to match with the JAD file as specified in Mobile Information Device Profile (MIDP) Specification, Version 1.0a (http://jcp.org/aboutJava/communityprocess/final/jsr037/index.html). This emulator does not perform these checks. Care must be taken to ensure, that JAD and JAR file contents is in line with the spec. Otherwise a MIDlet may run in the emulator but fail to install into a real device. MIDlet size limitations ----------------------- The emulator does not emulate the real memory size of a device. It should be kept in mind that there are limitations in real devices for maximum size of a MIDlet suite. This emulator does not limit the amount of RMS data that a MIDlet suite can store. However, real devices, may have some device specific limitations for RMS data size. MIDP UI components ------------------ Command mapping: -The implementation will add an Exit command into Options menu if one is not provided by the application. For this reason it is sometimes possible to see two Exit commands in Options menu. This happens if the application uses Command types incorrectly, i.e. has not used the proper Command.EXIT type for the Exit command. Form: - Commands "Copy text" and "Find in page" get automatically added into the displayable. Button mappings --------------- Basic navigation: Navigating the MIDP lcdui high level UI elements is done with the navigation keys (up, down, left, right). Pressing OK can be used as SELECT. lcdui commands get mapped to the two soft buttons below the screen. Game action mapping: - Key 2 and key 'up' -> UP - Key 8 and key 'down' -> DOWN - Key 4 and key 'left' -> LEFT - Key 6 and key 'right' -> RIGHT - Key 5 and key 'OK' -> FIRE - Key 7 -> GAME_A - Key 9 -> GAME_B - Key * -> GAME_C - Key # -> GAME_D RMS Database ------------ RMS database has to be deleted manually when midlet is not installed. RMS database file is rms.db, this directory is located in \bin\\epoc32\wins\c\tmp\midp. When midlet that uses RMS database is installed and used in emulator the uninstallation of midlet could give a notice that rms is used by some application and it not be deleted. In those cases rms.db has to be deleted manually from \bin\\epoc32\wins\c\system\midp\\untrusted\\1_090\rms.db Using RAS connection --------------------- Direct HTTP is the default HTTP connection method. Normally users do not need null modem RAS connection with MIDP SDK 1.2. For those users who sometimes want to use null modem + RAS connection we have connection profiles: - Direct HTTP profile - RAS profile - User's profile 1 - User's profile 2 Each profile consists of CommsDB + additional configuration files. To manage your configurations we have configuration scripts: - Direct_http_current.cmd Replace current configuration with Direct HTTP default settings - RAS_current.cmd Replace current configuration with RAS default settings - Config_1_Current.cmd Replace current configuration with user's configuration 1 - Config_2_Current.cmd Replace current configuration with user's configuration 2 - Current_Config_1.cmd Replace user's configuration 1 with current configuration - Current_Config_2.cmd Replace user's configuration 2 with current configuration The scripts are located in Series_60_MIDP_SDK_for_Symbian_OS_v_1_2\bin\Series_60_MIDP_SDK_for_Symbian_OS_v_1_2 directory. Using HTTP proxies ---------------------- HTTP proxy support is available with direct http connections only. In RAS connections, http proxy is not supported. Configuring HTTP proxy: - Start emulator - Press application button in emulator (top left) - Find proxy settings application and start it - Fill in your settings and press ok Known issues and features ----------------------- - Note that the emulator must be installed into a directory, where the full absolute directory name does NOT contain spaces. - MIDlet does not always get execution time in the emulator in debug mode unless the user presses the menu key followed by selecting the MIDlet process. - This emulator does not properly support the -classpath command line flag. MIDP libraries are inbuilt into the emulator and location of the application JAR is determined using the JAD file. - This emulator does not support -D flags. - This emulator does not emulate the real memory size of a device - Unsupported command line parameters may print out wrong usage information message saying: "usage: MIDletMain midletName " - Neither Enter key, nor Space bar work as Select key. One must press the OK button (selection key) or choose select from options list (under left soft key). - Number of colors supported by the device is reported incorrectly. This should be 4096. - Copy text command in TextField/TextBox crashes the emulator. - Uncaught exceptions do not present any dialog to the user. - No support for ringing tones (*.rng) format. - Audio simulation within this emulator is using external audio engine, which might support more content types than actual Series 60 platform. ---------------------------------------------------------------------------- The phone simulation used in this SDK is designed to show how applications may appear on J2ME(TM) enabled mobile phones. It simulates the look&feel and behavior of the Nokia Series 60 based phones as faithfully as possible but there may be some differences between this simulator and the final products. Copyright Đ 2001-2003 Nokia Corporation. All rights reserved. Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Includes Java(TM) technology from Sun Microsystems, Inc. Portions of this software are Copyright by Sun Microsystems, Inc. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.