CSV Provider Migration

Author: erikbosch

.github/workflows/kuksa_csv_provider.yml

@@ -17,16 +17,16 @@ on:
   push:
     branches: [ main ]
   pull_request:
-    paths:
-      - ".github/workflows/kuksa_csv_provider.yml"
-      - ".github/actions/post-container-location/action.yml"
-      - "csv_provider/**"
   workflow_dispatch:
 
 concurrency:
       group: ${{ github.ref }}-${{ github.workflow }}
       cancel-in-progress: true
 
+# Needed as default_workflow_permissions is "read"
+permissions:
+  packages: write
+
 jobs:
   check_ghcr_push:
     uses: eclipse-kuksa/kuksa-actions/.github/workflows/check_ghcr_push.yml@2
@@ -42,7 +42,6 @@ jobs:
 
     - name: Run pylint (but accept errors for now)
       run: |
-        cd csv_provider
         pip3 install --no-cache-dir -r requirements.txt
         pip3 install --no-cache-dir pylint
         # First just show, never fail
@@ -65,7 +64,7 @@ jobs:
       with:
         # list of Docker images to use as base name for tags
         images: |
-          ghcr.io/eclipse/kuksa.val.feeders/csv-provider
+          ghcr.io/eclipse-kuksa/kuksa-csv-provider/csv-provider
         # generate Docker tags based on the following events/attributes
         tags: |
           type=ref,event=branch
@@ -96,12 +95,12 @@ jobs:
         platforms: |
           linux/amd64
           linux/arm64
-        file: ./csv_provider/Dockerfile
-        context: ./csv_provider/
+        file: ./Dockerfile
+        context: ./
         push: true
         tags: |
           ${{ steps.meta.outputs.tags }}
-          ttl.sh/kuksa.val/kuksa-csvprovider-${{github.sha}}
+          ttl.sh/eclipse-kuksa/kuksa-csv-provider/csv-provider-${{github.sha}}
         labels: ${{ steps.meta.outputs.labels }}
 
     - name: Build ephemeral CSV provider container and push to ttl.sh
@@ -112,13 +111,13 @@ jobs:
         platforms: |
           linux/amd64
           linux/arm64
-        file: ./csv_provider/Dockerfile
-        context: ./csv_provider/
+        file: ./Dockerfile
+        context: ./
         push: true
-        tags: "ttl.sh/kuksa.val/kuksa-csvprovider-${{github.sha}}"
+        tags: ttl.sh/eclipse-kuksa/kuksa-csv-provider/csv-provider-${{github.sha}}
         labels: ${{ steps.meta.outputs.labels }}
 
     - name: Posting message
-      uses: ./.github/actions/post-container-location
+      uses: eclipse-kuksa/kuksa-actions/post-container-location@2
       with:
-        image: ttl.sh/kuksa.val/kuksa-csvprovider-${{github.sha}}
+        image: ttl.sh/eclipse-kuksa/kuksa-csv-provider/csv-provider-${{github.sha}}

csv_provider/Dockerfile renamed to Dockerfile

@@ -1,18 +1,96 @@
-# Kuksa Feeders
+# KUKSA CSV Provider
+
 ![kuksa.val Logo](./doc/img/logo.png)
 
-This are data feeders for VSS based systems. The feeders here work with [KUKSA.val](https://github.com/eclipse/kuksa.val)
+The aim of this script is to provide and replay VSS data into a [KUKSA Databroker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker).
+Therefore, it takes a CSV-file, containting pre-defined sequences of VSS signals including timing delays, and provides it to the KUKSA Databroker.
+
+## Usage
+
+The provider requires an installation of Python in version 3 and can be executed with the following commands:
+
+```
+pip install -r requirements.txt
+python3 provider.py
+```
+
+This assumes a running KUKSA Databroker at `127.0.0.1:55555` and a file named `signals.csv` containing the signals to apply. See the section [Arguments](#arguments) for more details on possible arguments and default values.
+
+The provider uses the [kuksa_client]() Python implementation which you need to install on your system, e.g., by applying the [requirement.txt](requirements.txt) with pip.
+
+## Arguments
+
+You can start the provider with the following arguments on a command line:
+
+| short argument | long argument | environment variable | description | default value |
+|---- | ---- | ---- |----- | ----|
+|-f| --file | PROVIDER_SIGNALS_FILE | This indicates the CSV-file containing the signals to update in the KUKSA Databroker. | signals.csv |
+| -a | --address | KUKSA_DATA_BROKER_ADDR | This indicates the address of KUKSA Databroker to connect to. | 127.0.0.1 |
+| -p | --port | KUKSA_DATA_BROKER_PORT | This indicates the port of the KUKSA Databroker to connect to. | 55555 |
+| -i | --infinite | PROVIDER_INFINITE | If the flag is set, the provider loops over the file until stopped, otherwise the file gets processed once. | not present/False
+| -l | --log | PROVIDER_LOG_LEVEL | This sets the logging level. Possible values are: DEBUG, INFO, DEBUG, WARNING, ERROR, CRITICAL | WARNING
+|    | --cacertificate | - | Path to root CA. If defined the client will attempt to use a secure connection and identify the server using this certificate. | None
+|    | --tls-server-name | - | TLS server name, may be needed if addressing a server by IP-name. | None
+
+## CSV File
+
+An example CSV-files is available in [signals.csv](signals.csv) where an example line is:
+
+```
+current,Vehicle.Speed,48,1
+```
+
+The delimiter for the CSV-file is the ',' sign. The first line is interpreted as header and not as data.
 
-Name | Description
----- | -----------
-[GPS Provider](https://github.com/eclipse-kuksa/kuksa-gps-provider)        | GPS data source for KUKSA.val Server and KUKSA.val Databroker *- NOTE: Moved to new repo!*
-[CAN Provider (DBC feeder)](https://github.com/eclipse-kuksa/kuksa-can-provider)        | DBC feeder for for KUKSA.val Server and KUKSA.val Databroker *- NOTE: Moved to new repo!*
-[SOME/IP feeder](./someip2val) | SOME/IP feeder for KUKSA.val Databroker
-[DDS Provider](https://github.com/eclipse-kuksa/kuksa-dds-provider)      | DDS provider for KUKSA.val Databroker *- NOTE: Moved to new repo!*
-[Replay](./replay)             | KUKSA.val Server replay script for previously recorded files, created by providing KUKSA.val Server with `--record` argument
-[CSV provider](./csv_provider) | Script to replay VSS signals to KUKSA.val Databroker as defined in a CSV-file
+Each line in the csv file consists of the following elements:
+
+| header | description | example |
+| -- | -----------| --|
+| field | indicates whether to update the current value (`current`) or the target value (`target`) for the signal. | current |
+| signal | the name of the signal to update | Vehicle.Speed
+| value | the new value | 48 |
+| delay | Indicates the time in seconds which the provider shall wait after processing this signal. This way one can emulate the change of signals over time. | 0 |
+
+## TLS
+
+If connecting to a KUKSA Databroker that require a secure connection you must specify which root certificate to
+use to identify the Server by the `--cacertificate` argument. If your (test) setup use the KUKSA example
+certificates you must give [CA.pem](https://github.com/eclipse/kuksa.val/blob/master/kuksa_certificates/CA.pem)
+as root CA. The server name must match the name in the certificate provided by KUKSA.val databroker.
+Due to a limitation in the gRPC client, if connecting by IP-address you may need to give a name listed in the certificate
+by the `--tls-server-name` argument. The example server certificate lists the names `Server` and `localhost`,
+so one of those names needs to be specified if connecting to `127.0.0.1`. An example is shown below:
+
+```
+python provider.py --cacertificate /home/user/kuksa.val/kuksa_certificates/CA.pem --tls-server-name Server
+```
+
+## Limitations
+
+* CSV Provider does not support authentication, i.e. it is impossible to communicate with a Databroker that require authentication!
+
+## Recorder
+
+One way to generate a CSV-file for the CSV-provider is to record it from an KUKSA Databroker. This way one can reproduce an interaction of different providers with the KUKSA Databroker. The script in `csv_provider/recorder.py` allows this recording.
+An example call, only recording the vehicle speed and width would be:
+
+```
+pip install -r requirements.txt
+python3 recorder.py -s Vehicle.Speed Vehicle.Width
+```
+
+The recorder supports the following parameters:
+
+| short argument | long argument | description | default value |
+|---- | ---- | ----- | ----|
+|-f| --file | This indicates the filename to which to write the VSS-signals. | signalsOut.csv |
+|-s| --signals | A list of signals to record. | There is no default value, but the argument is required.| |
+| -a | --address | This indicates the address of KUKSA Databroker to connect to. | 127.0.0.1 |
+| -p | --port | This indicates the port of the KUKSA Databroker to connect to. | 55555 |
+| -l | --log | This sets the logging level. Possible values are: DEBUG, INFO, WARNING, ERROR, CRITICAL | INFO
 
 ## Pre-commit set up
+
 This repository is set up to use [pre-commit](https://pre-commit.com/) hooks.
 Use `pip install pre-commit` to install pre-commit.
 After you clone the project, run `pre-commit install` to install pre-commit into your git hooks.