Ethernet/IP™ for SoftPLC® Runtime

# Ethernet/IP Driver Configuration for SoftPLC Runtime Software.
# This file uses an "s-expression" format, which is like XML but uses
# parentheses instead of angle bracketed keywords.  The syntax of s-expression
# files is well documented and can be googled.  The grammar, on the other hand,
# unlike the syntax, is application specific.  SoftPLC uses '#' to indicate
# a single line comment. If the first non-blank character is #, then this
# line is a single line comment.  Single line comments cannot follow
# any other token on the same line.  Multiline 'C' style comments are also
# supported.  Its best to use these also only as the first non-blank combo:
# /* followed by an eventual */
#
# S-expressions are thought to be more human readable than XML
# and are easy to parse with a programming language.  Parentheses are balanced.
#
# The supported grammar is documented in the next several lines of comments.
# Grammar rules are declared like this, for example:
# (timeout_mult <4 | 8 | 16 | 32 | 64 | 128 | 256 | 512 > )
# This means "timeout_mul" is a keyword and it can be followed with
#   4, 8, 16, 32, 64, 128, 256, or 512.  The '|' means "or". e.g. (timeout_mult 4)
#
# If something is wrapped in square brackets [] in a grammar rule, this means
# whatever appears in the brackets is optional.  If omitted, then a default value
# will be used and the default is defined in the grammar rule by a comment following
# a ':'.  The square brackets, being only part of the grammar definition,
# are never actually used in real configuration statements.
#
# If something is wrapped in angle brackets <> in a grammar rule, this means
# it is a grouping.  Only one of the choices in a grouping may actually be used.
# Angle brackets, being only part of the grammar definition, are never actually
# used in real configuration statements.
#
# White spaces includeing tabs and newlines (CR, LF, etc.) are all ignored.
# Numbers may be provided either in decimal or in hex with a prefix of 0x.

#------ Grammar Rules: ----------
# (ethernet_ip                  ` is the master containing element and it may contain
#                               ` the indicated 6 top level elements.  Some of the
#                               ` 6 are optional, indicated with enclosing [].
#                               ` Every nested element is contained within this
#                               ` master element.
#   (driver_version ...)
#   (interface ...)
#   (debug ...)
#   [(plc2_compatibility_file ...)]
#   [(my_assemblies ...)]
#   [(target_role_connections ...)]
#   [(originator_role_connections ...)]
#   )  /* end of "ethernet_ip" s-expression element */
#
# Details on nested elements:
#
# (driver_version <VERSION_NUM>)            ` VERSION_NUM should be 1
# (interface <ETH_PORT>)                    ` which ethernet interface to use,
#                                           ` e.g. ethernet0 (on Smart4) or eth0 (on x86)
# (debug <BIT_SET>)                         ` turns on debugging features given in
#                                           ` the integer bitset.
# (plc2_compatibility_file 7)               ` the N file number which mimics a
#                                           ` PLC2 datatable for old PCCC commands.
#
# Section (my_assemblies ...) causes the creation of the listed assemblies in
# the CIP domain and ties them into the SoftPLC datatable based on what PLC
# address the "tag" is defined to in the descriptor table.  Assemblies each
# must have a unique number from 1-65000, called an assembly instance id.
# These ids are then used in the two sections named
# target_role_connections and originator_role_connections which follow.
#
# (my_assemblies                            ` gives the CIP assemblies that the
#                                           ` TLM should create
#   <(my_producing ...) |
#    (my_consuming ...) |
#    (my_cfg ...) |
#    (my_explict ...)> ...
#   ) /* end of my_assemblies */
#
#   (my_producing <ASSEMBLY_ID>             ` flows from the datatable onto the network
#     (data <int16 | float32>)(elements <ELEMENT_COUNT>)(tag <TAG_NAME>)
#     )
#   (my_consuming <ASSEMBLY_ID>             ` flows from network into datatable
#     (data <int16 | float32>)(elements <ELEMENT_COUNT>)(tag <TAG_NAME>)
#     )
#   (my_config <ASSEMBLY_ID>                ` is bidirectional with datatable
#     (data <int16 | float32>)(elements <ELEMENT_COUNT>)(tag <TAG_NAME>)
#     )
#   (my_explicit <ASSEMBLY_ID>              ` is bidirectional with datatable
#     (data <int16 | float32>)(elements <ELEMENT_COUNT>)(tag <TAG_NAME>)
#     )
#
# Section (target_role_connections ...) is a list of i/o connections that should
# be accepted should we see an inbound forward_open containing a matching
# combination of assembly ids.
# (my_consuming ...) and (my_producing ...) and (my_config ...) are from
# my perspective within this network node.
#
# (target_role_connections
#   (expect exclusive_owner                 ` which kind of i/o connection, only
#                                           ` exclusive_owner for now
#     (my_consuming 150)                    ` which consuming assembly id
#     (my_producing 100)                    ` which producing assembly id
#     [(my_config 151)]                     ` optional config assembly id
#     )
#   (expect exclusive_owner (my_consuming 150)(my_producing 100))
#   )   /* end of target_role_connections */
#
#
# Section (originator_role_connections ...) lists client connections which
# will be made and manageed as a scanner.
# (originator_role_connections
#   (target ...)
#   [(target ...)] ...
#   )   /* end of originator_role_connections */
#
# 'target' is a TCP node that is capable of being an Ethernet/IP explicit message
#  server that supports the forward_open command.  One or more forward_open
#  commands will be sent to this node in order to setup the requested number
#  of io_connections, which are all UDP based.
#
# (target <IP_ADDRESS | HOSTNAME>           ` HOSTNAME ok if findable via DNS,
#                                           ` else provide an IP_ADDRESS
#   [(tcp_connect_timeout_ms <MSECS>)]      ` TCP connect() time limit of
#                                           ` originating : 5000 is default
#   [(tcp_connect_retry_delay_ms <MSECS>)]  ` How long after failed TCP connection
#                                           ` to try again. : 5000 is default
#   (io_connection ...)
#   [(io_connection ...)] ...
#   )   /* end of target */
#
# (io_connection
#   [(conn_path ...)]                       ` Hex bytes in CIP segment form to
#                                           ` precede the 1-3 Application Paths.
#                                           ` If used at all, probably just a port path.
#   [(fwd_open_timeout_ms <MSECS>)]         ` how long client waits for server after
#                                           ` sending forward_open : 1000 is default
#   [(io_timeout_mult <4|8|16|32|64|128|256|512> )] `see CIP docs for forward_open.
#                                           ` Actual io_connection timeout is unique for
#                                           ` each connection half, and is rpi_usecs times
#                                           ` this number : 4 is default
#   [<cyclic | change_of_state>]            ` CIP connection trigger
#                                           ` type : cyclic is default
#   [<class0 | class1>]                     ` CIP transport class : class1 is default
#   [(config ...)]                          ` configuration one shot transfer
#   [(t_o ...)]                             ` target to originator connection half,
#                                           ` if missing means no t->o transfer
#   [(o_t ...)]                             ` originator to target connection half,
#                                           ` if missing means no o->t transfer
#   )   /* end of io_connection */
#
# (config
#   (my_config <ASSEMBLY_ID>)               ` A block of data to send to the target,
#                                           ` or it can be zero length also.
#   [(tgt_config <ASSEMBLY_ID>)]            ` Which assembly is to receive it.
#                                           ` May be omitted if this info is in (conn_path ...)
#   [(size_bytes <NUM_BYTES>)]              ` If missing then the size of
#                                           ` my_config will be used.
#   )
#
# (t_o                                      ` target to originator connection half
#   (rpi_us <NUM_USECS>)                    ` Requested Packet Interval in usecs not msecs
#   [<p_to_p | multicast>]                  ` peer to peer or multicast
#                                           ` : p_to_p is default
#   [(priority <low | high | scheduled | urgent>)]
#                                           ` : low is default
#   [(rt_fmt <32_bit_header | modeless>)]   ` CIP Vol1 3-6.1
#                                           ` : "modeless" is default for t_o
#   (my_consuming <ASSEMBLY_ID>)            ` my assembly which is the consumer
#   [(tgt_producing <ASSEMBLY_ID>) | (tgt_producing_conn_pt <ASSEMBLY_ID>)]
#                                           ` the producing assembly number or the
#                                           ` producing connection point within the target.
#                                           ` Some target adapters require 0x2C as connection
#                                           ` path field prefixes rather than 0x24.
#                                           ` tgt_producing generates 0x24.
#                                           ` tgt_producing_conn_pt generates 0x2C.
#   [(size_bytes <NUM_BYTES>)]              ` If zero then this is a heartbeat half.
#                                           ` If missing then the size of
#                                           ` my_consuming will be used.
#   )   /* end of t_o */
#
# (o_t                                      ` originator to target connection half
#   (rpi_us <NUM_USECS>)                    ` Requested Packet Interval in usecs not msecs
#   [<p_to_p | multicast>]                  ` peer to peer or multicast
#                                           ` : p_to_p is default
#   [(priority <low | high | scheduled | urgent>)]
#                                           ` : low is default
#   [(rt_fmt <32_bit_header | modeless>)]   ` CIP Vol1 3-6.1
#                                           ` : "32_bit_header" is default for o_t
#   (my_producing <ASSEMBLY_ID>)            ` my assembly which is the producer
#   [(tgt_consuming <ASSEMBLY_ID>) | (tgt_consuming_conn_pt <ASSEMBLY_ID>)]
#                                           ` the consuming assembly number or the
#                                           ` consuming connection point within the target.
#                                           ` Some target adapters require 0x2C as connection
#                                           ` path field prefixes rather than 0x24.
#                                           ` tgt_consuming generates 0x24.
#                                           ` tgt_consuming_conn_pt generates 0x2C.
#   [(size_bytes <NUM_BYTES>)]              ` If zero then this is a heartbeat half.
#                                           ` If missing then the size of
#                                           ` my_producing will be used.
#   )   /* end of o_t */
#
# end of intro comments and grammar rules.
# Next comes actual configuration statements:

(ethernet_ip
  (driver_version 1)
  (interface ethernet0)
  #(debug 0x3f)
  (debug 0)
  #(plc2_compatibility_file 7)

  (my_assemblies
    # 3 assemblies for originator_role_connections
    (my_producing   1   (data int16)(elements   6)(tag "TO_DRIVE"))
    (my_consuming   2   (data int16)(elements   6)(tag "FROM_DRIVE"))
    (my_config      3   (data int16)(elements   0)(tag "DRIVE_CONFIG"))

    # 5 assemblies for target_role_connections
    #   first expected connection:
    (my_producing   100 (data int16)(elements  64)(tag "TO_PLC"))
    (my_consuming   150 (data int16)(elements  64)(tag "FROM_PLC"))
    (my_config      151 (data int16)(elements  32)(tag "CONFIG_FOR_ME"))
    #   second expected connection:
    (my_producing   200 (data int16)(elements 100)(tag "TO_HMI"))
    (my_consuming   201 (data int16)(elements 100)(tag "FROM_HMI"))
    )

  (target_role_connections
    (expect exclusive_owner (my_consuming 150)(my_producing 100)(my_config 151))
    (expect exclusive_owner (my_consuming 201)(my_producing 200))
    )

  (originator_role_connections
    (target 192.168.1.99
      # The (tgt_*) elements may be used to create fragments of the connection path.
      # Alternatively, you may omit the (tgt_*) elements and instead supply a
      # (conn_path) element for the whole connection path.
      (io_connection
        (config (my_config 3)(tgt_config 103))
        (t_o (rpi_us 150000)(my_consuming 2)(tgt_producing 101))
        (o_t (rpi_us 150000)(my_producing 1)(tgt_consuming 102))
        )
      )
    )

  )