diff --git a/.github/workflows/check_license.yml b/.github/workflows/check_license.yml index 831dc45..df728a0 100755 --- a/.github/workflows/check_license.yml +++ b/.github/workflows/check_license.yml @@ -14,7 +14,7 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: # required to grab the history of the PR fetch-depth: 0 diff --git a/.github/workflows/kuksa_gps_feeder.yml b/.github/workflows/gps_provider.yml similarity index 64% rename from .github/workflows/kuksa_gps_feeder.yml rename to .github/workflows/gps_provider.yml index 8629b66..32630f2 100644 --- a/.github/workflows/kuksa_gps_feeder.yml +++ b/.github/workflows/gps_provider.yml @@ -4,18 +4,18 @@ on: push: branches: [ main ] pull_request: - paths: - - ".github/workflows/kuksa_gps_feeder.yml" - - ".github/actions/post-container-location/action.yml" - - "gps2val/**" workflow_dispatch: concurrency: group: ${{ github.ref }}-${{ github.workflow }} cancel-in-progress: true +# Needed as default_workflow_permissions is "read" +permissions: + packages: write + env: - EPHEMERAL_IMAGE: "ttl.sh/kuksa.val.feeders/gps-${{ github.sha }}" + EPHEMERAL_IMAGE: ttl.sh/eclipse-kuksa/kuksa-gps-provider/gps-provider-${{github.sha}} jobs: @@ -23,27 +23,26 @@ jobs: uses: eclipse-kuksa/kuksa-actions/.github/workflows/check_ghcr_push.yml@2 secrets: inherit - - build-gps-feeder: - name: "Build GPS feeder" + build-gps-provider: + name: "Build GPS provider" runs-on: ubuntu-latest needs: check_ghcr_push steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up QEMU - uses: docker/setup-qemu-action@v2 + uses: docker/setup-qemu-action@v3 - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v2 + uses: docker/setup-buildx-action@v3 - name: Docker meta id: meta - uses: docker/metadata-action@v4 + uses: docker/metadata-action@v5 with: # list of Docker images to use as base name for tags - images: ghcr.io/${{ github.repository }}/gps + images: ghcr.io/${{ github.repository }}/gps-provider # generate Docker tags based on the following events/attributes tags: | type=ref,event=branch @@ -54,7 +53,7 @@ jobs: - name: Log in to the Container registry if: needs.check_ghcr_push.outputs.push == 'true' - uses: docker/login-action@v2 + uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.repository_owner }} @@ -63,12 +62,12 @@ jobs: - name: Build and push KUKSA gps feeder container image and push to ghcr.io and ttl.sh if: needs.check_ghcr_push.outputs.push == 'true' - uses: docker/build-push-action@v4 + uses: docker/build-push-action@v5 with: platforms: | linux/amd64 linux/arm64 - context: gps2val + context: . push: true tags: | ${{ steps.meta.outputs.tags }} @@ -77,25 +76,17 @@ jobs: - name: Build ephemeral KUKSA gps feeder and push to ttl.sh if: needs.check_ghcr_push.outputs.push == 'false' - uses: docker/build-push-action@v4 + uses: docker/build-push-action@v5 with: platforms: | linux/amd64 linux/arm64 - context: gps2val + context: . push: true tags: ${{ env.EPHEMERAL_IMAGE }} labels: ${{ steps.meta.outputs.labels }} - - name: Posting ghcr.io Summary - if: needs.check_ghcr_push.outputs.push == 'true' - uses: ./.github/actions/post-container-location - with: - image: ${{ steps.meta.outputs.tags }} - docker-run-args: "-it --rm" - - - name: Posting ttl.sh Summary - uses: ./.github/actions/post-container-location + - name: Posting message + uses: eclipse-kuksa/kuksa-actions/post-container-location@2 with: image: ${{ env.EPHEMERAL_IMAGE }} - docker-run-args: "-it --rm" diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index c94edd7..e00578d 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -12,11 +12,13 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: # required to grab the history of the PR fetch-depth: 0 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v5 + with: + python-version: '3.10' - uses: pre-commit/action@v3.0.0 with: extra_args: --color=always --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.event.pull_request.head.sha }} diff --git a/gps2val/Dockerfile b/Dockerfile similarity index 100% rename from gps2val/Dockerfile rename to Dockerfile diff --git a/LICENSE.txt b/LICENSE similarity index 99% rename from LICENSE.txt rename to LICENSE index 7a4a3ea..d645695 100644 --- a/LICENSE.txt +++ b/LICENSE @@ -199,4 +199,4 @@ 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. \ No newline at end of file + limitations under the License. diff --git a/README.md b/README.md index 742fdf1..a2443c6 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,167 @@ -# Kuksa Feeders +# KUKSA GPS 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 KUKSA GPS Provider consumes [gpsd](https://gpsd.gitlab.io/gpsd/) as datasource and pushes location to +[KUKSA Databroker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) or +[KUKSA Server](https://github.com/eclipse/kuksa.val/tree/master/kuksa-val-server). -Name | Description ----- | ----------- -[GPS feeder](./gps2val) | GPS data source for KUKSA.val Server and KUKSA.val Databroker -[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 +The [`gpsd_feeder.ini`](./config/gpsd_feeder.ini) contains configuration for connection to KUKSA and gpsd. + +Before starting the KUKSA GPS Provider, you need to start the KUKSA Databroker or KUKSA Server. You have to start an instance of `gpsd` by running: + +``` +gpsd -S -N +``` + +If you do not have a gps device, you can use your cellphone to forward gps data to `gpsd`. For example [gpsd-forward](https://github.com/tiagoshibata/Android-GPSd-Forwarder) is an open source android app. +You can start gpsd with the following command to receive data from the app: + +``` +gpsd -N udp://0.0.0.0:29998 +``` + +## Install dependencies and execution + +``` +usage: gpsd_feeder.py [-h] [--ip [IP]] [--port [PORT]] [--protocol [PROTOCOL]] [--insecure [INSECURE]] [--cacertificate [CACERTIFICATE]] [--tls-server-name [TLS_SERVER_NAME]] [--token [TOKEN]] + [--file [FILE]] [--gpsd_host [GPSD_HOST]] [--gpsd_port [GPSD_PORT]] [--interval [INTERVAL]] + +options: + -h, --help show this help message and exit + --ip [IP] Specify the host where too look for KUKSA Databroker/Server; default: 127.0.0.1 + --port [PORT] Specify the port where too look for KUKSA Databroker/Server; default: 8090 + --protocol [PROTOCOL] + If you want to connect to KUKSA Server specify ws. If you want to connect to KUKSA Databroker specify grpc; default: ws + --insecure [INSECURE] + Specify if you want an insecure connection (i.e. without TLS); default: False + --cacertificate [CACERTIFICATE] + Specify the path to your CA.pem; default: CA.pem. Needed when not using insecure mode + --tls-server-name [TLS_SERVER_NAME] + TLS server name, may be needed if addressing a server by IP-name + --token [TOKEN] Specify the JWT token string or the path to your JWT token; default: authentication information not specified + --file [FILE] Specify the path to your config file; by default not defined + --gpsd_host [GPSD_HOST] + Specify the host for gpsd to start on; default: 127.0.0.1 + --gpsd_port [GPSD_PORT] + Specify the port for gpsd to start on; default: 2948 + --interval [INTERVAL] + Specify the interval time for feeding gps data; default: 1 +``` + +A template config file that can be used together with the `--file` option +exists in [config/gpsd_feeder.ini](config/gpsd_feeder.ini). Note that if `--file` is specified all other options +are ignored, instead the values in the config file or default values specified by kuksa-client will be used. + +``` +pip install -r requirements.txt +python gpsd_feeder.py +``` + +## Authorization + +gpsd_feeder will try to authenticate itself towards the KUKSA Databroker/Server if a token is given. +Note that the KUKSA Databroker by default does not require authentication. + +An example for authorizing against KUKSA Databroker using an example token is shown below. + +``` +python gpsd_feeder.py --protocol grpc --port 55555 --insecure true --token /home/user/kuksa.val/jwt/provide-all.token +``` + +## TLS + +The KUKSA GPS Provider supports using TLS connections. A TLS connection will be used unless `--insecure=True` +is specified. When using a TLS connection a path to the root certificate used by the Server/Databroker must be given. +The client validates the name of the server against the certificate provided by the Server/Databroker. +If addressing with a numeric IP-address and using grpc as protocol the "real" server name must be given using +`--tls-server-name`. For the [KUKSA example certificates](https://github.com/eclipse-kuksa/kuksa-common/tree/main/tls) +the names `localhost`and `Server`can be used. + +``` +python gpsd_feeder.py --port 55555 --protocol grpc --ip 127.0.0.1 --cacertificate ~/kuksa-common/tls/CA.pem --tls-server-name Server +``` + +## Using docker + +You can also use `docker` to execute the feeder platform independently. +To build a docker image: + +``` +docker build -t gps-provider . +``` + + +You can also download docker images from [our container registry](https://github.com/eclipse/kuksa.val.feeders/pkgs/container/kuksa-gps-provider%2Fgps-provider). + +To run: +``` +docker run -it -p 29998:29998/udp -v $PWD/config:/config gps-provider +``` + +The container contains an internal gpsd daemon and the exposed UDP port can be used to feed NMEA data e.g. with [gpsd-forward](https://github.com/tiagoshibata/Android-GPSd-Forwarder) from an Android phone. +If you already have a configured GPSd, just modify the config file to point to it. + +Keep in mind, that GPSd normally only listens on localhost/loopback interface. To connect it from another interface start gpsd with the `-D` option + +## Test with gpsfake + +You can also use [gpsfake](https://gpsd.gitlab.io/gpsd/gpsfake.html) to playback a gps logs in e.g. nmea format. +To install `gpsfake`, follow the command in this [link](https://command-not-found.com/gpsfake). +After installation, run the following command to simulate a gps device as datasource: + +``` +gpsfake -P 2947 simplelog_example.nmea +``` + +Note: You need to use the `gpsfake` with the same version like the installed `gpsd`. + +There are several tools for generating nmea log files: +- [nmea-gps logger](https://www.npmjs.com/package/nmea-gps-logger) +- [nmeagen](https://nmeagen.org/) + +### gpsfake troubleshouting + +If you see a gpsfake error message similar to this one after the feeder connected: + +``` +gpsfake: log cycle of simplelog_example.nmea begins. +gpsd:ERROR: SER: device open of /dev/pts/8 failed: Permission denied - retrying read-only +gpsd:ERROR: SER: read-only device open of /dev/pts/8 failed: Permission denied +gpsd:ERROR: /dev/pts/8: device activation failed, freeing device. +``` + +This might be due to a an overly restrictive apparmor configuration. On Ubuntu edit the file `/etc/apparmor.d/usr.sbin.gpsd` + +search for a section looking like this + +``` + # common serial paths to GPS devices + /dev/tty{,S,USB,AMA,ACM}[0-9]* rw, + /sys/dev/char r, + /sys/dev/char/** r, +``` + +And add a line for pts device so that it looks like + +``` + # common serial paths to GPS devices + /dev/tty{,S,USB,AMA,ACM}[0-9]* rw, + /dev/pts/[0-9]* rw, + /sys/dev/char r, + /sys/dev/char/** r, +``` + + +Restart apparmor + +``` +sudo systemctl restart apparmor +``` + +and try again ## 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. diff --git a/gps2val/config/gpsd_feeder.ini b/config/gpsd_feeder.ini similarity index 100% rename from gps2val/config/gpsd_feeder.ini rename to config/gpsd_feeder.ini diff --git a/gps2val/entrypoint.sh b/entrypoint.sh similarity index 99% rename from gps2val/entrypoint.sh rename to entrypoint.sh index 44f0aac..62055f8 100755 --- a/gps2val/entrypoint.sh +++ b/entrypoint.sh @@ -40,4 +40,4 @@ python -u ./gpsd_feeder.py $* cleanup # check for remaining gpsd processes -pidof gpsd \ No newline at end of file +pidof gpsd diff --git a/gps2val/README.md b/gps2val/README.md deleted file mode 100644 index 115de2a..0000000 --- a/gps2val/README.md +++ /dev/null @@ -1,147 +0,0 @@ -# GPS Feeder -consumes [gpsd](https://gpsd.gitlab.io/gpsd/) as datasource and pushes location to kuksa.val server. -The [`gpsd_feeder.ini`](./config/gpsd_feeder.ini) contains `kuksa.val` and `gpsd` configuration. - -Before starting the gps feeder, you need to start `kuksa.val server/databroker` (for this have a look at [KUKSA.val server]( https://github.com/eclipse/kuksa.val/blob/master/kuksa-val-server/README.md) and [KUKSA.val databroker]( https://github.com/eclipse/kuksa.val/blob/master/kuksa_databroker/README.md)). You have to start an instance of `gpsd` by running: -``` -gpsd -S -N -``` - -If you do not have a gps device, you can use your cellphone to forward gps data to `gpsd`. For example [gpsd-forward](https://github.com/tiagoshibata/Android-GPSd-Forwarder) is an open source android app. You can start gpsd with the following command to receive data from the app: - -``` -gpsd -N udp://0.0.0.0:29998 -``` -## Install dependencies and execution - -``` -usage: gpsd_feeder.py [-h] [--ip [IP]] [--port [PORT]] [--protocol [PROTOCOL]] [--insecure [INSECURE]] [--cacertificate [CACERTIFICATE]] [--tls-server-name [TLS_SERVER_NAME]] [--token [TOKEN]] - [--file [FILE]] [--gpsd_host [GPSD_HOST]] [--gpsd_port [GPSD_PORT]] [--interval [INTERVAL]] - -options: - -h, --help show this help message and exit - --ip [IP] Specify the host where too look for KUKSA.val server/databroker; default: 127.0.0.1 - --port [PORT] Specify the port where too look for KUKSA.val server/databroker; default: 8090 - --protocol [PROTOCOL] - If you want to connect to KUKSA.val server specify ws. If you want to connect to KUKSA.val databroker specify grpc; default: ws - --insecure [INSECURE] - Specify if you want an insecure connection (i.e. without TLS)default: False - --cacertificate [CACERTIFICATE] - Specify the path to your CA.pem; default: CA.pem. Needed when not using insecure mode - --tls-server-name [TLS_SERVER_NAME] - TLS server name, may be needed if addressing a server by IP-name - --token [TOKEN] Specify the JWT token string or the path to your JWT token; default: authentication information not specified - --file [FILE] Specify the path to your config file; by default not defined - --gpsd_host [GPSD_HOST] - Specify the host for gpsd to start on; default: 127.0.0.1 - --gpsd_port [GPSD_PORT] - Specify the port for gpsd to start on; default: 2948 - --interval [INTERVAL] - Specify the interval time for feeding gps data; default: 1 -``` - -A template config file that can be used together with the `--file` option -exists in [config/gpsd_feeder.ini](config/gpsd_feeder.ini). Note that if `--file` is specified all other options -are ignored, instead the values in the config file or default values specified by kuksa-client will be used. - -``` -pip install -r requirements.txt -python gpsd_feeder.py -``` - -## Authorization - -gpsd_feeder will try to authenticate itself towards the KUKSA.val Server/Databroker if a token is given. -Note that the KUKSA.val Databroker by default does not require authentication. - -An example for authorizing against KUKSA.val Databroker using an example token is shown below. - -``` -python gpsd_feeder.py --protocol grpc --port 55555 --insecure true --token /home/user/kuksa.val/jwt/provide-all.token -``` - -## TLS - -The KUKSA.val GPS Feeder supports using TLS connections. A TLS connection will be used unless `--insecure=True` -is specified. When using a TLS connection a path to the root certificate used by the Server/Databroker must be given. -The client validates the name of the server against the certificate provided by the Server/Databroker. -If addressing with a numeric IP-address and using grpc as protocol the "real" server name must be given using -`--tls-server-name`. For the [KUKSA.val example certificates](https://github.com/eclipse/kuksa.val/tree/master/kuksa_certificates) -the names `localhost`and `Server`can be used. - -``` -python gpsd_feeder.py --port 55555 --protocol grpc --ip 127.0.0.1 --cacertificate ~/kuksa.val/kuksa_certificates/CA.pem --tls-server-name Server -``` - -### Using docker -You can also use `docker` to execute the feeder platform independently. -To build a docker image: -``` -docker build -t gpsd_feeder . -``` - -You can also download docker images from [our container registry](https://github.com/eclipse/kuksa.val.feeders/pkgs/container/kuksa.val.feeders%2Fgps). - -To run: -``` -docker run -it -p 29998:29998/udp -v $PWD/config:/config gpsd_feeder -``` - -The container contains an internal gpsd daemon and the exposed UDP port can be used to feed NMEA data e.g. with [gpsd-forward](https://github.com/tiagoshibata/Android-GPSd-Forwarder) from an Android phone. If you already have a configured GPSd, just modify the config file to point to it. - -Keep in mind, that GPSd normally only listens on localhost/loopback interface. To connect it from another interface start gpsd with the `-D` option - -## Test with gpsfake -You can also use [gpsfake](https://gpsd.gitlab.io/gpsd/gpsfake.html) to playback a gps logs in e.g. nmea format. -To install `gpsfake`, follow the command in this [link](https://command-not-found.com/gpsfake). -After installation, run the following command to simulate a gps device as datasource: - -``` -gpsfake -P 2947 simplelog_example.nmea -``` - -Note: You need to use the `gpsfake` with the same version like the installed `gpsd`. - -There are several tools for generating nmea log files: -- [nmea-gps logger](https://www.npmjs.com/package/nmea-gps-logger) -- [nmeagen](https://nmeagen.org/) - -### gpsfake troubleshouting -If you see a gpsfake error message similar to this one after the feeder connected: - -``` -gpsfake: log cycle of simplelog_example.nmea begins. -gpsd:ERROR: SER: device open of /dev/pts/8 failed: Permission denied - retrying read-only -gpsd:ERROR: SER: read-only device open of /dev/pts/8 failed: Permission denied -gpsd:ERROR: /dev/pts/8: device activation failed, freeing device. -``` - -This might be due to a an overly restrictive apparmor configuration. On Ubuuntu edit the file `/etc/apparmor.d/usr.sbin.gpsd` - -search for a section looking like this - -``` - # common serial paths to GPS devices - /dev/tty{,S,USB,AMA,ACM}[0-9]* rw, - /sys/dev/char r, - /sys/dev/char/** r, -``` - -And add a line for pts device so that it looks like - -``` - # common serial paths to GPS devices - /dev/tty{,S,USB,AMA,ACM}[0-9]* rw, - /dev/pts/[0-9]* rw, - /sys/dev/char r, - /sys/dev/char/** r, -``` - - -Restart apparmor - -``` -sudo systemctl restart apparmor -``` - -and try again diff --git a/gps2val/gpsd_feeder.py b/gpsd_feeder.py similarity index 100% rename from gps2val/gpsd_feeder.py rename to gpsd_feeder.py diff --git a/gps2val/requirements.txt b/requirements.txt similarity index 100% rename from gps2val/requirements.txt rename to requirements.txt diff --git a/gps2val/simplelog_example.nmea b/simplelog_example.nmea similarity index 100% rename from gps2val/simplelog_example.nmea rename to simplelog_example.nmea