Improve documentation

Split Codesys page into two pages Better example string in GSDML file Improve logging Improve error message display in sample app.
rtlabs-com · Mar 24, 2021 · 52e6136 · 52e6136
1 parent 0fe6303
commit 52e6136
Show file tree

Hide file tree

Showing 46 changed files with 1,583 additions and 760 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,9 +5,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## 2021-03-03
+### Changed
+- Set thread priority and stack size via configuration
+
+## 2021-02-19
+### Changed
+- Split options.h into two files.
+- Simplify configuration
+
+## 2020-02-03
+### Added
+ - Improved support for multiple ports
+
 ## 2021-01-29
 ### Changed
- -Move remaining Linux sample app files to src/ports/linux
+ - Move remaining Linux sample app files to src/ports/linux
 
 ## 2020-01-11
 ### Added

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -85,7 +85,7 @@ set(PNET_NUMBER_OF_PHYSICAL_PORTS          1
 set(PNET_MAX_LOG_BOOK_ENTRIES   16
   CACHE STRING "")
 set(PNET_MAX_ALARMS             3
-  CACHE STRING "Per AR and queue. One queue for high and one for low priority alarms.")
+  CACHE STRING "Per AR and queue. One queue for high and one for low priority alarms. 'Automated RT Tester' uses 2.")
 set(PNET_MAX_ALARM_PAYLOAD_DATA_SIZE 28
   CACHE STRING "Min 24 or PNET_MAX_DIAG_MANUF_DATA_SIZE + 12. Max is 1408")
 set(PNET_MAX_DIAG_ITEMS         200

diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ Web resources
 * Source repository: [https://github.com/rtlabs-com/p-net](https://github.com/rtlabs-com/p-net)
 * Documentation: [https://rt-labs.com/docs/p-net](https://rt-labs.com/docs/p-net)
 * Continuous integration: [https://github.com/rtlabs-com/p-net/actions](https://github.com/rtlabs-com/p-net/actions)
-* RT-Labs: [https://rt-labs.com](https://rt-labs.com)
+* RT-Labs (stack integration, certification services and training): [https://rt-labs.com](https://rt-labs.com)
 
 
 [![Build Status](https://github.com/rtlabs-com/p-net/workflows/Build/badge.svg?branch=master)](https://github.com/rtlabs-com/p-net/actions?workflow=Build)
@@ -59,12 +59,11 @@ Limitations or not yet implemented:
 
 * This is a device stack, which means that the IO-controller/master/PLC side is not supported.
 * No media redundancy (No MRP support)
-* No startup mode legacy
+* Legacy startup mode is not fully implemented
 * 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)
@@ -99,17 +98,40 @@ having 8 digital inputs and 8 digital outputs (one bit each). The values are
 sent and received each millisecond (PLC watchdog setting 3 ms).
 
 
+Getting started
+---------------
+See the tutorial in the documentation: [https://rt-labs.com/docs/p-net/tutorial.html](https://rt-labs.com/docs/p-net/tutorial.html)
+
+Note that you need to include submodules when cloning:
+
+```
+git clone --recurse-submodules https://github.com/rtlabs-com/p-net.git
+```
+
 Dependencies
 ------------
+Some of the platform-dependent parts are located in the OSAL repository and the
+cmake-tools repository.
+
+* [https://github.com/rtlabs-com/osal](https://github.com/rtlabs-com/osal)
+* [https://github.com/rtlabs-com/cmake-tools](https://github.com/rtlabs-com/cmake-tools)
+
+Those are downloaded automatically during install.
+
 The p-net stack contains no third party components. Its external dependencies are:
 
 * C-library
 * An operating system (if used)
+* For conformance class B you need an SNMP implementation. On Linux is
+   net-snmp (BSD License) used [http://www.net-snmp.org](http://www.net-snmp.org)
 
-Tools used for building and documentation (not shipped in the resulting binaries):
+Tools used for building, testing and documentation (not shipped in the resulting binaries):
 
-* cmake (BSD 3-clause License)
-* Sphinx (BSD license)
+* cmake (BSD 3-clause License)  [https://cmake.org](https://cmake.org)
+* gtest (BSD-3-Clause License) [https://github.com/google/googletest](https://github.com/google/googletest)
+* Sphinx (BSD license) [https://www.sphinx-doc.org](https://www.sphinx-doc.org)
+* Doxygen (GPL v2) [https://www.doxygen.nl](https://www.doxygen.nl/index.html)
+* clang-format (Apache License 2.0) [https://clang.llvm.org](https://clang.llvm.org/docs/ClangFormat.html)
 
 
 Contributions

diff --git a/doc/abbreviations.rst b/doc/abbreviations.rst
@@ -11,7 +11,8 @@ Commissioning
 Engineering tool
     A desktop program for configuring PLC. For example Siemens TIA portal.
 Parameterization
-    Write parameter values to all submodules
+    Write parameter values to all submodules. Parameterization is done via
+    the Write and Control commands.
 Record data
    Data that can be accessed with acyclic Profinet Read and Write. Addressed by
    slot, subslot and index.

diff --git a/doc/additional_linux_details.rst b/doc/additional_linux_details.rst
@@ -127,19 +127,30 @@ Study the resulting core::
 SNMP (Conformance class B)
 --------------------------
 Conformance class B requires SNMP support. Linux uses net-snmp as agent,
-see http://www.net-snmp.org/. P-Net for Linux implements
-a Net-SNMP subagent that handles the Profinet mandatory MIB:s. Also
+see http://www.net-snmp.org/. The name of the SNMP agent binary is ``snmpd``.
+
+P-Net for Linux implements a Net-SNMP subagent that handles the Profinet
+mandatory MIB:s. Also
 see :ref:`network-topology-detection` for information regarding SNMP.
 
-Enable SNMP by setting ``PNET_OPTION_SNMP`` to ``ON``. Net-SNMP also needs to
+Enable SNMP by setting ``PNET_OPTION_SNMP`` to ``ON`` in the p-net compilation
+options. Net-SNMP also needs to
 be installed. On Ubuntu you can install the required packages using::
 
   sudo apt install -y snmpd libsnmp-dev
 
-The p-net SNMP subagent will handle the system objects so the default
-SNMP system module should be disabled by adding the snmpd argument
-``-I -system_mib``, otherwise the subagent will complain about
-"registering pdu failed" at startup. On Ubuntu Linux you should change
+To show the installed version of ``snmpd``, use::
+
+   snmpd -v
+
+
+Change snmpd command line arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The p-net SNMP subagent will handle the system objects, so the default
+SNMP "system" module should be disabled by adding the snmpd argument
+``-I -system_mib``. Otherwise the subagent will complain about
+"registering pdu failed" at startup. If you use systemd init system (for
+example on Ubuntu Linux) you should change
 ``/lib/systemd/system/snmpd.service`` to read::
 
   [Unit]
@@ -166,13 +177,30 @@ To restart the service after modification::
    sudo systemctl daemon-reload
    sudo systemctl restart snmpd.service
 
+The command line arguments ``-u`` and ``-g`` are for the user id and group id
+of the snmpd process will use after its initial startup.
+They are not necessary to use snmpd.
+However snmpd must be started with permissions to open relevant sockets,
+typically root permissions.
+
+If you use "system V init" instead of systemd, then snmpd is typically started
+by a script file named ``/etc/init.d/snmpd``. Change the snmpd command line
+arguments in the file, typically via ``SNMPDOPTS``. Stop and start the
+service with::
+
+   sudo /etc/init.d/snmpd stop
+   sudo /etc/init.d/snmpd start
+
+
+Configuration file for snmpd
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 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]
+   agentaddress  udp:161
    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
@@ -189,6 +217,8 @@ See :ref:`network-topology-detection` for more details on SNMP and how to
 verify the SNMP communication to the p-net stack.
 
 
+Start your application after snmpd
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 You probably would like your application to wait for the ``snmpd`` application to
 be up and running. If you use systemd as init system, modify this line in
 the ``[Unit]`` part of your ``.service`` file::
@@ -200,6 +230,42 @@ You might also need to add this to the ``[Service]`` part of your
 
    ExecStartPre=/usr/bin/sleep 0.3
 
+If the p-net application fails to connect to snmpd, a message "Warning: Failed
+to connect to the agentx master agent" will be written to the p-net sample
+app log file every 15 seconds.
+
+
+Debugging snmpd settings
+^^^^^^^^^^^^^^^^^^^^^^^^
+The command line argument ``-LOw`` for snmpd sets the snmpd logging to
+standard out with log level "warning".
+To change to log level debug, use ``-LOd``. You should also use the ``-D`` flag
+to select which debug messages you are interested in. Use the ``-Dagentx``
+command line argument to debug the agentx communication between the snmpd and
+the subagent in the p-net stack. A log example when asked for a single OID::
+
+   Connection from UDP: [192.168.0.30]:43833->[192.168.0.50]:161
+   agentx/master: agentx master handler starting, mode = 0xa0
+   agentx/master: request for variable (iso.3.6.1.2.1.1.4.0)
+   agentx/master: sending pdu (req=0x8,trans=0x7,sess=0x6)
+   agentx_build: packet built okay
+   agentx/master: got response errstat=0, (req=0x8,trans=0x7,sess=0x6)
+   agentx/master: agentx_got_response() beginning...
+   agentx/master:   handle_agentx_response: processing: iso.3.6.1.2.1.1.4.0
+   agentx/master: handle_agentx_response() finishing...
+
+Note that there might be a warning message "pcilib: Cannot open /proc/bus/pci"
+in the snmpd log if you specify that it should use all interfaces.
+That is because it will look also for (possibly non-existing) PCI interfaces.
+
+To trouble-shoot snmpd issues, verify that no other snmpd instances are running::
+
+   ps -ef | grep snmpd
+
+and verify that no other process is using UDP port 161::
+
+   sudo lsof -i udp -n -P
+
 
 snmpd in a Yocto build
 ----------------------
@@ -232,3 +298,78 @@ commands to analyze the startup::
    systemd-analyze
    systemd-analyze blame
    systemd-analyze critical-chain pnet-sampleapp.service
+
+
+Debug the sample application on a Linux Laptop
+----------------------------------------------
+It can be convenient to be able to run the sample application and the p-net
+stack in a debugger tool. It is easy using gdb and the Visual Studio Code
+editor.
+
+First make sure you can run the application from a terminal on your Linux
+laptop.
+
+Next step is to be able to run it from the terminal within Visual Studio Code.
+In case of compilation error messages, you can click on the code line given
+in the terminal (within Visual Studio Code) and the corresponding file will
+be opened.
+
+To use debug features while running (for example breakpoints) you need to adapt
+the settings file for Visual Studio Code. Click the "Run and Debug" icon
+in the left side tool bar. Then click "Create a launch.json file". In the
+"Select environment", use "C++ (GDB/LLDB)".
+
+Modify the ``launch.json`` file to point at the correct executable, working
+directory and to use correct command line arguments.
+
+If you need to run the application with root permissions, you need to add a path in the
+``"miDebuggerPath"`` field. It should point to a text file typically named
+``gdb``, with this content::
+
+   pkexec /usr/bin/gdb "$@"
+
+Put the ``gdb`` file for example in the ``.vscode`` subdirectory within
+the ``p-net`` directory. Set the executable flag::
+
+   chmod +x gdb
+
+An example of a ``launch.json`` file::
+
+   {
+      "version": "0.2.0",
+      "configurations": [
+
+         {
+            "name": "(gdb) Launch",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceFolder}/build/pn_dev",
+            "args": ["-vv", "-i", "enp0s31f6"],
+            "stopAtEntry": false,
+            "cwd": "${workspaceFolder}/build/",
+            "environment": [],
+            "externalConsole": false,
+            "MIMode": "gdb",
+            "miDebuggerPath": "${workspaceFolder}/.vscode/gdb",
+            "setupCommands": [
+               {
+                  "description": "Enable pretty-printing for gdb",
+                  "text": "-enable-pretty-printing",
+                  "ignoreFailures": true
+               }
+            ]
+         }
+
+      ]
+   }
+
+The given ``"args"`` command line arguments in the example is for
+increasing the verbosity level and to set the Ethernet interface name.
+Adapt those and also paths to your particular setup.
+
+Use the CMAKE_BUILD_TYPE setting as ``Debug`` when running the executable
+via the debugger.
+
+Start the debugging by clicking on the small green "Run" icon on the
+"Run and Debug" page. It will stop at any breakpoint. Set a breakpoint in
+any file by clicking on a line to the left of the line number.
diff --git a/doc/applications_and_porting.rst b/doc/applications_and_porting.rst
@@ -55,6 +55,21 @@ Hardware requirements for the Ethernet ports:
 * Auto negotiation (should be possible to turn off for fast startup)
 
 
+Interacting with other parts of your application software
+---------------------------------------------------------
+When the PLC sends a "factory reset" command, not only the p-net stack but
+also the rest of your application should be reset to factory settings.
+
+If there is a method to do a factory reset of your application, it should also
+reset the p-net stack.
+
+It is possible to set the IP-address, netmask and gateway address via Profinet
+from a PLC. Consider how this affects other aspects of your application.
+
+Serial number, software version, model name etc should be available for the
+p-net stack to use.
+
+
 Minimum cycle time for your application and hardware
 ----------------------------------------------------
 At PLC configuration, there are two adjustable parameters regarding the

diff --git a/doc/capturing_packets.rst b/doc/capturing_packets.rst
@@ -23,8 +23,8 @@ For details on how to add yourself to the ``wireshark`` user group, see
 https://linuxhint.com/install_wireshark_ubuntu/
 
 
-Filtering frames in Wirehark based on protocol
-----------------------------------------------
+Filtering frames in Wireshark based on protocol
+-----------------------------------------------
 To show only frames with specific protocols, enter this into the "display
 filter" text box::
 
@@ -34,6 +34,32 @@ To hide frames with specific protocols::
 
    not (pn_ptcp or arp or mdns or llmnr or ssdp or dhcp or dhcpv6 or icmpv6 or igmp or nbns or browser or ipv6)
 
++--------------------------+----------------------------------------------------+
+| Filter expression        | Wireshark protocol names                           |
++==========================+====================================================+
+| arp                      | ARP                                                |
++--------------------------+----------------------------------------------------+
+| epm                      | EPM                                                |
++--------------------------+----------------------------------------------------+
+| lldp                     | LLDP                                               |
++--------------------------+----------------------------------------------------+
+| pn_dcp                   | PN-DCP                                             |
++--------------------------+----------------------------------------------------+
+| pn_io                    | PNIO and PNIO_PS and PNIO-AL                       |
++--------------------------+----------------------------------------------------+
+| pn_io_controller         | PNIO-CM (application ready)                        |
++--------------------------+----------------------------------------------------+
+| pn_io_device             | PNIO-CM (connect, read, read implicit, write,      |
+|                          | param end, release)                                |
++--------------------------+----------------------------------------------------+
+| pn_ptcp                  | PN-PTCP                                            |
++--------------------------+----------------------------------------------------+
+| snmp                     | SNMP                                               |
++--------------------------+----------------------------------------------------+
+| syslog                   | Syslog                                             |
++--------------------------+----------------------------------------------------+
+
+
 
 Filter frames in Wireshark based on frame contents
 --------------------------------------------------
@@ -131,6 +157,10 @@ Use the ``-i`` argument to specify Ethernet interface.
 
 Transfer the resulting file to your laptop, where you can open it in Wireshark.
 
+Note that Wireshark and tcpdump modifies the network interface settings on Linux.
+The promiscuous bit will be enabled, as seen when looking at
+``/sys/class/net/eth0/flags``. It will not be visible via ``ifconfig`` though.
+
 
 Hardware for capturing packets on network
 -----------------------------------------