Difference between revisions of "Koneki/Simulators/OMA-DM/User Guide"

From Eclipsepedia

Jump to: navigation, search
m (Access to the database of dm-server)
m (OMA-DM commands)
(21 intermediate revisions by 3 users not shown)
Line 11: Line 11:
 
===== Step 1: Select wizard page  =====
 
===== 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”.  
+
To create a new OMA-DM simulator you just have to select “OMA DM Simulator” in “File” → “New” → “Other” → “OMA Dm Simulator”.
 +
 
 +
<u>'''Warning:'''</u> the new OMA-DM simulator have to be into a project ("New" → "Project" → "General") , else, it doesn't work.
  
 
[[Image:Wizard_page_1.png|center]]
 
[[Image:Wizard_page_1.png|center]]
Line 19: Line 21:
 
===== Step 2: OMA DM simulation file page  =====
 
===== Step 2: OMA DM simulation file page  =====
  
Chose the location and the name of the future simulator file.  
+
Choose the location and the name of the future simulator file.  
  
 
[[Image:Wizard page 2.png|center]]  
 
[[Image:Wizard page 2.png|center]]  
Line 37: Line 39:
  
 
[[Image:Wizard page 3.png|center]]  
 
[[Image:Wizard page 3.png|center]]  
 +
 +
<u>'''Warning:'''</u> The simulator just supports the basic authentication. It doesn't yet support the auth-md5 authentication.
  
 
Click on the "Next" button.
 
Click on the "Next" button.
Line 79: Line 83:
 
===== Data representation  =====
 
===== Data representation  =====
  
The device's data are represented 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.  
+
The device's data are represented by a tree nodes. This tree is stored 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.  
 
There are two types of nodes in the tree: nodes and leaf.  
Line 97: Line 101:
 
===== OMA-DM commands  =====
 
===== OMA-DM commands  =====
  
The protocol provides some commands which could be send by the server and executed on the client device. Below is the list of commands which are supported by the simulator:  
+
The protocol provides some commands which could be sent by the server and executed on the client device. Below is the list of commands which are supported by the simulator:  
  
 
* Add: insert a new node in the tree  
 
* Add: insert a new node in the tree  
Line 114: Line 118:
 
== Simulate one connection by the client device 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. These tags allow you to configure the simulator before to run connections on the OMA-DM server. The first and the second tag offer you to configure the simulator. The last tag is use to run connections to one OMA-DM server.
+
The simulator is divided in three tags: Configuration, Simulation and Dashboard. These tags allow you to configure the simulator before to run connections on the OMA-DM server. The two first tabs offer you a way to configure the simulator. The last tab is use to run connections to one OMA-DM server.
  
===== The Configuration tag =====
+
===== The Configuration tab =====
  
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 [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#Step_3:_Device_configuration_page Device Configuration page of the wizard].
+
The first tab 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 [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#Step_3:_Device_configuration_page Device Configuration page of the wizard].
  
 
[[Image:Configuration OMA-DM tag.png|center]]
 
[[Image:Configuration OMA-DM tag.png|center]]
Line 124: Line 128:
 
==== The Device Management Tree tag: three sections  ====
 
==== The Device Management Tree tag: three sections  ====
  
Device Management Tree tag is divided in three sections: Device tree, Node properties and Node management.  
+
Device Management Tree tab is divided in three sections: Device tree, Node properties and Node management.  
  
 
[[Image:DeviceManagement OMA-DM tag.png|center]]  
 
[[Image:DeviceManagement OMA-DM tag.png|center]]  
Line 132: Line 136:
 
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. Delete non optional nodes is forbidden by the editor.
 
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. Delete non optional nodes is forbidden by the editor.
  
You can recognize into the tree the informations that you filled in the [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#The_Configuration_tag Configuration tag]. Below is the correspondence between information in the Configuration tag and leafs into the OMA-DM tree:  
+
You can recognize into the tree the informations that you filled in the [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#The_Configuration_tag Configuration tag]. Below is the correspondence between information in the Configuration tab and leafs into the OMA-DM tree:  
  
 
* Server URI: ./DMAcc/AppAddr/Default/Addr  
 
* Server URI: ./DMAcc/AppAddr/Default/Addr  
Line 149: Line 153:
 
===== Section 3: Node management  =====
 
===== 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:
+
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  
+
*Automatic mode: the simulator perform the command like a real device  
* Constant mode: the simulator return the status code selected  
+
*Constant mode: the simulator return the status code selected  
* Inherited mode: the node management of the parent node is used  
+
*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
+
*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 the simulation.  
+
The manual mode is very interesting. The user can change the result of any command directly during the simulation. For example, during one Replace command, you can refuse to set the value of the node.  
For example, during one Replace command, you can refuse to set the value of the node.  
+
  
 
[[Image:Manual Replace OMA-DM Command.png|center]]  
 
[[Image:Manual Replace OMA-DM Command.png|center]]  
Line 165: Line 168:
 
[[Image:Manual Get OMA-DM Command.png|center]]  
 
[[Image:Manual Get OMA-DM Command.png|center]]  
  
One last example of the command management is available in [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#Simulate_FUMO_.28Firmware_Update_Management_Object.29 this section]. Here, the command management is use during one Exec command with FUMO.
+
One last example of the command management is available in [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#Simulate_FUMO_.28Firmware_Update_Management_Object.29 the FUMO section]. Here, the command management is use during one Exec command with FUMO.
  
 
==== The Dashboard tag: three other sections  ====
 
==== The Dashboard tag: three other sections  ====
Line 230: Line 233:
  
 
This section explains how install the OMA-DM server provided by Funambol. This server is called dm-server. The document also explains how use the web interface of the dm-server and where data are stored. To finish, the document shows how interact the OMA-DM simulator with the dm-server.  
 
This section explains how install the OMA-DM server provided by Funambol. This server is called dm-server. The document also explains how use the web interface of the dm-server and where data are stored. To finish, the document shows how interact the OMA-DM simulator with the dm-server.  
The official documentation about Funambol's products is available at this address: [https://www.forge.funambol.org/download/documentation.html https://www.forge.funambol.org/download/documentation.html]. All versions of the source code and documentations about Funambol are available at this address: [http://download.forge.objectweb.org/sync4j/ http://download.forge.objectweb.org/sync4j/]
+
 
 +
The official documentation about Funambol's products is available at this address: [https://www.forge.funambol.org/download/documentation.html www.forge.funambol.org/download/documentation].  
 +
 
 +
All versions of the source code and documentations about Funambol are available at this address: [http://download.forge.objectweb.org/sync4j/ download.forge.objectweb.org/sync4j]  
  
 
=== Prerequisites  ===
 
=== Prerequisites  ===
Line 236: Line 242:
 
This tutorial has been realized with  
 
This tutorial has been realized with  
  
* Ubuntu version 11.10
+
*Ubuntu version 11.10  
* Funambol Device Management server version 3.6  
+
*Funambol Device Management server version 3.6  
* JDBC 3 version 9.1-901  
+
*JDBC 3 version 9.1-901  
* JBoss version 5.1.0  
+
*JBoss version 5.1.0  
* PostgreSQL version 9.1.2
+
*PostgreSQL version 9.1.2
  
 
=== Install the Funambol Device Management server  ===
 
=== Install the Funambol Device Management server  ===
  
This section explains how install Funambol dm-server with PostgreSQL database. It supposes PostgreSQL is already installed on your machine.
+
This section explains how install Funambol dm-server with PostgreSQL database. It supposes PostgreSQL is already installed on your machine.  
  
 
===== Step 1: Download required programs  =====
 
===== Step 1: Download required programs  =====
Line 250: Line 256:
 
====== Funambol Device Management server  ======
 
====== Funambol Device Management server  ======
  
The dm-server is available at this address: [http://sourceforge.net/projects/funambol/files/dm-server/v36/ http://sourceforge.net/projects/funambol/files/dm-server/]
+
The dm-server is available at this address: [http://sourceforge.net/projects/funambol/files/dm-server/v36/ sourceforge.net/projects/funambol/files/dm-server]  
  
====== JBoss ======
+
====== JBoss ======
  
JBoss is available at this address: [http://www.jboss.org/jbossas/downloads/ http://www.jboss.org/jbossas/downloads/]<br>  
+
JBoss is available at this address: [http://www.jboss.org/jbossas/downloads/ www.jboss.org/jbossas/downloads]<br>  
  
<u>Warning:</u> 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.
+
<u>'''Warning:'''</u> 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 ======
+
====== JDBC driver for PostgreSQL ======
  
The JDBC driver is available at this address: [http://jdbc.postgresql.org/download.html http://jdbc.postgresql.org/download.html]
+
The JDBC driver is available at this address: [http://jdbc.postgresql.org/download.html jdbc.postgresql.org/download]  
  
===== Step 2: Extract archives =====
+
===== Step 2: Extract archives =====
  
The architecture which has been used for this document looks like this:
+
The architecture which has been used for this document looks like this:  
  
* /opt/Funambol/dm-server -> the device management server  
+
*/opt/Funambol/dm-server the device management server  
* /opt/Funambol/postgresql.jar -> the JDBC driver  
+
*/opt/Funambol/postgresql.jar the JDBC driver  
* /opt/Funambol/jboss -> the jboss server
+
*/opt/Funambol/jboss the jboss server
  
Extract downloaded archive in the good path.
+
Extract downloaded archive in the good path.  
  
===== Step 3: Configure PostgreSQL database =====
+
===== Step 3: Configure PostgreSQL database =====
  
* Create a new PostgreSQL user with these parameters: username = <i>"funambol"</i>, password = <i>"funambol"</i>
+
*Create a new PostgreSQL user with these parameters: username = ''"funambol"'', password = ''"funambol"''
* Create a new database called <i>"funambol"</i>
+
*Create a new database called ''"funambol"''
  
Of course, all these parameters are settable.
+
Of course, all these parameters are settable.  
  
===== Step 4: Set your environment variable =====
+
===== Step 4: 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
+
  
<u>Warning:</u> JBOSS_CLASSPATH variable may already exists. To don't break your system, a good solution is to use this command: <code>export JBOSS_CLASSPATH=$JBOSS_CLASSPATH":/opt/Funambol/postgresql.jar</code>.
+
*J2EE_HOME points to the top directory of Jboss server: /opt/Funambol/jboss
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.
+
*JAVA_HOME points to the top directory of your JDK
 +
*JBOSS_CLASSPATH points to the JDBC driver for PostgreSQL: /opt/Funambol/postgresql.jar
  
===== Step 5: Edit the file /opt/Funambol/dm-server/install.properties =====
+
<u>'''Warning:'''</u> JBOSS_CLASSPATH variable may already exists. To don't break your system, a good solution is to use this command: <code>export JBOSS_CLASSPATH=$JBOSS_CLASSPATH":/opt/Funambol/postgresql.jar</code>. 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.
  
This file is use to configure the installation of the dm-server. Some parameters have to be set.
+
===== Step 5: Edit the file /opt/Funambol/dm-server/install.properties  =====
  
* Set the parameter jdbc.user with the name of the user of PostgreSQL. In this document the password is <i>“funambol”</i>
+
This file is use to configure the installation of the dm-server. Some parameters have to be set.  
* Set the parameter jdbc.password with the password of the user of PostgreSQL. In this document the password is <i>“funambol”</i>
+
* Replace this line: <i>“jdbc.classpath=/opt/postgresql/share/java/postgresql.jar”</i> by this line: <i>“jdbc.classpath=/opt/Funambol/postgresql.jar”</i>. This line point to the path of the JDBC driver.
+
* 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 local machine.)
+
  
===== Step 6: Install the dm-server =====
+
*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”''. This line point to the path of the JDBC driver.
 +
*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 local machine.)
  
To install the dm-server you just need 2 commands:
+
===== Step 6: Install the dm-server =====
  
* <code>cd /opt/Funambol/dm-server/</code>
+
To install the dm-server you just need 2 commands:
* <code>sh ./bin/install.sh jboss5</code>
+
  
<u>Warning</u>: jboss5 is not an optional parameter. Without it, the installation doesn't work !
+
*<code>cd /opt/Funambol/dm-server/</code>  
 +
*<code>sh ./bin/install.sh jboss5</code>
  
The program will offer you to recreate the PostgreSQL database. Accept, and choose 'y'. If it's the first time you run the script, some errors will appear. It's not a bug. It just means the program tried to delete some SQL tables which doesn't exist yet...
+
<u>'''Warning'''</u>: jboss5 is not an optional parameter. Without it, the installation doesn't work&nbsp;!
If everything is OK, the last message should be: <cite>“BUILD SUCCESSFUL”</cite>. Then, you are ready to run the dm-server.
+
  
===== Step 7: Run the dm-server =====
+
The program will offer you to recreate the PostgreSQL database. Accept, and choose 'y'. If it's the first time you run the script, some errors will appear. It's not a bug. It just means the program tried to delete some SQL tables which doesn't exist yet... If everything is OK, the last message should be: <cite>“BUILD SUCCESSFUL”</cite>. Then, you are ready to run the dm-server.
 +
 
 +
===== Step 7: Run the dm-server =====
  
 
To run the dm-server you just need 2 commands:  
 
To run the dm-server you just need 2 commands:  
  
* <code>cd /opt/Funambol/dm-server/</code>  
+
*<code>cd /opt/Funambol/dm-server/</code>  
* <code>sh ./bin/start.sh</code>
+
*<code>sh ./bin/start.sh</code>
  
After a few seconds, you should have one message which inform that the server is started.
+
After a few seconds, you should have one message which inform that the server is started.  
  
If you want to change the server name parameter setted in the install.properties file during the [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#Step_5:_Edit_the_file_.2Fopt.2FFunambol.2Fdm-server.2Finstall.properties Step 5], you don't have to re-install the dm-server. A good way consists to edit the file <i>"/opt/Funambol/dm-server/config/Funambol.properties"</i>. The first line (<i>server.uri</i>) set the dm-server name.
+
If you want to change the server name parameter setted in the install.properties file during the [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#Step_5:_Edit_the_file_.2Fopt.2FFunambol.2Fdm-server.2Finstall.properties Step 5: Edit the file /opt/Funambol/dm-server/install.properties ], you don't have to re-install the dm-server. A good way consists to edit the file ''"/opt/Funambol/dm-server/config/Funambol.properties"''. The first line (''server.uri'') set the dm-server name.  
  
=== Use the web interface of the dm-server ===
+
=== Use the web interface of the dm-server ===
  
==== Create one new device on the dm-server ====
+
==== 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:  
+
To test the dm-server, go on this page: http://localhost:8080/dmdemo/. You should see one page which looks like this:  
  
 
[[Image:OMA-DM Funambol Login.png|center]]  
 
[[Image:OMA-DM Funambol Login.png|center]]  
  
<u>Warning</u>: 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. The server name parameter is only use for the OMA-DM protocol, not for the web interface.
+
<u>'''Warning:'''</u> 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. The server name parameter is only use for the OMA-DM protocol, not for the web interface.  
  
Click on <i>“Add New device”</i> and choose one device ID. "MyID” has been choose for this document. Once you chose your device ID, 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 your dm-server which is identify by its ID: “MyID”.  
+
Click on ''“Add New device”'' and choose one device ID. "MyID” has been choose for this document. Once you chose your device ID, 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 your dm-server which is identify by its ID: “MyID”.  
  
 
[[Image:OMA-DM Funambol Device Created.png|center]]  
 
[[Image:OMA-DM Funambol Device Created.png|center]]  
Line 343: Line 348:
 
From this page, you can chose three types of operations  
 
From this page, you can chose three types of operations  
  
*Get device details: send one Get command to many important nodes (./DevInfo/Man, ./DevInfo/Mod, ./DevDetail/DevTyp, ./DevDetail/OEM, ./DevInfo/Lang, ./DevDetail/FwV, ./DevDetail/SwV, ./DevDetail/HwV, ./DevInfo/DmV)
+
*Get device details: send one Get command to many important nodes (./DevInfo/Man, ./DevInfo/Mod, ./DevDetail/DevTyp, ./DevDetail/OEM, ./DevInfo/Lang, ./DevDetail/FwV, ./DevDetail/SwV, ./DevDetail/HwV, ./DevInfo/DmV)  
*Tree discovery: discover all or a part of the device's OMA-DM tree by sending Get commands to which node you want
+
*Tree discovery: discover all or a part of the device's OMA-DM tree by sending Get commands to which node you want  
 
*Custom operation: create a collection of commands (Get, Add, Replace or Delete) on which node you want
 
*Custom operation: create a collection of commands (Get, Add, Replace or Delete) on which node you want
  
Line 365: Line 370:
 
[[Image:OMA-DM Funambol End Command.png|center]]  
 
[[Image:OMA-DM Funambol End Command.png|center]]  
  
Now, you can launch new operations.
+
Now, you can launch new operations.  
  
=== Use the dm-server with the OMA-DM simulator ===
+
=== Use the dm-server with the OMA-DM simulator ===
  
 
Using the OMA-DM simulator with the dm-server needs one specific configuration. In the Configuration tag, fill these informations:  
 
Using the OMA-DM simulator with the dm-server needs one specific configuration. In the Configuration tag, fill these informations:  
* Server URI = http://localhost:8080/funambol/dm
 
* Server Login = funambol
 
* Server Password = funambol
 
* Device ID = MyID
 
  
This parameters are those which have been fill in the [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#Step_4:_Edit_the_file_.2Fopt.2FFunambol.2Fdm-server.2Finstall.properties Step 4: Edit the file install.properties].
+
*Server URI = http://localhost:8080/funambol/dm
The server URI is different than the URI of the web page of the server. Indeed, the web interface is available on this URI: http://localhost:8080/dmdemo/ whereas the OMA-DM server is available on this page: http://localhost:8080/funambol/dm. The server Login and password are used to identify the user on the OMA-DM server. It's the user name and the password for the PostgreSQL account. The device ID is the ID which was use to create a new device on the dm-server.
+
*Server Login = funambol
 +
*Server Password = funambol
 +
*Device ID = MyID
 +
 
 +
This parameters are those which have been fill in the [http://wiki.eclipse.org/Koneki/Simulators/OMA-DM/User_Guide#Step_4:_Edit_the_file_.2Fopt.2FFunambol.2Fdm-server.2Finstall.properties Step 4: Edit the file install.properties]. The server URI is different than the URI of the web page of the server. Indeed, the web interface is available on this URI: http://localhost:8080/dmdemo/ whereas the OMA-DM server is available on this page: http://localhost:8080/funambol/dm. The server Login and password are used to identify the user on the OMA-DM server. It's the user name and the password for the PostgreSQL account. The device ID is the ID which was use to create a new device on the dm-server.  
  
Once all parameters are set on the simulator, you can run a new connection to the dm-server. If some commands are associated to the device which you want to simulate they will be executed. Then, you will see the result of the operations in the Command view of the dashboard and on web interface of the dm-server.
+
Once all parameters are set on the simulator, you can run a new connection to the dm-server. If some commands are associated to the device which you want to simulate they will be executed. Then, you will see the result of the operations in the Command view of the dashboard and on web interface of the dm-server.  
  
=== Access to the database of dm-server ===
+
=== Access to the database of dm-server ===
  
In this document, the dm-server uses PostgreSQL server. The dm-server can use other database server like MySQL or ORACLE. You can get and set the database of the dm-server with your PostgreSQL account (user name = <i>"funambol"</i>, password = <i>"funambol"</i>, database name = <i>"funambol"</i>). Below is the list of all tables which are created by dm-server during the installation.
+
In this document, the dm-server uses PostgreSQL server. The dm-server can use other database server like MySQL or ORACLE. You can get and set the database of the dm-server with your PostgreSQL account (user name = ''"funambol"'', password = ''"funambol"'', database name = ''"funambol"''). Below is the list of all tables which are created by dm-server during the installation.  
  
* fnbl_device: store all informations about each device
+
*fnbl_device: store all informations about each device  
* fnbl_dm_state: store all current commands which are waiting to be execute on on device
+
*fnbl_dm_state: store all current commands which are waiting to be execute on on device  
* fnbl_id: store come counters to create many unique ids
+
*fnbl_id: store come counters to create many unique ids  
* fnbl_principal: store the associations between one device and one user. In future version many users could manage many device and vice versa
+
*fnbl_principal: store the associations between one device and one user. In future version many users could manage many device and vice versa  
* fnbl_role: store different role which are available for users. It's not really use in this version of the dm-server
+
*fnbl_role: store different role which are available for users. It's not really use in this version of the dm-server  
* fnbl_treediscovery_processor: specific table to store only about “Discover tree”
+
*fnbl_treediscovery_processor: specific table to store only about “Discover tree”  
* fnbl_user: store the user name and password which are in the file install.properties during the installation of dm-server. Currently, this table is not really use
+
*fnbl_user: store the user name and password which are in the file install.properties during the installation of dm-server. Currently, this table is not really use  
* fnbl_user_dm_demo: this table is not use yet
+
*fnbl_user_dm_demo: this table is not use yet  
* fnbl_user_role: store the associations between fnbl_user and fnbl_user
+
*fnbl_user_role: store the associations between fnbl_user and fnbl_user
  
 
A complete description of this database with the foreign keys is available in the document [http://download.forge.objectweb.org/sync4j/funambol_dm_server_developer_guide.pdf Funambol DM Server Developer’s Guide].
 
A complete description of this database with the foreign keys is available in the document [http://download.forge.objectweb.org/sync4j/funambol_dm_server_developer_guide.pdf Funambol DM Server Developer’s Guide].

Revision as of 09:44, 23 October 2012

Contents

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

All informations you will fill into the wizard's pages are settable directly with the simulator. The wizard just offer you an easy way to edit basic informations about the simulation.

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”.

Warning: the new OMA-DM simulator have to be into a project ("New" → "Project" → "General") , else, it doesn't work.

Wizard page 1.png

Click on the "Next" button.

Step 2: OMA DM simulation file page

Choose the location and the name of the future simulator file.

Wizard page 2.png

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 simulated
Wizard page 3.png

Warning: The simulator just supports the basic authentication. It doesn't yet support the auth-md5 authentication.

Click on the "Next" button.

Step 4: Device informations page

In this page you can fill basic information about the device. the Device ID must not be empty. Other informations could be empty.

Explications

  • Device id: 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 natural language of the device, for example: "En"
Wizard page 4.png

Click on the "Next" button.

Step 5: Device details page

In this page you can fill other informations 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
Wizard page 5.png

Click on the "Finish" button.

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 is available here: www.openmobilealliance.org/Technical/current_releases.aspx

Data representation

The device's data are represented by a tree nodes. This tree is stored 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, all informations have to be fill.

For the nodes, Type an Data information must be 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 non optionals 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 sent by the server and executed 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: invoke an executable file 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. These tags allow you to configure the simulator before to run connections on the OMA-DM server. The two first tabs offer you a way to configure the simulator. The last tab is use to run connections to one OMA-DM server.

The Configuration tab

The first tab 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.

Configuration OMA-DM tag.png

The Device Management Tree tag: three sections

Device Management Tree tab is divided in three sections: Device tree, Node properties and Node management.

DeviceManagement OMA-DM tag.png
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. Delete non optional nodes is forbidden by the editor.

You can recognize into the tree the informations that you filled in the Configuration tag. Below is the correspondence between information in the Configuration tab 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

This section allows you to edit informations about the current node or leaf which is selected in the Device tree. These informations are described in the Data representation section.

As you can see in the screen shot above, you just can edit the data of the selected node. Indeed, for standard nodes, the name, format and type are not settable. But, for non standard nodes, all informations are settable.

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 the simulation. For example, during one Replace command, you can refuse to set the value of the node.

Manual Replace OMA-DM Command.png

You can also change the value of one node during one Get command.

Manual Get OMA-DM Command.png

One last example of the command management is available in the FUMO 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.

Dashboard Command OMA-DM tag.png

The dashboard with the message view.

Dashboard Message OMA-DM tag.png
Section 1: Device tree

This section is almost similar with the tree section in the Device Management Tree tag. But here, you just can to select one node. You can't edit the tree.

Section 2: Node properties

This section is almost similar with the properties section in the Device Management Tree 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 the 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 which 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.

OMA-DM FUMO step 1.png

And for other nodes:

OMA-DM FUMO step 2.png
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".

OMA-DM FUMO step 3.png

Now a pop-up appears and demand you to select FUMO result code and if you choose "Successful" the new version of the firmware version.

OMA-DM FUMO step 4.png

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 and use the OMA-DM server provided by Funambol

This section explains how install the OMA-DM server provided by Funambol. This server is called dm-server. The document also explains how use the web interface of the dm-server and where data are stored. To finish, the document shows how interact the OMA-DM simulator with the dm-server.

The official documentation about Funambol's products is available at this address: www.forge.funambol.org/download/documentation.

All versions of the source code and documentations about Funambol are available at this address: download.forge.objectweb.org/sync4j

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

This section explains how install Funambol dm-server with PostgreSQL database. It supposes PostgreSQL is already installed on your machine.

Step 1: Download required programs
Funambol Device Management server

The dm-server is available at this address: sourceforge.net/projects/funambol/files/dm-server

JBoss

JBoss is available at this address: 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: jdbc.postgresql.org/download

Step 2: Extract archives

The architecture which has been used for this document looks like this:

  • /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 path.

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 4: 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. To don't break your system, a good solution is 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 5: 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”. This line point to the path of the JDBC driver.
  • 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 local machine.)
Step 6: Install the dm-server

To install the dm-server you just need 2 commands:

  • cd /opt/Funambol/dm-server/
  • sh ./bin/install.sh jboss5

Warning: jboss5 is not an optional parameter. Without it, the installation doesn't work !

The program will offer you to recreate the PostgreSQL database. Accept, and choose 'y'. If it's the first time you run the script, some errors will appear. It's not a bug. It just means the program tried to delete some SQL tables which doesn't exist yet... If everything is OK, the last message should be: “BUILD SUCCESSFUL”. Then, you are ready to run the dm-server.

Step 7: 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.

If you want to change the server name parameter setted in the install.properties file during the Step 5: Edit the file /opt/Funambol/dm-server/install.properties , you don't have to re-install the dm-server. A good way consists to edit the file "/opt/Funambol/dm-server/config/Funambol.properties". The first line (server.uri) set the dm-server name.

Use the web interface of the dm-server

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:

OMA-DM Funambol Login.png

Warning: 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. The server name parameter is only use for the OMA-DM protocol, not for the web interface.

Click on “Add New device” and choose one device ID. "MyID” has been choose for this document. Once you chose your device ID, 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 your dm-server which is identify by its ID: “MyID”.

OMA-DM Funambol Device Created.png

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 the device

Once you are logged, you can choose an operation and add it in the operation list.

OMA-DM Funambol Device Management.png

From this page, you can chose three types of operations

  • Get device details: send one Get command to many important nodes (./DevInfo/Man, ./DevInfo/Mod, ./DevDetail/DevTyp, ./DevDetail/OEM, ./DevInfo/Lang, ./DevDetail/FwV, ./DevDetail/SwV, ./DevDetail/HwV, ./DevInfo/DmV)
  • Tree discovery: discover all or a part of the device's OMA-DM tree by sending Get commands to which node you want
  • Custom operation: create a collection of commands (Get, Add, Replace or Delete) on which node you want
Operations example
Tree discovery operation Custom operation
OMA-DM Funambol Discovery Command.png OMA-DM Funambol Custom Command.png

Once you chose which operation you want to execute, it is showed in the operations table.

OMA-DM Funambol New Command.png

After the execution of the new command, its status change and the date of start time and end time is set.

OMA-DM Funambol End Command.png

Now, you can launch new operations.

Use the dm-server with the OMA-DM simulator

Using the OMA-DM simulator with the dm-server needs one specific configuration. In the Configuration tag, fill these informations:

This parameters are those which have been fill in the Step 4: Edit the file install.properties. The server URI is different than the URI of the web page of the server. Indeed, the web interface is available on this URI: http://localhost:8080/dmdemo/ whereas the OMA-DM server is available on this page: http://localhost:8080/funambol/dm. The server Login and password are used to identify the user on the OMA-DM server. It's the user name and the password for the PostgreSQL account. The device ID is the ID which was use to create a new device on the dm-server.

Once all parameters are set on the simulator, you can run a new connection to the dm-server. If some commands are associated to the device which you want to simulate they will be executed. Then, you will see the result of the operations in the Command view of the dashboard and on web interface of the dm-server.

Access to the database of dm-server

In this document, the dm-server uses PostgreSQL server. The dm-server can use other database server like MySQL or ORACLE. You can get and set the database of the dm-server with your PostgreSQL account (user name = "funambol", password = "funambol", database name = "funambol"). Below is the list of all tables which are created by dm-server during the installation.

  • fnbl_device: store all informations about each device
  • fnbl_dm_state: store all current commands which are waiting to be execute on on device
  • fnbl_id: store come counters to create many unique ids
  • fnbl_principal: store the associations between one device and one user. In future version many users could manage many device and vice versa
  • fnbl_role: store different role which are available for users. It's not really use in this version of the dm-server
  • fnbl_treediscovery_processor: specific table to store only about “Discover tree”
  • fnbl_user: store the user name and password which are in the file install.properties during the installation of dm-server. Currently, this table is not really use
  • fnbl_user_dm_demo: this table is not use yet
  • fnbl_user_role: store the associations between fnbl_user and fnbl_user

A complete description of this database with the foreign keys is available in the document Funambol DM Server Developer’s Guide.