Improve documentation

README.md

@@ -61,6 +61,7 @@ Limitations or not yet implemented:
 * No iPar (parameter server) support
 * No support for time synchronization
 * No UDP frames at alarm (just the default alarm mechanism is implemented)
+* No ProfiDrive or ProfiSafe profiles.
 
 This software is dual-licensed, with GPL version 3 and a commercial license.
 See LICENSE.md for more details.

doc/additional_linux_details.rst

@@ -123,6 +123,7 @@ Study the resulting core::
 
     gdb pf_test core
 
+
 SNMP (Conformance class B)
 --------------------------
 Conformance class B requires SNMP support. Linux uses net-snmp as agent,
@@ -164,18 +165,25 @@ To restart the service after modification::
    sudo systemctl daemon-reload
    sudo systemctl restart snmpd.service
 
-The file snmpd.conf controls access to the snmp agent. It should be
+The file ``snmpd.conf`` controls access to the snmp agent. It should be
 set to listen on all interfaces and allow read-write access to the
 Profinet MIB:s. On Ubuntu Linux you should change
 ``/etc/snmp/snmpd.conf`` to read::
 
    master  agentx
    agentaddress  0.0.0.0,[::1]
    view   systemonly  included   .1.3.6.1.2.1.1
+   view   systemonly  included   .1.3.6.1.2.1.2.2
    view   systemonly  included   .1.0.8802.1.1.2
    rocommunity  public  default -V systemonly
    rwcommunity  private default -V systemonly
 
+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``::
 
@@ -184,10 +192,40 @@ connection to the device, and then use ``snmpwalk``::
    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.
 
 
 snmpd in a Yocto build
 ----------------------
 In an embedded Linux Yocto build, you would include the ``snmpd`` daemon by
 using the ``net-snmp`` recipe.
+
+
+Persistent logs
+---------------
+To make the journalctl logs persistent between restarts::
+
+   sudo mkdir -p /var/log/journal
+   sudo systemd-tmpfiles --create --prefix /var/log/journal
+
+Remove all contents of the journalctl logs::
+
+   sudo journalctl --rotate
+   sudo journalctl --vacuum-time=1s
+
+
+Boot time optimization
+----------------------
+The boot time should be less than approximately 15 seconds, for the "missing
+peer" alarm to be sent within 30 s after the power on.
+
+To improve the startup time of your Linux device, it is useful to study what
+is delaying the start. If you use the "systemd" init system, you can use these
+commands to analyze the startup::
+
+   systemd-analyze
+   systemd-analyze blame
+   systemd-analyze critical-chain pnet-sampleapp.service

doc/capturing_packets.rst

@@ -65,7 +65,10 @@ to add a new column. Change "Title" to "Delta displayed" and "Type" to
 
 Plot transmission time periodicity using Wireshark
 --------------------------------------------------
-To plot the periodicity of sent frames, use the menu "Statistics" -> "I/O Graph".
+To plot the periodicity of sent frames, you first need to filter the displayed
+frames in the main Wireshark window, as described above.
+
+Then use the menu "Statistics" -> "I/O Graph".
 
 * Display filter: ``eth.src == 54:ee:75:ff:95:a6 and pn_io``
 * Y Axis: AVG(Y Field)

doc/compliancetest.rst

@@ -74,6 +74,10 @@ More details are given in the "Product Documentation" document for the tool.
 You might also need to turn off LLDP protocol for the selected network
 interface. Both Windows and Simatic TIA can have LLDP implemented.
 
+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.
 
 Use a separate network for running tests with Advanced RT tester
@@ -345,9 +349,11 @@ Relevant test cases for conformance class B
 Set the GSDML file attributes ``ConformanceClass="B"`` and
 ``SupportedProtocols="SNMP;LLDP"``.
 
+* Behavior scenario 10
 * Topology discovery check, standard setup
 * Topology discovery check, non-Profinet-neighbour setup
 * Port-to-port
+* Behavior of reset to factory (manual)
 
 
 Relevant test cases for multi-port devices
@@ -383,6 +389,8 @@ describes the startup time in milliseconds.
 
 * FSU
 * Different Access Ways
+* Manual FSU test case
+* Hardware (no auto-negotiation)
 
 
 Relevant test cases for DHCP
@@ -405,45 +413,106 @@ Load PLC program
 Verify that the sample application PLC program is working properly with your
 IO-device. Button1 should be able to control the state of data LED (LED1).
 
+Interoperability
+^^^^^^^^^^^^^^^^
+Run with PLC for 10 minutes without errors.
+If the device under test has more than one port, there should be 5 IO-devices
+connected to the non-PLC port.
+
+The timing should be the fastest allowed according to the GSDML
+file, and use 3 "accepted update cycles without IO data".
+Record startup and data exchange using Wireshark.
+
+In the Wireshark file, make sure IOPS and IOCS in the cyclic data from the
+IO-device have the value GOOD after it has sent the "application ready"
+message.
+Also verify that there have been no alarms (sort the frames by protocol).
+
+* "Record data"?
+* ExpectedIdentification is equal to the RealIdentification?
+* How to create additional net load? (using DCP Identify all)
+* Implicit read?
 
 Data Hold Timer
 ^^^^^^^^^^^^^^^
-Unplug network cable from the PLC while recording the cyclic data (use Wireshark).
-Count the number of cyclic data frames before the alarm from the IO-device is sent.
-It is allowed that 3-6 data frames are sent before sending the alarm frame.
+Run with PLC. The timing should be the fastest allowed according to the GSDML
+file, and use 3 "accepted update cycles without IO data".
+Record startup and data exchange using Wireshark.
 
-Perform the cable unplugging measurements with reduction ratios 1, 2, 4, 8 and 16.
-The data hold time should be 3x the frame interval.
-With a cycle time of 1 ms this corresponds to a frame send interval of
-1 ms to 16 ms, and a data hold time of 3 ms to 48 ms.
+Unplug network cable from the PLC.
 
-In Siemens TIA portal, set the update time to for example 2 ms (values
-1, 2, 4, 8, and 16 ms should be used).
-The "Accepted update cycles without IO data" should be set to 3.
+In the Wireshark file:
 
-At startup the first valid data frame should be sent within the data hold time.
-Check IOPS.
+* Count the number of cyclic data frames sent by the IO-device before the
+  alarm frame appears. It is allowed that 3-6 data frames are sent before
+  the alarm frame.
+* At startup the first valid data frame should be sent within the data
+  hold time.
+* The IOCS in the cyclic data from the IO-device should have the value GOOD
+  after the "application ready" message has been sent.
+* Verify the data cycle time.
 
-Verify the data cycle time.
+Repeat the cable unplugging measurements with reduction ratios (1), 2, 4, 8
+and 16. With a cycle time of for example 1 ms this corresponds to a frame
+send interval of 1 ms to 16 ms, and a data hold time of 3 ms to 48 ms.
 
 Check that a LLDP frame is sent within 5 seconds, and then every 5 seconds.
 The TTL value in the LLDP frame should be 20 seconds.
 The MAUtype, "autonegotiation supported" and "autonegotiation enabled" must
 be correct.
 
+Interoperability with controller
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Run with PLC. The timing should be the fastest allowed according to the GSDML
+file, and use 3 "accepted update cycles without IO data".
+Record startup and data exchange using Wireshark.
 
-Interoperability
-^^^^^^^^^^^^^^^^
-Run with PLC for 10 minutes without errors. Record startup and data exchange using Wireshark.
+Verify that the outputs are according to the manual of your IO-device when
+you do these actions (repeat several times):
 
-* ExpectedIdentification is equal to the RealIdentification?
-* Additional net load?
-* Implicit read?
+* PLC powered off
+* PLC powered on. The program should be running.
+* Switch the PLC to stop.
+* Switch the PLC to run.
+* Disconnect cable from PLC.
+* Reconnect the PLC cable.
 
-Interoperability with controller
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Run with PLC, and verify that the outputs are according to the manual of your
-IO-device.
+In the Wireshark file, make sure IOPS and IOCS in the cyclic data from the
+IO-device have the value GOOD after it has sent the "application ready"
+message.
+
+* Record data?
+
+Security Level 1 tester
+-----------------------
+Install the tester software on an Ubuntu machine, or in a virtual Ubuntu
+machine running on Windows.
+See the PDF in the "Security Level 1"/"tester" folder in the downloaded
+test bundle.
+
+Use a non-Profinet switch (no LLDP packet filtering) to connect the device
+under test (DUT), the PLC and the personal computer running the Security
+Level 1 tester software. For single port devices, use port 1 on the PLC and
+port 1 on the DUT.
+
+A PLC program is used to both establish cyclic data communication, and to
+repeatedly do acyclic data read out from the IO-device.
+
+In Siemens TIA Portal, open the file "normal_d_V2.40.0_V15.1.zap15_1" as
+an existing project. Give the path to a local directory that will be used
+for the project.
+
+Delete the existing "dut" device and "d" device. Insert your IO-device and
+adjust the settings (as described on the page about Siemens PLCs in
+this documentation).
+
+In the "Main [OB1]" program, change the line with ``Ihw_ID`` to::
+
+   Ihw_ID := "rt-labs-dev~Head",
+
+Right-click on the PLC icon, and select Compile > "Hardware (rebuild all)" and
+then "Software (rebuild all)". Use "Download to device" > "Hardware
+configuration" and then "Software (all)".
 
-* Switch the PLC to stop. Study the outputs of the IO-device.
-* Disconnect cable from PLC. Study the outputs of the IO-device.
+Verify that there is cyclic communication, and that there is repeated
+acyclic data read out.

doc/getting_started_rtkernel.rst

@@ -299,6 +299,9 @@ connection to the device, and then use ``snmpwalk``::
    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`.
 
 

doc/implementation_details.rst

@@ -654,6 +654,18 @@ Name functions and variables using "snake_case", for example
 
 Pointer names start with ``p_``, for example ``p_data_status``.
 
+Instead of::
+
+   if (have_dhcp == true){...}
+   if (!have_dhcp){...}
+
+use::
+
+   if (have_dhcp){...}
+   if (have_dhcp == false){...}
+
+(Note that this not yet is fully implemented in the stack.)
+
 Run clang-format on staged files before committing::
 
     $ git add .
@@ -677,5 +689,5 @@ Github workflow:
 * Commit your fix to the branch. Add the line "Closes #123" (for example)
   in the commit message, to indicate which Github issue it closes.
 * Push the branch to your Github account.
-* Create a pull request to rtlabs-com/p-net on Github.
+* Create a pull request to https://github.com/rtlabs-com/p-net
 * After review the fix will be merged.

doc/index.rst

@@ -24,6 +24,7 @@ documentation.
    sampleapp_details.rst
    profinet_details.rst
    prepare_raspberrypi.rst
+   multiple_ports.rst
    creating_gsdml_files.rst
    network_topology_detection.rst
    applications_and_porting.rst

doc/multiple_ports.rst

@@ -1,6 +1,5 @@
 Multiple ports
 ==============
-
 This section describes how to configure the p-net stack, sample application
 and system for multiple network interfaces or ports.
 
@@ -9,20 +8,20 @@ Terminology
 -----------
 
 Interface
-    Abstract group of ports. In Profinet context, interface typically doesn't mean a 
-    specific network interface. This is a common cause of confusion. 
+    Abstract group of ports. In Profinet context, interface typically doesn't mean a
+    specific network interface. This is a common cause of confusion.
 Port
-    Network interface. The physical connectors are referred to as "physical ports". 
+    Network interface. The physical connectors are referred to as "physical ports".
     A "management port" is the network interface to which a controller / PLC connects.
 
-In the example described in this section, br0 is the management port 
-and eth0 and eth1 are the physical ports. The interface consists of br0, eth0 and eth1.
+In the example described in this section, ``br0`` is the management port
+and ``eth0`` and ``eth1`` are the physical ports. The interface consists of
+``br0``, ``eth0`` and ``eth1``.
 
 
 Configuration of bridge using Linux
 -----------------------------------
-
-Tested with Raspberry PI 3B+ and USB ethernet dongle USB3GIG.
+Tested with Raspberry PI 3B+ and USB Ethernet dongle USB3GIG.
 
             +-------------+
             |    br0      |
@@ -32,8 +31,8 @@ Tested with Raspberry PI 3B+ and USB ethernet dongle USB3GIG.
 
 
 p-net supports multiple Ethernet ports. To use multiple ports, these
-shall be grouped into a bridge. In such a configuration the management port / main network interface 
-is the bridge and the ethernet interfaces are named physical ports.
+shall be grouped into a bridge. In such a configuration the management port / main network interface
+is the bridge and the Ethernet interfaces are named physical ports.
 
 To create a bridge and add network interfaces to it, create the following files and content::
 
@@ -98,7 +97,7 @@ Configuration of p-net stack and sample application (TBD)
 To run p-net and the sample application with multiple ports a couple
 of things need to be done:
 
-* Reconfigure setting ``PNET_MAX_PORT`` to the actual number of physical ports available in the system. 
-  For this example ``PNET_MAX_PORT`` shall be set to 2. 
+* Reconfigure setting ``PNET_MAX_PORT`` to the actual number of physical ports available in the system.
+  For this example ``PNET_MAX_PORT`` shall be set to 2.
 
 * TBD - update this document when multiport support is implemented