Merge pull request #14 from AlexanderBarbie/main

added RS232 example

README.md

@@ -1,4 +1,9 @@
 # Welcome to my research on Digital Twins
-In the folder IEEE Internet Computing you will find a video that shows Digital Twins of ocean observation systems taken in the Baltic Sea in October 2020.
 
-In the folder PiCar-X you will find an example of a Digital Twin.
+This project offers three valuable insights into digital twins and digital twin prototypes:
+
+- Within the IEEE Internet Computing folder, there is a video showcasing Digital Twins of ocean observation systems. These were recorded in the Baltic Sea in October 2020 and provide a practical illustration of digital twins in action.
+
+- The PiCar-X folder contains a Digital Twin Prototype, developed using the ARCHES Digital Twin Framework. This prototype is accompanied by various Docker compose files, each illustrating different aspects of the digital twin concept.
+
+- In the examples folder, you'll find smaller projects that demonstrate integration tests and the virtualization of communication protocols, such as RS232. These projects serve as practical guides to implementing digital twin technologies.

examples/RS232-integration-test-simple/.dockerignore

@@ -0,0 +1,7 @@
+#Dockerignore
+Dockerfile
+Dockerfile-*
+*/dist
+*/*.egg*
+*/build
+venv/*

examples/RS232-integration-test-simple/.gitignore

@@ -0,0 +1,13 @@
+.installed.cfg
+bin
+develop-eggs
+dist
+downloads
+eggs
+parts
+src/*.egg-info
+lib
+lib64
+build
+.idea/*
+venv/*

examples/RS232-integration-test-simple/.gitlab-ci.yml

@@ -0,0 +1,39 @@
+# This file is a template, and might need editing before it works on your project.
+# Official docker image.
+image: docker:stable
+
+variables:
+  CONTAINER_TEST_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG-temp
+  CONTAINER_RELEASE_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH:latest
+  CONTAINER_TEST_IMAGE_ARM_RPI3: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG-temp
+  CONTAINER_RELEASE_IMAGE_ARM_RPI3: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG
+  CONTAINER_TEST_IMAGE_ARM_RPI4: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG-temp
+  CONTAINER_RELEASE_IMAGE_ARM_RPI4: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG
+
+before_script:
+  - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN git.geomar.de:11411
+
+stages:
+  - build
+  - test
+  - release
+  - trigger
+
+build:
+  tags:
+    - arches
+  stage: build
+  script:
+    - docker build --build-arg gitlab_ci_arches_ssh="$gitlab_ci_arches_ssh" --no-cache --pull -t $CONTAINER_TEST_IMAGE .
+    - docker push $CONTAINER_TEST_IMAGE
+
+release:
+  tags:
+    - arches
+  stage: release
+  script:
+    - docker pull $CONTAINER_TEST_IMAGE
+    - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE
+    - docker push $CONTAINER_RELEASE_IMAGE
+  only:
+    - master

examples/RS232-integration-test-simple/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Alexander Barbie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

examples/RS232-integration-test-simple/README.md

@@ -0,0 +1,30 @@
+# Simple Integration Tests Example (RS232 Interface)
+Digital Twin Prototypes (DTP) need emulators of sensors and actuators to replace the hardware of a physical twin (PT). Learn
+more about DTPs in my [preprint on Techrxiv](https://www.techrxiv.org/articles/preprint/Continuous_Integration_Testing_of_Embedded_Software_with_Digital_Twin_Prototypes/14770983).
+
+### Why should I use an emulator instead of tools such as Mockito?
+By using tools such as Mockito, you test your code against a mockup, but not against the interfaces used by the real system.
+With Docker and Socat you can proxy a serial interface on TCP/IP and test a "real" serial connection.
+
+# How to start the example
+1. Install Docker and docker-compose
+2. Clone the project.
+
+`git clone https://github.com/cau-se/DigitalTwinPrototypes`
+
+3. Go to the main folder
+
+`cd \path\to\simple-integration-testing-example`
+
+4. Execute docker-compose
+
+`docker-compose up`
+
+### How to execute the tests
+1. Go to the test folder in simple-driver
+
+`cd \path\to\simple-integration-testing-example\simple-driver\tests`
+
+2. Execute docker-compose
+
+`docker-compose up`

examples/RS232-integration-test-simple/docker-compose.yml

@@ -0,0 +1,40 @@
+version: "3.5"
+services:
+  simple-driver:
+    container_name: "simple-driver"
+    build:
+      context: ./simple-driver
+    environment:
+      - EMU_SIM_TTY_1=/dev/ttyUSB0
+      - EMU_SIM_TTY_1_PORT=7060
+    ports:
+      - 7060:7060
+    tty: true
+    command: bash -c "sleep 0.5 && python3 /home/driver/simple-driver/src/simple-driver/driver.py $${EMU_SIM_TTY_1} 0.0"
+    networks:
+      simple-test-network:
+        ipv4_address: 172.18.0.10
+
+  simple-emulator:
+    container_name: "simple-emulator"
+    build:
+      context: ./simple-emulator
+    environment:
+      - SIM_TTY_1=/dev/ttyUSB0
+      - SIM_TTY_1_ADDRESS=172.18.0.10
+      - SIM_TTY_1_PORT=7060
+    tty: true
+    command: bash -c "sleep 0.5 && python3 /home/emulator/simple-emulator/src/simple-emulator/emulator.py $${SIM_TTY_1} /home/emulator/simple-emulator/include/data/tempdata.csv 0.0"
+    depends_on:
+      - simple-driver
+    networks:
+      simple-test-network:
+        ipv4_address: 172.18.0.11
+
+networks:
+  simple-test-network:
+    driver: bridge
+    ipam:
+      driver: default
+      config:
+        - subnet: 172.18.0.0/24

examples/RS232-integration-test-simple/simple_driver/.dockerignore

@@ -0,0 +1,7 @@
+#Dockerignore
+Dockerfile
+Dockerfile-*
+*/dist
+*/*.egg*
+*/build
+venv/*

examples/RS232-integration-test-simple/simple_driver/.gitignore

@@ -0,0 +1,13 @@
+.installed.cfg
+bin
+develop-eggs
+dist
+downloads
+eggs
+parts
+src/*.egg-info
+lib
+lib64
+build
+.idea/*
+venv/*

examples/RS232-integration-test-simple/simple_driver/.gitlab-ci.yml

@@ -0,0 +1,39 @@
+# This file is a template, and might need editing before it works on your project.
+# Official docker image.
+image: docker:stable
+
+variables:
+  CONTAINER_TEST_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG-temp
+  CONTAINER_RELEASE_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH:latest
+  CONTAINER_TEST_IMAGE_ARM_RPI3: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG-temp
+  CONTAINER_RELEASE_IMAGE_ARM_RPI3: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG
+  CONTAINER_TEST_IMAGE_ARM_RPI4: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG-temp
+  CONTAINER_RELEASE_IMAGE_ARM_RPI4: $CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG
+
+before_script:
+  - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN git.geomar.de:11411
+
+stages:
+  - build
+  - test
+  - release
+  - trigger
+
+build:
+  tags:
+    - arches
+  stage: build
+  script:
+    - docker build --build-arg gitlab_ci_arches_ssh="$gitlab_ci_arches_ssh" --no-cache --pull -t $CONTAINER_TEST_IMAGE .
+    - docker push $CONTAINER_TEST_IMAGE
+
+release:
+  tags:
+    - arches
+  stage: release
+  script:
+    - docker pull $CONTAINER_TEST_IMAGE
+    - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE
+    - docker push $CONTAINER_RELEASE_IMAGE
+  only:
+    - master

examples/RS232-integration-test-simple/simple_driver/Dockerfile

@@ -0,0 +1,17 @@
+FROM ubuntu:20.04
+
+ENV EMU_SIM_TTY_1 ""
+ENV EMU_SIM_TTY_1_PORT ""
+
+WORKDIR /home/driver/simple_driver
+
+RUN apt-get update \
+    && apt-get install -y socat python3-pip
+
+COPY . .
+RUN chmod +x ./docker/entrypoint.sh
+
+RUN pip3 install .
+
+ENTRYPOINT ["./docker/entrypoint.sh"]
+

examples/RS232-integration-test-simple/simple_driver/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Alexander Barbie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

examples/RS232-integration-test-simple/simple_driver/README.md

@@ -0,0 +1,3 @@
+# Simple Driver
+You find the integration tests in the folder tests.
+

examples/RS232-integration-test-simple/simple_driver/docker/entrypoint.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -e
+
+if [[ $EMU_SIM_TTY_1 && $EMU_SIM_TTY_1_PORT ]];
+then
+  {
+    socat tcp-listen:"$EMU_SIM_TTY_1_PORT" pty,link="$EMU_SIM_TTY_1"
+  }&
+fi
+
+exec "$@"

examples/RS232-integration-test-simple/simple_driver/setup.py

@@ -0,0 +1,14 @@
+from setuptools import setup
+
+setup(
+    name='simple_driver',
+    version='1.0',
+    description='A simple driver to demonstrate integration tests of RS232 interfaces with Docker',
+    license="MIT",
+    author='Alexander Barbie',
+    author_email='[email protected]',
+    url="https://github.com/",
+    package_dir={'': 'src'},
+    packages=['simple_driver'],  # same as name
+    install_requires=['pyserial'],  # external packages as dependencies
+)

examples/RS232-integration-test-simple/simple_driver/src/simple_driver/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2024 Alexander Barbie
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+