...
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 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.
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.
...
The POD object holds one set of programming instructions to be called by the Scan Table based on the Scan Period.
...
Attributes | Function |
---|---|
Object Type | DirectorPod |
Parent(s) | System → Clients → Master Channels → Internal Channel |
Instance | Must be between 0 and 9999. The instance number is the POD number in the Poll Table ("Src Count" column) used for running the program. |
...
Properties | Values |
---|---|
Row Delay | Enter the amount of delay (in milliseconds) to insert after each instruction in the list of Instructions is executed. Entering 0 will allow the POD to run as fast as possible. Inserting non-zero a delay will help debug a POD by slowing it while viewing diagnostics and enables more diagnostic messages from the POD interpreter. |
Max Instructions | Maximum number of instruction rows that can be executed per scan in the sequence of the POD program. This includes all instructions executed while inside a program loop. This parameter is designed to prevent the POD program getting into an infinite loop based on incorrect design of a POD program. Set this to 0 to disable loop testing. This might be used, for instance, with a POD routine that never needs to exit, or which loops through several hundreds of instruction lines. |
Instructions | Click the Edit Table button to enter the sequence of instructions of each POD program. The POD program instructions are executed top to bottom each time the POD is triggered using a Scan Table entry in the Internal Master. Enter the data in the columns of the table. Source Addr – The Source Addr column either refers to the location of data in the Field Device RTDB, or values in one of the Scratchpad elements (-1 to -40). The type of data from the RTDB/Scratchpad sets the data type for the entire row to either INTEGER, REAL or STRING. (A Function can change the data type that will be saved to the Result Address). Some functions ignore the Source Addr parameter. Function – There are over 100 "Functions" available as POD programming instructions. Some functions only accept only one data type (Integer, Floating point, String), while others can accept two or all three data types. See POD Function List for a complete description of the available programming instructions. Operand Type and Operand – The Operand Type column determines how to interpret the 11-character string contained in the "Operand" entry. The Operand is normally used by the simpler functions (+,-,*,/, AND, OR, XOR, etc). Some Functions ignore the "Operand".
Result Addr – The Result Addr column can be either a register address in the RTDB of the Internal Master field unit, or one of the Scratchpad elements (-1 to -40). See Rules for Using the Result Addr for rules on how the Function output will be converted based on the destination type. Cast Result As – The Cast Result As column determines the output type of data, when the Function operates on a numeric value. The data type (Boolean, UINT32, FLOAT, STRING-32, etc.) must match the data type configured for the Result Addr register in the RTDB. |
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.
...
- 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.
- 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.
- 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.
- 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.
- Use the DiagLog function to view intermediate values or determine flow of routine.
- 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.
- 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’.
- 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.
- 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.
- 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.
- 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.
- 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.
- How to use XML functionality. If you need to work with XML formatted string data, you can use the following techniques.
- 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>.
- 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.
- 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.
- 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.
- 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.
- 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 http://ftp.elecsyscorp.com/ACE/PODDemoConfigurations.zip
...
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.
...
Row | Source Addr | Function | Operand Type | Operand | Result Addr | Cast Result As |
23 | 0 | ** COMMENT ** ... 11 Chars in Operand. Not a LABEL (Src and Result Ignored) | STRING as is (Eleven Characters) | ..... | 0 | SINT32 |
24 | 0 | LABEL ONLY in Operand as a STRING (Src and Result ignored) | STRING as is (Eleven Characters) | --CHKLIMIT | 0 | STRING-32 |
25 | -34 | INDEXed GET : SourceAddr value is RegAddr used as SrcData=> ResultAdr : Operand Ignored | Constant (Integer or Floating Point) | 0 GetLimit | -37 | SINT32 |
26 | -40 | GET TIME Src/Oprnd=Ignored Result> INT16[0-6]=YYYY,MM,DD,HH,MM,SS,ms INT32=1970+Secs STRING=YYYYMMDD-HHmmSS.ds | Constant (Integer or Floating Point) | 0 Seconds | -38 | SINT32 |
27 | -38 | < LESS THAN Operand? (Including String Compare) | RTDB Address (or Scratch-Pad[-1 to -40]) | -37 Limit | -39 | SINT32 |
28 | -39 | EXIT Stop this POD processing Src=Enable | Constant (Integer or Floating Point) | 0 EXIT | -40 | SINT32 |
Rows 24 through 28 compare the current date/time with the augmented date/time for this point, and exit the POD if the time hasn’t yet exceeded the configured delay timer. Row 24 is the label “--CHKLIMIT”, used in a previous GOTO statement. Row 25 does an Indexed Get from the register contained in Scratchpad [-34] (410xx register) and stores the augmented date/timestamp into Scratchpad [-37]. Row 26 gets the current date/time from the RediGate and stores into Scratchpad [-38], then a comparison is made whether current time is less than the stored timestamp. If so (Scratchpad [-39] is True), then exit the POD.
...
The following sections describe the operation of the Functions used in the POD instruction list. There are over 100 "Functions" available. Some functions only accept Integer or Floating point or String data while others can accept two or all three data types.
- Function Reference Chart gives a categorized cross-reference of functions based on function type.
- Commonly Used Functions describes many of the most essential functions.
- Other Functions describes the remainder of the function list in alphabetical order.
...
Function | Description | # |
CENTI-SEC CLOCK | Returns the current system time in 1/100ths of a second. | 92 |
CHANNEL CONTROL | Enable or disable a RediGate master channel. | 121 |
DIAGLOG | Enter a message in the RediGate’s diagnostic log. | 27 |
FORCE POD RTU STATUS | Set the status of the Internal Master POD RTU. | 104 |
GET CHANNEL NAME | Return Master Channel name from RediGate configuration. | 127 |
GET COLUMN FROM POLL RECORD | Get a value from the Poll Table record that called this POD routine, allows values to be passed into the POD. | 103 |
GET RTU STATUS | Get the status of a FieldUnit | 108 |
GET TIME | Get current RediGate system time. | 65 |
MY RTU ADDRESS | Get RTU address of Internal Master RTU running the POD. | 75 |
RTU NAME | Return RTU name from Director configuration. | 30 |
SET RTU STATUS | Set the communication status of an RTU in the RediGate. | 101 |
SYSTEM COMMAND | Issue a system call to a shell script or command line function. | 20 |
UNIT NAME | Return Linux system name (set in configuration). | 29 |
...
I/O board functions
Function | Description | # |
PC-104 DS-DMM-16-AT | Access I/O on the PC/104 DS-DMM-16-AT board. | 115 |
PC-104 IN-8 | Read digital I/O on the PC/104 IN-8 board. | 48 |
PC-104 IN-16 | Read digital I/O on the AIM104-IN16 board. | 49 |
PC-104 MULTI-IO-16se | Read I/O on the AIM104-MULTI/IO board (16 single-ended analogs). | 52 |
PC-104 MULTI-IO-8-DIFF | Read I/O from the AIM104-MULTI/IO I/O board (8 differential analogs). | 107 |
PC-104 OUT-8 | Write outputs to the AIM104-RELAY8/IN8 relay outputs. | 50 |
PC-104 OUT-16 | Write outputs to the AIM104-OUT16 digital outputs. | 51 |
PC-104 TS-ADC16 | Access I/O from the PC/104 TS-ADC16 board. | 113 |
...
Function | Description | # |
ASYNC-IN | Read data on an acscomm serial port. | 23 |
ASYNC-OUT | Send data to an acscomm serial port. | 22 |
CHECK HTTPPOST | Check the response of an HTTPPOST function. | 68 |
DB9-READ | Read CTS and DCD signals from serial port. | 56 |
DB9-WRITE | Write RTS and DTR signals to serial port. | 57 |
HTTPPOST | Send a POST message to an HTTP server. | 19 |
MODBUS WRITE | Send a Modbus write communication command. | 24 |
MQtt SEND CMD | Publish a message using MQTT protocol. | 120 |
PARSE MQtt RBE | Parse an MQTT RBE message. | 119 |
PUBCONN | Return connection status with MQTT broker. | 42 |
PUBHOST | Return index of which MQTT broker we are connected to. | 46 |
PUBNUMQ | Return number of pending MQTT messages to be delivered. | 43 |
PUBLISH | Publish an MQTT message to a broker. | 18 |
PUBQUERY | Check state of a message on the MQTT queue. | 44 |
PUBWALK | Force MQTT client to connect to each broker in its host list. | 45 |
SEGRECV | Receive bytes on a serial port and pack them into a consecutive RTDB registers. | 55 |
SEGSEND | Send bytes from consecutive RTDB registers to a serial port. | 21 |
SEND BIRTH/DEATH CERTIFICATE | Send MQTT birth certificate or death certificate. | 102 |
SUBSCRIBE TO TOPIC | Issue MQTT subscription for a data topic. | 116 |
SUBSCRIBED RECV’d DATA | Receives raw MQtt packet payloads directly into RTDB registers. | 117 |
TTYsIN | Read data on a ttyS serial port. | |
TTYsOUT | Send data to a ttyS serial port. | 62 |
...
If "Source Addr" data is non-zero (integer/real) then move the row pointer by the number of rows in the Operand data. Negative numbers jump to a previous row, positive numbers jump to a later row.
NOTE: 0 is invalid, and 1 moves pointer to the next row (i.e., no effect). Use 2 to skip over a single POD row step, or >2 for later rows.
Strings are not allowed in the Source Addr.
...
Whole row ignored by Interpreter. Type up to 11 characters into Operand and any number in Src/Result columns.
Anchor | ||||
---|---|---|---|---|
|
...
Strings are not allowed in Source Addr or Operand.
ARCWRITE Src=Enbl Opernd(AdrOf5CfgRegs) [0]=NameAdr 1=Offst 2=Rtu 3=Rtdb 4=Cnt
...
GET RTU STATUS of Any RTU Src=Channel : Oprnd=RtuAddr : Result=(0=OK,-2=NoChan,2=Timeout,3=BadDat,4=FramErr,5=Stop,6=Trans,7=NoPoll)
...
Result register (should be integer type) returns the status:
- -2 = Incorrect channel or RTU address
- 0 = OK, good statuscommunication
- 2 = Timeout
- 3 = Bad Data
- 4 = Framing Error
- 5 = Stopped
- 6 = Trans
- 7 = No Polls
...
Returns an Integer Result of zero if successful
INDEXed GET : SourceAddr value is RegAddr used as SrcData=> ResultAdr : Operand Ignored
...
124 or x7c → VERTICAL-BAR
INVERT Bool=Not-Bool, IntBits=iNTbITS, Real=1.0/Real, String=gnirtS (SrcVal-Cast-to-ResultType) Ignore-Operand
...
Source Addr is unused.
Operand is the card’s I/O address as hex string beginning with “x”, such as “x160”. This must match the address jumper setting of the board. Use “Constant” as the Operand Type.
...
21st Register=Counter Input 4 (4th DI)
The POD only supports one Multi-IO card.
...
Source Addr is a pointer to an integer registers containing 16 packed digital bits which will be used to control the digital outputs on the board.
...
Operand is the card’s I/O address as hex string beginning with “x”, such as “x160”. This must match the address jumper setting of the board. Use “Constant” as the Operand Type.
...
8th Register=BIG Endian data stored in MQtt payload? 1=Big Endian, 0=Little Endian
Returns an Integer Handle (1 to 32000) to track this Published data, or -3 if topic is not a String-256 data register. The handle can be used by PUBQUERY to track the status of the publication.
If the 5th, 6th and 7th values are set to zero then the ‘TOPIC’ is actually a file name composed of two parts. The portion preceding the last FORWARD SLASH (/) character is the complete Directory Path. The portion following the last SLASH (/) is used as both the ‘Topic Name’ and ‘File Name’. TILDE (~) characters in the ‘File Name’ will be converted to SLASH (/) characters before being published as the ‘Topic Name’. Any characters following DOUBLE TILDEs (~~) are removed.
...
"Source Addr" data and Operand data are ignored.