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.

This adapter supports USB-to-serial-port cables that use the FTDI chipset.

The number of output ports on this adapter are defined by its setup. See the next 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.

Class name: Shows the fully qualified class name that implements the functionality of this operator. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this operator starts.

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 Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Operator Properties Tab

Property Type Description
WITS Configuration Edit Button Shortcut to the StreamBase Configuration File Editor, used for additional adapter configuration.
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.

Cluster Aware Tab

Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

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 adapter configuration file.

Shared Adapter Location

Each shared adapter configuration must be under an element called WITS.conf 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 configuration file must reside in your project's src/main/configurations directory.

Example Shared Adapter Configuration

name = "WITS.conf"
type = "com.tibco.ep.streambase.configuration.adapter"
version = "1.0.0"
configuration = {
          
// An adapter group type defines a collection of EventFlow adapter configurations, indexed by adapter type.
  AdapterGroup = {
        
// A collection of EventFlow adapter configurations, indexed by adapter type. 
// This object is required and must contain at least one configuration.
    adapters = {
          
// The root section for an EventFlow adapter configuration.
      WitsAdapters = {
          
// Section list. This array is optional and has no default value.
        sections = [
          
// A configuration for an EventFlow adapter named section.
        {
          
// Section name. The value does not have to be unique; that is, you can have multiple sections with the 
// same name in the same array of sections. This object is required.
          name = "WitsAdapter"
          
// Section for setting adapter properties. All values must be strings. This object is optional and 
// has no default value.
            settings = {
              baudRate = "9600"
              connectOnStartup = "true"
              dataBits = "8"
              dictionary = "WITSDictionary.json"
              doubleNullValue = ""
              heartBeatInterval = "30"
              heartBeatValue = "&&\r\n0111-9999\r\n!!\r\n"
              id = "Wits"
              intNullValue = ""
              lineSeparator = """
              """
              packetFooter = "!!"
              packetHeader = "&&"
              parity = "0"
              serialPortAppName = "WITS"
              serialPortName = "COM1"
              stopBits = "1"
              stringNullValue = "null"
              }
          }
        ]
      }
    }
  }
}

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.
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.