SKA-463: Update SKA TAP Adaptive Guide for CANoe 18 (#70)

- adaptive guide has been restructured to reduce redundancy for showcasing several CANoe workflows
- new workflow for CANoe 18 (and newer) has been added

CMakeLists.txt

@@ -132,6 +132,18 @@ install(
     EXCLUDE_FROM_ALL
 )
 
+install(
+    FILES            
+        ${CMAKE_CURRENT_SOURCE_DIR}/adaptive/helper-scripts/start_app_sil_kit_adapters_setup.sh
+    DESTINATION adaptive/helper-scripts
+    PERMISSIONS
+        OWNER_READ OWNER_WRITE OWNER_EXECUTE
+        GROUP_READ GROUP_EXECUTE
+        WORLD_READ WORLD_EXECUTE
+    COMPONENT source
+    EXCLUDE_FROM_ALL
+)
+
 install(
     FILES
         CMakeLists.txt

README.md

@@ -104,5 +104,5 @@ Vector SIL Kit. Traffic being exchanged are ping (ICMP) requests, and the answer
 
 This demo is further explained in [tap/demos/DemoWindows/README.md](tap/demos/DemoWindows/README.md).
 
-## Connecting an adaptive executable to CANoe
-The SIL Kit Adapter TAP allows you to connect adaptive executables to CANoe. A guide describes step by step how to do this can be found here [adaptive/README.md](adaptive/README.md). 
+## Connecting an Adaptive executable to CANoe
+The Vector SIL Kit Adapter TAP allows you to connect Adaptive executables to CANoe. A step-by-step guide on how to do this can be found [here](adaptive/README.md).

adaptive/helper-scripts/start_app_sil_kit_adapters_setup.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+export AMSR_DISABLE_INTEGRITY_CHECK=1
+export SILKIT_ADAPTER_TAP_PATH=/home/vector/SilKit/sil-kit-adapters-tap/bin
+
+# check if user is root
+if [[ $EUID -ne 0 ]]; then
+    echo "This script must be run as root / via sudo -E!"
+    exit 1
+fi
+
+# check if AMSR_SRC_DIR is set
+if [[ -z $AMSR_SRC_DIR ]]; then
+    echo "Make sure \$AMSR_SRC_DIR is set to your BSW Package folder and this script is run with sudo -E!"
+    exit 1
+fi
+
+startapp_cm_server1_pid=
+# cleanup trap for child processes
+trap 'kill $startapp_cm_server1_pid $(jobs -p); exit' EXIT SIGINT;
+
+echo "Recreating tap_demo_ns network namespace"
+if test -f "/run/netns/tap_demo_ns"; then
+    ip netns delete tap_demo_ns
+fi
+
+echo "Creating tap device silkit_tap"
+#Add device with name silkit_tap with mode tap
+ip tuntap add dev silkit_tap mode tap
+
+echo "Starting sil-kit-adapter-tap..."
+$SILKIT_ADAPTER_TAP_PATH/sil-kit-adapter-tap --name 'SilKit_TapDevice' --tap-name 'silkit_tap'  --registry-uri 'silkit://localhost:8501' --network 'Ethernet1' &> /$SCRIPT_DIR/sil-kit-adapter-tap.out &
+sleep 1 # wait 1 second for the creation/existense of the .out file
+timeout 30s grep -q 'Press CTRL + C to stop the process...' <(tail -f /$SCRIPT_DIR/sil-kit-adapter-tap.out) || { echo "[error] Timeout reached while waiting for sil-kit-adapter-tap to start"; exit 1; }
+echo "sil-kit-adapter-tap has been started"
+
+# Hint: It is important to establish the connection to the the adapter before moving the tap device to its separate namespace
+echo "Moving tap device 'silkit_tap' to network namespace 'tap_demo_ns'"
+#network namespace, means : add network namespace called tap_demo_ns
+ip netns add tap_demo_ns
+#established link between our silkit_tap device and network namespace tap_demo_ns
+ip link set silkit_tap netns tap_demo_ns
+
+echo "Configuring tap device 'silkit_tap'"
+ip -netns tap_demo_ns addr add 192.168.7.2/16 dev silkit_tap
+ip -netns tap_demo_ns link set silkit_tap up
+
+# start crypto daemon
+cd $AMSR_SRC_DIR/Examples/startapplication/build/gcc7_linux_x86_64/install/opt/amsr_crypto_daemon
+bash -c "nsenter --net=/run/netns/tap_demo_ns ./bin/amsr_crypto_daemon &" &> $SCRIPT_DIR/crypto.out
+sleep 2
+echo "crypto daemon has been started."
+
+# start someip daemon
+cd $AMSR_SRC_DIR/Examples/startapplication/build/gcc7_linux_x86_64/install/opt/amsr_someipd_daemon
+bash -c "nsenter --net=/run/netns/tap_demo_ns ./bin/amsr_someipd_daemon -c ./etc/someipd-posix.json &" &> $SCRIPT_DIR/someipd.out
+sleep 2
+echo "someip daemon has been started."
+
+# start server application
+cd $AMSR_SRC_DIR/Examples/startapplication/build/gcc7_linux_x86_64/install/opt/startapp_cm_server1
+echo "starting server application..."
+./bin/startapp_cm_server1 &
+startapp_cm_server1_pid=$!
+wait $startapp_cm_server1_pid

adaptive/readme-sub-sections/interaction_with_CANoe17_and_COs.md

@@ -0,0 +1,68 @@
+## Create CANoe configuration (CANoe 17 and newer)
+
+Create a new CANoe configuration based on the template `Ethernet (Communication Setup)`.  
+
+An Adaptive application usually has multiple ARXML files, the CANoe AUTOSAR Preprocessor allows you to merge these ARXML files. You can start it from the CANoe `Tools` ribbon.
+
+With the option `Choose Input Directory...` you can select the whole *model* folder of the *start application*. In that case be aware to delete the client .arxml files for this demo use case as mentioned [here](../README.md#setup-canoe-as-a-client-tester-and-sil-kit-participant).
+
+![Combine ARXML files with the AUTOSAR preprocessor](../images/AutosarPreprocessor.png)
+
+The combined system descriptions (ARXML) can be added in the Communication Setup (`Communication Setup -> Load Data Source`). This will configure the network setup and generate communication objects, allowing you to test the available services.
+
+![Load Data Source](../images/CommunicationSetup_Load.png)
+
+### Testing the server - CANoe as client
+
+In this demo we run the server executable in the Linux system and use CANoe as a client.
+CANoe will derive a participant as application layer object for the executable defined in the combined ARXML. This participant builds the server, which is executed on the Linux system as real device. It consists of multiple communication objects; a communication object will be derived for every service interface and allows accessing events, fields, methods and PDUs. As CANoe will build the counterpart to the real device, automatically another application layer participant `CANoe` is derived.
+
+Depending on the amount of ARXMLs that were added and their contained service interfaces, additional communication objects may have been derived.  
+
+- Set the state of communication objects that are not needed for the moment, e.g. the Diagnostic Service Interface, to `Off`.
+- Set the state of the participant CANoe to `On/Simulated (CANoe)` and enable to generate the C# API, since we will write a C# test.  
+- The state of the participant running in the Linux system shall be set to `Real (Device)` - in our example this is the participant ``StartApplicationMachineDesign``.
+
+You may need to press the `Publish` button to make the changes available e.g. in the Symbol Explorer.
+
+![Adapt states in Communication Setup](../images/CommunicationSetup_Off.png)
+
+![Adapt states in Communication Setup](../images/CommunicationSetup_Simulated.png)
+
+![Adapt states in Communication Setup](../images/CommunicationSetup_Real.png)
+
+
+The following test checks the availability of the service provided by the server application and tests if the *StartApplicationMethod1* works correctly. You can add it to the CANoe Test Setup and run it after [starting the simulation](../README.md#canoe-common-sil-kit-configuration-steps).
+
+```csharp
+  [TestCase("TestClientMethod")]
+  private void TestClientMethod()
+  {
+    Report.TestCaseDescription("Check valid operation of service method \"Add\"");
+
+    for(uint number = 201; number < 204; number++)
+    {
+      Report.TestStep("INVOKE_METHOD", "Transmit request to server provider: StartApplicationMethod1" + number.ToString());
+      DataTypes.StartApplicationMethod1_prototype_Base.CallContext call_handle;
+      call_handle = NetworkDB.ProvidedSomeipStartApplicationCmService1_ServiceInterface.consumerSide.StartApplicationMethod1.CallAsync(number);
+      // Wait until result received or timeout
+      if (Execution.WaitForAnswer(call_handle, 10000).WaitResult == 1)
+      {
+        Report.TestStepPass("CHECK_RESULT", "Received response from server");
+        uint received_value = call_handle.output_argument;
+        uint expected_value = number + 1;
+        // Compare received result to expected value
+        if (received_value == expected_value)
+        {
+          Report.TestStepPass("CHECK_RESULT", "Expected return value received: " + call_handle.output_argument.ToString());
+        }
+        //[...]
+      }
+      else
+      {
+        Report.TestStepFail("TestCase timed out.");
+      }
+    }
+  }
+```
+Continue with the [common steps](../README.md#canoe-common-sil-kit-configuration-steps).

adaptive/readme-sub-sections/interaction_with_CANoe18_and_DOs.md

@@ -0,0 +1,78 @@
+## Create CANoe configuration (CANoe 18 and newer)
+
+Create a new CANoe configuration based on the template `Ethernet (Application Objects)`.
+
+**Hint (optional):** If you do not want or can not use the template mentioned above you can also activate the new workflow for an existing configuration with the *Simulation Setup Application Layer Objects* option:
+
+![Simulation Setup Application Layer Objects](../images/sim_setup_app_layer_options.png)
+
+An Adaptive application usually has multiple ARXML files, the CANoe AUTOSAR Preprocessor allows you to merge these ARXML files. It is a separate tool installed together with CANoe. You can start it from the Windows start menu or from the CANoe `Tools` ribbon.
+
+With the option `Choose Input Directory...` you can select the whole *model* folder of the *start application*. In that case be aware to delete the client .arxml files for this demo use case as mentioned [here](../README.md#setup-canoe-as-a-client-tester-and-sil-kit-participant).
+
+**Hint:** There is an known issue with the combination of the *start application* e2e use case from version D94 and the CANoe 18 database import. We don't need this use case for this demo. Therefore delete the selected files as well to avoid any issues:
+
+![Combine ARXML files with the AUTOSAR preprocessor](../images/selection_of_e2e_arxmls.png)
+
+Leave the settings in the AUTOSAR Preprocessor at their default values:
+
+![AUTOSAR preprocessor settings](../images/autosar_preprocessor_settings.png)
+
+The combined system descriptions (ARXML) can be added to the simulation setup via the *Databases Import Wizard*:
+
+![Simulation Setup Import Wizard](../images/sim_setup_import_wizard.png)
+
+Use the `Select...` button to choose the file, assign both available nodes and complete the wizard process:
+
+![Simulation Setup Import Wizard node selection](../images/wizard_definiton_of_nodes.png)
+
+This will configure the network setup and generate distributed objects, allowing you to test the available services. You will get an overview about the generated distributed objects and derived participants in the *Symbol Explorer*. The ones derived for the client mockup of CANoe which can be used for testing can be found in *VectorSimulationNode*:
+
+![Symbol Explorer overview](../images/symbol_explorer_overview.png)
+
+You also need to add *CANoeILNL_AUTOSAR_Eth.vmodule* to the *Components* of the *VectorSimulationNode*. This can be done in the *Node Configuration* which you can access via the context menu of the the *VectorSimulationNode* with the entry *Configuration...*. The .vmodule file itself can be found in your CANoe installation folder:
+
+![Node Configuration](../images/node_config_and_autosarEth_IL.png)
+
+### Testing the server - CANoe as client
+
+In this demo we run the server executable in the Linux system and use CANoe as a client. Letting CANoe act as a client can be done by accessing the derived distributed objects with the automatically generated C# API.
+
+A first test could consist of checking the availability of the service provided by the server application and test if the *StartApplicationMethod1* works correctly:
+
+```csharp
+  [TestCase("TestClientMethod")]
+  private void TestClientMethod()
+  {
+      Report.TestCaseDescription("Check valid operation of service method \"Add\"");
+
+      for (uint number = 201; number < 204; number++)
+      {
+          Report.TestStep("INVOKE_METHOD", "Transmit request to server provider: StartApplicationMethod1" + number.ToString());
+          var call_handle = StartApplicationEthernetCluster.VectorSimulationNode.ProvidedSomeipStartApplicationCmService1_ServiceInterface.StartApplicationMethod1.CallAsync(number);
+          // Wait until result received or timeout
+          if (Execution.WaitForAnswer(call_handle, 10000).WaitResult == 1)
+          {
+              Report.TestStepPass("CHECK_RESULT", "Received response from server");
+              uint received_value = call_handle.output_argument;
+              uint expected_value = number + 1;
+              // Compare received result to expected value
+              if (received_value == expected_value)
+              {
+                  Report.TestStepPass("CHECK_RESULT", "Expected return value received: " + call_handle.output_argument.ToString());
+              }
+              //[...]
+          }
+          else
+          {
+              Report.TestStepFail("TestCase timed out.");
+          }
+
+      }
+  }
+```
+
+Continue with the [common steps](../README.md#canoe-common-sil-kit-configuration-steps).
+
+
+

adaptive/readme-sub-sections/interaction_with_CANoe_common_steps.md

@@ -0,0 +1,40 @@
+## Configuration of SIL Kit
+
+Enable SIL Kit in CANoe by entering the global: `Options -> Extensions -> SIL Kit -> Enable SIL Kit`.
+
+1. **Registry URI**: Set the IP address and port to the values of the system where the sil-kit-registry is running. In our example we run the sil-kit-registry on the Linux system, where the Adaptive application is executed.
+
+2. **Participant Name**: This name is the identifier of CANoe in the context of SIL Kit communication.  
+
+3. **Configuration File**: For our first example the name of the network in CANoe ("Ethernet1") equals the name of the SIL Kit network that is passed to the Vector SIL Kit Adapter TAP. Therefore we do not need to specify a configuration file because both participants will be in the same SIL Kit network by default.
+
+      ![Enable SIL Kit in global options](../images/EnableSILKit.png)
+
+## Advanced configuration of SIL Kit (optional)
+
+To use a custom network for the interaction, create a new YAML file containing the configuration of the SIL Kit for CANoe.
+
+In this file, the option "EthernetControllers" with the attributes "Name" and "Network" needs to be defined:
+
+```YAML
+Description: Configuration for CANoe participant
+EthernetControllers:
+- Name: "Ethernet1/IPStack_CANoe_NetworkInterface_CANoe"
+  Network: "silkit_network"
+```
+
+**Important**: The "Name" of the "EthernetControllers" in the YAML file must match the pattern "CANoeEthNetworkName/CANoeSimulationPortName". The value given at "Network" needs to match the network name which has been set for Vector SIL Kit Adapter TAP as well. To check the names of the Simulation Ports in CANoe, go to the `Hardware` tab and select `Port Configuration`:
+
+![Port Configuration](../images/PortConfiguration.png)
+
+## SIL Kit Channel Mapping
+
+In a last configuration step, the simulation and channel settings need to be adapted in CANoe. First change the simulation mode to `Real Bus`.
+
+![Switch simulation mode to real bus](../images/SwitchToRealBus.png)  
+
+Now switch to the `Hardware` tab and click on `Channel Mapping`. In this window one Ethernet channel should be shown. In the dropdown menu for the option `Hardware` set the value to `SIL Kit`.
+
+![SIL Kit channel mapping](../images/ChannelMapping.png)  
+
+After you changed the mapping you can switch back to `Simulated Bus (animated with factor=1)` again.