Java User’s Guide Siemens Cellular Engines Version: DocId: 12 wm_java_usersguide_v12 Products: TC65, AC65, AC75, XT65, XT75 User’s Guide s
s Java User’s Guide Document Name: Java User’s Guide Version: 12 Date: 2008-02-25 DocId: wm_java_usersguide_v12 Status Confidential / Released Supported Products: TC65, AC65, AC75, XT65, XT75 GENERAL NOTES - EXCLUSION OF LIABILITY PRODUCT IS DEEMED ACCEPTED BY RECIPIENT AND IS PROVIDED WITHOUT INTERFACE TO RECIPIENT'S PRODUCTS. THE DOCUMENTATION AND/OR PRODUCT ARE PROVIDED FOR TESTING, EVALUATION, INTEGRATION AND INFORMATION PURPOSES.
s Java User’s Guide Content 123 Content 1 Preface ....................................................................................................................... 11 2 Overview .................................................................................................................... 12 2.1 Related Documents ......................................................................................... 12 2.2 Terms and Abbreviations ............................................................
s Java User’s Guide Content 123 4.3 4.4 5 4.2.8.3 Other Interfaces .................................................................. 31 Data Flow of a Java Application Running on the Module ................................ 32 Handling Interfaces and Data Service Resources ........................................... 33 4.4.1 Module States ..................................................................................... 33 4.4.1.1 State 1: Default – No Java Running ...................................
s Java User’s Guide Content 123 5.13 5.12.3.4 Upload................................................................................. 46 5.12.3.5 Download ............................................................................ 47 System Time .................................................................................................... 49 6 MIDlets ....................................................................................................................... 50 6.
s Java User’s Guide Content 123 11.3 11.4 11.5 11.6 12 Java IDE .......................................................................................................... 75 11.3.1 NetBeans IDE 5.0, NetBeans 5.5 or NetBeans 5.5.x.......................... 75 11.3.1.1 Switching Emulator to IMP-NG Emulator ............................ 76 11.3.1.2 Templates ............................................................................ 77 11.3.1.3 Examples .....................................................
s Java User’s Guide Content 123 13 Java Tutorial ............................................................................................................ 113 13.1 Using the AT Command API.......................................................................... 113 13.1.1 Class ATCommand........................................................................... 113 13.1.1.1 Instantiation with or without CSD Support......................... 113 13.1.1.
s Java User’s Guide Tables 8 Tables Table 1: Table 2: Table 3: Table 4: Table 5: Table 6: Table 7: Table 8: Table 9: Table 10: GPRS upload data rate with different number of timeslots, CS2 ................... GPRS upload data rate with different number of timeslots, CS4 ................... EDGE upload data rate with two timeslots, CS5............................................ EDGE upload data rate with two timeslots, CS9............................................
s Java User’s Guide Figures 10 Figures Figure 1: Figure 2: Figure 3: Figure 4: Figure 5: Figure 6: Figure 7: Figure 8: Figure 9: Figure 10: Figure 11: Figure 12: Figure 13: Figure 14: Figure 15: Figure 16: Figure 17: Figure 18: Figure 19: Figure 20: Figure 21: Figure 22: Figure 23: Figure 24: Figure 25: Figure 26: Figure 27: Figure 28: Figure 29: Figure 30: Figure 31: Figure 32: Figure 33: Figure 34: Figure 35: Figure 36: Figure 37: Figure 38: Figure 39: Figure 40: Figure 41: Figure 42: Figure 43: Figure
s Java User’s Guide Figures 10 Figure 47: Figure 48: Figure 49: Figure 50: Figure 51: Figure 52: Figure 53: Figure 54: Figure 55: Figure 56: Figure 57: Figure 58: Figure 59: Figure 60: Figure 61: Figure 62: Figure 63: Figure 64: Eclipse 3.2.x ME1.5.x and 1.6.x select System Java Thread for showing breakpoint line in Java source .................................................... 90 JBuilder X – JDK settings...............................................................................
s Java User’s Guide 1 Preface 11 1 Preface This document covers the full range of IMP-NG Java products from Siemens, currently including: 1. TC65 Module 2. TC65 Terminal 3. AC75/AC65 Module 4. XT75/XT65 Module Differences between the products are noted in the particular chapters. Throughout the document, all supported products are referred to as ME (Mobile Equipment). For use in file, directory or path names, the string “” represents the actual name of a product, for example TC65.
s Java User’s Guide 2 Overview 14 2 Overview The ME features an ultra-low profile and low-power consumption for data (CSD and GPRS), voice, SMS and fax. Java technology and several peripheral interfaces on the module allow you to easily integrate your application. This document explains how to work with the ME, the installation CD and the tools provided on the installation CD. Figure 1: Overview 2.
s Java User’s Guide 2.2 Terms and Abbreviations 14 2.
s Java User’s Guide 2.
s Java User’s Guide 3 Installation 27 3 Installation 3.1 System Requirements The Siemens Mobility Toolkit (SMTK) requires that you have: 1. Windows 2000, Windows XP or Windows Vista1 installed 2. 110 Mbytes free disk space for SMTK 3. Administration privileges 4. Java 2 SDK, Standard Edition 1.4. To install the JDK version 1.4.2_09 provided, follow the instructions in Section 3.5.1 Java 2 SDK, Standard Edition 1.5 is required for TC65. If a Java IDE such as NetBeans IDE 5.0, NetBeans IDE 5.5.
Java User’s Guide 3.2 Installation CD for AC65/AC75 and XT65/XT75 27 3.2 s Installation CD for AC65/AC75 and XT65/XT75 The Siemens Mobility Toolkit Installation CD includes: • Module Exchange Suite (MES setup is distributed on CD under "MES\Setup.exe") • WTK (is distributed as zip file on the CD e.g. "WTK\ac75_wtk.zip") bin - various tools doc - html - java docs for APIs lib - classes.zip src - various examples • Java SDK J2sdk-1_4_2_09-windows-i586-p.exe • NetBeans IDE 5.0 netbeans-5_0-windows.
s Java User’s Guide 3.3 Installation CD for TC65 27 3.3 Installation CD for TC65 The Siemens Mobility Toolkit Installation CD includes: • Module Exchange Suite (MES setup is distributed on CD under "MES\Setup.exe") • WTK (is distributed as zip file on the CD e.g. "WTK\tc65_wtk.zip") bin - various tools doc - html - java docs for APIs lib - classes.zip src - various examples • Java SDK jdk-1_5_0_07-windows-i586-p.exe • NetBeans IDE 5.5.1 netbeans-5_5_1-windows.exe (NetBeans IDE 5.5.
s Java User’s Guide 3.3 Installation CD for TC65 27 3.3.1 3.3.1.1 Components Module Exchange Suite The Module Exchange Suite allows the developer to access the Flash file system on the cellular engine from the development environment over a serial interface. File transfers from PC to module are greatly facilitated by this suite. The Module Exchange Suite (MES) will be installed under the following directories: • MES executables (e.g. MESCopy.exe, etc.) in the windows system directory (e.g.
s Java User’s Guide 3.3 Installation CD for TC65 27 3.3.1.3 SDK / JDK This is software provided by SUN to support Java application development. SMTK emulator uses the following JDK (stored in JavaSoft Registry key) for starting the Debug Agent: • Registry path: HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\1.4 HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\1.55 • Registry key: JavaHome (e.g. "C:\j2sdk1.4.2_09") JavaHome (e.g. "C:\Program Files\Java\jdk1.5.
s Java User’s Guide 3.3 Installation CD for TC65 27 3.3.1.6 Eclipse 3.1.2 IDE and Eclipse ME Plugin 1.5.x This is a Java IDE provided by the Eclipse Foundation to support Java application development. The integration of SMTK into Eclipse with ME Plugin 1.5.0 is supported by the TC65, XT65/XT75 and AC65/AC75 CDs. Eclipse ME Plugin 1.5.5 is only distributed on TC65 CD.
s Java User’s Guide 3.3 Installation CD for TC65 27 3.3.1.8 GPS Evaluation Software The GPS Evaluation Software (u-center) was developed by u-blox AG, Switzerland. This software demonstrates the capabilities of global positioning system (GPS) part incorporated in the XT75 module. The latest version of the GPS Evaluation Software (u-center) can be downloaded for free from the internet: http://www.u-blox.com/products/u_center.html.
Java User’s Guide 3.4 Set up Java Development Environment with Eclipse IDE (Quick Start-up) 27 3.4 s Set up Java Development Environment with Eclipse IDE (Quick Start-up) Please complete the following steps to set up your Eclipse Java development environment: Step 1: Install JDK 1.4.2_09 → JDK 1.4\j2sdk-1_4_2_09-windows-i586-p.exe For TC65 install JDK 1.5.0_07 , if no JDK 1.5 or higher is installed on your machine. Step 2: Install Eclipse 3.1.2 → Unzip from CD ("\Eclipse\eclipse-SDK-3.1.2-win32.
Java User’s Guide 3.4 Set up Java Development Environment with Eclipse IDE (Quick Start-up) 27 s - Select the path where Eclipse ME plugin is located on CD (EclipseMEplugin_123\.....") and select „eclipseme.feature_1.2.3_site.zip" Figure 4: Installation of Eclipse ME-Plugin 1.2.3: dialog box Search Results - In the dialog box Verification, select Install All. - In the dialog box Install/Update, select Yes to restart Eclipse. Figure 5: Installation of Eclipse ME-Plugin 1.2.
s Java User’s Guide 3.5 Siemens Mobility Toolkit Installation 27 3.5 Siemens Mobility Toolkit Installation The SMTK comes with an installation CD. The installation program automatically installs the necessary components and IDE integrations. Software can be uninstalled and updated with the install program. The next sections cover the installation and removal of the SMTK and the installation of the SDK and the supported IDEs. 3.5.1 Installing the Standard Development Toolkit 1. The JDK version 1.4.
s Java User’s Guide 3.5 Siemens Mobility Toolkit Installation 27 IDE please follow the instructions below and in Section 3.5.3. If no installed IDE is found the SMTK offers to install NetBeans IDE 5.0 and NetBeans Mobility package 5.0 (NetBeans 5.5.1 and NetBeans Mobility package 5.5.1 is distributed with TC65 CD). Alternatively, you can install the SUN IDE by following the instructions in Section 3.5.3. 7.
s Java User’s Guide 3.5 Siemens Mobility Toolkit Installation 27 3.5.3 Installing NetBeans IDE 5.0 / NetBeans IDE 5.5.1 1. NetBeans IDE 5.0 is provided on the SMTK installation disk in the subdirectory “NETBEANS_5_0”. To begin installation, start first “netbeans-5_0-windows.exe” and follow the NetBeans IDE 5.0 setup procedure instructions. 2. Please install next the Mobility package of SunTM NetBeans IDE 5.0. The Mobility package is required before integration of SMTK! The SunTM NetBeans IDE 5.5.
s Java User’s Guide 3.6 SMTK Uninstall 27 3.5.5 Installing Borland JBuilder X, 2005 and 2006 Enterprise/ Developer Borland JBuilder can be purchased from http://www.borland.com/jbuilder. There are also 30 days trial versions available on the website. Installation instructions can be found there. Note: The installation path name of JBuilder should not include space characters. 3.5.6 Installing Module Exchange Suite (MES) The Module Exchange Suite (MES) is installed during the SMTK installation.
s Java User’s Guide 4 Software Platform 35 4 Software Platform In this chapter, we discuss the software architecture of the SMTK and the interfaces to it. 4.1 Software Architecture The SMTK enables a customer to develop a Java application on a PC and have it be executable on the Java enabled module. The application is then loaded onto the module. The platform comprises: • JavaTM Micro Edition (Java METM), which forms the base of the architecture.
s Java User’s Guide 4.2 Interfaces 35 4.2 Interfaces 4.2.1 ASC0 - Serial Device ASC0, an Asynchronous Serial Controller, is a 9-wire serial interface. It is described in [2]. Without a running Java application the module can be controlled by sending AT commands over ASC0. Furthermore, ASC0 is designed for transferring files from the development PC to the module. When a Java application is started, ASC0 can be used as an RS-232 port or/and System.out. Refer to [3] for details. 4.2.
s Java User’s Guide 4.2 Interfaces 35 4.2.7 GPS The on-board GPS functionality can be accessed in 4 different ways from a Java application. • AT commands via ATCommand • Java API JSR179 • transparent via CommConnection • transparent via ATCommand It is discouraged to use the forth possibility since it uses up a valuable ATCommand instance. Use Java API for non-transparent, use CommConnection for transparent GPS access.
s Java User’s Guide 4.2 Interfaces 35 4.2.8 JVM Interfaces Figure 6: Interface Configuration Java ME, CLDC and MIDP were implemented by SUN. IMP-NG is a stripped down version of MIDP 2.0 prepared by Siemens and does not include the graphical interface LCDUI. Siemens developed additional APIs like the File I/O and the AT command API. Documentation for Java ME and CLDC can be found at http://java.sun.com/javame/. Documentation for the other APIs is found in [3]. 4.2.8.
Java User’s Guide 4.3 Data Flow of a Java Application Running on the Module 35 4.3 s Data Flow of a Java Application Running on the Module Figure 7: Data flow of a Java application running on the module. The diagram shows the data flow of a Java application running on the module. The data flow of a Java application running in the debug environment can be found in Figure 29. The compiled Java applications are stored as JAR files in the Flash File System of module.
Java User’s Guide 4.4 Handling Interfaces and Data Service Resources 35 4.4 s Handling Interfaces and Data Service Resources To develop Java applications the developer must know which resources, data services and hardware access are available. • There are multiple AT parsers available • There is hardware access over - two serial interfaces: ASC1 and ASC0 (both fully accessible). - general purpose I/O. To configure the hardware access, please refer to [1] and [2].
Java User’s Guide 4.4 Handling Interfaces and Data Service Resources 35 4.4.1.2 s State 2: No Java Running, General Purpose I/O and I2C/ SPI The Java application is inactive. There is an AT parser with CSD on ASC0 as well as ASC1. Up to ten I/O pins are used as general purpose I/O plus a I2C/SPI interface. The pins are configured by AT^SCPIN and AT^SSPI (refer [1]). Figure 9: Module State 2 4.4.1.
Java User’s Guide 4.4 Handling Interfaces and Data Service Resources 35 4.4.2 s Module State Transitions Figure 12: Module State Transition Diagram Note: No AT parser is available over serial interface ASC0 or ASC1 while a Java application is running on the module.
s Java User’s Guide 5 Maintenance 49 5 Maintenance The basic maintenance features of the ME are described below. Explicit details of these functions and modes can be found in [1] and [2]. 5.1 IP Service Apart from the standard Java IP networking interfaces (UDPDatagramConnection, SocketConnection, ...) the ME also supports a set of Internet Services controlled by AT command. There are some correlations between the Java and the AT IP Services.
s Java User’s Guide 5.2 Remote SIM Access 49 5.2 Remote SIM Access While Remote SIM Access (RSA) is normally closely coupled with the GSM 07.10 multiplexer there are some things to keep in mind when using it with Java. • Java must not be started when RSA and/or the GSM 07.10 multiplexer is activated.
s Java User’s Guide 5.4 Charging 49 5.4 Charging Please refer to [1] and [2] for general information about charging. Charging can be monitored by the running Java application. The JVM is active in Charge mode and in Charge-Only mode if autostart is activated. Only a limited number of AT commands are available when the module is in Charge-Only mode. A Java application must be able to handle the Charge-Only mode and reset the module to reinstate the normal mode.
s Java User’s Guide 5.7 Shutdown 49 5.7 Shutdown If an unexpected shutdown occurs, data scheduled to be written will get lost due to a buffered write access to the flash file system. The best and safest approach to powering down the module is to issue the AT^SMSO command. This procedure lets the engine log off from the network and allows the software to enter a secure state and save all data. Further details can be found in [2]. 5.7.
Java User’s Guide 5.8 Special AT Command Set for Java Applications 49 5.8 s Special AT Command Set for Java Applications For the full AT command set refer to [1]. There are differences in the behaviour AT commands issued from a Java application in comparison to AT commands issued over a serial interface. 5.8.1 Switching from Data Mode to Command Mode Cancellation of the data flow with “+++” is not available in Java applications, see [1] for details. To break the data flow use breakConnection().
s Java User’s Guide 5.9 System Out 49 5.8.5 Java Commands There is a small set of special Java AT commands: • AT^SJRA, start a Java application • AT^SJNET, configuration of Java networking connections • AT^SJOTAP, start and configuration of over the air provisioning • AT^SJSEC, security configuration Refer to the AT command Set [1]. 5.8.6 AutoExec Function Under Java, the AutoExec function’s AT command execution has some restrictions (see [1] for details on the AutoExec function).
s Java User’s Guide 5.10 GPIO 49 5.9.2 File The System.out print can be redirected into log files within the module’s flash file system. The output will be written alternatingly into two files which can be concatenated afterwards to have a single log file. Writing the output to a file will slow down the virtual machine. To reduce the impact of logging the output may be written first to a buffer before it is written to the file (buffered mode).
s Java User’s Guide 5.12 Performance 49 5.12 Performance The performance study was focused on comparable performance values under various circumstances. 5.12.1 Java This section gives information about the Java command execution throughput (“jPS”= Java statements per second). The scope of this measurement is only the statement execution time, not the execution delay (Java command on AT interface → Java instruction execution → reaction on GPIO).
s Java User’s Guide 5.12 Performance 49 5.12.2 Pin I/O The pin I/O test was designed to find out how fast a Java MIDlet can process URCs caused by Pin I/O and react to these URCs. The URCs are generated by feeding an input pin with an external frequency. As soon as the Java MIDlet is informed about the URC, it tries to regenerate the feeding frequency by toggling another output pin.
s Java User’s Guide 5.12 Performance 49 5.12.3.1 Plain Serial Interface Scenario: A device is connected to ASC0 (refer to Section 4.2.4). The Java application must handle data input and output streams. A simple Java application (with only one thread) which loops incoming data directly to output, reaches data rates up to 180kbit/s. Test conditions: hardware flow control enabled ( and ), 8N1, and baud rate on ASC0 set to 230kbaud (→ theoretical maximum: 184kbit/s net data rate).
s Java User’s Guide 5.12 Performance 49 5.12.3.4 Upload The ME supports up to four uplink time slots for GPRS and up to two for EGDE. The Java application receives data over RS232 API and sends them over GPRS to a server. Table 1: GPRS upload data rate with different number of timeslots, CS2 Upload data rate with x timeslots Coding scheme 2 [kbit/s] 1 timeslot theor. % Value1 from theor. Value 2 timeslots theor. % Value1 from theor. Value 3 timeslots theor. % Value1 from theor.
s Java User’s Guide 5.12 Performance 49 Figure 17: Scenario for testing data rates on ASC1 with GPRS data upload 5.12.3.5 Download The data rate for downloading data over GPRS/EDGE depends on the number of assigned timeslots and the coding schemes given by the net. The ME supports up to four downlink time slots. For the measurements, the Java application receives data from the server over GPRS and sends them over RS232 to an external device.
s Java User’s Guide 5.12 Performance 49 The tables below show the download data rates that can be achieved if hardware flow control is enabled on the CommConnection interface and the port speed is set to 460800. Table 5: GPRS Download data rate with different number of timeslots, CS2 Download data rate with x timeslots Coding scheme 2 [kbit/s] 1 timeslot theor. % Value from 1 theor. Value 2 timeslots theor. % Value1 from theor. Value 3 timeslots theor. % Value1 from theor. Value 4 timeslots theor.
s Java User’s Guide 5.13 System Time 49 5.13 System Time When Java starts up, it initializes its time base from the system’s real time clock. If the RTC is changed by AT command (AT+CCLK) later on, the Java time does not adjust. So, the time you get with (AT+CCLK) and the time you get with System.currentTimeMilis() may not necessarily be identical.
s Java User’s Guide 6 MIDlets 52 6 MIDlets The Java METM Mobile Information Device Profile (MIDP) provides a targeted Java API for writing wireless applications. The MIDP runs on top of the Connected Limited Device Configuration (CLDC), which in turn, runs on top of the Java METM. MIDP applications are referred to as MIDlets. MIDlets are controlled by the mobile device implementation that supports the CLDC and MIDP. Since IMP-NG is a subset of MIDP 2.0, IMP includes MIDlets.
s Java User’s Guide 6.2 MIDlet Life Cycle 52 • • • notifyDestroyed() – the MIDlet notifies the application management software that it has cleaned up and is done. Note: the only way to terminate a MIDlet is to call notifyDestroyed(), but destroyApp() is not automatically called by notifyDestroyed(). You must not terminate your midlet (i.e. having no threads left) and not calling notifyDestroyed() before.
s Java User’s Guide 6.3 Hello World MIDlet 52 6.3 Hello World MIDlet Here is a sample HelloWorld program. /** * HelloWorld.java */ package example.helloworld; import javax.microedition.midlet.*; import java.io.*; public class HelloWorld extends MIDlet { /** * HelloWorld - default constructor */ public HelloWorld() { System.out.println("HelloWorld: Constructor"); } /** * startApp() */ public void startApp() throws MIDletStateChangeException { System.out.println("HelloWorld: startApp"); System.out.
s Java User’s Guide 7 File Transfer to Module 54 7 File Transfer to Module 7.1 Module Exchange Suite The Module Exchange Suite allows you to view the Flash file system on the module as a directory from Windows Explorer. Make sure that the module is turned on and that one of the module’s serial interfaces (ASC0, ASC1 or USB) is connected to the COM port that the Module Exchange Suite is configured to. The configured COM port can be checked or changed under Properties of the Module directory.
s Java User’s Guide 7.3 Security Issues 54 7.3 Security Issues The developer should be aware of the following security issues. Security aspects in general are discussed in Chapter 12. 7.3.1 Module Exchange Suite The serial interface should be mechanically protected. The copy protection rules for Java applications prevent opening, reading, copying, moving or renaming of JAR files. It is not recommended that the name of a Java application (for example .
s Java User’s Guide 8 Over The Air Provisioning (OTAP) 63 8 Over The Air Provisioning (OTAP) 8.1 Introduction to OTAP OTA (Over The Air) Provisioning of Java Applications is a common practice in the Java world. OTAP describes mechanisms to install, update and delete Java applications over the air. The ME implements the Over The Air Application Provisioning as specified in the IMP-NG standard (JSR228).
s Java User’s Guide 8.3 OTAP Parameters 63 8.3 OTAP Parameters There is a set of parameters that control the OTAP procedures. These parameters can either be set by AT command (AT^SJOTAP, refer to [1] during the production of the device, or by SM (see Section 8.4) during operation of the device in the field. None of the parameters, which are set by AT command, can be overwritten by SM. • • • • • • • • • • JAD File URL: the location of the JAD file is used to install or update procedures.
s Java User’s Guide 8.4 Short Message Format 63 Table 10: Parameters and keywords Parameters Max. Length AT Keyword SM Install/update delete Ignore SM PID -- -- -- -- Hide HTTP authentication parameters -- -- -- -- The length of the string parameters in the AT command is limited (see Table 10), the length in the SM is only limited by the maximum SM length. The minimum set of required parameters depends on the intended operation (see Table 10).
s Java User’s Guide 8.5 Java File Format 63 The values of APPDIR, BEARER and START are used internally and must be lower case. The password (PWD) is case sensitive. The case sensitivity of the other parameter values depends on the server application or the network. It is likely that not all parameters can be sent in one SM. They can be distributed over several SMs. Every SM needs to contain the identifying first line (OTAP_IMPNG) and the PWD parameter if a mandatory password has been enabled.
s Java User’s Guide 8.6 Procedures 63 A suitable Manifest file for the JAD file above might look like: Manifest-Version: 1.0 MIDlet-Name: MyTest MIDlet-Version: 1.0.1 MIDlet-Vendor: TLR Inc. MIDlet-1: MyTest, , example.mytest.MyTest MicroEdition-Profile: IMP-NG MicroEdition-Configuration: CLDC-1.1 8.6 Procedures 8.6.
s Java User’s Guide 8.6 Procedures 63 the old and the new application at the same time, the old application is deleted before the download of the new one, therefore it is lost when an error occurs.If install/update was successful, autostart is set to the new application. 8.6.
s Java User’s Guide 8.7 Time Out Values and Result Codes 63 8.
s Java User’s Guide 8.9 OTAP Tracer 63 8.9 OTAP Tracer For easy debugging of the OTAP scenario, the OTAP procedure can be traced over the serial interface. The trace output shows details of the OTAP procedure and the used parameters. To enable the OTAP trace output use the AT command AT^SCFG, e.g. AT^SCFG=Trace/Syslog/OTAP,1 The serial interface on which you issue this command is then exclusively used for the OTAP tracer.
s Java User’s Guide 8.11 How To 63 device reboots. You can now check the content of the file system and if the correct jar and jad files were loaded into the correct location. 8. Analyze errors.
Java User’s Guide 9 Compile and Run a Program without a Java IDE 66 9 s Compile and Run a Program without a Java IDE This chapter explains how to compile and run a Java application without a Java IDE. 9.1 Build Results A JAR file must be created by compiling an SMTK project. A JAR file will contain the class files and auxiliary resources associated with an application. A JAD file contains information (file name, size, version, etc.) on the actual content of the associated JAR file.
s Java User’s Guide 9.2 Compile 66 9.2 • • • Compile Launch a Command Prompt. This can be done from the Programs menu or by typing „cmd“ at the Run... prompt in the Start menu. Change to the directory where the code to be compiled is kept. Compile the program with the SDK. Examples of build batch files can be found in each sample program found in the examples directory, \Siemens\SMTK\ \wtk\src\example. If the compile was successful the program can be run from the command line.
s Java User’s Guide 9.4 Run on the Module with Autostart 66 9.4 • • Compile the application at the prompt as discussed in Section 9.2 or in an SMTK integrated IDE. Transfer the .jar and .jad file from the development platform to the desired directory on the module using the Module Exchange Suite or OTA provisioning. See Chapter 7. 9.4.1 • • Run on the Module with Autostart Switch on Autostart There is an AT command, AT^SCFG, for configuring the autostart functionality. Please refer to [1].
Java User’s Guide 10 Compile and Run a Program with a Java IDE 71 s 10 Compile and Run a Program with a Java IDE 10.1 Eclipse 3.1.2 (with ME Plugin 1.2.3) The following description assumes that Eclipse 3.1.2 is installed from SMTK CD as described in Section 3.3.1.6 10.1.1 Setup a New Project Step 1: Create new Java Project: - Select Eclipse menu File → New → Other… - Select J2ME Midlet Suite: Figure 22: Create new Eclipse project: Create a J2ME MIDP Midlet Suite - Type in the used name (e.g.
s Java User’s Guide 10.1 Eclipse 3.1.2 (with ME Plugin 1.2.3) 71 - Select e.g.
s Java User’s Guide 10.1 Eclipse 3.1.2 (with ME Plugin 1.2.
s Java User’s Guide 10.1 Eclipse 3.1.2 (with ME Plugin 1.2.3) 71 Step 2: Modify Java source file “printme.java” template: Figure 28: Create new Eclipse project: Edit some Java commands This application prints the given line via ASC1 (default setting). Please keep in mind to add “notifyDestroyed();” in destroyApp() method. Please refer to Chapter 6 “MIDlets” for more details about Midlet life cycles. Step 3: Configure Jad file: - Double click on “Project01.
s Java User’s Guide 10.1 Eclipse 3.1.2 (with ME Plugin 1.2.3) 71 Step 4: Create Jad and Jar file: - Select “Project01” - Open context menu of “Project01” and select Create Package from item J2ME - Jad and Jar file are be created under the “deployed” directory (default setting of Eclipse) Step 5: Download Jad and Jar file into the Flash File System of the module and start the Java application: Manual download and start of Java application: - Copy Jad and Jar files manually using MES (e.
s Java User’s Guide 11 Debug Environment 97 11 Debug Environment 11.1 Data Flow of a Java Application in the Debug Environment Figure 30: Data flow of a Java application in the debug environment In the debug environment the module is connected to a PC via a serial interface. This can be a USB or an RS232 line. The application can then be edited, built, debugged or run within an IDE on the PC.
s Java User’s Guide 11.2 Emulator 97 11.2 Emulator The ME emulator is part of the SMTK and is used as the controlling entity for on-device debugging. Some values can be configured in the file wtk/bin/WM_Debug_config.ini (see below note for TC65). The emulator is running fine without changes in WM_Debug_config.ini file, because the settings for the serial interface (COM port and baudrate) are configured during installation of SMTK. Note: For TC65 the file "WM_Debug_config.
s Java User’s Guide 11.2 Emulator 97 needs some seconds to enable the USB port once again after the "IP connection for remote debugging" is closed. If necessary, the IP addresses used for the debug connection can also be changed. This is done in the file "WM_Debug_config.ini". For details, see also the AT^SCFG command and its “Userware/DebugInterface” parameters described in [1]. Please keep in mind, that the IP address range 10.x.x.
s Java User’s Guide 11.3 Java IDE 97 11.3 Java IDE The SMTK is integrated into your Java IDE during installation. Please note that the IDE integration is intended to create MIDlets suitable for the Java enabled module and for debugging using the emulator. JAR files used in the module must be configured according to the batch file examples given.
s Java User’s Guide 11.3 Java IDE 97 Figure 31: NetBeans IDE 5.0 - installed emulators 11.3.1.1 Switching Emulator to IMP-NG Emulator You can switch to the SMTK emulator project dependent using the context menu for project properties (e.g. "Hello Sample" ) and select the emulator platform and the device e.g. “Siemens IMP-NG TC65 R2 Wireless Toolkit” and “IMP_NG_TC65_R2” for TC65 Release 2. See Figure 32. Figure 32: NetBeans IDE 5.
s Java User’s Guide 11.3 Java IDE 97 11.3.1.2 Templates Templates for a Siemens MIDlet can be found in the file explorer and under NetBeans IDE 5.0 menu File → New File... The MIDlet template provides the skeleton of an IMP-NG MIDlet application. The New File wizard opens. Select category “IMP-NG” and File Type “IMP-NG MIDlet” and press the Next button for working with this skeleton. Figure 33: NetBeans IDE 5.0 - Selecting an IMP-NG MIDlet template (e.g.
s Java User’s Guide 11.3 Java IDE 97 11.3.1.3 Examples There are three IMP-NG MIDlet sample projects (“HelloSample”, “NetDemo” and “RS232Sample”) included. Each sample project can be selected directly in NetBeans IDE 5.0. You can open the sample project (e.g. “HelloSample”) using the NetBeans IDE 5.0 menu File → New Project... The New Project wizard opens. Select Category Samples → Mobile → IMPNG and select (e.g. “Hello World Example”). Press the Next button. Figure 34: NetBeans IDE 5.
s Java User’s Guide 11.3 Java IDE 97 11.3.1.4 Compile and Run Ensure that the proper emulator will be used and compile the project as normal. Any output will be shown in the output window in the IDE together with some debugging information of the IDE. The html help files of the SMTK can be accessed directly by pressing Alt+F1. 11.3.1.5 Starting Debug Session without Downloading Java Files It is possible to start a debugging session without download of the Java files (*.jad and *.jar) again.
s Java User’s Guide 11.3 Java IDE 97 11.3.1.6 Displaying Java "System.out" in NetBeans IDE window Please prepare redirection of Java “System.out” during a debugging session as described in Section 11.5 Switching Java “System.out” to IDE debug window. The Debugging Console tab of the NetBeans IDE window is selected by default after starting the debugging session. To display the Java “System.out”s after starting the debugging session select the “build.
s Java User’s Guide 11.3 Java IDE 97 11.3.2 Eclipse 3.0 and Eclipse 3.1 We recommend that Eclipse 3.0.1 or higher is to be used. 11.3.2.1 Eclipse 3.0 Please use the customized Eclipse ME Plugin version that is distributed with the SMTK CD under the directory “EclipseMEplugin_WM” only for Eclipse 3.0.1 and 3.0.2 and install Eclipse ME as described in Section 3.4. However, instead of selecting "eclipseme.feature_1. 2.3_site.zip" choose “\EclipseMEpluging_WM\plugin.
s Java User’s Guide 11.3 Java IDE 97 11.3.2.4 Using Eclipse with ME Plugin up to Version 1.2.3 11.3.2.4.1 Additional Configuration of Integrated Emulator The following configuration is displayed after SMTK integration into Eclipse by using the Eclipse menu Windows → Preferences → J2ME → Platform Components: Figure 38: Eclipse – Display of different integrated emulators To use the debugger it is necessary to increase the debug server delay timeout of Eclipse IDE.
s Java User’s Guide 11.3 Java IDE 97 11.3.2.4.2 Switching Emulators You can easily switch between different installed emulators by using the preferences of a project and choosing e.g. Siemens IMP-NG TC65 R2 Module, see figure below. Figure 39: Eclipse – J2ME platform 11.3.2.5 Using Eclipse with ME Plugin 1.5.x Eclipse ME Plugin 1.5.x is supported by the TC65, XT65/XT75 and AC65/AC75 CDs. This Eclipse ME Plugin is using a completely new device management concept to integrate different emulators.
s Java User’s Guide 11.3 Java IDE 97 11.3.2.5.1 Additional Configuration of Integrated Emulator The following configuration is displayed after SMTK integration into Eclipse by using the Eclipse menu Windows → Preferences → J2ME → Device Management: Figure 40: Eclipse with ME Plugin 1.5.0 – Display of different integrated emulators To use the debugger it is necessary to increase the debug server delay timeout of Eclipse IDE.
s Java User’s Guide 11.3 Java IDE 97 11.3.2.5.2 Switching Emulators You can easily switch between different installed emulators by using the properties of a project and choosing a Device Group, e.g. "Siemens IMP-NG XT75 Wireless Toolkit". You can select a device also by using the Manage Devices… button, see figure below. Figure 41: Eclipse with ME Plugin 1.5.0 – J2ME platform 11.3.2.6 Using Eclipse with ME Plugin 1.6.x Automatic integration into Eclipse ME Plugin 1.6.
s Java User’s Guide 11.3 Java IDE 97 11.3.2.7 Import Example You can import an existing Eclipse project using the following steps: - Open menu: File → Import → Existing Project into Workspace - Choose the root directory of the Eclipse project (e.g. “Hello World” example of the SMTK CD). See figure below. Figure 42: Eclipse – Project import The following figure shows the “Hello World” example in the IDE.
s Java User’s Guide 11.3 Java IDE 97 11.3.2.8 Compile and Debug To build the jar and jad files you have rebuild the project with the Create Package function. Open the context menu of the project and go to J2ME → Create Package. Figure 44: Eclipse – Create package Now you are ready to debug your project. Run → Debug… An emulator launcher with pre-settings is provided for starting the debugging session. Please ensure that you have selected the right project and executable midlet.
s Java User’s Guide 11.3 Java IDE 97 Figure 45: Eclipse - Configuration Restriction: The integration of the SMTK using the SMTK installer depends selecting the offered default workspace “\workspace” of Eclipse (e.g. Eclipse 3.0.1 and 3.0.2 “..\eclipse\workspace\..” or Eclipse 3.1.0, 3.1.1 and 3.1.2 “..\Documents and Settings\\workspace\..”).
s Java User’s Guide 11.3 Java IDE 97 11.3.2.9 Starting Debug Session without Downloading Java Files It is possible to start a debugging session without download of the Java files (*.jad and *.jar) again. The emulator has to be started with an additional parameter “-noload” and downloading of the Java files is suppressed.
s Java User’s Guide 11.3 Java IDE 97 Note for using Eclipse 3.2.x ME 1.5.x and 1.6.x: During debugging it is sometimes possible, that if a breakpoint is reached, the Java program stops, but no breakpoint is indicated in the Java source line (Java source windows). In this case please select the Java Thread in the "Debug" window and select "System Thread" where the hit breakpoint is shown. The corresponding source line is highlighted inside the Java source windows (e.g. "HelloWorld.
s Java User’s Guide 11.3 Java IDE 97 11.3.3 Borland JBuilder X If you want to use JBuilder X and it is not installed, first install JBuilder X and follow the installation wizard instructions. Run the SMTK installation program in maintenance mode. The SMTK will find the installed JBuilder X IDE. Select JBuilder X to integrate the SMTK into JBuilder X. After integration of SMTK into JBuilder X you can examine the integration by opening the menu Tools → Configure JDKs… (see Figure below).
s Java User’s Guide 11.3 Java IDE 97 11.3.3.1 Examples There are sample projects provided with the SMTK. These projects can be found in the JBuilderSamples directory of the SMTK installation directory. This directory is accessed by opening a project using the menu File → Open Project… (see Figure below). Figure 50: JBuilder X – Sample Projects Open the Project (e.g. “HelloWorld.jpx”), rebuild the sources and start the debugger using the micro edition (context menu “HelloWorld.
s Java User’s Guide 11.3 Java IDE 97 11.3.3.2 Starting Debug Session without Downloading Java Files It is possible to start a debugging session without download of the Java files (*.jad and *.jar) again. The emulator has to be started with an additional parameter “-noload” and downloading of the Java files is suppressed. Please add the parameter in the following emulator running configuration line as described in the figures above. Select the project properties (e.g. “HelloWorld.
s Java User’s Guide 11.3 Java IDE 97 11.3.4 Borland JBuilder 2005 and JBuilder 2006 Enterprise/Developer If JBuilder 2005 or JBuilder 2006 Enterprise/Developer is not installed, run the JBuilder 2005 or JBuilder 2006 Enterprise/Developer install program and follow the installation wizard instructions. Use the SMTK installation routine in maintenance mode. The SMTK will find the installed JBuilder 2005 or JBuilder 2006 Enterprise/Developer IDE.
s Java User’s Guide 11.4 Breakpoints 97 11.3.4.1 Examples There are sample projects provided with the SMTK. These projects can be found in the JBuilderSamples directory of the SMTK installation directory. This directory is accessed by opening a project using the menu File → Open Project… (see Figure below). Figure 56: JBuilder 2006 Enterprise/Developer – Sample Projects Starting the debugging session is done in the same way as for JBuilder X (see chapter for JBuilder X above). 11.
Java User’s Guide 11.5 Switching Java “System.out” to IDE Debug Window 97 11.5 s Switching Java “System.out” to IDE Debug Window The Java “System.out” can be redirected during a debugging session using a UDP socket connection as described in Section 5.9 “System Out” and Section 5.9.3 “UDP”. Switching between Java “System.out” using serial port and Java “System.out” using UDP socket is done by a setting inside of the emulator configuration file “WM_Debug_config.ini” (e.g.
Java User’s Guide 11.6 Important Information for Java Debugging on Windows Vista 97 11.6 s Important Information for Java Debugging on Windows Vista This section applies only to TC65. Java Debugging on Windows Vista requires that administrator privileges be set. To do so, follow these steps: 1. Log on your system using an administrator account. 2.
s Java User’s Guide 12 Java Security 112 12 Java Security The Java Security Model follows the specification of MIDP 2.0 and is IMP-NG conforming. It integrates only a simple protection domain concept since protection domains are not needed for module use cases. Java Security is divided into two main areas: • Secure MIDlet data links (HTTPS, Secure Connection) (see Section 12.1) • Execution of signed/unsigned MIDlets (see Section 12.2) The interface of Java Security offers the following functionality.
s Java User’s Guide 12.1 Secure Data Transfer 112 Two modes exist for safe data links. Mode 1: • No examination of the server certificate takes place when setting up the connection. The authenticity of the server certificate is not verified. See Figure 59. Figure 59: Mode 1 – Customer Root Certificate does not exist Mode 2 (see Section 12.2.1, 1. Step): • Customer Root Certificate is inside of the module. • Command: Switch on Certificate Verification for HTTPS Connections was sent.
s Java User’s Guide 12.1 Secure Data Transfer 112 Figure 61: Mode 2 - Server Certificate and self signed root Certificate in module form a chain 12.1.1 Create a Secure Data Transfer Environment Step by Step The following steps describe the configuration: • The certificate exists within the module (see Section 12.2.1, Step 1). • Certificate verification is activated for a data connection (HTTPS or SecureConnection).
s Java User’s Guide 12.1 Secure Data Transfer 112 1. Create CA and generate CA Root Certificate - We need certificates with sha1 signature. Java Security supports a sha1 signature of the certificate only. Add the parameter "-sha1" to the command "Making CA certificate ..." in the section of file CA.pl (cygwin location \cygwin\usr\ssl\misc”) - Create a shell (use location \cygwin\usr\ssl\misc) - Execute commands >perl CA.pl –newca - Convert file format from PEM to DER CA certificate cacert.
s Java User’s Guide 12.1 Secure Data Transfer 112 5. Import CA root certificate and CA private key into java keystore - Use the CA Root Certificate for the creation of Java Security Command. See Section 12.5.3. - Execute command >java -jar setprivatekey.jar -alias dummyca -storepass keystorepass -keystore customer.ks -keypass cakeypass -keyfile ./democa/private/cakey.der -certfile ./democa/cacert.der 6.
s Java User’s Guide 12.2 Execution Control 112 12.2 Execution Control The Java environment of the ME supports two modes. Unsecured mode: • The device starts all Java applications (MIDlets). Secured mode: • A condition for the secured mode of the device is the existence of a certificate inside of the module. • The customer can activate the secured mode of the device. To do so, the customer sends a root certificate (x.
s Java User’s Guide 12.2 Execution Control 112 12.2.1 Change to Secured Mode Concept Create and insert a customer root certificate: A condition for the change to the secured mode is the existence of a customer root certificate inside of the module. Figure 62: Insert Customer Root Certificate After this action the module is in the following conditions: - The module changes into the mode “trusted” for MIDlet execution. “Untrusted Domain” is OFF. - HTTPS certificate verification is OFF. - MES is ON.
s Java User’s Guide 12.2 Execution Control 112 12.2.
s Java User’s Guide 12.3 Application and Data Protection 112 12.3 Application and Data Protection In addition to the Java secured mode it is possible to prevent the activation of the Module Exchange Suite. When Module Exchange Suite access is deactivated with AT^SJSEC, it is no longer possible to access to the Flash file system on the module. A condition for the deactivation of the access to the Flash file system is the existence of a customer root certificate inside of the module (see Section 12.2.1).
Java User’s Guide 12.4 Structure and Description of the Java Security Commands 112 12.4.
Java User’s Guide 12.4 Structure and Description of the Java Security Commands 112 12.4.
Java User’s Guide 12.4 Structure and Description of the Java Security Commands 112 12.4.3 s Send Java Security Command to the Module Use a terminal program. Enter: AT^SJSEC Wait for the answer: CONNECT JSEC READY: SEND COMMAND ... Now you can send the binary data of the command (for example: from a file with the binary data of the command). The module’s answer depends on the result of the operation. The read command, AT^SJSEC?, can be used to request the current Java security status.
Java User’s Guide 12.5 Create a Java Security Environment Step by Step 112 s 12.5 Create a Java Security Environment Step by Step 12.5.1 Create Key Store The key store contains the key pairs for signing data. For producing the key store with keys the tool “keytool.exe” can be used. The program is in the Java SDK. (for a description see http:// java.sun.com/j2se/1.3/docs/tooldocs/solaris/keytool.html). Example: keytool -genkey -alias keyname -keypass keypassword -keystore customer.
Java User’s Guide 12.5 Create a Java Security Environment Step by Step 112 s Command: switch on Java Security Mode java -jar jseccmd.jar -cmd TrustedModeOn -imei 012345678901234 -alias keyname -storepass keystorepassword -keypass keypassword -keystore customer.ks > TrustedModeOn.bin Command: switch off Java Security Mode java -jar jseccmd.jar -cmd TrustedModeOff -imei 012345678901234 -alias keyname -storepass keystorepassword -keypass keypassword -keystore customer.ks > TrustedModeOff.
s Java User’s Guide 12.6 Attention 112 12.5.4 Sign a MIDlet Use the tool “jadtool.jar” to sign a Java MIDlet. This program is in the folder “wkt\bin”. java -jar jadtool.jar -addjarsig -jarfile helloworld.jar -inputjad helloworld.jad -outputjad helloworld.jad -alias keyname -storepass keystorepassword -keypass keypassword -keystore customer.ks -encoding UTF-8 12.6 Attention The central element of Java Security is the private key.
s Java User’s Guide 13 Java Tutorial 122 13 Java Tutorial This small tutorial includes explanations on how to use the AT Command API and suggestions for programming MIDlets. The developer should read about MIDlets, Threads and AT commands as a complement to this tutorial. 13.1 Using the AT Command API Perhaps the most important API for the developer is the AT command API. This is the API that lets the developer issue commands to control the module.
s Java User’s Guide 13.1 Using the AT Command API 122 13.1.1.2 Sending an AT Command to the Device, the send() Method An AT command is sent to the device by using the send() method. The AT command is sent as a string which must include the finalizing line feed "\r" or the corresponding line end character. String response = atc.send(“at+cpin?\r”); /* method returns when the module returns a response */ System.out.println(response); #Possible response printed to System.
s Java User’s Guide 13.1 Using the AT Command API 122 13.1.1.3 Data Connections If a data connection is created with the ATCommand class, for instance with ‘atd’, an input stream is opened to receive the data from the connection. Similarly, an output stream can be opened to send data on the connection. /* Please note that this example would not work unless the module had * been initialized and logged into a network. */ System.out.println("Dialing: ATD" + CALLED_NO); response = atc.
s Java User’s Guide 13.1 Using the AT Command API 122 These streams behave slightly differently than regular data streams. The streams are not closed by using the close() method. A stream remains open until the release() method is called. A module can be switched from the data mode to the AT command mode by calling the breakConnection() method. /* continue example */ if (rcv != -1) { // Now break the data connection System.out.println("\n\n\rBreaking connection"); try { strRcv = ATCmd.
s Java User’s Guide 13.1 Using the AT Command API 122 13.1.1.4 Synchronization For performance reasons no synchronization is done in the ATCommand class. If an instance of this class has to be accessed from different threads ensure that the send() functions, the release() function, the cancelCommand() function and the breakConnection() function are synchronized in the user implementation. 13.1.
s Java User’s Guide 13.1 Using the AT Command API 122 13.1.3 ATCommandListener Interface The ATCommandListener interface implements callback functions for: • URCs • Changes of the serial interface signals RING, DCD and DSR • Opening and closing of data connections The user must create an implementation class for ATCommandListener to receive AT events. The ATEvent method of this class must contain the processing code for the different AT-Events (URCs).
s Java User’s Guide 13.1 Using the AT Command API 122 13.1.3.2 Implementation class ATListenerA implements ATCommandListener { public void ATEvent(String Event) { if (Event.indexOf("+CALA: Reminder 1") >= 0) { /* take desired action after receiving the reminder */ } else if (Event.indexOf("+CALA: Reminder 2") >= 0) { /* take desired action after receiving the reminder */ } else if (Event.
s Java User’s Guide 13.1 Using the AT Command API 122 13.1.3.3 Registering a Listener with an ATCommand Instance After creating an instance of the ATCommandListener class, it must be passed as a parameter to the ATCommand.addListener() method. The callback methods of the instance will be called by the runtime system each time the corresponding events (URCs or signal state changes) occur on the corresponding device AT parser.
s Java User’s Guide 13.2 Programming the MIDlet 122 13.2 Programming the MIDlet The life cycle and structure of MIDlets are described in Chapter 6. Since the MIDlets will run on Java METM, all of Java METM’s features, including threads, are available. Small applications, such as those without any timer functions or those used only for tests and simple examples, can be written without using threads. Longer applications should be implemented with threads. 13.2.
s Java User’s Guide 13.2 Programming the MIDlet 122 /* Print loop counter and wait 1 second, * do something useful here instead */ System.out.println("Thread(" + loops + "): Loop " + i); try { Thread.sleep(1000); } catch(InterruptedException e) { System.out.println(e); } } System.out.println("Thread(" + loops + "): Finished naturally"); } } /** * ThreadDemo - constructor */ public ThreadDemo() { System.out.
s Java User’s Guide 14 Differences to the TC45 123 14 Differences to the TC45 For those who are familiar with the Siemens WM IMP1.0 product (TC45) this is an overview of the main differences between this and the IMP-NG product line (e.g. TC65). • „real“ TCP and UDP access interfaces: SocketConnection, ServerSocketConnection, UDPDatagramConnection. Use of StreamConnection, StreamConnectionNotifier, DatagramConnection is now discouraged.
