Improve documentation

Author: Jonas Berg

README.md

@@ -52,12 +52,14 @@ Features:
 
 Limitations or not yet implemented:
 
+* This is a device stack, which means that the IO-controller/master/PLC side is not supported.
 * Only a single Ethernet port (no media redundancy)
 * No startup mode legacy
 * No support for RT_CLASS_UDP
 * No support for DHCP
 * No fast start-up
 * No MC multicast device-to-device
+* No support of shared device (connection to multiple controllers)
 * No iPar (parameter server) support
 * No support for time synchronization
 * No UDP frames at alarm (just the default alarm mechanism is implemented)

doc/abbreviations.rst

@@ -12,6 +12,9 @@ Engineering tool
     A desktop program for configuring PLC. For example Siemens TIA portal.
 Parameterization
     Write parameter values to all submodules
+Record data
+   Data that can be accessed with acyclic Profinet Read and Write. Addressed by
+   slot, subslot and index.
 Transfer syntax
     Coding of the different fields in a message. See also "Abstract syntax".
 

doc/additional_linux_details.rst

@@ -178,24 +178,14 @@ Profinet MIB:s. On Ubuntu Linux you should change
    rocommunity  public  default -V systemonly
    rwcommunity  private default -V systemonly
 
-If your linux distribution does give a long description for ``ifDesc`` you can
+If your Linux distribution does give a long description for ``ifDesc`` you can
 override it by adding a line to the ``snmpd.conf`` file. Adapt the interface
 index (last digit in OID) and the interface name::
 
    override 1.3.6.1.2.1.2.2.1.2.3 octet_str "enp0s31f6"
 
-To verify the SNMP capabilities, first use ``ping`` to make sure you have a
-connection to the device, and then use ``snmpwalk``::
-
-   ping 192.168.0.50
-   snmpwalk -v1 -c public 192.168.0.50 1
-   snmpget -v1 -c public 192.168.0.50 1.3.6.1.2.1.1.4.0
-   snmpset -v1 -c private 192.168.0.50 1.3.6.1.2.1.1.4.0 s "My new sys contact"
-
-If you enable debug logging in the p-net stack, the two last commands will
-cause entries in the p-net log.
-
-See :ref:`network-topology-detection` for more details on SNMP.
+See :ref:`network-topology-detection` for more details on SNMP and how to
+verify the SNMP communication to the p-net stack.
 
 
 snmpd in a Yocto build

doc/applications_and_porting.rst

@@ -27,3 +27,73 @@ Required features of the hardware
 
 * It should be possible to send and receive raw (layer 2) Ethernet frames
 * It should be possible to store data between runs, in a file system or some nonvolatile memory
+
+
+Minimum cycle time for your application and hardware
+----------------------------------------------------
+At PLC configuration, there are two adjustable parameters regarding the
+cyclic data timing for an IO-device. One basically controls the
+frame-to-frame transmission interval (given as a multiple of the cycle time),
+and the other one controls the PLC watchdog timeout setting.
+The watchdog triggers an alarm when a number of consecutive cyclic data
+frames from the IO-device are missing.
+
+During conformance testing, the PLC watchdog timeout setting is 3 x
+frame-to-frame interval times, ie the PLC will trigger an alarm if three
+consecutive cyclic data frames are missing. Thus the smallest allowed
+frame-to-frame interval given in the GSDML file must take the smallest
+useful PLC watchdog timeout setting into account.
+
+There can be different factors limiting the ability to send Profinet frames at
+a regular pace:
+
+* The initial work at Profinet communication startup should not cause
+  delays in the cyclic data transmission once started.
+* The hardware needs to keep up with the steady-state sending and receiving
+  of Profinet cyclic data.
+* Other work done by the Profinet application, for example work done in
+  callbacks, might slow down the communication.
+* Operating system jitter, which basically is that the operating system is
+  busy doing other work, will cause frame delays.
+* Using a network interface connected via USB can cause additional frame
+  delays.
+
+For real-time operating systems (RTOS) for example rt-kernel, the
+frame-to-frame transmission will have little jitter.
+
+For non-real-time operating systems, for example Linux, the limiting factor
+is typically the jitter caused by the operating system.
+See the page on Linux timing in this documentation for ideas on improving
+Linux real-time properties.
+
+
+Measure Profinet frame transmission jitter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Set the PLC watchdog time to 100 x frame interval, to avoid any alarms
+from the PLC.
+Use Wireshark to record cyclic data transmission for a few minutes.
+Plot the maximum frame-to-frame transmission interval (see the page on
+capturing Ethernet packets in this documentation).
+This will show which PLC watchdog setting you need in order not to trigger
+"missing frame" alarms.
+
+For example if the transmission interval is 1 ms but there sometimes is a 10 ms
+delay between the frames, then you need to use the next standard PLC timeout
+value which is 12 ms. In order to handle that with a watchdog setting of 3 x
+frame interval, you need to use a minimum cycle time of 4 ms (as
+will be stated in your GSDML file).
+
+
+Example measurement results
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Measurements with p-net on a XMC4800 board running rt-kernel shows that the
+hardware is able to send frames with a periodicity of 1 ms with little jitter.
+The liming factor is that the PLC watchdog timeout value needs to be 12 ms,
+due to the time it takes for the first cyclic data frame to be sent from
+the IO-device.
+A GSDML file should state that the smallest allowed cycle time is 4 ms.
+
+Similar measurements on a Raspberry Pi 3B+ show that it is possible to send
+frames with a cycle time of 1 ms. However there is sometimes a frame-to-frame
+interval of up to 40 ms, resulting in that a GSDML file should state that the
+minimum frame interval is 16 ms.

doc/compliancetest.rst

@@ -78,7 +78,7 @@ Adjust the settings of the Ethernet card of your personal computer to use
 100 Mbit/s full duplex (otherwise the test case "Different access ways
 port-to-port" will fail).
 
-Set the IP address to 192.168.0.25 and netmask to 255.255.255.0.
+Set the IP address to ``192.168.0.25`` and netmask to ``255.255.255.0``.
 
 Use a separate network for running tests with Advanced RT tester
 (avoid running it on a network with unrelated devices).
@@ -136,19 +136,23 @@ Some of the test cases requires additional hardware; a Profinet-enabled switch
 ("Device B") and an IO-controller ("Device A"). Also a remote controlled
 power outlet can be used to simplify the tests.
 
-+-------------------------+-----------------------------+-------------------+
-| Item                    | IP address                  | Description       |
-+=========================+=============================+===================+
-| Device under test (DUT) | 192.168.0.50                |                   |
-+-------------------------+-----------------------------+-------------------+
-| ART tester on PC        | 192.168.0.25, 192.168.1.143 |                   |
-+-------------------------+-----------------------------+-------------------+
-| PLC ("Device A")        | 192.168.0.100               |                   |
-+-------------------------+-----------------------------+-------------------+
-| Switch (“Device B”)     | 192.168.0.99                |                   |
-+-------------------------+-----------------------------+-------------------+
-| Power outlet            | 192.168.1.244               | Separate network  |
-+-------------------------+-----------------------------+-------------------+
++-------------------------+-----------------------------+------------------------+
+| Item                    | IP address                  | Description            |
++=========================+=============================+========================+
+| Device under test (DUT) | 192.168.0.50                |                        |
++-------------------------+-----------------------------+------------------------+
+| ART tester on PC        | 192.168.0.25, 192.168.1.143 |                        |
++-------------------------+-----------------------------+------------------------+
+| PLC ("Device A")        | 192.168.0.100               |                        |
++-------------------------+-----------------------------+------------------------+
+| Switch (“Device B”)     | 192.168.0.99                |                        |
++-------------------------+-----------------------------+------------------------+
+| Neighbour (“Device D”)  | 192.168.0.98                | To port 2 of DUT       |
++-------------------------+-----------------------------+------------------------+
+| Neighbour (“Device E”)  | 192.168.0.97                | To highest port of DUT |
++-------------------------+-----------------------------+------------------------+
+| Power outlet            | 192.168.1.244               | Separate network       |
++-------------------------+-----------------------------+------------------------+
 
 
 Profinet-enabled switch
@@ -158,7 +162,7 @@ switch.
 
 The test specification of version V 2.41 recommends the use of a
 Siemens Scalance X204IRT (article number 6GK5204-0BA00-2BA3).
-It should have IP address 192.168.0.99, netmask 255.255.255.0 and station name "b".
+It should have IP address ``192.168.0.99``, netmask ``255.255.255.0`` and station name "b".
 Use for example Codesys to scan for the device, and to adjust the IP settings.
 Alternatively, use SinecPni to change the IP address (see the Simatic
 page in this documentation).
@@ -183,21 +187,31 @@ Connection of the switch ports is described in the table below:
 The Automated RT tester will detect "Device B" by itself. No configuration is
 required in the Automated RT tester menu.
 
+The setting "Use IEC V2.2 LLDP mode" available via the STEP7 Profinet setup
+tool controls the format of the sent portID in LLDP frames.
+With the "Use IEC V2.2 LLDP mode" enabled the portID is sent as ``port-001``,
+while it is sent as ``port-001.b`` if disabled. The latter format is used in
+Profinet 2.3 and newer. The ART tester requires the LLDP format to be in the
+2.2 format, otherwise it will complain about portID length.
+One way to restore the behavior to the 2.2 format is to do a factory reset
+of the switch via the web interface or by pressing the SET button for more than
+20 seconds (if the button not is disabled in the web interface).
+
 
 Remote controlled power outlet
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The Automated RT Tester can control an "Anel Net-PwrCtrl" power outlet via Ethernet.
 It must be connected via a separate Ethernet
-interface on the personal computer. Use a static IP address 192.168.1.243 with
-subnet mask to 255.255.255.0 on that interface.
+interface on the personal computer. Use a static IP address ``192.168.1.243`` with
+subnet mask to ``255.255.255.0`` on that interface.
 
-The Power outlet has a default IP address of 192.168.0.244, and it has a
+The Power outlet has a default IP address of ``192.168.0.244``, and it has a
 built-in web server. Enter its IP address in your web browser to log in
 (username and password printed on the hardware).
-(You might need to temporary set your Ethernet interface to IP 192.168.0.1
-and subnet mask to 255.255.255.0)
+(You might need to temporary set your Ethernet interface to IP ``192.168.0.1``
+and subnet mask to ``255.255.255.0``)
 Modify the IP settings (on the "Einstellung" page) to use a static IP address
-of 192.168.1.244.
+of ``192.168.1.244``.
 On the "Steuerung" page you can control the individual power outputs.
 
 Connect power for your device under test to connector number 3 on the power outlet.
@@ -207,6 +221,21 @@ left of the "PowerOutlet" text in the tool bar. The symbol to the right of the
 "PowerOutlet" text shows a green check mark when the outputs are on, and a
 black cross when the outputs are off (or when the power outlet not is connected).
 
++--------------+------------------------------------------------------------+
+| Power outlet | Connected to                                               |
++==============+============================================================+
+| 1            | PLC "A"                                                    |
++--------------+------------------------------------------------------------+
+| 2            | Profinet enabled switch "B"                                |
++--------------+------------------------------------------------------------+
+| 3            | Device under test (DUT) running p-net                      |
++--------------+------------------------------------------------------------+
+| 4            | Neighbour device "D", connected to DUT port 2              |
++--------------+------------------------------------------------------------+
+| 5            | Neighbour device "E", connected to DUT highest port number |
++--------------+------------------------------------------------------------+
+
+
 Hardware naming
 ^^^^^^^^^^^^^^^
 Different types of Siemens hardware are used for the conformance test.
@@ -216,23 +245,106 @@ a list of Siemens naming conventions is provided here:
 * AI: Analog input module
 * AQ: Analog output module
 * BA: Basic
+* BA: Busadapter (with RJ45 or fiber optic connectors)
 * BU: BaseUnit (for mounting input and output modules)
 * CM: Communication module
 * DI: Digital input module
 * DP: Profibus DP
 * DQ: Digital output module
 * F-: Fail safe
+* FC: Fast Connect (A bus adapter for network cables)
 * HF: High feature
 * HS: High speed
 * IM: Interface Module
+* L+: +24 V DC
+* M: Ground connection
 * P: Port
 * PN: Profinet
 * R: Ring port for media redundancy
 * SM: Special module
+* SP: Scalable Peripherals
 * ST: Standard
 * TM: Technology module
 * X: Interface
 
+
+Siemens IO-device for verification of multi-port devices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++--------------------------------------+-------------------------------------------+
+| Part                                 | Comments                                  |
++======================================+===========================================+
+| Interface module ET200 IM155-6PN/2HF |                                           |
++--------------------------------------+-------------------------------------------+
+| Digital output module DQ 132         | In slot 1 (closest to interface module)   |
++--------------------------------------+-------------------------------------------+
+| Digital input module DI 131          | In slot 2                                 |
++--------------------------------------+-------------------------------------------+
+| Base uint A0 (24 VDC, light colored) | One for each input/output module          |
++--------------------------------------+-------------------------------------------+
+| Bus adapter                          | With two RJ45 connectors                  |
++--------------------------------------+-------------------------------------------+
+| Server module                        | Delivered with the interface module. Put  |
+|                                      | it in slot 3.                             |
++--------------------------------------+-------------------------------------------+
+
+See the Profinet test specification for part numbers.
+
+Light-colored bus adapters are used for supply voltage distribution.
+The cyan-colored (auxiliary) terminals on bus-adapters are all connected together.
+If you only use light-colored bus adapters, then the cyan-colored terminals on
+one bus adapter are isolated from the corresponding terminals on other bus adapters.
+
+Connect +24 V to the red terminals of the interface module and the base units.
+Connect 0 V to the blue terminals of the interface module and the base units.
+
+Connect a button via wires to the digital input (DI) module. Connect it between
+DI.7 (pin 18) and and +24 V. The LED ".7" on the input module will be green
+when the button is pressed.
+
+The LED ".7" on the digital output module (DQ) will be green when the output
+is high (+24 V).
+
+.. image:: illustrations/SimaticIoDevice.jpg
+
+See the page on setting up a Simatic PLC in this documentation for
+instructions on usage.
+
+
+Set up Cisco SF352-08P switch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For multiport Profinet devices, also SNMP-communication to non-Profinet
+devices is verified. This Cisco switch can be used for that purpose.
+
+Connect an Ethernet cable to port G1.
+Set your laptop IP address to ``192.168.1.143`` and netmask to be ``255.255.255.0``.
+Log in to ``192.168.1.254``. Default username is ``cisco`` and password is ``cisco``.
+Change password when prompted.
+
+Set the IP address via the left side menu "IP configuration" -> "IPv4 Management and Interfaces" -> "IPv4 Interface".
+Click "Add" and enter the static IP address ``192.168.0.98``. Use netmask ``255.255.255.0``.
+The switch will change IP address to a new subnet, so you might need to change your
+laptop network setting before connecting to the new IP address.
+
+Adjust LLDP settings via menu Administration -> "Discovery - LLDP" -> Properties.
+In the page top bar, set "Display mode" to Advanced. Set "Chassis ID Advertisement"
+to "MAC Address".
+
+Via Administration -> "Discovery - LLDP" -> "Port settings" select port FE1 and
+click Edit. Enable SNMP notification. Select the optional TLVs that start with "802.3".
+
+Via the menu Security -> "TCO/UDP Services", enable "SNMP Service".
+
+In the page top bar, set "Display mode" to Advanced.
+Add a SNMP community via the menu SNMP -> Communities and click Add. The
+community string should be "public". Set "SNMP Management Station" to "All".
+Click "Apply" and "Close".
+
+In the top of the page click the "Save" icon.
+
+For the actual measurements, use the port 1 on the Cisco switch.
+
+
 Tips and ideas
 --------------
 If you end up with ``Pass with Hint "The device made a EPM Request from a
@@ -359,7 +471,7 @@ Set the GSDML file attributes ``ConformanceClass="B"`` and
 Relevant test cases for multi-port devices
 ------------------------------------------
 
-* PDEV_RECORDS
+* PDEV_RECORDS Requires additional hardware ("Device B")
 
 
 Relevant test cases for legacy startup mode

doc/creating_gsdml_files.rst

@@ -302,6 +302,14 @@ Use an ``<MAUTypeItem>`` element to describe the Medium Attachment Unit type,
 which can be radio (0), copper at 100 Mbit/s (16) or fiber optics.
 
 
+Additional ports
+----------------
+Additional physical ports are created by adding ``<PortSubmoduleItem>`` nodes
+to the ``<SystemDefinedSubmoduleList>`` node.
+The ID, submodule identity number and subslot number shall be unique for
+all ports.
+
+
 Details on the module list
 --------------------------
 Profinet field devices can have different hardware modules, therefore there is

doc/getting_started_rtkernel.rst

@@ -291,18 +291,8 @@ SNMP
 ----
 To enable SNMP support, set the ``PNET_OPTION_SNMP`` value to ``ON``.
 
-To verify the SNMP capabilities, first use ``ping`` to make sure you have a
-connection to the device, and then use ``snmpwalk``::
-
-   ping 192.168.0.50
-   snmpwalk -v1 -c public 192.168.0.50 1
-   snmpget -v1 -c public 192.168.0.50 1.3.6.1.2.1.1.4.0
-   snmpset -v1 -c private 192.168.0.50 1.3.6.1.2.1.1.4.0 s "My new sys contact"
-
-If you enable debug logging in the p-net stack, the two last commands will
-cause entries in the p-net log.
-
-For more details on SNMP and its usage, see :ref:`network-topology-detection`.
+See :ref:`network-topology-detection` for more details on SNMP and how to
+verify the SNMP communication to the p-net stack.
 
 
 IP-stack lwip