Table of Contents

Introduction

The RediGate is a multi-application remote data communications computer/data integration device.  It provides a wide array of SCADA and other communication and logic processing functionality.  In order to configure the operational characteristics of the RediGate, Elecsys provides the Advanced Configuration Environment (ACE) program. 

The RediGate allows for programmable logic routines to be included in its ACE configuration, called PODs (for “Programming On Director”).  This allows some reasonably complex operations to be performed during the RediGate’s operation, such as examining or changing contents of data registers, performing logical decisions or mathematical computations, publishing data, and a variety of other functions. 

Unlike ISaGRAF, which requires a third-party software development environment and generates a reusable, multi-module logic program that is semi-autonomous from the RediGate configuration, the POD logic routines are small, individual programs built into each configuration and may be more easily customized for the needs of a specific device.  Both ISaGRAF logic and POD routines may be used in the same RediGate, if desired.  Refer to the RediGate Configuration Manual for more discussion on the differences between ISaGRAF and POD logic.

It is assumed that the user has already installed the ACE Editor and is familiar with the ACE configuration tools.  Please refer to the ACE Operation Manual for more details on using ACE to configure basic RediGate features such as master or slave protocol communication.

POD Programming

Historically, the RediGate has supported the ISaGRAF programming environment for adding functional logic programs that provide a wide variety of powerful application development options.  ISaGRAF provides a full-featured application development environment, allowing the RediGate to operate as a programmable logic controller (PLC) in addition to its built-in routing, protocol translator, and host data publishing capabilities.

However, some applications only require a small to moderate level of programmability, such as manipulating or making decisions on data stored in real-time databases (RTDBs).  For these types of requirements, the RediGate now supports the POD (Programming On Director) capability.  POD programming is similar in concept to Assembly Language programming, having a list of opcodes having one or more parameters.

There can be up to 9999 PODs per Internal Master Channel.  The following sections describe how to program POD modules in the RediGate’s ACE configuration.

POD Configuration Structure

POD objects are executed by the Internal Master Channel, by calling an Internal Master Poll Table entry that references the POD definition.  The Internal Master RTU object determines which POD will be executed and the Scan Table determines when it is called.  More than one Field Unit in the Internal Channel can call the same POD.

To run a POD program, the following set of ACE objects need to be configured:

Internal Channel       Configure Scan entry points to a Poll Record of an Internal Master field unit that’s configured to run a POD.  The Scan Table entry is used like any other Scan Table entry (Unit Address and Poll Record point to the Internal Master Poll Table entry, and the Scan Period determines the frequency at which the POD will be executed, sequentially with other Scan Table entries in the list).

Null Circuit – Placeholder for Internal Master field unit

Internal Master – The Internal Master FieldUnit may contain other Poll Table entries for data transfers between RTDBs.  One or more Poll Table entries may also be configured to point to a POD object, which will contain the programming instructions to be run.  The normal Source/Destination fields of the Internal Master Poll Table have special uses when calling a POD program.

The Poll Table entry for a POD routine should contain:

• Src Chan – The Source Channel column for a POD poll entry MUST be any valid Master Channel in the RediGate configuration. Otherwise, the Src Chan, Src RTU, Src Data, and Dest Data parameters are not used in the Poll Table entry and may typically be set to 0. However, these columns may be used to pass important information into the POD. There is a POD function ("GET COLUMN FROM POLL RECORD") which can read values from these fields of the Poll Table row that called the POD.

• Src RTU – Unused for POD, but can be used for a configurable parameter (see note for “Src Chan”, above).

• Src Data – Unused for POD, but can be used for a configurable parameter (see note for “Src Chan”, above).

• Src Type – Select the “Run POD” option to use this poll record to call a POD function.

• Src Count – This must be set to the instance number of the POD object in the ACE configuration.

• Dest Data – Unused for POD, but can be used for a configurable parameter (see note for “Src Chan”, above).

The screen capture below shows an Internal Master unit with a regular poll in Poll Record 1 and a call to a POD function in Poll Record 2. Both polls would need to be scanned by the Internal Channel in order to operate, and a POD object with instance number 5 would also need to be configured with one or more program steps.

Open

RTDB – All FieldUnits require an RTDB definition.  The POD is associated with the RTDB for whichever instance of the Internal Master FieldUnit that triggered it.  Programming instructions act on the RTDB registers associated with that Internal Master FieldUnit.

POD – Include one or more POD object with programming logic instructions. Configuration of the POD object and the available instruction types are described in the remainder of this manual.

POD programs may use RTDB registers for storing or using data during program execution.  There is also a Scratchpad area containing 40 elements (numbered -1 to -40).  The Scratchpad elements may use any of the following three data types:

• 32-Bit INTEGER.  These are used for BOOLEAN (Zero=False, Non-Zero=True), CHAR, SHORT integer, and LONG integer data.

• 32-Bit REAL (Floating Point)

• 256-Byte STRING

When the RediGate restarts, the values in Scratchpad areas are all set to zero/empty and the type is set to INTEGER. Scratchpad elements are global to a Channel (shared in common among all PODs and devices on a Channel), but each Channel has its own set of numeric Scratchpad elements (-1 to -40). An element in the Scratchpad can have its value and type changed each time a POD program writes to it.  Once written to, the element retains its value and type (INTEGER, REAL or STRING) until the next write, even between successive executions of different PODs.

For example, writing a REAL value (such as 3.14159) to element ‘-5’ makes that element into a REAL type, and the value can be accessed as the same.  Later, a STRING value (such as “Hello, World”) can be written to element “-5”, which changes the element’s type to STRING.  The next read of element ‘-5’ will return “Hello, World”.  When POD programs need to use intermediate values in calculations, it is much faster to read or write Scratchpad elements than the read or write RTDB registers.

The POD maintains a row execution counter which is used to prevent infinite loops.  If the POD Interpreter does not return to the normal Internal Master Scan Table within this limit, then the POD Interpreter routine is aborted.

POD Object

The POD object holds one set of programming instructions to be called by the Scan Table based on the Scan Period.

The following sections below describe some additional help in programming with PODs, the Functions used in the POD programming instructions, and some application examples using  PODs.

Rules for Using the Result Addr

Here are some rules for the Result Addr parameter of the POD Instruction list, when storing a value.

1. Saving result to Scratchpad elements [-1 to -40].

   1. When the Cast Result as is BOOLEAN, CHAR, SINT16, or SINT32 – The Scratchpad data is stored as INTEGER. If the original value was REAL, then the value is truncated at the decimal point before being stored.  If the original data was STRING, then the atoi() function (Alpha to Integer) converts the string to an integer. 

   2. When the Cast Result as is REAL32 – The Scratchpad data is stored as REAL.  If the original value was INTEGER, then the value is converted to a REAL.  If the original value is a STRING, then the atof() function will convert the string to a floating point value.

   3. When the Cast Result as is STRING-32 or STRING-256 – The Scratchpad data is stored as STRING.  If the original value was INTEGER, then the “%d” C format is used to convert the integer to a string.  If the original value was REAL, then the “%g” C format is used to convert the floating value to a string.

2. Saving result to RTDB registers of the following types using INTEGER functions.

   1. Boolean register: Non-zero INTEGER stored as True, Zero stored as False.

   2. UINT8 register: Least Significant Byte of INTEGER stored in register.

   3. SINT16/UINT16 register: Least Significant Word of INTEGER stored in register.

   4. SINT32/UINT32 register: Entire INTEGER result will be stored.

   5. REAL32 register: INTEGER result will be converted to floating point and stored.

   6. STRING-32/256 registers: INTEGER result stored as formatted string.

3. Saving result to RTDB registers of the following types from REAL functions.

   1. Boolean register: Non-zero value stored as True, Zero stored as False.

   2. UINT8 register: Least Significant Byte of the REAL value after it has been truncated to an Integer.

   3. SINT16/UINT16 register: Least Significant Word of the REAL value after it has been truncated to an Integer.

   4. SINT32/UINT32 register: REAL value will be truncated to an Integer and stored.

   5. REAL32 register: REAL value stored directly.

   6. STRING-32/256 registers: REAL result will be formatted using the “%g” C format.

4. Saving result to RTDB registers of the following types from STRING functions.

   1. Boolean register: Non-zero STRING stored as True, Zero stored as False.

   2. UINT8 register: Up to 256 registers will receive one corresponding byte from the STRING.

   3. SINT16/UINT16 register: Up to 128 registers will receive two corresponding bytes from the STRING, with the first ASCII character in the least-significant byte.

   4. SINT32/UINT32 register: Up to 64 registers will receive four corresponding bytes from the STRING with the first ASCII character in the least-significant byte.

   5. STRING-32 register: First 32 characters of the STRING will be stored, the remainder will be truncated.

   6. STRING-256 register: Entire STRING will be stored.

POD Editing Tips

The following tips will be helpful suggestions when creating the POD Instruction list.

1. Create a row with the Function set to **COMMENT**, with zeroes in all of the numeric columns, and “...” in the Operand Type column.  Then select this row and press the “Insert Before...” button dozens of times to create dozens of new identical rows.  Then modify these rows to write the POD routine.

2. If you know the first few letters of the ‘Function’ then move the cursor to that column and type a few characters and then press ALT-DOWN-ARROW.  This will highlight the first matching entry from the list of 100+ Functions. If the exact Function that you want was highlighted, then you either need to LEFT CLICK on the entry or use DOWN ARROW followed by an UP ARROW and then press the ENTER key.

3. Labels may be easier to read by starting them with two hyphens (--) and then up to 9 more characters, entered in the Operand column.  This label is used in the GOTO LABEL for ‘FOR LOOP’ Functions.  Labels are case sensitive.

4. Integer values in the Operand column can start with a lower case ‘x’ to indicate the value is in hexadecimal.  For example, 255 and x0ff are the same integer value.

POD Programming Tips

Here are some additional tips for programming techniques in writing POD program routines.

1. Use the DiagLog function to view intermediate values or determine flow of routine.

2. When designing a program, you can use RTDB registers to store the function's intermediate calculations/results, which will slow the execution speed, but allow you to more easily access the values to troubleshoot problems. Later, you can increase execution speed and reduce use of RTDB registers by converting the program to use ScratchPad elements for storing the intermediate results, if you choose.

3. A quick technique to pass a couple of configuration parameters to a POD routine is to use the Internal RTU’s Poll Table ‘Src Data’ column or ‘Dest Data’ which are not required for normal POD execution.  The ‘GET COLUMN FROM POLL RECORD’ function will use a ‘2’ for ‘Src Data’ and ‘5’ for ‘Dest Data’.

4. The ‘DUMP SCRATCHPADS’ Function will dump the contents of all of the elements to the file /tmp/director/S_PADpp.rr.txt where ‘pp’ is the POD Index and ‘rr’ is Row Number used making the call.

5. A technique to implement an expiration timer is to call either the CENTI-SEC CLOCK or GET TIME functions and save the results to a 32 bit integer.  Then add the number of 1/100s of seconds to the CENTI-SEC CLOCK value or whole seconds to the GET TIME value.  Then compare the current CENTI-SEC CLOCK or GET TIME values to determine if a timer has expired.

6. It is handy to use the ‘PreInitRTDB.ODF’ object to setup groups of configuration parameters for functions such as MODBUS WRITE, COPY BLOCK, HTTPPOST or any other function that uses the Operand value as a reference to a start of a block of configuration parameters.  Also use PreInitRTDB to setup longer strings (31 chars at a time) versus the 11 at a time max in the ‘Operand’ column.

7. String SEARCH and REPLACE can be implemented using the BIT_OR/XOR with BIT_AND functions.  The ‘Source Addr’ data string is searched for all occurrences of Operand Strings and replaced with “<~Or?>” string(s) using the BIT_OR Function.  Then you will call the BIT_AND which will search the ‘Source Addr’ data string for “<~Or?>” and replace all matches with the Operand String.  The BIT_XOR will only search for the first occurrence of Operand String.

8. If you have some knowledge of writing Linux shell scripts then you can use SYSTEM CALL to echo text to an output file in /tmp/director/ and then call the script.  You should output the results of shell scripts to something like /tmp/director/ResultXX.txt.  You can use the OPEN_TEXT, FIND_TEXT, etc., to read the contents of these result files.

9. How to use XML functionality.  If you need to work with XML formatted string data, you can use the following techniques.

   1. Open XML text file with TEXT OPEN function call.  This reads the file into an allocated memory buffer.  Parent Sections must begin as <ThisParent> and terminate with </ThisParent>.  Child Sub-sections must begin with <ThisChild> and terminate with </ThisChild>.

   2. Get the count of Parent sections to read with XML GET COUNT.  Set String-0 to the Parent/Major section name with a NULL string in String-1 and String-2. String-1 would normally be Parent Section name so setting it null indicates that there is not a Parent Section.  A technique to place nulls into strings is to call INTEGER to ASCII with Constant 0 in Operand.  The Major section name should be something like… <remote  …or…   <channel  …as long as it begins with a Greater-than symbol.

   3. Get the count of Child/sub-sections in current Parent/major section with String-0 as the Child/Sub-section name, String-1 as Parent Section name, and String-2,3 set to null. 

   4. Read the attributes of the Current Parent with XML GET FIELD using String-0 as Parent Name, String-1 set NULL (No parent of this field) and String-[2-9] as Attributes retrieved for this Parent.  Strings[2-9] should be look like… address=  …or… interface=  …etc.  The ‘Result Address’ for the XML GET FIELD function is actually used as a starting address of STRING-32 for values of associated Attributes found in Parent.  Each Value String will have original Attribute string requested.  Remove the original Attribute string (address=) with STRING TRAILER and associated Attribute for Value without attribute.  Double quotes that can be removed with ‘- Subtract’, STRING as is, “ which will removed all double quotes.  Lastly STRING VALUE can convert the ASCII Value string into an Integer.

   5. Read attributes of each Child/Sub-section (String-0) with String-1 containing the Section’s Parent name.  Strings[2-12] are the Attributes to be searched for this child.  You can request more Attributes than might be found in the Child’s sub-section.  Attributes can be like… lowlimit value=  …or… normalstate value= …or… maximum delta= .  The Attributes can be continuations of elements in the Child Declaration header or as their own <attrib=”content” /> entries before the </ThisChild> marker.  Once the XML GET FIELD reads a Sub-section set of attributes it eliminates the marker starting this Child’s Sub-section.  This prevents searching and finding this Child a second time.

   6. After getting the field data for the last Child under the current parent you must call XML NEXT FIELD to eliminate this section’s Parent Marker so that the next Parent will be processed.

POD Programming Examples

This section gives some examples of POD programs to illustrate the POD programming methods.  The sample ACE configurations for the programs illustrated here can be downloaded from https://ftp.elecsyscorp.com/ACE/PODDemoConfigurations.zip

See the RediGate Configuration Manual for a more complete explanation of the configuration properties of the individual ACE objects.  This section will primarily focus on explaining how the POD logic works, with only minimal discussion on the other parts of the configuration.

Unlatch Relays Example

This example shows how to use a POD to monitor one or more digital registers for a transition from False to True.  After the signal becomes true, a configurable timer is started.  Once the timer expires, the POD clears the digital register back to a zero.

The background of this example is that a host system writes a Trip signal to the RediGate, which may be read or used by other processes.  But the host only sets the Trip value to True and doesn’t clear it, requiring the RediGate to clear the point itself.

UnlatchRelays-PODdemo ACE Configuration

Open the example configuration in the ACE editor. 

For purposes of this example, the data coming from a host system is simulated by writing into Virtual RTU 4 using a Custom Report.  The Internal Master RTU 5, along with the POD 99, demonstrate the POD programming logic to read and clear the input data points after they are tripped.

This section provides an overview of the parts of the configuration that will be important for understanding this demo.

Open

• Virtual RTU 4 – Provides RTDB data location, simulating data that would be coming from the host computer.  Registers 1, 3, and 9 are the digital points being written into with Trip signals and cleared by the POD logic.

• Internal Master RTU 5 – The Internal Master RTU reads the data internally from RTU 4 into its own RTDB, then runs the POD logic for each of the monitored points (1, 3, and 9).  The Internal Master’s Poll Table uses two rows per point to be monitored for Trip values.  In each pair of registers, the first row copies the point value from the source RTDB (channel 14, RTU 4) to the Internal Master (RTU 5).  The point number in the source and destination databases are the same, and the same number must also be used in the 2nd row of each pair for the Src Data column (this is read by the POD function).

  Open

  

           Internal Channel 14 – The Internal Channel contains the Virtual and Internal Master RTUs, and its Scan Table continuously scans the six poll records of RTU 5.

• PreInit Data (RTU 5) – The Pre-Initialized Data object stores some default values into the RTU 5 database on startup of the RediGate.  These values will be explained in more detail in a later section.  The most important of these points is the first, register 41099.  This is set to a value of 10, which is the number of seconds for the timer.

Open

• POD – The POD program exists as a child object under the Internal Channel (arbrarily set to instance #99 in this example).  The details of each step in the POD logic will be explained in more detail in a later section.

• Custom Report – A Custom Report is used to give an easy user interface for entering simulated data and seeing the results of the POD activity.

Open

Using the UnlatchRelays Example

If necessary, modify the Ethernet address in the example and download the configuration to a RediGate.  After restarting with this configuration, log in to the RediGate’s user menu and go to the Diagnostics menu.  Select option 535, View Custom Reports.

Enter ‘99’ for the custom report number, and ‘1’ for the refresh rate.  In the custom report, the “DO1”, “DO3”, and/or “DO9” entries will be written to a value of 1 to simulate incoming data from a host system.  Once any of these signals goes to ‘ON’, the “PO1”, “PO3”, and/or “PO9” will also be set to ‘ON’.  These are registers in the Internal Master RTU 5 used to keep track of the current state of the input.  After 10 seconds, both of these values will be reset to ‘OFF’ by the POD logic.

With the Custom Report pointer on the DO1 value, enter ‘C’ to change a value.  Enter a value of ‘1’ for DO1, then Enter again to return to the Custom Report screen.  The “DO1” and “PO1” should be ‘ON’ for about 10 seconds, then both switch back to ‘OFF’.  The same can be done with “DO3” and “DO9”, but changing “DO2”, “DO4”, or “DO5” will not have the same effect, because the configuration is not set up to monitor those points.

Open

Understanding the UnlatchRelays POD Logic

This section gives a detailed explanation of the POD program for the UnlatchRelays example.  For more general information about each instruction type in the POD program, see the POD Function List.

Open the Instructions table for the POD in the example program.  The following paragraphs describe what each instruction does.

This instruction is just a comment.  Comments are used throughout the POD to provide a brief description of what follows (“SETUP”), but also to break up the POD into sections as a visual aid when analyzing the program’s function.

These rows define the POD’s Scratchpad registers [-30] and [-31] to be constant values of 0 and 1, respectively (everything after the space is ignored and treated as a comment).  The ASSIGN function assigns the constant value contained in the Operand column to the Scratchpad register given in the Result Addr column.

These rows get a value from the Poll Record of the Internal Master of RTU 5.  This instruction refers to the Poll Table record that called this execution of the POD function.  The Operand column contains a constant pointing to the column (starting from 0).  For example, the 4th row in the Poll Table has the following entries:

The two POD rows read column 2 (Src Data) into Scratchpad register [-32], and column 5 (Dest Data) into Scratchpad register [-33].  These values represent the RTDB register number of the point to be examined, and the POD’s index number for this point, respectively.  The index number is a consecutive number starting from 0, used to keep track of each point and their timers individually.

This row adds the value in Scratchpad [-33] (index number) to the constant 41001, and stores the result into Scratchpad [-34].  This will be the register holding the timestamp for each point whenever the Trip value occurs.  Registers 41001 through 410xx are required to exist in the RTU 5 database, depending on the highest index number used.

This row does an Indexed Get (indirect read of an RTDB register).  The value in Scratchpad [-32] contains a number of the RTDB register of the data point.  The value stored in that register is read into register 10097 in the Internal Master.  Note that this the Internal Master Poll table must have already polled the data from its original location into the RTU 5 database before this function is called.  As an example, the 3rd row in the Poll Table reads register 3 (Channel 14, Unit 4) into RTU 5 at register 3.  This is the “Current” value of the point.

These rows add 10000 to the Scratchpad [-32] and stores the result into Scratchpad [-35].  This will create a value pointing to a 100xx register in RTU 5.  Then an Indexed Get takes the value from the 100xx register snd stores it into register 10098.  This is the “Previous” value of the point.  The Current and Previous values of the point will be compared below.

Row 12 performs a comparison between register 10097 (Current) and the constant of 0 in the Operand column.  The result is stored into Scratchpad [-36], which is checked in the next row – a True indicates that register 10097=0 (current value of register is not tripped), which triggers the EXIT function in the POD, returning control back to the Internal Master Channel.  No further instructions are run on this execution of the POD.

Row 15 checks register 10098, and if true (previous value of coil is ON), jump to the POD instruction with the label “--CHKLIMIT” (Row 24).  When the original coil is first set to ON, this GOTO statement doesn’t occur, but does happen on subsequent executions of the POD, until the timer expires.

Rows 16 through 22 are only executed when the point value goes from OFF to ON.