WITS Adapter

Introduction

The TIBCO StreamBase® Adapter for WITS allows for receiving of WITS data from the serial comm port. All the adapters sharing a configuration work together on the same underlying connection; see the section below about shared configurations for more information.

The number of output ports on this adapter are defined by its setup. Please see the Adapter Properties section 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 required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. 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 module. 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 sbadmin resume command, or until you start the component with StreamBase Manager.

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 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.
Record Types String List This option allows you to specify which record types this WITS adapter instance will handle for the selected configuration. The configuration must include a dictionary file, and that dictionary file will contain one or more record types to handle. This list allows you to specify one or more of those records that this adapter will handle. Only a single instance of the WITS adapter can handle a specific record type per configuration.

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.

Adapter Shared Location

The shared adapter configuration for the WITS adapters is located in the sbd.sbconf file under the streambase-configuration and adapter-configurations XML elements.

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.

Example Shared Adapter Configuration

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<streambase-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 -->
            <setting name="receiveTimeout" val="0"/> <!-- Timeout value in milliseconds, unset if value is 0, value must be below 25500 -->
            <setting name="receiveThreshold" val="0"/> <!-- Enables receive threshold, unset if value is 0, value must be below 255  -->
            <setting name="connectionDelayBetweenRetriesMS" val="1000"/> <!-- The delay in milliseconds between reconnect attempts if the comm port is disconnected or fails. If the value is 0 no reconnects are attempted.  -->
            <setting name="connectionRetryCount" val="10"/> <!-- The number of times to attempt to reconnect to the serial port if there is a failure. If the value is 0 the system will attempt to reconnect indefinitely.  If the number of attempts is greater than 0 and a reconnect is not successful a status error with the event type 'Serial' will be emitted on the status port. -->
         </section>
      </adapter-configuration>
   </adapter-configurations>
</streambase-configuration>

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 config file.
packetFooter string !! The value to use when determining the end of a packet of data. This value must be XML encoded in the config file.
lineSeparator string \r\n The value to use when determining the line separator. This value must be XML encoded in the config 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.
receiveTimeout int 0 Timeout value in milliseconds, unset if value is 0, value must be below 25500.
receiveThreshold int 0 Enables receive threshold, unset if value is 0, value must be below 255.
connectionDelayBetweenRetriesMS int 1000 The delay in milliseconds between reconnect attempts if the comm port is disconnected or fails. If the value is 0 no reconnects are attempted.
connectionRetryCount int 10 The number of times to attempt to reconnect to the serial port if there is a failure. If the value is 0 the system will attempt to reconnect indefinitely. If the number of attempts is greater than 0 and a reconnect is not successful a status error with the event type 'Serial' will be emitted on the status port.

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.