Cop

yrig

ht ©

200

2-20

03 N

okia

. All

right

s re

serv

ed.

Iss

ue 2

.0

9355

602

NOKIA M2M PLATFORM

TERMINAL MANAGEMENT COMPONENT

USER GUIDE

Contents

ACRONYMS AND TERMS ......................................................................................................1 1. ABOUT THIS DOCUMENT ..............................................................................................2 2. INTRODUCTION..............................................................................................................3 3. GETTING STARTED........................................................................................................5

3.1 PRELIMINARY INFORMATION ...................................................................................5 3.2 WORKING ORDER ......................................................................................................6

4. USING THE TERMINAL MANAGEMENT COMPONENT APPLICATION PROGRAMMING INTERFACE ........................................................................................7

4.1 SETTING THE TERMINAL MANAGEMENT COMPONENT CONFIGURATION ........7 4.1.1 Initialising the CORBA Naming Service .................................................................8 4.1.2 Initialising the CORBA Object Request Broker ......................................................9

4.2 SETTING THE GATEWAY CONFIGURATION..........................................................10 4.3 INITIALIZING AND RUNNING THE TERMINAL MANAGEMENT COMPONENT.....11

4.3.1 Listening to messages and events .......................................................................12 4.4 TERMINAL CONFIGURATION ..................................................................................14

4.4.1 Initialising bearers ................................................................................................14 4.4.2 Initialising terminals ..............................................................................................15 4.4.3 Initialising terminal configuration options..............................................................17 4.4.4 Starting the configuration process........................................................................19 4.4.5 Closing the Terminal Management Component...................................................20 4.4.6 Terminal Management Component log ................................................................20

4.5 EXAMPLE APPLICATION USING THE TERMINAL MANAGEMENT COMPONENT APPLICATION PROGRAMMING INTERFACE .........................................................20

5. USING THE TERMINAL MANAGEMENT COMPONENT USER INTERFACE .............24 5.1 USER INTERFACE DESCRIPTION...........................................................................24 5.2 GENERAL USE ..........................................................................................................24 5.3 BEARER MANAGEMENT ..........................................................................................25

5.3.1 Adding bearers .....................................................................................................25 5.3.2 Removing bearers ................................................................................................25

5.4 TERMINAL MANAGEMENT.......................................................................................26 5.4.1 Adding terminals...................................................................................................26

5.4.2 Removing terminals..............................................................................................26 5.5 TERMINAL MANAGEMENT COMPONENT CONFIGURATION ...............................26

5.5.1 Terminal Management Component settings ........................................................26 5.5.2 Gateway settings..................................................................................................27 5.5.3 Modifying the Terminal Management Component User Interface properties.......28

5.6 STARTING THE TERMINAL CONFIGURATION.......................................................29 5.7 TERMINAL MANAGEMENT COMPONENT USER INTERFACE LOG .....................30

Legal Notice

Copyright © 2002-2003 Nokia. All rights reserved.

Reproduction, transfer, distribution or storage of part or all of the contents in this document in any form without the prior written permission of Nokia is prohibited.

Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. 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.

Nokia operates a policy of continuous development. Nokia reserves the right to make changes and improvements to any of the products described in this document without prior notice.

Under no circumstances shall Nokia be responsible for any loss of data or income or any special, incidental, consequential or indirect damages howsoever caused.

The contents of this document are provided "as is". Except as required by applicable law, no warranties of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose, are made in relation to the accuracy, reliability or contents of this document. Nokia reserves the right to revise this document or withdraw it at any time without prior notice.

ACRONYMS AND TERMS

Acronym/term Description

API Application Programming Interface

CORBA Common Object Request Broker Architecture

CP Connection Provider

CSD Circuit Switched Data

ET Embedded Terminal – a remote object interface implemented in a Nokia GSM Connectivity Terminal

GPRS General Packet Radio Service

GSM Global System for Mobile Communications

IP Internet Protocol

M2M Machine-to-Machine

MSISDN Mobile Subscriber International ISDN Number

ORB Object Request Broker

OTA Over-the-Air technology

SMS Short Message Service

TCP Transmission Control Protocol

TMC Terminal Management Component

UI User Interface

USSD Unstructured Supplementary Service Data

WTP Wireless Transaction Protocol

1/31

1. ABOUT THIS DOCUMENT

This document instructs how to use the Terminal Management Component (TMC) and its Application Programming Interface (API) and User Interface (UI).

2/31

2. INTRODUCTION

The TMC is used to configure Nokia GSM Connectivity Terminals to communicate with a specified Nokia M2M Gateway. It can be used together with the Nokia M2M Gateway Corporate Edition (see Figure 1) or Nokia M2M Gateway Service Provider Edition in which case it connects to the Gateway Access Software (see Figure 2).

TerminalManagement

Component API

Customerapplication

GSM

GSMNokia GSM Connectivity

Terminal Nokia GSM Connectivity

Terminal

Nokia M2MGatewayCorporate

Edition

TCP/IP

Figure 1. TMC in the Nokia M2M Platform with the Corporate Edition

Nokia M2MGateway

Service ProviderEdition

Gateway AccessSoftware

TerminalManagement

Component API

Customerapplication

Nokia GSM Connectivity

Terminal Nokia GSM Connectivity

Terminal

GSM

GSMTCP/IP

Database

TCP/IP

Figure 2. TMC in the Nokia M2M Platform with the Service Provider Edition

The TMC is a software component that can be embedded into Java™ applications. It incorporates the necessary methods to configure terminals with various communication bearers using different configuration options.

The TMC package also contains a reference application implementation with a graphical UI. This UI can be used to configure terminals without writing any

3/31

Java code. However, the functionality of this reference implementation is limited.

The TMC API is included in the terminal_management_component.jar file located in the <Gateway installation directory>/utils/ TerminalManagementComponent/lib directory. The path of this file must be added into the CLASSPATH environment variable before using the TMC API.

4/31

3. GETTING STARTED

This chapter provides basic information on how to configure Nokia GSM Connectivity Terminals using the TMC UI, the Gateway, and the Gateway Access Software.

The TMC is included in the Gateway Access Software and Nokia M2M Gateway Corporate Edition installation packages.

For more detailed information on how to use the TMC API and UI, refer to Chapters 4 and 5.

3.1 PRELIMINARY INFORMATION Before starting, you need the following preliminary information:

• Name of the SmartMessaging Connection Provider (CP) in the Gateway (Service Provider Edition or Corporate Edition)

• Domain name of the Gateway Access Software in the Service Provider Edition (if Gateway Access Software is used)

• Bearer types to be configured into the target Nokia GSM Connectivity Terminals

• Wireless Transaction Protocol (WTP) ports for bearers to be used with Nokia GSM Connectivity Terminals

If the target terminals do not contain any bearer configurations, you can use the SmartMessaging configuration feature. The TMC needs to know the name of the SmartMessaging CP that is configured into the Gateway.

Confirm that the Gateway offers those bearers that you want to configure into the target terminals. The Gateway can support the following bearers:

• Circuit Switched Data (CSD)

• General Packet Radio Service (GPRS)

• Short Message Service (SMS)

• Unstructured Supplementary Service Data (USSD)

However, the actual available set of bearers depends on the Gateway configuration, the GSM network, and on the selection of bearers supported by terminals.

5/31

You also need to select WTP ports for the target terminals. The recommended ports to be used with different bearers are:

• Port 2 for SMS

• Port 3 for GPRS

• Port 4 for CSD

• Port 5 for USSD

3.2 WORKING ORDER To configure a Nokia GSM Connectivity Terminal:

1. Collect the required preliminary information (refer to Chapter 3.1).

2. Ensure that either the Corporate Edition is running Gateway Access Software is running and connection to the Service Provider Edition is established.

3. Start the TMC UI with the ready-made starting script. Select a script that initialises the chosen CORBA ORB in the chosen operating system. Starting scripts using Visibroker ORB:

− terminal_management_component_visibroker.bat (Windows) − terminal_management_component_visibroker_hp.sh (HP-UX)

Note: Set DISPLAY variable if using HP server from remote host (export DISPLAY=<remote host ip-address>:0.0)

− terminal_management_component_visibroker_solaris.sh (Solaris)

4. Configure the necessary options in the TMC UI.

5. Select the bearers and terminals you want to configure.

6. Send the configuration to the target terminals.

6/31

4. USING THE TERMINAL MANAGEMENT COMPONENT APPLICATION PROGRAMMING INTERFACE

This chapter describes the TMC API.

The TMC API classes are included in the terminal_management_component.jar file. The TMC classes can be found in the com.nokia.m2m.terminalmanagement package.

4.1 SETTING THE TERMINAL MANAGEMENT COMPONENT CONFIGURATION The TMC configuration class can be found in the com.nokia.m2m.terminalmanagement.TerminalManagementConfig package.

The TMC configuration parameters are:

• Minimum sending threads (set using the setMinSendThreads method)

• Maximum sending threads (set using the setMaxSendThreads method)

• SmartMessaging delay (set using the setDelaySecAfterSmartMessaging method)

• Default terminal bit rate (set using the setDefaultBitrate method)

• Connection timeout (set using the setDefaultConnectionTimeoutSec method)

Minimum and Maximum sending threads The Minimum and Maximum sending threads parameters define the size of a thread pool that offers working threads to TMC for the terminal configuration process. The more threads available in the pool, the more terminals can be configured simultaneously. The minimum number of threads is running by default and the number of threads can grow to the maximum if more connections are required.

The default value for the Minimum sending threads is ‘5’ and for the Maximum sending threads ‘10’.

SmartMessaging delay This parameter defines the time in seconds the configuration process is blocked after sending the configuration with SmartMessaging. The delay time is used only when there is more than one bearer that needs to be configured using the

7/31

Embedded Terminal (ET) object, or when the configuration is tested after configuring with SmartMessaging. The delay time should be higher than what it takes to send an SMS from the Gateway to a terminal.

The default value for SmartMessaging delay is ‘20’ seconds.

Note: If the SmartMessaging delay is too short, the SmartMessaging configuration data does not reach the terminal before the new connection is started. In that case, the connection to terminal fails because there is no bearer configured to the target terminal.

Default terminal bitrate and Connection timeout These parameters are used in CSD or GPRS bearer configurations. If you leave the Default terminal bitrate or Connection timeout parameters blank when setting the CSD or GPRS bearers, the default values for these parameters are used. The reason for this is that these values are required when configuring CSD or GPRS bearers.

The default value for Default terminal bitrate is ‘9600’ and for Connection timeout ‘120’ seconds. When the TerminalManagementConfig class is initiated, it contains the default values. The default values can be used, but sometimes these values may need to be modified for different environments.

Setting the TMC configuration // Creating the configuration object TerminalManagementConfig tmcConfig = new TerminalManagementConfig(); // Setting up parameters tmcConfig.setDelaySecAfterSmartMessaging(30); tmcConfig.setDefaultConnectionTimeoutSec(120); // Two minutes connection timeout tmcConfig.setDefaultBitrate(TerminalBearerCsd.BITRATE_9600); tmcConfig.setMinSendThreads(5); tmcConfig.setMaxSendThreads(10); // TMC configuration parameters ready

4.1.1 INITIALISING THE CORBA NAMING SERVICE The TMC must use the same CORBA Naming Service with the Gateway Access Software or the Corporate Edition.

8/31

Example: how to make an initial reference while starting the TMC application The Gateway Access Software runs on a different workstation from the TMC, and the Device Information Storage (DIS) that implements the User Information and Bearer Information interfaces is typically registered into the CORBA Naming Service that runs on the same host with the Gateway Access Software.

Setting the ORBInitRef.NameService property for Visibroker 4.5.1:

java -DORBInitRef=NameService=corbaloc::192.168.1.1:9999/NameService MyTmcApplication

Setting the ORBInitRef.NameService property for JacORB 1.3.0:

Java-DORBInitRef.NameService=corbaloc::192.168.1.1:9999/StandardNS/NameServer-POA/_root MyTmcApplication

In both cases, the CORBA Naming Service reference is used from host 192.168.1.1, and the Gateway Access Software uses a default port 9999 for the Naming Service.

You can also set a location for the Naming Service using System Properties.

Example: how to initialise the Naming Service location using Visibroker // Initializing Name Service location (tnameserv from Sun JDK 1.4.0 / Visibroker) java.util.Properties properties = System.getProperties(); properties.put("ORBInitRef", "NameService=corbaloc::192.168.1.1:9999/NameService");

4.1.2 INITIALISING THE CORBA OBJECT REQUEST BROKER You can initialize the TMC with an Object Request Broker (ORB) that has already been initialized in your own application. This procedure is optional.

Initialize the CORBA ORB and set the ORB reference into the TMC component using the setOrb(ORB) method.

9/31

Initialising the TMC with CORBA ORB // Creating tmc object TerminalManagement tmc = new TerminalManagement(); // Initializing ORB (ORB classes set in System properties) org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init((String[])null,null); // Delivering ORB reference into TMC tmc.setOrb(orb);

Note: If you do not initialise the CORBA ORB, the TMC tries to automatically initialise it based on the System Properties.

4.2 SETTING THE GATEWAY CONFIGURATION The Gateway configuration class can be found in the com.nokia.m2m.terminalmanagement.GatewayConfig package.

The Gateway configuration parameters are as follows:

• Gateway host

• Gateway port

• Domain name

• SmartMessaging CP name (set using the setSmartMessagingCpName method)

• User Information interface (set using the setUserDatabaseName method)

• Bearer Information interface (set using the setBearerDatabaseName method)

Gateway host and port These parameters define the location of the Gateway Access Software or Corporate Edition that is used to communicate with remote terminals.

Domain name This parameter defines the domain name of the user in the Gateway. The domain name is required only when using the Gateway Access Software to communicate with the Service Provider Edition.

The domain name is empty by default.

Note: If the Corporate Edition is used, the configuration value for the domain name must be left empty.

10/31

SmartMessaging CP name This parameter defines the Smart Messaging CP name that the domain is allowed to use from the Gateway. You must set this parameter if you need to use the SmartMessaging configuration option.

The SmartMessaging CP name is empty by default.

User Information interface (part of DIS) This parameter contains the name of the User Information interface implementation used by the Gateway in authentication. The same name is used to register the User Information interface implementation into the CORBA Naming Service.

The User Information interface name is empty by default.

Bearer Information interface (part of DIS) This parameter contains the name of the Bearer Information interface implementation used by the Gateway. This same name is used to register the Bearer Information interface implementation into the CORBA Naming Service. The Bearer Information interface is used by the Active NamingContext.

The Bearer Interface implementation can be used to retrieve information on bearers used in the Gateway Access Software or Corporate Edition.

This parameter is required.

Setting the Gateway configuration // Creating configuration object with parameters GatewayConfig gwConfig = new GatewayConfig("192.168.1.1",(short)6777, "DOMAIN_1"); // Setting up other configuration values gwConfig.setSmartMessagingCpName("SMARTMESSAGE-CP"); gwConfig.setUserDatabaseName("myUserInformation"); gwConfig.setBearerDatabaseName("myBearerInformation"); // Configuration set

4.3 INITIALIZING AND RUNNING THE TERMINAL MANAGEMENT COMPONENT To initialize and start the TMC:

1. Create the TMC object from the TerminalManagement class.

2. Set the listener and adjust the log level if necessary.

11/31

3. Configure the TMC object using the init(TerminalManagementConfig, GatewayConfig) method.

4. Start the TMC using the start() method.

Note: After you have started the TMC and are not using it anymore, you must close it with the close() method. This method contains the mechanisms for closing threads and connections.

Initialising and starting the TMC // Initializing TMC TerminalManagement tmc = new TerminalManagement(); tmc.setLogLevel(5); tmc.setTerminalManagementListener(tmcListener); // Corba ORB initiated earlier tmc.setOrb(orb); // Configurations initiated earlier tmc.init(tmcConfig,gwConfig); // Starting the TMC tmc.start(); // . . . // Performing terminal configuration with TMC // . . . // Closing TMC tmc.close();

4.3.1 LISTENING TO MESSAGES AND EVENTS To write messages and send events, the TMC uses the com.nokia.m2m.terminalmanagement.TerminalManagementListener interface.

The interface methods to be implemented are:

• configurationCompleted(TerminalConfiguration configuration) • logMessage(String sLogMessage)

The configurationCompleted() method is used when the configuration process for one terminal is completed. The TerminalConfiguration object contains the Terminal, TerminalBearer, and TerminalConfigurationResult objects.

The TerminalConfigurationResult object includes a list of TerminalConfigurationResultItem objects that contain information on the configuration process in different configuration phases. The Terminal and

12/31

TerminalBearer objects contain also those parameters that were initialized by the TMC.

Listening to configuration events from the TMC public void configurationCompleted(TerminalConfiguration configuration) { System.out.println("Configuration completed to terminal " + configuration.getTerminal().getTerminalId()); TerminalConfigurationResultItem[] resultItemArray = configuration.getConfigurationResult().getConfigurationResultItems(); // Printing the results for(int i=0;i<resultItemArray.length;i++) { System.out.println("- " + resultItemArray[i].getConfigurationPosition() + "\t" + resultItemArray[i].getDescription() + "\t" + resultItemArray[i].getTimeStamp().toString() ); } }

The logMessage() method is used to print messages generated by the TMC. The TMC log level defines the amount of messages received. If the TMC log level is set to ‘3’, the method receives log messages that are in level 0,1,2, 3, or 4.

The default log level is ‘0’.

Log level descriptions:

• 0 = Fatal Error

• 1 = Error

• 2 = Warning

• 3 = Note

• 4 = Debug

Listening to log messages from the TMC public void logMessage(String sLogMessage) { System.out.println("TMC Log: " + sLogMessage); }

13/31

4.4 TERMINAL CONFIGURATION

4.4.1 INITIALISING BEARERS The bearer information class can be found in the com.nokia.m2m.terminalmanagement.TerminalBearer package.

Each type of bearer is inherited from the TerminalBearer class.

Bearer types:

• CSD - TerminalBearerCsd

• GPRS - TerminalBearerGprs

• SMS - TerminalBearerSms

• USSD – TerminalBearerUssd

Bearer data:

• WTP port

• Bearer index

When you creating a bearer, you do not necessarily need to set any other parameters because the generated or default values can be used. However, you can configure these other parameter values if necessary.

WTP port This parameter defines the communication port number. The WTP port number must be unique for each bearer.

Bearer index This parameter defines the index used to store the chosen bearer in the target terminal. This parameter is optional. If the parameter is not set, it is generated automatically depending on the order of bearers in the bearer array. The possible index numbers in Nokia 30/31 GSM Connectivity Terminals range from 0 to 4.

You can set some optional values for CSD and GPRS bearers. Both bearers have a Connection timeout parameter. The CSD bearer also has a Default terminal bitrate parameter. If these values are not set, they are obtained from values initialised in the TerminalManagementConfig object.

14/31

Initialising bearers // Creating CSD bearer TerminalBearerCsd csdBearer = new TerminalBearerCsd(); csdBearer.setWtpPort(1); // Creating GPRS bearer TerminalBearerGprs gprsBearer = new TerminalBearerGprs(); gprsBearer.setWtpPort(2); // Creating SMS bearer TerminalBearerSms smsBearer = new TerminalBearerSms(); smsBearer.setWtpPort(3); // Creating USSD bearer TerminalBearerUssd ussdBearer = new TerminalBearerUssd(); ussdBearer.setWtpPort(4); // Creating array of bearers TerminalBearer[] bearerArray = { csdBearer, gprsBearer, smsBearer, ussdBearer }; // Using bearer array in configuration tmc.configure(terminalArray,bearerArray,configurationOptions);

Note: The TMC automatically collects other needed bearer information from the Gateway.

4.4.2 INITIALISING TERMINALS The Terminal information class can be found in the com.nokia.m2m.terminalmanagement.Terminalpackage.

Required values:

• Terminal ID

• Data MSISDN

• Voice MSISDN

Optional values:

• Local password

• Remote password

• Default bearer

• Connection bearer

• Connection timeout (GPRS/CSD)

15/31

If the optional parameters are left empty, the TMC generates them or uses the default values.

Terminal ID This parameter identifies the terminal in the Device Information Storage, and must be unique for each terminal in the same domain.

This parameter is required.

Note: If a terminal with an identical ID already exists in the same domain with Gateway Access Software, the existing terminal data is replaced with the new terminal data. The same applies also to the Corporate Edition where the domain concept does not exist (all terminals can be said to belong to the same domain).

Data MSISDN This parameter defines the data dial number for a terminal, and must be unique for each terminal. It is recommended to use an international number format for the Data MSISDN.

This parameter is required.

Voice MSISDN This parameter defines the voice/SMS dial number for a terminal, and must be unique for each terminal. In the Nokia M2M Platform, this number is mainly used for SMS communication, regardless of its name. It is recommended to use an international number format for the Voice MSISDN.

This parameter is required.

Local password This parameter defines the password used to authenticate a terminal when it is connecting to the Gateway.

This parameter is optional, and if left empty, it is generated automatically. The maximum password length is 15 characters.

Note: The Local password information is sent as plain text through the Gateway.

Remote password This parameter defines the password used to authenticate the Gateway, when it is connecting to a terminal.

This parameter is optional, and if left empty, it is generated automatically. The maximum password length is 15 characters.

16/31

Note: The Remote password information is sent as plain text through the Gateway.

Default bearer This parameter defines the default bearer for the Gateway and terminal when the user has not identified any bearer for communication.

Note: The default bearer needs to be configured first when using the SmartMessaging configuration option. If the default bearer has not been initialised, the TMC sets the first bearer in the array as the default bearer.

Connection bearer This parameter defines the bearer the TMC uses to connect to a terminal when the SmartMessaging option is not used. The Connection bearer option is used when the target terminal already contains bearers and the SmartMessaging option cannot be used.

Connection timeout This parameter defines the timeout for GPRS and CSD bearers. The value is shown in seconds.

This parameter is optional. If the parameter has not been set, the TMC uses the value initialised in the configuration options.

Creating a terminal object // Creating terminal object Terminal terminal = new Terminal("terminal1","+358*****567","+358*****321"); // Setting passwords (optional) terminal.setPasswordLocal("secret"); terminal.setPasswordRemote("secret"); terminal.setConnectionTimeout(120); // Two minutes timeout . . . // Using one terminal in configuration Terminal[] terminalArray = {terminal}; tmc.configure(terminalArray,bearerArray,configurationOptions);

4.4.3 INITIALISING TERMINAL CONFIGURATION OPTIONS You need to set the terminal configuration options before starting the configuration process.

The terminal configuration options class can be found in the com.nokia.m2m.terminalmanagement.TerminalConfigurationOptions package

17/31

The terminal configuration options are:

• Use SmartMessaging

• Test communication after configuration

• Maximum test communication trials

• Delay between test communication trials

• Maximum communication trials

• Delay between communication trials

• Maximum bearers in one terminal

• Connection bearer (used if a default or connection bearer has not been set for the terminal object)

Use SmartMessaging This parameter flag indicates whether the SmartMessaging configuration is used when setting the first bearer for the target terminal.

The default value for Use SmartMessaging is ‘true’.

Note: If the SmartMessaging flag is set to ‘false’, the target terminals should have at least one bearer installed. Also, a connection bearer must be initialised in the configuration options.

Test communication This parameter flag indicates whether the bearers configured to terminals are tested after the configuration. If this flag is set to ‘true’, all bearers in all terminals are tested.

The default value for Test communication is ‘false’.

Maximum test communication trials This parameter defines how many times the communication test is done at maximum if the test fails.

The default value for Maximum test communication trials is ‘2’.

Delay between test communication trials This parameter defines the gap between test retrials in seconds.

The default value for Delay between test communication trials is ‘2’.

18/31

Maximum communication trials This parameter defines the maximum number of communication efforts to a target terminal when using CORBA for configuration.

The default value for Maximum communication trials is ‘2’.

Delay between communication trials This parameter defines the gap between communication retrials in seconds.

The default value for Delay between communication trials is ‘2’.

Maximum bearers in one terminal This parameter defines the limit of bearer count in the target terminal.

The default value for Maximum bearers in one terminal is ‘5’.

Setting the terminal configuration options affects all terminals configured during one configuration session using the configure(Terminal[], TerminalBearer[], TerminalConfigurationOptions) method.

Initializing terminal configuration options // Initializing options TerminalConfigurationOptions options = new TerminalConfigurationOptions(); // Use SmartMessaging for the first bearer options.setSmartMessaging(true); // Test communication after configuration options.setTestCommunication(true); // Define connection bearer parameters (CSD using WTP port 3) options.setConnectionBearerData(TerminalBearer.TYPE_CSD,3); // Try communication max 4 times, wait 5 sec between trials options.setMaxCommunicationTrials(4); options.setCommunicationTrialDelaySec(5); // Test communication max three times when errors occurs, wait 5 sec between trials options.setMaxCommunicationTestTrials(3); options.setTestTrialDelaySec(5);

4.4.4 STARTING THE CONFIGURATION PROCESS Start the configuration process using the configure(Terminal[], TerminalBearer[], TerminalConfigurationOptions) method.

19/31

You need to set the following parameters:

• Terminal array

• Bearer array

• Configuration options

All bearers in the Bearer array are configured to all terminals in the terminal array. The Configuration options parameter affects all terminals that are configured.

Starting the configuration process // Starting configuration process tmc.configure(terminalArray,bearerArray,configurationOptions);

4.4.5 CLOSING THE TERMINAL MANAGEMENT COMPONENT Close the TMC with the close() method before shutting down your application. This method contains mechanisms for closing threads and connections used by TMC.

4.4.6 TERMINAL MANAGEMENT COMPONENT LOG The TMC writes a log through the TerminalManagementListener interface.

You can set the log level of the TMC using the setLogLevel(int level) method. The log level can range from 0 to 10. The greater the level number, the more detailed log messages are printed.

4.5 EXAMPLE APPLICATION USING THE TERMINAL MANAGEMENT COMPONENT APPLICATION PROGRAMMING INTERFACE This section introduces an example application that uses the TMC API. The application configures one terminal with three bearers.

The configuration information is:

• The Gateway Access Software is located in host ‘192.168.1.1’, port ‘6777’.

• The Gateway Access Software uses the domain name ‘DOMAIN1’ in the Service Provider Edition.

• DOMAIN1 uses a Connection Provider called ‘SMARTMESSAGE-CP’ to send Over-the-Air (OTA) configuration to terminals.

20/31

• The User Information interface name in the CORBA Naming Service used by the Gateway Access Software is ‘myUserInformation’ and the Bearer Information interface name is ‘myBearerInformation’.

Information for the terminal to be configured is:

• Terminal ID is ‘terminal1’

• Data MSISDN is ‘+358*****567’

• Voice MSISDN is ‘+358*****321’

Bearers to be configured into the target terminal are:

• SMS for WTP port 2

• GPRS for WTP port 3 using a Connection timeout of 3 minutes

• CSD for WTP port 4

Example application using the TMC API package com.nokia.m2m.terminalmanagement.sample; import com.nokia.m2m.terminalmanagement.*; /** * Very simple application using TMC API. * */ public class SampleTmcApp implements TerminalManagementListener { /** * SampleTmcApp constructor. */ public SampleTmcApp() { super(); } /** * Interface method implementation. */ public void configurationCompleted(TerminalConfiguration configuration) { System.out.println("Configuration completed to terminal " + configuration.getTerminal().getTerminalId()); TerminalConfigurationResultItem[] resultItemArray = configuration.getConfigurationResult().getConfigurationResultItems(); for(int i=0;i<resultItemArray.length;i++) { System.out.println("- " + resultItemArray[i].getConfigurationPosition() + "\t"

21/31

+ resultItemArray[i].getDescription() + "\t" + resultItemArray[i].getTimeStamp().toString() ); } } /** * Interface method implemented. * */ public void logMessage(String sLogMessage) { System.out.println("TMC Log: " + sLogMessage); } /** * Starts the application. * * Configures one terminal with some bearers * * @param args an array of command-line arguments */ public static void main(java.lang.String[] args) { try { System.out.println("Simple TMC application"); // Create an instance of tmc TerminalManagement tmc = new TerminalManagement(); // Create TMC configuration TerminalManagementConfig tmcConfig = new TerminalManagementConfig(); tmcConfig.setDelaySecAfterSmartMessaging(20); GatewayConfig gwConfig = new GatewayConfig("192.168.1.1",(short)6777, "DOMAIN1"); gwConfig.setSmartMessagingCpName("SMARTMESSAGE-CP"); gwConfig.setUserDatabaseName("myUserInformation"); gwConfig.setBearerDatabaseName("myBearerInformation"); // Initialize TMC tmc.setLogLevel(5); tmc.setTerminalManagementListener(new SampleTmcApp()); tmc.init(tmcConfig,gwConfig); // Start the TMC tmc.start(); // Creating terminal Terminal terminal = new Terminal("terminal1","+358*****567","+358*****321"); Terminal[] terminalArray = {terminal}; // Creating bearers TerminalBearerCsd bearerCsd = new TerminalBearerCsd(); bearerCsd.setWtpPort(4); TerminalBearerGprs bearerGprs = new TerminalBearerGprs(); bearerGprs.setWtpPort(3); bearerGprs.setConnectionTimeout(180); // 3 minutes timeout TerminalBearerSms bearerSms = new TerminalBearerSms(); bearerSms.setWtpPort(2); TerminalBearer[] bearerArray = {bearerCsd, bearerGprs, bearerSms}; // Creating configuration options TerminalConfigurationOptions configurationOptions =

22/31

new TerminalConfigurationOptions(); // Test communication after configuration configurationOptions.setTestCommunication(true); // Start configuration tmc.configure(terminalArray,bearerArray,configurationOptions); // Close the TMC component tmc.close(); } catch(Exception e) { e.printStackTrace(); } } }

Note: For more information on using the TMC API, refer also to the TMC reference implementation source code.

23/31

5. USING THE TERMINAL MANAGEMENT COMPONENT USER INTERFACE

This chapter describes how to use the TMC UI application that is included in the TMC package.

5.1 USER INTERFACE DESCRIPTION When you start the TMC UI application and have not entered any initial properties to the tmcui.properties file, the Terminal Management Component window presented in Figure 3 opens without any added information.

If you have entered some initial properties to the tmcui.properties file before starting the application, these properties are read from the file on starting the application.

Figure 3. Terminal Management Component User Interface

To view and alter the property settings, choose the Settings command on the Window menu. If you need to change the TMC or Gateway settings, you must do that before clicking the Configure button on the TMC UI (see Figure 3).

5.2 GENERAL USE With the TMC UI, you can define the terminal and bearer properties and configure terminals with the set properties. It is not possible to alter or remove information from already configured terminals using the TMC UI. If the terminals

24/31

have been configured incorrectly, the bearers can be removed only with the Nokia 30 Configurator application.

If you want to use a default bearer, it is best to set up the terminal bearers first. When you have set the bearers, you can select them as default bearers for different terminals.

5.3 BEARER MANAGEMENT

Note: Adding or removing bearers affects only the bearer information in the TMC UI.

5.3.1 ADDING BEARERS You can add bearers using the controls on the Bearer Information pane. All information is mandatory. When you have set the bearer information, click the Add button. The added bearer properties appear in the bearer table.

Clicking the Add button adds the bearers also to the Default bearer combo box, which is located on the Terminal Information pane. A given bearer can then be selected as the default bearer for one or more terminals.

If one or more text fields in the Bearer Information pane are left empty, the TMC UI shows an Error Description window, and the adding procedure is stopped.

You must use integers in the Index and WTP port text fields. If you enter an incorrect value, the TMC UI shows an Error Description window, and the adding procedure is stopped.

5.3.2 REMOVING BEARERS You can remove bearers one by one or all at once. If the bearer you are about to remove is assigned as the default bearer for one or more terminals, you cannot remove it until the given terminal has been removed or the default bearer of that terminal is changed. This restriction applies also when trying to remove all bearers at once.

Remove a single bearer by selecting it from the bearer table and clicking the Remove button. Remove all bearers at once by clicking the Clear button.

25/31

5.4 TERMINAL MANAGEMENT

Note: Adding or removing terminals affects only the terminal information in the TMC UI.

5.4.1 ADDING TERMINALS You can add terminals using the controls on the Terminal Information pane. All information is mandatory. When you have set the terminal information, click the Add button. The added terminal properties appear in the terminal table.

Note: If the target terminal already has some bearers installed, you must select one of these bearers from the Connection Method pane. In that case, the SmartMessaging feature is not functional.

If you have not selected a default bearer, the TMC decides which bearer will be used as the default bearer for a given terminal.

If one or more text fields in the Terminal Information pane are left empty, the TMC UI shows an Error Description window, and the adding procedure is stopped.

5.4.2 REMOVING TERMINALS You can remove terminals one by one or all at once.

Remove a single terminal by selecting it from the terminal table and clicking the Remove button. Remove all terminals at once by clicking the Clear button.

5.5 TERMINAL MANAGEMENT COMPONENT CONFIGURATION

5.5.1 TERMINAL MANAGEMENT COMPONENT SETTINGS You can view the TMC properties by choosing the Settings command on the Window menu, and then clicking the TMC Settings tab (see Figure 4).

26/31

Figure 4. TMC Settings

The TMC Settings tab shows you the current TMC settings. If you need to change a property value, add a new value for a given property to the respective text field and click the Set button. Changes are made only to those properties that have a value entered to their text field.

5.5.2 GATEWAY SETTINGS You can view the Gateway properties by choosing the Settings command on the Window menu, and then clicking the Gateway Settings tab (see Figure 5).

27/31

Figure 5. Gateway Settings

The Gateway Settings tab shows you the current Gateway settings. If you need to change a property value, add a new value for a given property to the respective text field and click the Set button. Changes are made only to those properties that have a value entered to their text field.

5.5.3 MODIFYING THE TERMINAL MANAGEMENT COMPONENT USER INTERFACE PROPERTIES If you want to change the initial TMC UI properties, you need to edit the tmcui.properties file. This file can be found in the installation directory of the TMC application.

The initial properties are read during the application start-up. If you have made changes to the tmcui.properties file, these changes come into effect only after the TMC UI application is restarted.

Initial properties of the TMC configuration org.omg.CORBA.ORBClass=org.jacorb.orb.ORB org.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton #Gateway settings tmcui.gwhost=192.164.1.1 tmcui.gwport=6777 tmcui.gwdomain=domain1 tmcui.smartmessagingcp=SMARTMESSAGE-CP tmcui.userDBname= myUserInformation tmcui.bearerDBname=myBearerInformation

28/31

5.6 STARTING THE TERMINAL CONFIGURATION When you have set all the needed parameters required for the terminal configuration, click the Configure button on the Terminal Management Component window (see Figure 3).

The TMC now proceeds to configure the terminals you have added to the terminal table with the bearers you have added to the bearer table.

When the configuration process has been completed successfully for an individual terminal, a tick mark is displayed in the Conf status column on the respective terminal row (see Figure 3). If you click the mark, you receive additional information on the configuration process for that terminal in a secondary window (see Figure 6).

Figure 6. Configuration Result: OK

If an error occurred in the configuration process for an individual terminal, ‘Error’ is displayed in the Conf status column on the respective terminal row. If you click the ‘Error’ text, a secondary window is opened (see Figure 7) showing you where in the configuration phase the error took place.

29/31

Figure 7. Configuration Result: ERROR

If the configuration process was incomplete or not started, an empty box is displayed in the Conf status column.

5.7 TERMINAL MANAGEMENT COMPONENT USER INTERFACE LOG You can open the TMC UI log by choosing the Log command on the Window menu (see Figure 8). The log service is activated during the start-up of the UI application, and the log entries remain until the UI application is shut down or the log is cleared.

You can clear the log by choosing the Clear Log command on the Program menu.

30/31

31/31

Figure 8. Terminal Management Component User Interface log