SmartControl

dsTest’s SmartControl API allows an external client to register for, send, and receive notification of dsTest events, allowing the external client to coordinate actions with the device under test (DUT) or an instance of dsTest that is running on a separate platform. dsTest simulators and emulators, such as a Policy and Charging Enforcement Function (PCEF) or Online Charging Sever (OCS), can also interact with the external device as part of the SmartControl coordinated events with the External Client. Subscriber control can be maintained via the use of a dsTest Subscriber Profile Repository (SPR) node.

Implementation of the API

dsTest maintains a TCP socket (server and passive) on port 10000. Upon successful registration by an external client, that client becomes associated with dsTest node with the name supplied by the client in the Sender Identification element contained in the registration message.

Within 5 seconds of opening a TCP connection the external client must initiate a Registration Message which includes identification information (as well as potential future ranging information and/or capabilities). 

All structures are Type-Length-Value (TLV) format; 4-byte (32 bit) sized and aligned. If the Most Significant Bit (MSB) of the Type field is set, the values within the structure are in TLV format.

The message structure is designed for high performance construction and parsing, not compact size. MSB set indicates that message contains values that are TLV structures.

All are 31-bit values, however most or all would have the MSB set due to their value being a series of TLV structures.

Registration Message

This message will result in a similar Registration Message from dsTest with dsTest-specific information, but with same type/purpose. 

Type Value: 0x00000001

Required Elements: Sender Identification, Event Source Node, Event Destination Node

Optional Elements: Event Registration, Event Map Entry

Event Registration Element

One or more of these elements may be included in the Registration Message to indicate to the receiver that the sender wishes to receive all events of this type that occur within the destination node's database. It must also include at least one Requested Event Contents element containing the requested subscriber ID type to be included in the resulting Event Trigger Messages.

The message may optionally contain one or more additional Requested Event Contents elements specifying additional elements to be in the resulting Event Trigger Messages.

Type Value: 0x80001003

Required Elements: Event Application, Event Name, Requested Event Contents (containing a 0x3xxx identifier for subscriber ID)

Optional Elements: Requested Event Contents (containing a 0x3xxx, 0x5xxx, or 0x6xxx identifier elements)

Event Map Entry

One or more of these elements may be included in the Registration Message to provide a mapping of the sender’s string based event identifiers to uint32 based event identifiers.  When these values are present in the registration message, the sender WILL send and the receiver MAY send the Event ID rather than the Event Application and Event Name in Event Trigger notifications.

Type Value: 0x80002006

Required Elements: Event Application, Event Name, Event ID

Error Indication Message

This message is sent to the originator of an Event Trigger message if the message cannot be successfully delivered.

Type Value: 0x00000002

Event Trigger Message

An event is triggered on a peer node by sending the Event Trigger message. This message must contain an indication of the event (App/Name or ID) and the identity of the subscriber.  It should also contain any event specific data needed to specifically target, direct and/or qualify the event.  There is no response to this message if successfully delivered.  On failure, an Error Indication message will be sent.

Type Value: 0x00000003

Required Elements: Event Application and Event Name plus at least one subscriber ID (Subscriber Index within Database, Subscriber IMSI, Subscriber MSISDN, Subscriber IMEI, Subscriber Private Identify, Subscriber IP Address

Message Elements

All are 31-bit values; however some may have the MSB set due to their value being a series of TLV structures.

SmartControl Example External Client App

The dsTest installation includes a smartControl application that can be used to demonstrate the use of SmartControl. You'll find the application on the dsTest platform in /usr/local/devsol/bin and the source code in /usr/local/devsol/dsTest/lib. smartControl must be executed with root privileges.

Command line Options:

-h<addr>

hostname/ip address of server

-n<name>

node name of dsTest node

-a<name>

notification triggering application name on dsTest

-v<name>

notification triggering application event name

-i

use subscriber index instead of IMSI

-r

register for notification instead of sending event

-s<num>

start subscriber ID (N/A for notifications)

-e<num>

end subscriber ID (N/A for notifications)

-p<num>

events per second to trigger (N/A for notifications)

-d

enable verbose output

-x<num:value,...>

add custom TLVs to event (N/A for notifications)

Registering for Notifications

An example use of the smartControl application to register for notifications:

>/usr/local/devsol/bin/smartControl -h test44 -n hss -a s6 -v update -r -i –d

smartControl registers with the dsTest instance running on host test44 for notifications of S6 update events for all subscribers on node hss, specifying the use of subscriber index as the subscriber id with verbose output of the event notifications.

Sending Events to a dsTest Node

An example use of smartControl application to send an event to a dsTest Node:

>/usr/local/devsol/bin/smartControl -h test44 -n mme_1 –i –s 1 –e 5 –p 1 -a s6 -v update –d

smartControl sends an S6 update for subscribers 1 through 5 at a rate of one-per-second to the MME node on host test44, specifying the use of subscriber index as the subscriber id, with verbose output of the responses.