Configuration/Execution Sequence

File-Based (RTAdapter)

To get RTAdapter up and running.

1. Login to Network Management System admin account with standard OPAL model configured and running.

2. Create RTAdapter specific RDBMS tables:

ISQL nms_schema_scada.sql

• creates scada_ids table

• creates scada_states table

• creates scada_synonyms table

• creates scada_links table

• creates scada_links_ops table

• creates scada_emulator_digital_out table

• creates scada_emulator_analog_out table

• creates scada_calc_func table

• creates scada_clac_alias table

ISQL nms_retain_scada.sql

• creates scada_points table

• creates scada_analog_in table (only used with "-dir RDBMS" option)

• creates scada_digital_in table (only used with "-dir RDBMS" option)

• creates scada_condition_in table (only used with "-dir RDBMS option)

• creates scada_controls table

• creates scada_response_in table (only used with -dir RDBMS option)

• creates scada_controls table

• creates scada_controls_st table

• creates scada_analog_history table

• creates scada_reg_dev_ops_history table

3. The OPAL_scada.sql file contains sample population data for the scada_ids, scada_synonyms, scada_states, ces_parameters, scada_calc_func, measure_placement_st, and measure_placement tables for the OPAL model. You must modify and rename this file for your project. The example below is for the OPAL model using file based updates (not RDBMS polling).

ISQL OPAL_scada.sql

4. Run "scadapop -partition 0 -initFile $NMS_DATA_FILES/OPAL_rti.dat -scada RTAdapter"

5. This should populate scada_measurements_st staging table - confirm that you have entries in this table before moving to the next step.

6. Validate the RTAdapter is in the $NMS_HOME/etc/system.dat file (see directions above).

7. Recommend using -watch and possibly the -debug options for RTAdapter to start; helps to identify configuration issues.

8. If the system.dat file is using the $NMS_SCADA_SCAN_FILE_DIR environment variable to specify the SCADA scan file directory, make sure this environment variable points to a directory that the RTAdapter process can both read and write. Generally, this means a directory owned by the id that is executing RTAdapter. For example, mkdir ~/scada. At the same time, suggest creating a test data holding directory (for example, mkdir ~/scada_tst).

9. Stop and restart Oracle Utilities Network Management System services (sms‑start).

10. Make sure RTAdapter is running.

11. The $NMS_HOME/templates/rtiadapter.dat.template file contains sample RTAdapter incoming data blocks. You can use the example data blocks in this file to validate basic RTAdapter functionality.

Example

Copy example data blocks from the rtiadapter.dat.template to individual test files under the RTAdapter scan file directory (normally ${NMS_SCADA_SCAN_FILE_DIR} – often ${NMS_ROOT}/scada. Copy files to ~/scada_tst (using the example configuration above). Cut example text out of rtiadapter.dat.template SCADA data file to "live" RTAdapter scan file directory to test.

1. Copy the following lines into a file (for example, BR2413_open).

DATA

OBJECT|BR2414

BREAKER_POS|OPEN

END_DATA

Copy the following lines into a file (for example, BR2413_close).

DATA

OBJECT|BR2414

BREAKER_POS|CLOSED

END_DATA

2. Copy BR2413_open and BR2413_close to ~/scada_tst (following example above).

3. cd ~/scada_tst

4. cp BR2413_open ~/scada

This should cause the BR2413 file to be read and processed by RTAdapter (you should see the BR2413 device open in the standard OPAL model).

5. cp BR2413_close ~/scada

6. This should cause the BR2413 file to be read and processed by RTAdapter (you should see the BR2413 device close in the standard OPAL model).

7. Follow other examples for conditions and quality codes.

8. Turn debug on RTAdapter to see what is going on. You should be able to send RTAdapter debug messages on the fly:

Action any.RTAdapter debug on

9. Validate that devices are changing state in the Network Management System Viewer as you execute steps 4 and 5 (cp BR2413_open ~/scada followed by cp BR2413_close ~/scada). Repeat as necessary to validate that the files are being processed as expected.

SCADA Data - File Input

When RTAdapter is configured to poll and process files, the SCADA system sends fixed format files. The following format rules generally apply:

Note: RTAdapter (in file mode) supports two different input file formats.

The original RTAdapter input file format uses "DATA" and "END_DATA" type constructs and requires at least two lines for every measurement. The original format supports analogs, digitals and conditions and is what is mostly referenced in the documentation below.

If an RTAdapter input file ends with a ".csv" suffix it will be interpreted as a comma separated value field file for a similar purpose. The *.csv file format only supports analogs and digitals (not conditions at this time). The file format ignores the first line (assumes it is a header). Actual data fields are positional and at least the first 3 values must be provided. Below is an example of a fully populated *.csv file.

rti_alias,value,quality,phase,date,scada_id

BR2412,CLOSED,0,7,05/17/2021 19:00:00.999,100

Quality represents any SCADA specific quality measures (>= 2^^16). Phase will default to 7 (ABC), date will default to current time and scada_id will default to the scada_id for the relevant RTAdapter. If milliseconds are provided they must be the last 4 digits of the timestamp and must begin with a period (.) separating milliseconds from the rest of the time stamp. The timestamp can otherwise be GMT (in seconds) or any timestamp format supported by DATEMSK processing.

Non ".csv" file format (any file that does NOT end in ".csv" is described below):

1. Actual SCADA data appears between ^DATA (the string DATA at the start of a line) and ^END_DATA.

2. Records between DATA and END_DATA are identified by OBJECT which must match a unique analog_measurements.rti_alias or digital_measurements.rti_alias entry.

3. SYNCHRONIZE|TRUE is a special case used to synchronize conditions and is outside the standard DATA/END_DATA block. If set the line following SYNCHRONIZE|TRUE should be something like TYPE|note - to indicate the data that follows is to be used to synchronize "note" class conditions. For SYNCHRONIZE scan files, the condition action code should be "syn" - not "add" or "rem".

4. All other fields are generally ignored.

5. For digital_measurements: device status: open or closed, battery low, and so on. Example:

DATA

OBJECT|BR2414

BREAKER_POS|OPEN

END_DATA

Full (all) options example with phase (1->7) and scada_id (defaults to the scada_id of the RTAdapter processing the file). Note that scada_id is typically only needed in complex configurations where multiple SCADA adapters are concurrently active. The optional quality field (if provided) represents an external quality code (must be >=65536).

DATA

OBJECT|BR2414|7|100

BREAKER_POS|OPEN|65536

END_DATA

6. For analog measurements: In this example, Amps_A=attribute 1501, Amps_B=attribute 1502, Amps_C=attribute 1503:

DATA

OBJECT|BR2414-1501

AMPS_A|2.1|4096

OBJECT|BR2414-1502

AMPS_B|2.2

OBJECT|BR2414-1503

AMPS_C|2.3|SUSPECT

END_DATA

Both digital and analog measurements can include quality codes for each attribute. Quality codes are part of the standard Oracle Utilities Network Management System attribute definition and are contained within a 32-bit integer field. Bits 0->15 are reserved for Oracle Utilities Network Management System purposes and will NOT be processed by RTAdapter (they will be ignored). Bits 16->31 are available for project specific configuration. Quality codes are generally defined in the quality_codes configuration table. In the analog example above (AMPS_C|2.3|SUSPECT) the SUSPECT string must be defined in the scada_states table and map to a valid quality code integer. Integers can also be used directly to provide quality codes (AMPS_A|2.1|4096).

7. Generic SCADA conditions (generally notes or tags - could be any condition) are also supported. To send a condition something like the following would be required:

DATA

OBJECT|BR2414

END_DATA

The above text would "add" a note condition to the model on the device mapped to BR2414. The following keyword phrases can be used to specify common condition fields:

8. WHO= who should be recorded as the creator of the condition - must be a valid NMS user name, the "system" (NMS Admin user name), or the name of the SCADA system that sent the update.

9. PHS= What phase to declare a condition for. This is a bitmask field representing affected phases. 1=A phase, 2=B phase, 4=C phase. 7=ABC phase, etc. If specified, it must be >= 1 and <= 7.

10. TIM= ISO timestamp for when the condition was added. Timestamp format must be defined in your $DATEMSK file.

11. TXT= Text string for the condition.text field (notes.text. tags.text, etc). Condition text string cannot contain newlines or the separator character - whatever it is configured to be. Text will truncate at the first newline or separator character.

12. EXT= SCADA unique identifier for the created condition. This field is necessary to allow the external system to later remove the condition.

13. To remove the SCADA condition above:

DATA

OBJECT|BR2414

NOTE_0|rem|WHO=system|TIM=2009-10-27T16:22:17|EXT=BR2414-note_0

END_DATA

RDBMS Table Polling (RTDBAdapter)

To get RTAdapter to use the RDBMS queue table mechanism (rather than file-based polling), follow steps similar to the following:

1. Follow steps (1-5) as noted above for the file based polling example above.

2. In the ~/etc/system.dat configuration file verify the RTAdapter option -dir RDBMS.

3. If the -dir option is set to anything other than keyword RDBMS, RDBMS polling will NOT be enabled.

4. Recommend using -watch and, possibly, the -debug options to help identify configuration issues.

5. Stop and restart Oracle Utilities Network Management System services (sms‑start).

6. Make sure RTDBAdapter is running.

7. Insert row into SCADA_DIGITAL_IN table either using alias or h_cls and h_idx with status = 'N'. Either the unique alias or the h_cls/h_idx must be specified, but not both.

8. The primary key on the scada_digital_in table is the id column – which is generally populated by a trigger on the scada_digital_in table that fires on insert and populates the id column with the next value in a sequence. Other example RDBMS input examples can be found in the $NMS_ROOT/templates/rtadapter.dat.template file.

Example sql statement:

INSERT into scada_digital_in (

alias,

phases

operation,

operation_date,

quality

source,

status

) VALUES (

'BR2414', /* Unique measurement name */

'7', /* Phase bitmask - 7=ABC, 1=A, 2=B, 4=C, etc */

'0', /* Defined in scada_synonyms - 0=open, 1=close */

SYSDATE,

'0', /* Quality bitmask - value >65535 and <2^32 */

'SCADA',

'N'

);

COMMIT WORK;