Applies To:
  • CitectSCADA
Summary:
 Commonly asked questions for the MOSCAD driver

Solution:

When the MOSCAD driver was rewritten, the way in which the driver is configured was changed.
This has caused confusion as a lot of the documentation for the original driver still persists.
The purpose of this document is to clarify these changes.
 

What INI parameters are available for this driver?

v2.x
----
This is the original driver, often referred to as "Mark1", and is now obsolete.
This generation of the driver had "Driver Scope" and "Device Scope" INI parameters.

The "Address" field of the IODevice Form took a format of 'a NameOfDevice'.
where:  
    "a" is the RTU address between 1 and 32768
    "NameOfDevice" is an optional field that associates this unit with the parameters defined in the Citect INI file defined by the section ‘[NameOfDevice]’.

The following INI parameters are only applicable for v2.x versions of the driver:
 DataRequiredInterval
 UnitDataFreshnessTime
 COSPollingRatio
 PollEverything
 IntegrityPollRequired
 PostPollDelay
 MaxOutstanding
 GlobalBroadcastSiteID
 AllUnitStatusSiteID
 PrimaryGatewayStatusAdd
 BackupGatewayStatusAdd
 DetailedDebugging
 GatewayCheckDelayInterval
 HaltCitectOnThreadShutdown

v3.x
----
This is the current generation of the driver.
Most of the driver was re-written, including INI parameters.
This generation of the driver has "Driver Scope" and "Port Scope" INI parameters.

These are the available INI parameters (with defaults) as at v3.1.5.0
Driver Scope
 [MOSCAD]Station ("Client")
 [MOSCAD]SetupFile ("moscad.cfg")
 [MOSCAD]MaxTimeouts (3)
 [MOSCAD]ConnTimeout (15000)
 [MOSCAD]Channel (7)
 [MOSCAD]Multiplexed (1)
 [MOSCAD]RedundancyTick (100)
 [MOSCAD]ResourceGain (5000)
 [MOSCAD]AnalogBitSwap (0)
 [MOSCAD]AnalogWordSwap (0)
 [MOSCAD]ChannelScanDelay (0)
Port Scope
 [<PortID>]SetupFile (Driver Scope)
 [<PortID>]Channel (Driver Scope)
 [<PortID>]Multiplexed (Driver Scope)
 [<PortID>]Timeout (3000)
 [<PortID>]NoPollPeriod (10000)
 [<PortID>]Polled (1)
 [<PortID>]Tick (500)
 [<PortID>]DebugLevel (0)
where <PortID> is the string [MOSCAD]Station appended with the port index (zero based).
For example, if [MOSCAD]Station is left at default, and only one port is configured, the PortID is "Client0".
There is one Channel/Port per gateway, hence the [<PortID>] subsections only apply per Gateway.


How is the Configuration Setup file formatted?

This file is only applicable to v3.x versions of the driver.
These are the config instructions as at v3.1.5.0
(Check examples to determine which parameters allow spaces)

TABLE Config
------------
<Table Name>:<Table Number>:<Poll Flag>;<Row Count>;<Col Count>:<Col Types>

<Table Name> - Text string with out space and not starting with a number
                      - This is required for cross reference in RTU Config
<Table Number> - Table number as configured in RTU (1-128)
<Poll Flag> - "polled" (indicates if this table is to be polled)
<Row Count> - "rows n" (where 'n' is rows in this table 0-249)
<Col Count> - "columns n" (where 'n' is columns in this table 0-7)
<Col Types> - "<Col1 type> <Col2 type> <Col3 type> ..." (type of all columns in use)
                   - <type> can be "real", "discrete" or "analog"

* Multiple TABLE entries allowed per file
* "off" can be added as an additional parameter (eg "<Table Number>:<Off Flag>;<Poll Flag>") to disable Table
* <Poll Flag> parameter can be removed to disable polling of table

Example
TableA1: 1 : Polled; Rows 4; Columns 1 : Discrete
TableA2: 2 : Polled; Rows 4; Columns 1 : analog
TableA3: 3 : Polled; Rows 4; Columns 1 : real
TableA4: 4 : Polled; Rows 4 ; Columns 3 : discrete real real
TableA5: 5 : ; Rows 4 ; Columns 3 : analog real real
TableB1: 1 : Polled; Rows 4 ; Columns 3 : real real real
TableB2: 2 : ; Rows 4 ; Columns 3 : real real discrete
TableB3: 3 : ; Rows 4 ; Columns 5 : real real discrete analog real

RTU Config
----------
<RTU Name>:<Site ID>:<Ratio Index>;<Poll Flag>;<Poll Period>;<Table Types>:<Cache Path>

<RTU Name> - This is only for documentation
                    - text string with out space and not starting with a number
<Site ID> - This is the RTU SiteID (1-32767)
<Ratio Index> - "ratio n" (where 'n' is the number of event polls between integrity polls)
<Poll Flag> - "polled" (indicates if this RTU is to be polled)
<Poll Period> - "period n" (where 'n' is is the number of ms between polls)
<Table Types>  - "tables <Table1 type> <Table2 type> <Table3 type> ..." (type of all Tables in use)
                       - <Table type> must be one of the <Table Name>s in TABLE config
<Cache Path>  - the path and file name for the persistent cache of the unit

* Multiple RTU entries allowed per file - Table entries can be reused when multiple RTUs have the same table at the same index

* "off" can be added as an additional parameter (eg "<Ratio Index>;<Off Flag>;<Poll Flag>") to disable RTU
* <Poll Flag> parameter can be removed to disable polling of RTU
* Also refer to "How do I set the [MOSCAD]Multiplexed INI and "noncritical" Config File fields?" 

Example
RTUA: 1 : Ratio 2; Polled; Period 6000; Tables TableA1 TableA2 TableA3 TableA4 TableA5 : C:\tmp\rtuA.dat
RTUB: 2 : Ratio 2; Polled; Period 5000; Tables TableB1 TableB2 TableB3 : C:\tmp\rtuB.dat

 

What logging is available with the driver?

* Standard logging is available using the usual "debugstr" INI option or "debug" kernel command that will provide driver debugging for the nominated ports to the syslog. 
   The level of debugging produced is controlled by the [<PortID>]DebugLevel INI parameter.
   Most of these traces are available with  the default level of 0, but additional traces are available with a level of 1.
* Advanced logging (typically for internal maintenance) is available by using a proprietary "journal" utility that was created for this driver.


How does the driver's polling engine operate?

* Every [<PortID>]Tick mSec, the polling engine will process through all units to flag the units now requiring a poll - the poll flag will be set when it has
  been polltime since the last poll response was received from that unit. Then the polling engine determines the next unit to poll. Starting with the next
  unit after the last polled unit, and proceeding in the order of the IODevice form, it searches for a unit with the poll flag set.
* The following is a guide on dividing RTUs into priority groups for polling:
  - Divide RTUs into groups based on their required polling rates, and sort the IODevice form so that all RTUs from the fastest group are entered first and all
    RTUs from the slowest group are entered last
  - For this discussion, we will assume three groups, with GroupA being the fastest and GroupC being the slowest.
  - Based on average request and response times, determine the time it would take to poll all RTUs from that group - TotalPollTime or TPT (ie TPT(A), TPT(B)
    and TPT(C) ).
  - Based on expected burst traffic, determine the required amount of radio silence between each RTU poll - BurstTime or BT.
  - The Total Burst Time for a group is the BT times the number of RTUs in the group (ie TBT(A), TBT(B) and TBT(C) )
  - The Time Between Polls (TBP) for a group is the addition of TPT and TBT.
  - Determine the polling ratio (PR) between groups (eg PR(A:B) is the number of times to poll Group A for every poll of Group B)
  - TBP(A) = TPT(A) + TBT(A)
    TBP(B) = TBP(A) *  PR(A:B) + TPT(B) + TBT(B)
    TBP(C) = TBP(B) *  PR(B:C) + TPT(C) + TBT(C)
  - The polltime for a particular RTU is the TBP for its group subtracted by the average request and response time for a poll to that RTU
  - If the site is using burst traffic, set a high value for radio silence and set the Integrity Poll to Event Poll ratio to 0 so all poles are Integrity
    Polls. To set radio silence interval, configure both [<PortID>]NoPollPeriod and [MOSCAD]ChannelScanDelay INI parameters to the required amount of mSec
    radio silence between RTU poll requests. Configure the Integrity Poll to Event Poll ratio in the cfg file.
* The polling engine will only poll RTUs that are
   - Marked as polled in the CFG file
   - Have an IODevice Form entry
   - Have not been disabled by IODeviceControl()
   - Are not a critical unit that can not be contacted
   - On a gateway that is online


What is the maximum polling period?

The polling period is a four byte quantity (ie 32 bits) and hence allows a max of ~ 24 days


What are the available RTUStatus virtual tags?
 
The RTUStatus flags supported are
STALE - used to indicate that the unit is stale
EPOLL - requires a event poll
IPOLL - requires a integrity poll
POLL - set if the unit is to be polled
AV- connection to unit is available via active gateway
INUSE- set if the units cache is valid
CRIT - set if the unit will cause channel to go offline


How do I set the [MOSCAD]Multiplexed INI and "noncritical" Config File fields?

By default all units are a critical unit unless they have the keyword "noncritical" listed as a field between the <Site ID> and <Table Types> fields of the CFG file.
Only critical units are marked OFFLINE when they can not be contacted, a non-critical unit will remain online to bypasss Citect redundancy. The RTUStatus.AV
virtual tag is available to determine if the unit is truly available.
The Multiplexed INI parameter determines whether fail of a critical unit results in fail over of that unit or of the entire Citect channel.
When the INI is enabled (default), loss of a critical unit will cause all units on the active Gateway to swap to the redundant Gateway.

How is scheduling implemented?

All scheduling is handled by the MOSCAD driver scheduling engine.
The "schedule" fields in the I/O device form are not required.


Does background polling need to be set for the device?

"Background poll" fields in the I/O device form are not required.


Does the cache need to be enabled?

"Cache" fields in the I/O device form can just be left at defaults. Both
caches will be in operation.


Why are some tags displayed as 0 when the device is shown as online?
  
When testing the online status of a unit, the driver checks that the gateway is contactable.
If data from last contact has not been persisted, then the driver will not have data for the RTU until a poll has completed.
The unit will be marked OFFLINE if the gateway reports comms problems or is unable to get a response from the RTUstatus.


In the syslog, what causes Driver error 32?

An example of this error in the syslog is
2009/06/23-19:10:18.066 Error: Data not yet valid
  READ     0019 Mine_S1_MOS_P DWIODev_PS10_PLC                        A8.16.0
  Generic 000025 Driver 00000032 (0x00000020)

Where "A" is Analog, 8 is the Table No, 16 is the Row No, and 0 is the Column No
(other types are "F" = Float and "B" = Bit)

This error  can be caused by either:
(A) A mismatch between table co-ords in the Tag address and that for the config file
(B) A Read command issued for a unit that the driver has marked as offline (this should not normally occur).


In the syslog, what causes Driver error 4236?

An example of this error in the syslog is
 2009/06/23-19:10:56.522 Error: Write data is invalid
  READ     0004 Mine_S1_MOS_P DWIODev_PS10                         B1.2.1   64
 Generic 000004 Driver 00004236 (0x0000108c)

This error  can be caused by either:
(A) Column type is not either Real, Analogue or Discrete
(B) A mismatch between column co-ords in the Tag address and that for the config file
Keywords:
 MOSCAD

Attachments