WITS Controller Adapter

Introduction

The TIBCO StreamBase® Adapter for WITS Controller allows for controlling of the WITS adapters set up with the same configuration, and outputs status information about the current WITS connection. This adapter is not required for the WITS adapter to work, but it is highly recommended, because no status output will occur on the other client adapters. All the adapters sharing a configuration work together on the same underlying connection; see the section below about shared configurations for more information.

Adapter Properties

This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.

General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Operator: A read-only field that shows the formal name of the operator.

Start with application: If this field is set to Yes (default) or to a module parameter that evaluates to true, this instance of this adapter starts as part of the JVM engine that runs this EventFlow fragment. If this field is set to No or to a module parameter that evaluates to false, the adapter instance is loaded with the engine, but does not start until you send an epadmin container resume command (or its sbadmin equivalent), or until you start the component with StreamBase Manager. With this option set to No or false, the adapter does not start even if the fragment as a whole is suspended and later resumed.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Operator Properties Tab

Property Type Description
Adapter Configuration Drop-down list The adapter configuration from the configuration file to use with this adapter.
Enable Control Port Check box Enable the control port to allow control commands.
Enable Data Port Check box Enable the data port to allow input of data to parse.
Enable Raw Data Output Port Check box If enabled each raw data packet from the serial port will be output on this port. This data can be captured and used later as playback data.
Log Level Drop-down list Controls the level of verbosity the adapter uses to issue informational traces to the console. This setting is independent of the containing application's overall log level. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Shared Adapter Configuration

This section describes the shared adapter configuration block found in the sbd.sbconf file.

Shared Adapter Location

Each shared adapter configuration must be under an element called adapter-configuration with a name attribute of WitsAdapters. Following that, an element named section with a name attribute of WitsAdapter is required.

In the example below, long lines wrap for legibility.

The adapter-configurations.xml must reside in your project's src/main/resources directory.

Example Shared Adapter Configuration

<adapter-configurations>
   <adapter-configuration name="WitsAdapters">
      <section name="WitsAdapter">
         <setting name="id" val="Wits"/> <!-- The ID that will show in the drop 
            down list of options on the adapter -->
         <setting name="dictionary" val="WITSDictionary.json"/> <!-- The 
            dictionary to use -->
         <setting name="connectOnStartup" val="false"/> <!-- A flag to determine 
            if the serial connection should connected at startup.  If false the 
            control port of the controller must be used to start -->
         <setting name="packetHeader" val="&amp;&amp;"/> <!-- The packet header  
            -->
         <setting name="packetFooter" val="!!"/> <!-- The packet footer -->
         <setting name="lineSeparator" val="&#13;&#10;"/> <!-- The value to send 
            as the heart beat, please include all line terminators.  NOTE XML 
             format rules apply, for example ampersand values must be escaped  -->
         <setting name="serialPortName" val="COM1"/> <!-- The name of the serial 
            port to use -->
         <setting name="serialPortAppName" val="WITS"/> <!-- The name of the 
            serial port to use -->
         <setting name="baudRate" val="9600"/> <!-- The baud rate to set the for 
            serial port -->
         <setting name="dataBits" val="8"/> <!-- The data bits to set the for 
            serial port -->
         <setting name="stopBits" val="1"/> <!-- The stop bits to set the for 
            serial port -->
         <setting name="parity" val="0"/> <!-- The parity to set the for serial 
            port -->
         <setting name="stringNullValue" val="null"/> <!-- The value to use if a 
            string field is missing from a packet (The value of "null" means to 
            set null, blank or empty string means to set the string value empty) -->
         <setting name="intNullValue" val="-999"/> <!-- The value to use if a 
            integer field is missing from a packet (blank means actually leave null) -->
         <setting name="doubleNullValue" val="-999.95"/> <!-- The value to use if
            a double field is missing from a packet (blank means actually leave null
            ) -->
         <setting name="heartBeatInterval" val="30"/> <!-- The number of seconds 
            between heart beats.  If less than or equal to 0 then no heart beat is
            sent -->
         <setting name="heartBeatValue" val="&amp;&amp;&#13;&#10;0111-9999&#13;&#1
            0;!!&#13;&#10;"/> <!-- The value to send as the heart beat, please 
            include all line terminators.  NOTE XML format rules apply, for example
            ampersand values must be escaped  -->
         <setting name="timeField" val="TIME"/> <!-- The field for each record that
            contains the TIME field -->
         <setting name="dateField" val="DATE"/> <!-- The field for each record that
            contains the DATE field -->
         <setting name="wellIdField" val="WELLID"/> <!-- The field for each record
            that contains the WELLID field -->
         <setting name="timeExpression" val="to_seconds(time(now()))"/> <!-- If none
            empty this StreamBase expression will be used to replace the value of the 
            TIME field if the TIME field is found and is null or contains the 
            doubleNullValue  -->
         <setting name="dateExpression" val="to_seconds(date(now()))"/> <!-- If none
            empty this StreamBase expression will be used to replace the value of 
            the DATE field if the DATE field is found and is null or contains the 
            doubleNullValue  -->
         <setting name="wellIdExpression" val="'Well1'"/> <!-- If none empty this
            StreamBase expression will be used to replace the value of the WELLID 
            field if the WELLID field is found and is null or contains the stringNull
            Value -->
         <setting name="timestampFieldName" val="RecordTime"/> <!-- If none empty 
            this field name will be added to each record and will use the timestampExpression 
            to combine the two fields into a single StreamBase timestamp  -->
         <setting name="timestampExpression" val="from_unixtime(DATE) + from_unixtime
            (TIME)"/> <!-- The StreamBase expression to use when combining the DATE and 
            TIME field together into the timestampFieldName -->                
        </section>
    </adapter-configuration>
</adapter-configurations>

Shared Adapter Configuration Options

If a value is not present, the default is used. Those values listed without a default are required.

Property Type Default Description
id string   This is the name that will link the adapters together and is displayed in the drop-down list on each adapters property configuration.
dictionary string   This is the filename of the WITS dictionary file that will be for WITS Records.
connectOnStartup boolean true A flag to determine whether the serial connection should connected at startup. If false, the control port of the controller must be used to start.
packetHeader string && The value to use when determining the start of a packet of data. This value must be XML encoded in the configuration file.
packetFooter string !! The value to use when determining the end of a packet of data. This value must be XML encoded in the configuration file.
lineSeparator string \r\n The value to use when determining the line separator. This value must be XML encoded in the configuration file.
serialPortName string COM1 The name of the serial port to use.
serialPortAppName string WITS The name to assign to the serial port usage.
baudRate int 9600 The baud rate to set the for serial port.
dataBits int 8 The data bits to set the for serial port.
stopBits int 1 The stop bits to set the for serial port.
parity int 0 The parity to set the for serial port.
stringNullValue string   The value to use if a string field is missing from a packet (The value of null means to set null; blank or empty string means to set the string value empty).
intNullValue int   The value to use if a integer field is missing from a packet (blank means actually leave null).
doubleNullValue double   The value to use if a double field is missing from a packet (blank means actually leave null).
heartBeatInterval int 30 The number of seconds between heart beats. If less than or equal to 0, then no heart beat is sent.
heartBeatValue int &&\r\n0111-9999\r\n!!\r\n The value to send as the heart beat. Please include all line terminators. NOTE XML format rules apply. For example, ampersand values must be escaped.
timeField string TIME The field for each record that contains the TIME field. This matches the actual StreamBase schema field name.
dateField string DATE The field for each record that contains the DATE field. This matches the actual StreamBase schema field name.
wellIdField string WELLID The field for each record that contains the WELLID field. This matches the actual StreamBase schema field name.
timeExpression string   If the value is none/empty, this StreamBase expression is used to replace the value of the TIME field if the TIME field is found and is null or contains the doubleNullValue.
dateExpression string   If the value is none/empty, this StreamBase expression is used to replace the value of the DATE field if the DATE field is found and is null or contains the doubleNullValue.
wellIdExpression string   If the value is none/empty, this StreamBase expression is used to replace the value of the WELLID field if the WELLID field is found and is null or contains the stringNullValue.
timestampFieldName string   If the value is none/empty, this field name will be added to each record and will use the timestampExpression to combine the two fields into a single StreamBase timestamp.
timestampFieldName string   The StreamBase expression to use when combining the DATE and TIME field together into the timestampFieldName.

WITS Dictionary

This section describes WITS dictionaries and how they are used with the adapters to handle WITS record types and items.

Dictionary files are in JSON format and are cumulative, in that you can include more dictionary files inside of other dictionary files to keep them organized and less complex.

WITS Standard Dictionary

The WITS sample that comes with StreamBase includes a WITSDictionary.json file that includes the standard WITS record types and items. This base dictionary includes all the required information for the WITS adapters to perform based on the WITS specification and shows the standard WITS record and item types to get the adapters up and running. If your WITS connection has non-standard record types or items then this dictionary file should be modified to include those extensions.

Dictionary Schema

The following shows the schema to which each dictionary must conform:

{
   "$schema":"http://json-schema.org/draft-04/schema#",
   "type":"object",
   "properties":{
      "IncludeDictionary":{
        "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "File":{
                  "type":"string"
               }
            },
            "required":[
               "File"
            ]
         }       
      },
      "Records":{
         "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "Rec":{
                  "type":"integer"
               },
               "Name":{
                  "type":"string"
               },
               "Description":{
                  "type":"string"
               },
               "Items":{
                  "type":"array",
                  "items":{
                     "type":"object",
                     "properties":{
                        "Item":{
                           "type":"integer"
                        },
                        "Description":{
                           "type":"string"
                        },
                        "LongMnemonic":{
                           "type":"string"
                        },
                        "ShortMnemonic":{
                           "type":"string"
                        },
                        "Type":{
                           "type":"string"
                        },
                        "Length":{
                           "type":"integer"
                        },
                        "MetricUnits":{
                           "type":"string"
                        },
                        "FPSUnits":{
                           "type":"string"
                        },
                     },
                     "required":[
                        "Item",
                        "LongMnemonic",
                        "ShortMnemonic",
                        "Type"                        
                     ]
                  }
               }
            },
            "required":[
               "Rec",               
               "Items"
            ]
         }
      }
   },
   "required":[
      "Records"
   ]
}
        

Dictionary Layout

The following are the major categories of the dictionary file and an overview of their usage.

includeDictionary

The includeDictionary section is an array of files that allows one dictionary file to include another dictionary file. This enables you to organize your dictionaries and combine them into a single dictionary.

  • file — The relative path to the linked dictionary file to include.

Records

The records section allows you to add any record types that are not currently present in the WITS dictionary. Each record type (based on Rec integer) can only appear once in the entire dictionary file.

  • Rec — An integer value representing the record type. This value is left 0 padded and used to match the packets record type.

    Name — (Optional) The name associated with this record type.

    Description — (Optional) The description of this record type.

    Items — An array of items associated with this record type:

    • Item — The integer item value representing the item. This value is left 0 padded and used to match the packets item type.

    • Description — (Optional) The description of this item.

    • LongMnemonic — The long mnemonic name of this item. This value is used as the StreamBase field name in the output schema produced. Using spaces and special characters is not recommended with this value.

    • ShortMnemonic — The short mnemonic name of this item.

    • Type — The type of this item. Valid values are:

      • A — Alphanumeric, which is converted to a StreamBase String.

      • L — 32 bit 2's complement signed integer, which is converted to a StreamBase Int.

      • S — 16 bit 2's complement signed integer, which is converted to a StreamBase Int.

      • F — 32 bit IEEE single precision floating point, which is converted to a StreamBase Double.

    • Length — (Optional) The integer size of the items type. This value is currently not used, but will display in the output schema description.

    • MetricUnits — (Optional) The metric unit of the item. This value is currently not used, but will display in the output schema description.

    • FPSUnits — (Optional) The FPS unit type of the item. This value is currently not used, but will display in the output schema description.

Command Input Port

Use the command port to send action commands to the adapter.

The schema for the command input port is a single field named command of type string.

The suggested full schema for the command input port is the following:

  • command, string. The command to send to the adapter. Valid values are:

    • start - Starts a connection to the serial comm port and processes the data received.

    • stop - Stops any current connection to the serial comm port and stop processing any data.

Data Input Port

Use the data port to send WITS data to the adapter for processing. This can be useful for replay when testing; the data must be in the identical format that would be received from the serial comm port.

The schema for the command input port is a single field named data of type string.

The suggested full schema for the command input port is the following:

  • data, string. The data to send to the adapter. This data must be in the same format which would be received from the serial comm port.

Status Output Port

The status output port will output tuples for the current configuration, giving relevant information about the connection.

The schema for the status output port is:

Field Name Field Type Description
type String The type of report, which follows normal log levels Debug, Error, Info, Trace, Warn.
action String  
object String An option object that has been affected by this status.
Message String A human-readable message about the status.
time Tuple The timestamp that the status occurred.