DIALOG Distributed information
architectures for collaborative logistics
 

About Dialog:

» Home
» Concept
» Publications
» Downloads
» Documentation
» Dialog team
» Contact info
» OSC
» Links

Last updated
April 22nd, 2010

id@uri

Installation of a PMI Dialog node

This page details the steps necessary to install the PMI-Dialog distributed messaging software, a revised version of Dialog with support for the PROMISE Messaging Interface (PMI).

Installation of the software is easy; just download a pre-compiled binary distribution and follow the instructions below. Dialog developers and interested members of the public will want to get the full sources of the software and build Dialog themselves.

Download the software

Prerequisites

To run PMI-Dialog, your system should have the following software installed:
  • Java runtime: JDK 1.6, or newer is needed if you want to run Dialog under Tomcat. The software is known to work on Linux 2.4 and 2.6 platforms running the Sun JDK 1.6. The client and "Axis standalone" versions of the software work on Linux JDK 1.5 or 1.6, and on Windows XP running JDK 1.5. Other java virtual machines (OpenJDK etc...) might or might not work.
  • Apache Tomcat application server, version 6.0.13 is known to work. (This is not strictly neccessary, as the Apache Axis SOAP implementation contains a simple HTTP server that can be used stand-alone. For details, please see the standaloneaxis.sh script in the build directory)
Additionally, the following prerequisites should be met, if applicable:
  • If this Dialog node should be able to store information item values locally, the MySQL database server version 5 or above must be installed. (Support for other databases might be added in the future)
  • If building the Dialog software from sources, the following are needed:
    • Apache Ant. Version 1.7 is known to work.

Performing installation from a pre-compiled distribution

  1. Unpack the pre-compiled binary distribution to a directory of your choice.
  2. go to the directory "new_dialog/build"
  3. copy the pmi subdirectory to the "webapps" directory of you Tomcat installation
  4. Start Tomcat, if it is not running already. (Note that in the following we assume that Tomcat is listening for requests at localhost port 8080.)
  5. run the Deploy.sh (UNIX) or Deploy.bat (Windows) script in the pmi/ subdirectory
  6. in the new_dialog/build directory, run the client by invoking the runclient.sh script (runclient.bat on Windows).
  7. You should be faced with this dialog:

    Press "OK". A window appears, choose "View Agents -> Generic PMI Agent" from the menu. You should see this:

  8. Press on the "New query" button located in the upper part of the window. A dialog pops up:

  9. The purpose of this window is to send a PMI request to the Tomcat running on your machine, so that the actual Dialog instance "wakes up". (This is because Tomcat does not start a web application until the first message arrives)

    The only thing you possibly need to change is the Web service URL. The default value should be ok for most installations. Click "Send" to send the message.

  10. Now the Web app under Tomcat starts up, and a window like this should pop up:

    In this window, you are given the possibility to configure a database connection, if you have/need one. The relevant fields are "DB url", "DB username" and "DB password". Please ignore the others.

    Field "DB url" must in the format

     
     jdbc:mysql://[hostname]/[database name] 
     

    If you use a DB, it is best (but not strictly neccessary) to create an own database for Dialog. All the neccessary tables will be created automagically.

  11. Press "Save". A small window like this should appear:

    Click on "Restore". A window similar to the client interface will appear. Choose "View Agents -> Generic PMI Agent". You should see something like this:

    This interface is the "server-side" user interface. Using the server-side Generic PMI agent it is possible to make any kind of PMI 2.0 requests, including subscriptions.

    In the "sent responses" field you can see requests that this PMI node has sent, and in the "received responses" field you can see responses that have arrived from other PMI nodes. If you select an item from either fields, you can see more details in the "Content" panel of the window.

    Felicitations you now have a basic PMI-Dialog node running at

    http://[hostname]:[port]/pmi/services/pmi
    .

Using PMI-Dialog for fun (and profit?)

If you want to test your PMI Dialog installation in a more realistic context, you can use your Dialog server user interface for contacting the PMI node at the Helsinki University of Technology at this address:

 
 http://dialog.hut.fi/pmi/services/pmi
 

You can start by querying the list of available devices, then the list of available information items on a particular device, then proceed by making a "read" of some device's information item.

Finally, you can enter a subscription for some information item, by writing your Dialog node address as the "Callback WS address", the time-to-live (the time, in minutes, that you wish the subscription to be valid) and subscription interval (the time, in minutes, between samples). After you have submitted the subscription you will first get a special "request ID" reply from the remote PMI node(The request ID can be used to cancel the subscription), and after some time the first actual "data result". You will continue to receive these data results at the given interval until the subscription expires, or you explicitly cancel the subscription.

Notes on running PMI-Dialog as a server application

The graphical user interface poses some trouble in server installations because server machines are typically operated remotely (via SSH). You have two options:
  • disable the server-side GUI by editing the file "pmi/WEB_INF/ServerProperties.cfg": Change the property "showClientInterface" to "false", and restart Tomcat. The GUI will not be drawn, but the PMI-Dialog node is still fully functional and responding to PMI requests.
  • If you need the server-side GUI for eg. debugging, you can use a remote desktop software like VNC and start Tomcat from inside a VNC session. Note that if you do start Dialog with a GUI, but later you exit your X11 session, Tomcat will be left running, but Dialog will not work, causing Tomcat to answer requests with "503 service unavailable".

Compiling PMI-Dialog from sources

Here is how you build PMI-Dialog from sources:
  1. Uncompress source distribution to a directory of your choice.
  2. go to the newly-created directory "new_dialog" and run "ant axisstandalonedeploy"
  3. You now have a PMI-Dialog build in the "build" subdirectory, and you can proceed with the installation as you would with the pre-compiled distribution.

Solutions to common problems

MySQL

  • Symptom: The node does not start up, but the message "Communications failure during handshake. Is there a server running on :?" is shown.
  • Solution: start the mysql client, and execute the following command:
    SET PASSWORD FOR 'username'@'servername' = OLD_PASSWORD('your_password_here');
    

Useful things to know about PMI-Dialog

  • Question: I have created a new agent, but it is not started!
  • Answer: check that your agent indeed compiles flawlessly. Then check that your agent is enabled in the file "[webapps]/pmi/WEB-INF/agents.txt". Also check in the Tomcat logfiles for any error messages from your Agent.
  • Question: I have the A8 Smart Adapter connected at port "/dev/ttyS0". How do I tell that to PMI-Dialog?
  • Answer: The Smart Adapter protocol has a configuration file named smartadaptercontroller.properties. It contains a property named "saSerialPort" that you can set to "/dev/ttyS0". This can also be performed though the GUI of the Smart Adapter agent, but you will have to re-start Tomcat for the change to take effect.

Tomcat

Compiling