Generic SCADA Adapter Configuration
RDBMS vs. File Mode
Each Generic SCADA Adapter instance can process input from either Network Management System RDBMS queuing tables (preferred) or from flat files, but not both. A Network Management System can support multiple file-based RTAdapter instances, but only one RTDBAdapter (configured for RDBMS input).
RDBMS mode: The external SCADA system writes SCADA updates to a set of RDBMS queuing tables. Updates are processed by RTAdapter on a first-in-first-out basis.
File mode: Each external SCADA system writes SCADA "scan files" to a dedicated directory that an appropriately configured RTAdapter can access in read/write mode. Incoming "scan files" are processed on a first-in-first-out basis.
Configure Adapter to Run as an NMS System Service
Configure the Generic SCADA Adapter to run as an Oracle Utilities Network Management System service by updating the $NMS_HOME/etc/system.dat file to include the Generic SCADA Adapter as a system service. There are three main sections of the system.dat file where a service needs to be defined: the service, program, and instance sections.
See the $NMS_BASE/templates/system.dat.template file for examples of how to configure the Generic SCADA Adapter. Search for RTAdapter in the file and copy those lines to $NMS_HOME/etc/system.dat file. Make sure all lines are uncommented so SMService will find them as active. You must either restart SMService or start SMService with a "-f system.dat" command line option to pick up changes to the $NMS_HOME/etc/system.dat configuration file (it looks in the $NMS_HOME/etc directory by default).
Notes: The adapter process is often given a configuration name adapted from the SCADA system from which it is receiving data. Reference the RTDBAdapter configuration option in the $NMS_BASE/templates/system.dat.template for an example of this type of configuration. The first parameter after the keyword program must match the -process_name parameter. The -scada option specifies the name of the SCADA for this instance of the RTAdapter (from the SCADA_IDS table) and often matches the -process_name option (though this is not required).
SRS_RULES Configuration for Generic SCADA Adapter
The Generic SCADA Adapter currently supports a few options that can only be configured via the Network Management System SRS_RULES mechanism. The Configuration Assistant tool provides rule specific details on what impact these SRS_RULES have on how the Generic SCADA Adapter responds to various forms of input. The adapter reloads SRS_RULES configuration when Service Recache button is clicked in Configuration Assistant.
Note: Only the rule names are listed here; use the Oracle Utilities Network Management System Configuration Assistant's Event Management Rules tab for details and to update the rules, if necessary.
• RT_PLANNED_OUTAGE_QUALITY
• RT_STALE_PROCESSING_CYCLE
• RT_CALCULATED_POINTS
• RT_CALCULATED_POINT
• RT_CONDITIONS_IN
• RT_CONDITIONS_OUT
• RT_RESPONSE_IN
• RT_IGNORE_TIMESTAMP
• RT_HEARTBEAT_CYCLE
• RT_LEC_KEY
Command Line Options for Generic SCADA Adapter
RTAdapter is the runtime service for the Generic SCADA Adapter. Its startup options select the SCADA interface, inbound measurement processing, outbound control handling, and connection security. Configure the required project-specific scripts and interface settings as described elsewhere in this chapter. Options marked for simulation require the stated offline or test mode.
Set startup options in the program or instance entries for the service in system.dat. Restart the affected service to apply changes. Startup options do not replace the database, rules, or interface configuration described elsewhere in this chapter.
The common Service startup options in the Configuration Guide also apply unless an adapter-specific option overrides them.
In the syntax below, angle brackets identify required values, square brackets identify optional values, and an ellipsis permits repetition. Enter values without the brackets and preserve the spelling and case shown.
Required Input and SCADA Identity
Configure all three required inputs together: -scada, -dir, and a nonzero -interval.
-scada <name>
Select the scada_ids.scada_name whose measurements are processed.
Prerequisites: Required at startup, together with -dir and a nonzero -interval.
The name must match an active entry in SCADA_IDS.SCADA_NAME. It selects the measurement identity, whereas -config can select a different active identity for adapter configuration. Use the exact configured name.
-dir <directory|RDBMS>
Select file input from a directory, or database input with the exact value RDBMS. Relative directories are resolved against the current working directory.
Prerequisites: Required at startup.
For file input the directory contains SCADA export scan files. For database input use the literal uppercase RDBMS, which selects the SCADA input tables instead of a file directory. Configure with -scada and -interval; neither input mode is selected just by supplying a SCADA name.
-interval <seconds>
Set the interval between processing cycles.
Prerequisites: Required at startup; zero is invalid.
The interval is the number of seconds between polling/processing cycles. Supply a positive integer. It also determines the elapsed time represented by the cycle count in -idle.
-config <name>
Select an alternative active SCADA_IDS.SCADA_NAME for loading adapter configuration while continuing to process measurements under the name supplied by -scada.
Default: The -scada value.
Use case: In an NMS MultiSpeak integration, RTAdapter and MultiSpeak may process measurements for the same SCADA identity but require separate configuration in SCADA_SYNONYMS, SCADA_STATES, and SCADA_LINKS. This option keeps those configuration sets from overlapping; it does not change the measurement identity selected by -scada.
-dbname <name>
Connect to the named DBService environment.
Default: The default DBService environment.
Select the same logical environment supplied to the intended DBService instance with -service; this is a database selection, not the RTAdapter message-bus process name. Without an override the adapter uses its default DBService connection.
-process_name <name>
Set the unique NMS message-bus identity of this adapter process.
Default: The -scada value; if that is empty, the executable argument is used.
Configuration dependency: When the program name in system.dat differs from the executable name, set -process_name to that configured program identity. Supply distinct names for multiple adapter instances. The name is also the target used by Action messages and must be consistent with the service configuration.
Measurement Processing and Files
-delimiter <character>
Use the first character of the value as the input-field delimiter.
Default: |.
For file input this separates fields in scan records. It can also delimit multiple external quality-code strings used by RDBMS-based input before they are mapped to internal integer codes. Supply a single intended delimiter character; only the first character of the value is used.
-idle <cycles>
Set the number of processing cycles without input before an alarm.
The unit is processing cycles, not seconds. The configured cycle length comes from -interval; consequently the approximate no-input alarm interval depends on both settings.
-lock
Use file locking to prevent input files from being overwritten during processing.
Applies to: File-based input only. Use locking where a producer can overwrite a scan filename while the adapter is reading it, for example when scan filenames are reused instead of being unique. This option does not lock RDBMS input tables.
-no_analogs
Disable analog measurement processing.
In RDBMS input mode, this prevents scanning SCADA_ANALOG_IN; analog measurements are not processed. Other enabled input processing is unaffected. The analogs_on and analogs_off messages control analog processing at runtime.
-noStaleProcessing
Do not generate stale (F) quality for measurements.
Useful in test/training environments where two adapter instances use the same SCADA points: disabling stale-quality generation in the appropriate instance avoids conflicting stale flags. This flag does not correct the source measurements or restore an external link.
-operate
Operate model devices when processing input; otherwise generate pseudo alarms only.
-retain
For RDBMS input, keep processed records in SCADA_DIGITAL_IN, SCADA_CONDITION_IN, and SCADA_RESPONSE_IN rather than deleting them after processing. Records are marked with their processed status so they can be inspected.
Depends on: -dir RDBMS.
Use: Validation and troubleshooting. This is not intended as general production retention or long-term logging; retained records can accumulate and need the project's cleanup procedure.
Outbound Controls and Simulation
Separate the production outbound-control script from the explicitly enabled test simulation behavior.
-controls <script>
Write outgoing control requests through the specified script, usually a project variation of rti-operate or rti-operate-curl.
Dependency: Required for outbound control-request processing. The named project/SCADA script handles digital open/close and analog set-point requests and normally invokes the external SCADA action. Configure the script for the project; enabling measurement input with -dir does not enable outbound controls by itself. Offline simulation uses its own response path.
-offline
Simulate control responses locally instead of sending control requests to SCADA.
Caution: Simulation only; use in a test environment.
For an incoming control request, simulate the external SCADA response and resulting device operation locally. Use -offlineDelay to simulate response latency and -batchResponse to group simulated responses within that interval. It is not a switch for connecting a production adapter to an offline database.
-offlineDelay <seconds>
Set the delay before simulated control responses.
Default: 10 seconds.
Prerequisites: -offline.
Caution: Simulation only; use in a test environment.
The delay is between receipt of a control request in offline mode and its simulated response, allowing a test to approximate external SCADA response time.
-batchResponse
Batch simulated responses within the offline response-delay interval.
Prerequisites: -offline.
Caution: Simulation only; use in a test environment.
-timeOffset <seconds>
Set the absolute time offset used for control-feedback simulation.
Caution: Simulation only; use in a test environment.
Incoming SOAP Connections
-port <number>
Select the port on which incoming SOAP requests are received.
-cert_file <filename>
Select the full path to the server PEM file used for incoming SCADA SOAP device/screen-navigation requests. The file contains the server private key concatenated with its certificate, as required by gSOAP.
Prerequisites: SSL-enabled build and a valid server key/certificate file. -client_cert additionally requires client authentication when SSL is configured.
Spelling: Use -cert_file; the -sslCertFileName spelling in older usage text is not accepted by this parser.
-client_cert
Require clients making incoming SOAP requests to authenticate with client certificates when the SOAP server uses SSL. This is a flag, not a filename option.
Depends on: A configured server certificate via -cert_file and an SSL-enabled build. Without SSL setup the client-authentication flag does not establish a secure connection by itself. The certificate must be presented by the connecting client; the server private key/certificate remains the file selected by -cert_file.
Help and Diagnostics
-help
Print RTAdapter startup usage and exit.
-debug [<level> | <facility> [level] ...]
Configure adapter diagnostics through the common Service debug parser. With no following value, set the default facility to level 2.
Notes: Adapter facilities include RT_NFY, RT_CALC, RT_CTRL, RT_PROC, RT_WATCH, RT_COND, and RT_STALE.
-watch <level>
Set the RT_WATCH diagnostic facility level.
Notes: Supply an explicit numeric level; the parser consumes a following value.
Generic SCADA Adapter High Level Messages
RTAdapter accepts high level messages to inspect adapter status and statistics, reload rules, and change measurement or outbound-control processing while it is running. Disabling processing or control actions affects the SCADA interface; review the effect of each command before use.
The common Service high level messages in the Configuration Guide also apply unless an adapter-specific handler overrides them. The entries below describe adapter-specific behavior and explicitly include inherited messages used in this chapter.
Send a request to the running service with:
Action any.RTAdapter <command> [arguments]
Use the configured process name if it differs from RTAdapter. The service target can contain a wildcard; select the intended service when changing state. Command names are normalized to lowercase; argument case follows the individual command. Output normally appears in the target service log. An acknowledgement can precede completion of the requested operation.
In the syntax below, angle brackets identify required values, square brackets identify optional values, and an ellipsis permits repetition. Enter values without the brackets and preserve the spelling and case shown.
Caution: Consult Oracle Support before first using diagnostic or maintenance commands, particularly in production. Commands can modify data, interrupt processing, or generate substantial output. Use sms-stop for routine service shutdown rather than the deprecated stop message.
RTAdapter
analogs_off
Disable analog processing.
Caution: Stops analog processing until it is re-enabled.
analogs_on
Enable analog processing and reset the analog measurements for processing.
control_actions <on|off>
Enable or disable outbound control actions.
Use: Oracle Support diagnostics.
Caution: Changes whether outbound controls can be processed.
debug [<level> | <facility> <level> ...]
Adjust diagnostics while RTAdapter is running through the inherited Service debug handler. A numeric level selects global verbosity; use 1 to enable basic global debugging or 0 to reduce global diagnostic output. With no argument the common handler toggles global debugging. Registered facility/level arguments are also accepted by that handler.
Use with input testing: Enable diagnostics before submitting a test scan file, then inspect the adapter log and resulting device/measurement state. Diagnostic output alone does not prove that an operation was applied; -operate, input selection, and the project configuration still determine processing.
Examples:
Action any.RTAdapter debug 1
Action any.RTAdapter debug 2
Action any.RTAdapter debug 0
Compatibility: The older file-input test example uses debug on. The current common high level message parser recognizes a numeric first argument as a global level; otherwise it expects facility/level pairs. Use the numeric forms above instead of relying on debug on or debug off as global switches.
dump
Print cached adapter state.
Use: Oracle Support diagnostics.
help
Print the adapter command reference to the service log.
Aliases: commands.
reload_rules
Reload RTAdapter rules and refresh the derived timestamp, quality, Flex SCADA, and interface settings.
report
Acknowledge an adapter status probe.
save_files [on|off|yes|no|true|false|1|0]
Enable or disable retaining processed files; omit the value to toggle. Reset the saved-file counter.
Use: Oracle Support diagnostics.
scada [0|1]
Set the SCADA link active with 1 or inactive with 0. With no argument, reapply the current link setting.
Caution: Changes the SCADA interface link state.
stats [minutes]
Print current processing statistics, or set the statistics cycle to a positive number of minutes.
Use: Oracle Support diagnostics.
stop
Stop the SOAP server when running, mark the SCADA link inactive, and stop the adapter.
Status: Deprecated.
Caution: Use the configured service shutdown procedure for routine operation.
Scripts Used by the Generic SCADA Adapter
The Generic SCADA Adapter calls various scripts to communicate and coordinate with an external SCADA system. Example scripts are provided. The example scripts use curl and expect the external SCADA systems will support some form of RESTful Web Service integration. You can create project-specific versions/variations of these scripts that are appropriate for a specific SCADA system.
Script | Description |
rti‑notify‑start | Notifies the SCADA system that the Generic SCADA Adapter has restarted. Call from RTAdapter on restart. |
rti‑operate | Example script for use with the RTAdapter controls option (for example, ‑controls rti‑operate). This script can either forward to SCADA or simulate a SCADA positive response when device control requests are sent from NMS. The rti-operate-curl script is a simplified version of the rti-operate script. It is an example of how to use curl to call an external system to propagate NMS initiated device operation requests to an external system. Either script (or a project alternative) can be specified via the "-controls <script>" command line option. |
rti-pseudo | pseudo measures are not actually telemetered from the field but may be maintained manually within a SCADA system. NMS identifies a pseudo measurement as having the corresponding scada_measurements_st.ttl=2 (see Understanding TTL). If a pseudo measure is changed by an NMS operator this script will be called to support optional propagation of the update to the external SCADA system. |
scada‑reload | Notifies the SCADA system that the set of measurements has changed due to an NMS model build. |
rti‑operate‑curl | Another example script for use with the RTAdapter controls option. Sends the control request to the SCADA system as a RESTful web-service request via curl. |
rti-condition | If RTAdapter is configured to propagate conditions (via the RT_CONDITIONS_OUT srs_rule) and a new/updated NMS condition inherits from the scada_out_tag abstract NMS class, this script will be called to propagate the condition. |
rti-emulator | Another example -controls <script> that can be used in conjunction with EMService to help simulate an external SCADA system. |
CES_PARAMETERS Configuration
The adapter needs to be restarted for CES_PARAMETERS configuration changes to take effect.
Parameter | Description |
SCADA_URL | Used to identify the external SCADA. RTAdapter will send navigation and SCADA controls to the SCADA system via this URL. The SCADA_URL should be the root URL. The scripts will add instruct, reload, navigate, etc. to the URL as needed. This is a site‑specific parameter. Legacy support only; not typically used. |
SCADA_CERT | The certificate to connect to the SCADA system. This is the client piece of a certificate generated by the SCADA system. This is a site‑specific parameter. Legacy support only; not typically used. |