Messaging Module Setup

Installing the Messaging Module is exactly like installing any other module, unless you need to also connect a USB modem or phone to OpenMRS. If that is the case, then things can get very complicated to set up. This process is currently very untested and may not work for everyone. If you have successfully completed this process, please modify this page with your comments at the bottom.

Prerequisites

• OpenMRS 1.7.x
• The java-6-sun JVM (we suspect that the OpenJDK does not work)
• Patience
• Phone and USB cable or Modem

Step 0: Selecting a proper modem or phone

It is generally advisable to select a phone or modem off of this list: http://smslib.org/doc/compatibility/. Unfortunately, many of these phones are out of date and no longer in production.

Step 1: Installing the RXTX library

The RXTX library is what the Messaging Module uses to communicate over serial ports. There are 2 components - a jar that is already packaged with the Messaging Module (don't worry about this), and a native library which must sit in a specific directory on your server. The goal of this section is to help you download the proper native library and put it in the proper folder on your server.

• Run the command:

• uname -a
  

  which will display a string describing the innards of your computer. Towards the end is a piece describing your processor architecture; common examples are 'i386', 'x86_64', and 'amd64'. Remember this snippet.
• Download the zip file containing the RXTX binaries. Inside this file you will see several folders. Open the folder that matches your processor architecture that you found in the previous step. Inside this folder will be a file called librxtxSerial.so. Copy this file to $JAVA_HOME/bin/<processor architecture>. If you don't have a JAVA_HOME environment variable set, copy it to /usr/lib/jvm/java-6-sun/bin/<processor architecture>
• In your home directory, create .bash_aliases if it does not already exist. Add this line

• export LD_LIBRARY_PATH="$JAVA_HOME/bin/
  

  This sets your java library path to include the directory in which you just placed librxtxSerial.so. 
• Run

• source ~/.bash_aliases
  

  to update your environment variables.

Step 2: Set up your modem's serial connection

In this section we will determine what serial port your modem or phone creates and make sure that the messaging module can contact it.

• With your modem disconnected, run this command:

  ls /dev/
  

   This will list all serial ports on your computer. 

• Now, plug in your modem, wait a few moments, and run the same command again. You should see some different ports this time. There will be many ports, so you may have to sift through a lot, but the new ports will probably be named something like 'ttyACM0" or "ttyS0" or "ttyUSB0". These new ports are the ones that will allow you to connect to your modem. If your serial port is named "ttyS0" (that's a zero not an O) then skip the rest of this section and section 2.5. If multiple serial ports appear, skip to section 2.5.
• Create a symlink from /dev/ttyS0/ to your modem's serial port with this command: 

  ln -sf /dev/ttyACM0 /dev/ttyS0
  

  You should replace 'ACM0' with the port that you discovered in the previous step. Because the messaging module only knows to scan a few standard ports, this symlink will allow it to find your modem's serial port.

Step 2.5: But what if multiple ports appear when I connect my modem?!?

Many modems or phones will create multiple serial ports, which is very confusing. They can create weird 'cu.Nokia' ports or multiple 'ttyUSB' ports or other weirdness as well. Unfortunately, there is no surefire way of telling which ports will actually communicate with the modem and which ones won't. In order to determine the port that you want to use for communicating with your modem, you will have to test them one by one. For this, we will use a program called minicom.

FYI: As a rule of thumb, you should probably ignore any ports that don't begin with 'tty', like those weird 'cu.' ports. However, if you test all tty ports and none work, then you should probably try the non-tty ports that your modem created.

FYI2: Another useful tool in discovering what ports your modem creates is dmesg. Try running the command "dmesg | grep tty" and combing its output for ports that look like they might be in use by your modem.

• First, install minicom. If you are on Ubuntu, you can do this:  

  sudo apt-get install minicom
  

  If you're on a mac, then minicom is available from darwinports here. 
• Now, you're going to go through every new port that your modem created and see if the modem actually responds to attempts to contact it over that port. Start by making sure your modem is plugged in.
• Then, start minicom in setup mode with this command:

  minicom -s
  

  This will bring up the minicom setup screen. Press down twice to select "Serial Port Setup" and then press enter. This will take you to a screen where you can set which port minicom attempts to connect with. Press 'a' to set the "Serial Device" and type in the first port you want to test. Press enter when you're done, then press it again to exit the serial port setup screen. Then move the cursor down and select "Exit" (Not "Exit from Minicom") to start minicom with the serial port you provided.
• Minicom will now attempt to connect to your modem by sending an "AT" command. The AT command spec is very long and complicated (google "Hayes AT Commands"), but basically if you send the command "AT" to your modem, it should respond with "OK". If you have the right serial port,  you should see an "OK" response from your modem when you start up minicom because it already initiated a connection. For good measure, send a few "AT" commands to your modem (type "AT<Enter>") and make sure it responds with the "OK" signal. If all of this works, then you've found the proper serial port! If it doesn't work, then exit minicom and try again with a different port until you've found the one that works.
• Once you have found a port that works with your modem, create a symlink to ttyS0, as detailed in section 2.

Step 3: Start Tomcat (or restart Tomcat)

Start or restart Tomcat, go to the module administration page, and install the messaging module. Currently, there is not a good way to immediately tell if a modem was found and connected other than trying to send a text message. If the module takes a while to load, then that's a good sign.

Successful Installations