Skip to content

Latest commit

 

History

History
122 lines (96 loc) · 8.87 KB

README.md

File metadata and controls

122 lines (96 loc) · 8.87 KB

{json:scada} PLC4X Client (PLC4GO)

A generic PLC client driver for JSON-SCADA. Based on the Apache PLC4X/PLC4GO project.

https://github.com/apache/plc4x
https://plc4x.apache.org/users/protocols/modbus.html

This driver intends to support all protocols provided by the PLC4GO library: Modbus (TCP/RTU/ASCII), KNXnet, ADS. Upcoming: S7, OPCUA, BACNET, ABETH, CBUS, DF1, EIP, Firmata. However, only Modbus TCP was tested. Any help with testing other protocols is welcome.

Discovery and Subscription features are currently not supported by this driver.

To configure the driver it is necessary to create one or more driver instances and at least one connection per instance. Also the tags intended to be updated should be configured appropriately. Alternatively, use the autotag feature to create tags automatically.

Configure a driver instance

To create a new PLC4X client instance, insert a new document in the protocolDriverInstances collection using the Admin UI or a Mongodb command like below.

use json_scada_db_name
db.protocolDriverInstances.insert({
        protocolDriver: "PLC4X",
        protocolDriverInstanceNumber: 1,
        enabled: true,
        logLevel: 1,
        nodeNames: ["mainNode"],
        activeNodeName: "mainNode",
        activeNodeKeepAliveTimeTag: new Date(),
        keepProtocolRunningWhileInactive: false
    });
  • protocolDriver [String] - Name of the protocol driver, must be "PLC4X". Mandatory parameter.
  • protocolDriverInstanceNumber [Double] - Number of the instance. Use 1 to N to number instances. For the same driver instance numbers should be unique. The instance number makes possible to run use multiple processes of the driver, each one with a distinct configuration. Mandatory parameter.
  • enabled [Boolean] - Controls the enabling of the instance. Use false here to disable the instance. Mandatory parameter.
  • logLevel [Double] - Number code for log level (0=minimum,1=basic,2=detailed,3=debug). Too much logging (levels 2 and 3) can affect performance. Mandatory parameter.
  • nodeNames [Array of Strings]- Array of node names that can run the instance. Use more than one node for redundancy. Each redundant instance running on separate node will have the same connections and data enabled for scanning and update. Mandatory parameter.
  • activeNodeName [String] - Name of the protocol driver that is currently active. This is updated by the drivers for redundancy control. Optional.
  • activeNodeKeepAliveTimeTag [Date] - This is updated regularly by the active driver. Optional.
  • keepProtocolRunningWhileInactive [Boolean] - Define a driver will keep the protocol running while not the main active driver. Currently only the false value is supported. Optional.

Changes in the protocolDriverInstances config requires that the driver instances processes be restarted to be effective.

Configure client connections to PLCs

Each instance for this driver can have many client connections defined that must be described in the protocolConnections collection. Create new connections using the Admin UI or Mongodb commands like below.

use json_scada_db_name
db.protocolConnections.insert({
    protocolDriver: "PLC4X",
    protocolDriverInstanceNumber: 1,
    protocolConnectionNumber: 201,
    name: "MODBUS-PLC1",
    description: "PLC device #1 on MODBUS TCP",
    enabled: true,
    commandsEnabled: true,
    autoCreateTags: true,
    endpointURLs: ["modbus-tcp://192.168.0.101:5001?unit-identifier=1",
                   "modbus-tcp://192.168.0.102:5001?unit-identifier=1"
                  ],
    topics: ["MODBUS_PLC1_REG_1|holding-register:4:UINT|LITTLE_ENDIAN",
             "MODBUS_PLC1_REG_20N|holding-register:20:INT[10]"
            ],
    giInterval: 300,
    stats: null
});
  • protocolDriver [String] - Name of the protocol driver, must be "PLC4X". Mandatory parameter.
  • protocolDriverInstanceNumber [Double] - Number of the instance. Use 1 to N to number instances. For the same driver instance numbers should be unique. The instance number makes possible to run use multiple processes of the driver, each one with a distinct configuration. Mandatory parameter.
  • protocolConnectionNumber [Double] - Number code for the protocol connection. This must be unique for all connections over all drivers on a system. This number is be used to define the connection that can update a tag. Mandatory parameter.
  • name [String] - Name for a connection. Will be used for logging. Mandatory parameter.
  • description [String] - Description for the purpose of a connection. Just documental. Optional parameter.
  • enabled [Boolean] - Controls the enabling of the connection. Use false here to disable the connection. Mandatory parameter.
  • commandsEnabled [Boolean] - Allows to disable commands (messages in control direction) for a connection. Use false here to disable commands. Mandatory parameter.
  • autoCreateTags [Boolean] - Allows to enable automatic creation of tags. Mandatory parameter.
  • endpointURLs [Array of Strings] - Array of PLC4X formatted PLC URL addresses. When having redundant devices, configure multiple entries. The driver will try to connect with the first device, when disconnected it will switch to the next device in the list. Supported protocol prefixes: "modbus-tcp", "modbus-rtu", "modbus-ascii". See PLC4X Modbus docs for URL parameters. Mandatory parameter.
  • topics [Array of Strings] - Array of PLC tag addresses to be scanned. The format is "TAG_NAME|PLC4X_ADDRESS|ENDIANNESS". A tag name can be provided for automatic creation of tags. See PLC4X docs for the address format. Endianness can be empty (default), LITTLE_ENDIAN, BIG_ENDIAN or REV_ENDIAN (reverse endianness). Mandatory parameter.
  • giInterval [Double] - General station interrogation period in seconds. Optional parameter.

Examples of topics to scan:

  • "MODBUS_PLC1_REG_1|holding-register:4:UINT|LITTLE_ENDIAN" - will scan the address 4 holding register, 16 bit unsigned int, little endian, tag will be autocreated as "MODBUS_PLC1_REG_1".
  • "MODBUS_PLC1_REG_20N|holding-register:20:INT[10]" - will scan 10 holding registers at address 20, as 16 bit int, default endianness, tags will be named MODBUS_PLC1_REG_20N[0] ... MODBUS_PLC1_REG_20N[9].

Configure tags for update

Each tag to be update on a connection must have a protocol source set configured. Only one source connection can update a tag.

Select an existing tag for a update on a connection as below. Or create a new tag in Admin UI with parameters as described below.

use json_scada_db_name
db.realtimeData.updateOne({"tag":"A_TAG_NAME"}, {
    $set: {
        protocolSourceConnectionNumber: 201,
        protocolSourceCommonAddress: null,
        protocolSourceObjectAddress: "holding-register:4:UINT",
        protocolSourceASDU: "LITTLE_ENDIAN",
        protocolSourceCommandDuration: 0,
        protocolSourceCommandUseSBO: false,
        kconv1: 1.0,
        kconv2: 0.0
        }
});
  • protocolConnectionNumber [Double] - Number code for the protocol connection. Only this protocol connection can update the tag. Mandatory parameter.
  • protocolSourceCommonAddress [String] - Common Address of ASDU. Ignored: leave it as null or empty string. Mandatory parameter.
  • protocolSourceObjectAddress [String] - Object address. Use the PLC4X address convention. Mandatory parameter.
  • protocolSourceASDU [String] - Source ASDU TI type. Ignored for supervised tags. For commands, use to force BIG_ENDIAN, LITTLE_ENDIAN or REV_ENDIAN values. Leave empty for PLC4X default option. Mandatory parameter.
  • protocolSourceCommandDuration [Double] - Ignored: use zero here. Mandatory parameter.
  • protocolSourceCommandUseSBO [Boolean] - Ignored: use false here. Mandatory parameter.
  • kconv1 [Double] - Analog conversion factor: multiplier. Use -1 to invert digital values. Mandatory parameter.
  • kconv2 [Double] - Analog conversion factor: adder. Mandatory parameter.

Command Line Arguments

This driver has the following command line arguments.

  • 1st arg. - Instance Number [Integer] - Instance number to be executed. Optional argument, default=1.
  • 2nd arg. - Log. Level [Integer] - Log level (0=minimum,1=basic,2=detailed,3=debug). Optional argument, default=1.
  • 3rd arg. - Config File Path/Name [String] - Complete path/name of the JSON-SCADA config file. Optional argument, default="../conf/json-scada.json".

Example of JSON-SCADA Protocol Driver Instances and Connections Numbering

Driver instances and connections