Mobile Sequence Monitor - OpenNMS

Overview

The mobile sequence monitor is designed to be able to connect one or more (SMSlib-compatible) mobile phones to an OpenNMS system, and measure the performance and validity of various sequences, much like the page sequence monitor.

It should be capable of sending and receiving USSD and SMS messages, and validating the responses based on various criteria.

Configuration

Poller-Configuration Parameters

The MobileMsgSequenceMonitor is configured just like any other monitor in poller-configuration.xml. It takes the usual parameters for basic configuration:

retry: how many times to retry before considering the sequence a failure
timeout: how long to wait before considering the sequence a failure, and retrying (if configured to do so)
rrd-repository: where to store RRD latency data
rrd-base-name: the base name for the RRD file
ds-name: the ds-name used in the RRD file

Additionally, it takes one custom parameter:

sequence: the sequence configuration XML, described below.

Sequence XML

The sequence(s) to perform are defined by an XML configuration embedded in the sequence parameter of the poller configuration entry.

XML Format

A sequence is a list of one or more transaction tags, which can then contain a request and 1 or more responses. A sequence can also define 0 or more session variables which can be used in sequences.

A response can contain 0 or more criteria that are used to match incoming SMS and USSD messages.

 <mobile-sequence xmlns="http://xmlns.opennms.org/xsd/config/mobile-sequence">
   <session-variable ... />
   <transaction ...>
     <[request] ... />
     <[response] ...>
       <matches>^regular-expression$</matches>
     </[response]>
   </transaction>
 </mobile-sequence>

The Transaction Tag

The transaction must contain one request tag, and one or more response tags. It can also optionally contain zero or more session-variable tags.

The following attributes are accepted:

gatewayId: the gateway ID (device) to use for all requests and responses in this transaction (unless overridden)
label: a descriptive label for the transaction (used in logs and error messages)

Request Tags

The following request tags are valid in a sequence:

sms-request: send an SMS message
- attributes
  - recipient (required)
    the phone number of the recipient
    text (required)
    the contents of the SMS message
    gatewayId
    the gateway ID (device) to use to send the request (defaults to the transaction tag's gateway ID if not set)
    label
    a descriptive label for this request (used in logs and error messages)
- example: <sms-request recipient="911" text="is a joke in your town" />
ussd-request: send a USSD message
- attributes
  - text (required)
    the contents of the USSD message
    gatewayId
    the gateway ID (device) to use to send the request (defaults to the transaction tag's gateway ID if not set)
    label
    a descriptive label for this request (used in logs and error messages)
- example: <ussd-request text="#123#" />

Response Tags

The following response tags are valid in a sequence:

sms-response: expect an incoming SMS message
- attributes
  - gatewayId
    the gateway ID (device) to expect the response on (defaults to the transaction tag's gateway ID if not set)
    label
    a descriptive label for this response (used in logs and error messages)
- tags
  - matchers
    the response can contain zero or more matcher tags, described below
- example: <sms-response><from-recipient /></sms-response>
ussd-response: expect an incoming USSD message
- attributes
  - gatewayId
    the gateway ID (device) to expect the response on (defaults to the transaction tag's gateway ID if not set)
    label
    a descriptive label for this response (used in logs and error messages)
- tags
  - matchers
    the response can contain zero or more matcher tags, described below
- example: <ussd-response><session-status>NO_FURTHER_ACTION_REQUIRED</session-status></ussd-response>

Matcher Tags

The following matcher tags are valid in a response:

from-recipient: confirm that the response came from the corresponding request's recipient
- example: <from-recipient />
validate-source: confirm that the response came from the specified originator
- example: <validate-source>+19195551212</validate-source>
matches: confirm that the response text matches the specified regular expression
- example: <matches>^[Hh]ello$</matches>
session-status: confirm that the USSD session status matches the specified status
- valid status types:
  - NO_FURTHER_ACTION_REQUIRED
  - FURTHER_ACTION_REQUIRED
  - TERMINATED_BY_NETWORK
  - OTHER_CLIENT_RESPONDED
  - OPERATION_NOT_SUPPORTED
  - NETWORK_TIMEOUT
- example: <session-status>NO_FURTHER_ACTION_REQUIRED</session-status>

Modem Configuration

To configure the modems, you will need to edit or create the $OPENNMS_HOME/etc/modemConfiguration.properties for SMSlib. On most Linux systems, the devices are /dev/ttyACM#. You can usually run "dmesg" to see the output of the kernel initializing modem devices.

The modemConfiguration.properties file has a "modems" entry, which lists the modems that will be activated as "gateways" in SMSlib. Then, you must configure a set of properties for each modem in that list.

For example:

 modems = acm0
 
 acm0.port = /dev/ttyACM0
 acm0.model = w760i
 acm0.manufacturer = SonyEricsson
 acm0.baudrate = 115200

Modem Disconnect Detection and Notification

For various reasons, modems may sometimes disconnect from the serial bus at runtime. The system needs to have a way to detect this situation and notify the user. When a method attempts to access a serial port that is not available, the RXTX library throws a gnu.io.NoSuchPortException. It may be possible to pass these exceptions into OpenNMS, where an event could be generated to trigger an alarm or notification. SMSLib may require modifications to pass through these exceptions.

User Story

A user attaches three GSM modems to an OpenNMS server and configures modemConfig.properties to use them all. During operation, the voltage on the USB port corresponding to acm2 goes outside the range acceptable to the modem; or a janitor unplugs the phone and uses it to call his friend. Either way, the modem disconnects from the serial bus and is no longer usable by OpenNMS. The user needs a clear indication that this has happened.

Acceptance Criteria

A log message is generated that clearly explains the likely situation
An OpenNMS event is generated
The user does not need to dig through log files to determine what has gone wrong

Phone Book Configuration

Additionally, you need to tell OpenNMS IP address that a given phone is associated with for polling purposes. This file is just a simple key=value list of IP addresses to phone numbers.

$OPENNMS_HOME/etc/smsPhonebook.properties:

 127.0.0.1=+19195551212
 216.216.217.254=+19195330160

Examples

T-Mobile USSD Balance Check

T-Mobile USA lets you check your minutes balance by dialing "#225#". To perform this as a sequence in OpenNMS, you would configure the following service in poller-configuration.xml:

 <service name="TMobileUSSDSequence" interval="300000" user-defined="false" status="on">
   <parameter key="retry" value="1" />
   <parameter key="timeout" value="30000" />
   <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />
   <parameter key="rrd-base-name" value="tmobile" />
   <parameter key="ds-name" value="tmobile" />
   <parameter key="sequence">
     <mobile-sequence xmlns="http://xmlns.opennms.org/xsd/config/mobile-sequence">
       <transaction label="ussd-balance" gatewayId="acm0">
         <ussd-request text="#225#" />
         <ussd-response>
           <matches>^.*[\d\.]+ received on \d\d/\d\d/\d\d. For continued service through \d\d/\d\d/\d\d, please pay [\d\.]+ by \d\d/\d\d/\d\d.*$</matches>
           <session-status>0</session-status>
         </ussd-response>
       </transaction>
     </mobile-sequence>
   </parameter>
 </service>

Version History/Availability

This feature was added in version 1.7.7

Get OpenNMS

Get Help

Get Involved

Get to Know Us

Toolbox

From OpenNMS

Contents