Skip to content

Commit

Permalink
Push to quay.io: Update and fix README.md
Browse files Browse the repository at this point in the history
Signed-off-by: Sebastian Schildt <[email protected]>
  • Loading branch information
SebastianSchildt authored and erikbosch committed Jun 11, 2024
1 parent 6bf227c commit 791bf27
Showing 1 changed file with 27 additions and 16 deletions.
43 changes: 27 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# KUKSA GPS Provider

![kuksa.val Logo](./doc/img/logo.png)

The KUKSA GPS Provider consumes [gpsd](https://gpsd.gitlab.io/gpsd/) as datasource and pushes location to
Expand All @@ -9,20 +10,20 @@ The [`gpsd_feeder.ini`](./config/gpsd_feeder.ini) contains configuration for co

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:

```
```console
gpsd -S <gpsd port> -N <gps device>
```

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:

```
```console
gpsd -N udp://0.0.0.0:29998
```

## Install dependencies and execution

```
```console
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]]

Expand Down Expand Up @@ -52,7 +53,7 @@ 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.

```
```console
pip install -r requirements.txt
python gpsd_feeder.py
```
Expand All @@ -64,7 +65,7 @@ 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.

```
```console
python gpsd_feeder.py --protocol grpc --port 55555 --insecure true --token /home/user/kuksa.val/jwt/provide-all.token
```

Expand All @@ -77,7 +78,7 @@ If addressing with a numeric IP-address and using grpc as protocol the "real" se
`--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.

```
```console
python gpsd_feeder.py --port 55555 --protocol grpc --ip 127.0.0.1 --cacertificate ~/kuksa-common/tls/CA.pem --tls-server-name Server
```

Expand All @@ -86,16 +87,26 @@ python gpsd_feeder.py --port 55555 --protocol grpc --ip 127.0.0.1 --cacertificat
You can also use `docker` to execute the feeder platform independently.
To build a docker image:

```
```console
docker build -t gps-provider .
```

To run:

You can also download docker images from [our container registry](https://github.com/eclipse/kuksa.val.feeders/pkgs/container/kuksa-gps-provider%2Fgps-provider).
```console
docker run -it -p 29998:29998/udp -v $PWD/config:/config gps-provider
```

To run:
You can also download pre-built docker images:

```console
docker run -it -p 29998:29998/udp -v $PWD/config:/config ghcr.io/eclipse-kuksa/kuksa-gps-provider/gps-provider:main
```
docker run -it -p 29998:29998/udp -v $PWD/config:/config gps-provider

If the ghcr registry is not easily accessible to you, e.g. if you are a China mainland user, we also made the container images available at quay.io:

```console
docker run -it -p 29998:29998/udp -v $PWD/config:/config quay.io/eclipse-kuksa/gps-provider:main
```

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.
Expand All @@ -109,21 +120,22 @@ You can also use [gpsfake](https://gpsd.gitlab.io/gpsd/gpsfake.html) to playback
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:

```
```console
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:

```
```console
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
Expand All @@ -134,7 +146,7 @@ This might be due to a an overly restrictive apparmor configuration. On Ubuntu e

search for a section looking like this

```
```console
# common serial paths to GPS devices
/dev/tty{,S,USB,AMA,ACM}[0-9]* rw,
/sys/dev/char r,
Expand All @@ -143,18 +155,17 @@ search for a section looking like this

And add a line for pts device so that it looks like

```
```console
# 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

```
```console
sudo systemctl restart apparmor
```

Expand Down

0 comments on commit 791bf27

Please sign in to comment.