Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Koneki/Simulators/OMA-DM/User Guide
Contents
- 1 Overview
- 2 Getting started
- 3 Concepts
- 4 Tasks
- 4.1 Simulate one connection by the client device to one OMA-DM server
- 4.2 Simulate FUMO (Firmware Update Management Object)
- 4.3 How to configure the OMA-DM server provided by Funambol
- 4.3.1 Prerequisites
- 4.3.2 Install the funambol Device Management server
- 4.3.3 Use the dm-server with its web interface
Overview
The OMA-DM simulator provides a way to simulate communications between a client living in the Eclipse workbench, and an OMA-DM server. The simulator supports a large part of the current OMA-DM Protocol version 1.2. In a nutshell, the OMA-DM protocol allows a client to synchronize the contents of a data tree with a server. More details about the OMA-DM protocol are available in the Concepts section.
Getting started
Create a new OMA-DM simulator
Step 1: Select wizard page
To create a new OMA-DM simulator you just have to select “OMA DM Simulator” in “File” → “New” → “Other” → “OMA Dm Simulator”.
Click on the "Next" button.
Step 2: OMA DM simulation file page
Chose the location and the name of the future simulator file.
Click on the "Next" button.
Step 3: Device configuration page
This page allows to fill some basic informations in the OMA-DM tree.
Explications
- Server URI: the URI of the OMA-DM server you want to use.
- Server login: the user name for the authentication on the OMA-DM server
- Server password: the user password for the authentication on the OMA-DM server
- Device ID: the id of the device which is simulate
Click on the "Next" button.
Step 4: Device informations page
In this page you can fill basic information about the device. Whereas other informations, the Device Id must not be empty.
Explications
- Device id: it's the same ID than the device ID in the previous step
- Manufacturer Name: the manufacturer's name of the device
- Model Name: the model's name of the device
- Language: the current language of the application
Click on the "Next" button.
Step 5: Device details page
In this page you can fill other information about the device.
Explications
- Device Type: The device ID type. The default type is "FREE". Two others type are recognized; "IMEI" and "MAC". All other words will be translate in "FREE"
- OEM Name: the OEM's name of the device
- Firmware Revision: the number of the current firmware version
- Software Revision: the number of the current software version
- Hardware Revision: the number of the current hardware version
Click on the "Finish" button.
Step 6: Use the simulator
Now a new OMA-DM simulator has been created where you indicated on the Step 2: OMA DM simulation file page. So, you just have to use it!
Concepts
Description of the OMA-DM protocol
The OMA-DM Protocol is based on the HTTP protocol. XML messages are exchanged between the client and the OMA-DM server through HTTP requests. The complete specification of the OMA-DM protocol and of standard tree nodes is available here: www.openmobilealliance.org/Technical/current_releases.aspx
Data representation
Data are represent by a tree nodes. This tree is store twice. Once on the client device and once on the OMA-DM server. The synchronization of these two trees is made during the exchanges between the client device and the server.
There are two types of nodes in the tree: nodes and leaf.
Each node and leaf contains four informations
- Name: the name of the node
- Data: the data of the node
- Type: the type of the node (MIME type for leaf node and empty or Management Object Identifier for interior node)
- Format: the standard OMA DM format of the node
For the leaf type, all informations have to be fill. For the node type, Type an Data information are empty. Name is the name of the node. The value of Format is "node".
The OMA-DM tree must contain some specific nodes and leafs. Some other nodes are just optional. The complete description of the basic tree is available in the OMA-DM specifications. After the specific nodes, the tree can contain other nodes and leafs which are specific for the client device.
OMA-DM commands
The protocol provides some commands which could be send by the server and execute on the client device. Below is the list of commands which are supported by the simulator :
- Add: insert a new node in the tree
- Delete: delete a node in the tree
- Get: ask the data of one node
- Replace: change the data of one node
- Copy: copy the value of one node to another
- Exec: Invokes an executable on the client device. It's usually used for FUMO (Firmware Update Managed Object).
The result of the execution of one command is send by the client device to the OMA-DM server. Once, the server receive the result, it can choose to send a new command to the client device.
Tasks
Once you have created a new OMA-DM simulator, you can simulate some connections to one OMA-DM server.
Simulate one connection by the client device to one OMA-DM server
The simulator is divided in three tags: Configuration, Simulation and Dashboard.
The Configuration tag
The first tag is Configuration. It allows to fill basic informations to identify the OMA-DM server and authenticate the client device on the server. These informations are similar with the Device Configuration page of the wizard. (See Step 3: Device configuration page in the Getting Started section to have more informations.)
The Simulation tag: three sections
Simulation tag is divided in three sections: Device tree, Node properties and Node management.
Section 1: Device tree
This section allows to edit the OMA-DM tree. By default, the simulator create one basic tree with non optional nodes. This section is the most important section of this tag. With this section, you can insert or delete nodes and leafs directly into all the tree.
You can recognize into the tree the informations that you filled in the Configuration tag. Below is the correspondence between information in the Configuration tag and leafs into the OMA-DM tree:
- Server URI: ./DMAcc/AppAddr/Default/Addr
- Server login: ./DMAcc/AppAuth/Default/AuthName
- Server password: ./DMAcc/AppAuth/Default/AuthSecret
- Device ID: ./DevInfo/DevId
The node "./DMAcc/AppAuth/Default" and "./DMAcc/AppAddr/Default" are optional nodes. The leafs "AuthName", "Addr" and "AuthSeret" can be stored anywhere in the node "./DMAcc/AppAuth". You can edit all informations about nodes and leafs in the next section : Node properties. If you change data of nodes which are listed above, the new values will be directly updated in the Configuration tag.
Section 2: Node properties
In this section you can change all informations about the current node or leaf which is selected in the Device tree. You can edit all informations which are described in the Data representation section.
Section 3: Node management
This section allows you to choose how execute all OMA-DM commands. There are four modes to execute one command. By default the root of the tree has all commands set in automatic mode. And all other nodes have commands set in inherit mode. There are two other modes: manual and constant. Below is the explication of all management modes:
- Automatic mode: the simulator perform the command like a real device
- Constant mode: the simulator return the status code selected
- Inherited mode: the node management of the parent node is used
- Manual mode: the simulator demand to the user the status code which must be returned
The manual mode is very interesting, the user can change the result of any command directly during one simulation.
For example, during one Replace command, you can refuse to set the value of the node.
You can also change the value of one node during one Get command.
One last example of the command management is available in this section. Here, the command management is use during one Exec command with FUMO.
The Dashboard tag: three other sections
The Dashboard tag is also divided in three sections: Device tree, Node properties and session management.
The dashboard with the Command view.
The dashboard with the message view.
Section 1: Device tree
This section is similar with the tree section in the Simulation tag. But here, you just can to select one node. You can't edit the tree.
Section 2: Node properties
This section is similar with the properties section in the Simulation tag. But, here, you just can edit Data information of the selected node. You can't edit other information.
Section 3: Session management: two views
This section is the most important section of this tag. With this section, you can create a new connection between the simulator and one OMA-DM server. When you click on the connect button the simulator create a connection. Then, the simulator and the OMA-DM server will exchange xml messages through HTTP requests. During these exchanges, if the OMA-DM server have to execute some commands, it will send instructions on simulator. Then, the simulator will execute each instructions. The execution of instructions depends on the node management which is associated with the concerned node.
Section 3.1: Command view
In this view, you can see an abstract of all commands which have been executed.
Section 3.2: Message view
In this view, you can see the details of all OMA-DM messages wich are exchange between the simulator and the server.
Simulate FUMO (Firmware Update Management Object)
This section describes all steps to simulate one firmware update with the simulator.
Step 1: Prepare the node management
If it is the first FUMO for your simulated device, this node management is recommended for the root node.
And for other nodes:
Step 2: Launch the simulation
Now click on the connect button for receive the FUMO. Perform the manual get and replace are automatically performed. At one point, the simulator demand you if you want perform a FUMO on the exec node. If you want select "Yes".
Now a popop appear and demand you to select FUMO result code and if you choose "Successfull" the new version of the firmware version.
When you click on "OK" the FUMO work flow end. Moreover, you can put management commands of the root node in "automatic" except "exec".
Like all commands, one notification of the exec command is show in the Command view.
How to configure the OMA-DM server provided by Funambol
This section explains how install the OMA-DM server provide by Funambol. This server is called dm-server. The document also explain how use the web interface of the dm-server and where data are saved. To finish, the document show how interact the OMA-DM simulator with the dm-server.
Prerequisites
This tutorial has been realized with
- Ubuntu version 11.10
- Funambol Device Management server version 3.6
- JDBC 3 version 9.1-901
- JBoss version 5.1.0
- PostgreSQL version 9.1.2
Install the funambol Device Management server
In this part, I will explain how install Funambol dm-server with postgreSQL database.I suppose PostgreSQL is already installed on your machine.
Step 1: Download requiered programs
Funambol Device Management server
The dm-server is available at this address: http://sourceforge.net/projects/funambol/files/dm-server/
JBoss
JBoss is available at this address: http://www.jboss.org/jbossas/downloads/
Warning: Funambol dm-server only works with Jboss 5.1! With latest versions of Jboss, the dm-server doesn't work! Indeed, the latest version of Jboss has a new architecture and Funambol dm-server doesn't support it.
JDBC driver for PostgreSQL
The JDBC driver is available at this address: http://jdbc.postgresql.org/download.html
Step 2: Extract archives
I used this architecture for the tutorial:
- /opt/Funambol/dm-server -> the device management server
- /opt/Funambol/postgresql.jar -> the jdbc driver
- /opt/Funambol/jboss -> the jboss server
Extract downloaded archive in the good pah.
Step 3: Configure PostgreSQL database
- Create a new PostgreSQL user with these parameters: username = "funambol", password = "funambol".
- Create a new database called "funambol".
Of course, all these parameters are settable.
- Step 6: Set your environment variable
- J2EE_HOME points to the top directory of Jboss server: /opt/Funambol/jboss
- JAVA_HOME points to the top directory of your JDK
- JBOSS_CLASSPATH points to the JDBC driver for PostgreSQL: /opt/Funambol/postgresql.jar
Warning: JBOSS_CLASSPATH variable may already exists. So, I suggest you to use this command: export JBOSS_CLASSPATH=JBOSS_CLASSPATH":/opt/Funambol/postgresql.jar"
The JBOSS_CLASSPATH variable is used by dm-server during its execution. If this variable is not set, you will not be able to correctly use the server.
Step 4: Edit the file /opt/Funambol/dm-server/install.properties
This file is use to configure the installation of the dm-server. Some parameters have to be set.
- Set the parameter jdbc.user with the name of the user of PostgreSQL. In this document the password is “funambol”
- Set the parameter jdbc.password with the password of the user of PostgreSQL. In this document the password is “funambol”
- Replace this line: “jdbc.classpath=/opt/postgresql/share/java/postgresql.jar” by this line : “jdbc.classpath=/opt/Funambol/postgresql.jar”
- You can set the line "server-name=http://localhost:8080/funambol/dm" with another ip address. It's the address which is use by the dm-server to receive OMA-DM messages. (The default value works to only use the server with your machine.)
Step 5: Install the dm-server
To install the dm-server you just need 2 commands:
- cd /opt/Funambol/dm-server/
- sh ./bin/install.sh jboss5
The program will offer you to recreate the postges database. Accept, and choose 'y'. If it's the first time you run the script, some errors will appear. It's not a problem. It just means the program tried to delete some sql tables which doesn't exist...
If everything is ok, the last message should be: “BUILD SUCCESSFUL”. Then, you are ready to run the dm-server.
Step 6: Run the dm-server
To run the dm-server you just need 2 commands:
cd /opt/Funambol/dm-server/
sh ./bin/start.sh
After a few seconds, you should have one message which inform that the server is started.
Use the dm-server with its web interface
Create one new device on the dm-server
To test the dm-server, go on this page : http://localhost:8080/dmdemo/. You should see one page which looks like this :
The address of the web interface is not settable. It's not the same address than the name-server parameter available in the install.properties file.
Then, click on “Add New device”. Choose one device Id. In this document I choose “MyID” and then, click on “Add”. If everything all right, you should have one message which inform you the device is correctly created. Now you have one new device store on the server which is identify by its ID : “MyID”.
Now you can go on the LogIn page and insert the ID of your new device. In this example, it's MyID. Once you’re logged in, you can choose some OMA-DM command which will be executed on the client device.
Add one new OMA-DM command to one device
Once you are logged, you can choose an operation and add it in the operation list.
From this page, you can chose three types of operations
- Get device details: send one Get command to many important nodes
- Tree dicovery: this operation offer you to discover all or a part of the device's OMA-DM tree.
- Custom operation: with this operation you can mainly send the commands Get, Add, Replace or Delete to one specific node