built-in aisdecoder

.github/workflows/container.yml

@@ -0,0 +1,47 @@
+name: Docker Builds
+
+on: [workflow_dispatch]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up QEMU
+      uses: docker/[email protected]
+      with:
+        image: tonistiigi/binfmt:qemu-v8.1.5
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Cache Docker layers
+      id: cache-docker
+      uses: actions/cache@v4
+      with:
+        path: /tmp/.buildx-cache
+        key: ${{ runner.os }}-buildx-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-buildx-
+
+    - name: Log in to GHCR
+      if: github.event_name != 'pull_request'
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.repository_owner }}
+        password: ${{ secrets.RTLAIS_GITHUB_TOKEN }}
+
+    - name: Build and push to ghcr
+      uses: docker/build-push-action@v6
+      with:
+        context: .
+        file: ./Dockerfile
+        platforms: linux/amd64,linux/arm64,linux/386,linux/arm/v6,linux/arm/v7
+        push: ${{ github.event_name != 'pull_request' }}
+        outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=AIS recevier using RTL-SDR dongle
+        tags: |
+          ghcr.io/bklofas/rtl-ais:latest
+

.gitignore

@@ -0,0 +1,4 @@
+*.o
+rtl_ais
+debianPackage/usr
+debianPackage/*.deb

Dockerfile

@@ -0,0 +1,47 @@
+# -------------------
+# The build container
+# -------------------
+FROM debian:bookworm-slim AS build
+
+WORKDIR /usr/src/app
+
+COPY . /usr/src/app
+
+# Upgrade bookworm and install dependencies
+RUN apt-get -y update && apt -y upgrade && apt-get -y install --no-install-recommends \
+    rtl-sdr \
+    librtlsdr-dev \
+    libusb-1.0-0-dev \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Build rtl_ais
+RUN make && \
+    make install
+
+
+# -------------------------
+# The application container
+# -------------------------
+FROM debian:bookworm-slim
+
+LABEL org.opencontainers.image.title="rtl-ais"
+LABEL org.opencontainers.image.description="AIS decoding using RTL-SDR dongle"
+LABEL org.opencontainers.image.authors="Bryan Klofas KF6ZEO bklofas@gmail"
+LABEL org.opencontainers.image.source="https://github.com/bklofas/rtl-ais"
+
+# Upgrade bookworm and install dependencies
+RUN apt-get -y update && apt -y upgrade && apt-get -y install --no-install-recommends \
+    tini \
+    rtl-sdr \
+    librtlsdr-dev \
+    libusb-1.0-0-dev &&\
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /usr/src/app /
+
+# Use tini as init.
+ENTRYPOINT ["/usr/bin/tini", "--"]
+
+CMD ["/rtl_ais", "-n"]
+

LICENCE

@@ -0,0 +1,18 @@
+/*
+ * Copyright (C) 2012 by Kyle Keen <[email protected]>  
+ * rtl-ais uses code from AISDecoder Copyright (C) 2013  Astra Paging Ltd / AISHub ([email protected])
+ * AISDecoder uses parts of GNUAIS project (http://gnuais.sourceforge.net/)
+ * 
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */

Makefile

@@ -0,0 +1,80 @@
+CFLAGS?=-O2 -g -Wall  
+CFLAGS+= -I./aisdecoder -I ./aisdecoder/lib -I./tcp_listener 
+LD_EXTRA_PATHS= -L /usr/lib/arm-linux-gnueabihf -L /usr/lib/i386-linux-gnu -L /usr/lib/x86_64-linux-gnu
+LDFLAGS+=-lpthread -lm $(LD_EXTRA_PATHS)
+ifeq ($(PREFIX),)
+    PREFIX := /usr/local
+endif
+UNAME := $(shell uname)
+ifeq ($(UNAME),Linux)
+#Conditional for Linux
+CFLAGS+= $(shell pkg-config --cflags librtlsdr)
+LD_LIBRTLSDR=$(shell pkg-config --libs librtlsdr)
+#Ugly hack. Check if the output of pkg-config is long enough to be valid
+LD_LIBRTLSDR_LENGTH := $(shell echo "$(LD_LIBRTLSDR)" | wc -c)
+ifeq ($(shell test $(LD_LIBRTLSDR_LENGTH) -gt 13; echo $$?),0)
+#The  pkg-config output seem to be ok, let's use it
+	LDFLAGS+=$(shell pkg-config --libs librtlsdr)
+else
+#The  pkg-config output seem to be too short, use the default lib name and default paths
+	LDFLAGS+=-lrtlsdr
+endif
+
+else
+#
+#ADD THE CORRECT PATH FOR LIBUSB AND RTLSDR
+#TODO:
+#    CMAKE will be much better or create a conditional pkg-config
+
+
+# RTLSDR
+RTLSDR_INCLUDE=/tmp/rtl-sdr/include
+RTLSDR_LIB=/tmp/rtl-sdr/build/src
+
+# LIBUSB
+LIBUSB_INCLUDE=/tmp/libusb/include/libusb-1.0
+LIBUSB_LIB=/tmp/libusb/lib
+
+ifeq ($(UNAME),Darwin)
+#Conditional for OSX
+CFLAGS+= -I/usr/local/include/ -I/opt/homebrew/include -I$(LIBUSB_INCLUDE) -I$(RTLSDR_INCLUDE)
+LDFLAGS+= -L/usr/local/lib -L/opt/homebrew/lib -L$(LIBUSB_LIB) -L$(RTLSDR_LIB) -lrtlsdr -lusb-1.0 
+else
+#Conditional for Windows
+CFLAGS+=-I $(LIBUSB_INCLUDE) -I $(RTLSDR_INCLUDE)
+LDFLAGS+=-L$(LIBUSB_INCLUDE) -L$(RTLSDR_LIB) -L/usr/lib -lusb-1.0 -lrtlsdr -lWs2_32
+endif
+
+
+endif
+
+CC?=gcc
+SOURCES= \
+	main.c rtl_ais.c convenience.c \
+	./aisdecoder/aisdecoder.c \
+	./aisdecoder/sounddecoder.c \
+	./aisdecoder/lib/receiver.c \
+	./aisdecoder/lib/protodec.c \
+	./aisdecoder/lib/hmalloc.c \
+	./aisdecoder/lib/filter.c \
+	./tcp_listener/tcp_listener.c
+
+OBJECTS=$(SOURCES:.c=.o)
+EXECUTABLE=rtl_ais
+
+all: $(SOURCES) $(EXECUTABLE)
+
+$(EXECUTABLE): $(OBJECTS) 
+	$(CC) $(OBJECTS) -o $@ $(LDFLAGS)
+
+.c.o:
+	$(CC) -c $< -o $@ $(CFLAGS)
+
+clean:
+	rm -f $(OBJECTS) $(EXECUTABLE) $(EXECUTABLE).exe
+
+install:
+	install -d -m 755 $(PREFIX)/bin
+	install -m 755 $(EXECUTABLE) "$(PREFIX)/bin/"
+
+

README.md

@@ -0,0 +1,162 @@
+`rtl-ais`, a simple AIS tuner and generic dual-frequency FM demodulator
+-----------------------------------------------------------------------
+
+rtl-ais provides the `rtl_ais` command, which decodes AIS data from Software Defined Radio (SDR) and outputs `AIVDM` / `AIVDO` sentences.
+
+| OS support |   |
+|------------|---|
+| Linux      | ✅ |
+| Windows    | ✅ |
+| OSX        | ✅ |
+
+
+Command Line
+------------
+```
+Use: rtl_ais [options] [outputfile]
+        [-l left_frequency (default: 161.975M)]
+        [-r right_frequency (default: 162.025M)]
+            left freq < right freq
+            frequencies must be within 1.2MHz
+        [-s sample_rate (default: 24k)]
+            maximum value, might be down to 12k
+        [-o output_rate (default: 48k)]
+            must be equal or greater than twice -s value
+        [-E toggle edge tuning (default: off)]
+        [-D toggle DC filter (default: on)]
+        [-d device_index (default: 0)]
+        [-g tuner_gain (default: automatic)]
+        [-p ppm_error (default: 0)]
+        [-R enable RTL chip AGC (default: off)]
+        [-A turn off built-in AIS decoder (default: on)]
+            use this option to output samples to file or stdout.
+        Built-in AIS decoder options:
+        [-h host (default: 127.0.0.1)]
+        [-P port (default: 10110)]
+        [-T use TCP communication as tcp listener ( -h is ignored)]
+        [-t time to keep ais messages in sec, using tcp listener (default: 15)]
+        [-n log NMEA sentences to console (stderr) (default off)]
+        [-L log sound levels to console (stderr) (default off)]
+        [-I add sample index to NMEA mesages (default off)]
+        [-S seconds_for_decoder_stats (default 0=off)]
+        When the built-in AIS decoder is disabled the samples are sent to
+        to [outputfile] (a '-' dumps samples to stdout)
+            omitting the filename also uses stdout
+        Output is stereo 2x16 bit signed ints
+        Examples:
+        Receive AIS traffic,sent UDP NMEA sentences to 127.0.0.1 port 10110
+             and log the senteces to console:
+        rtl_ais -n
+        Tune two fm stations and play one on each channel:
+        rtl_ais -l233.15M  -r233.20M -A  | play -r48k -traw -es -b16 -c2 -V1 -
+```
+
+
+Compiling
+---------
+Make sure you have the following dependencies:
+  - librtlsdr
+  - libusb
+  - libpthread
+
+```console
+$ # Get the source code:
+$ git clone https://github.com/dgiardini/rtl-ais
+$ # Change to the source dir
+$ cd rtl-ais
+$ make
+$ # Test running the command
+$ ./rtl_ais
+```
+
+For compiling a MS Windows executable you will need a working MSYS/MinGW environment.
+Edit the `Makefile`, and modify these lines:
+
+```Makefile
+#### point this to your correct path ###
+RTLSDR_PATH="/c/tmp/rtl-sdr/"
+RTLSDR_LIB=$(RTLSDR_PATH)/build/src/
+########################################
+```
+
+
+Installing
+----------
+* On Linux, `sudo make install`
+* On Windows, put the `librtlsdr.dll` and `libusb-1.0.dll` files in the same directory
+with `rtl_ais.exe`. You'll need the `zadig` driver installed too.
+
+
+Running
+-------
+
+rtl-ais uses software defined radio (SDR).  The specific
+hardware we use for this is a DVB-T dongle. A good starting point is:
+https://www.rtl-sdr.com/about-rtl-sdr
+
+You'll need also an antenna, and be located near (some miles)  the
+passing vessels.
+
+You'll also need to do some procedure to get the tunning error for the
+specfic dongle you have (aka ppm error), and pass that number as parameter
+of rtl-ais.
+
+
+Docker Container
+----------------
+Now you can run rtl-ais in a docker container. No dependencies to install. Total container size is 55 to 75 MB, depending on the host architecture. Get/install docker [here](https://docs.docker.com/get-docker/).
+
+Two options for obtaining the container: Either download and run a pre-built container, or build the container locally.
+
+ 1. Just to test things out: `docker run -it --rm --device=/dev/bus/usb ghcr.io/bklofas/rtl-ais:latest`
+    * This downloads a pre-built container from the Github container registry.
+    * Architectures supported are i386, amd64, arm32v6, arm32v7, and arm64. Tested on amd64, arm32v7, and arm64. arm packages run on all RaspberryPi flavors. Your client will automatically download the appropriate architecture.
+    * This image will run by default `./rtl_ais -n`, showing the received packets on STDOUT. Uses all other default values.
+    * You can add other ./rtl-sdr options, see below.
+    * Make sure at least one RTL-SDR dongle is connected.
+    * Startup messages and decoded packets will display in the terminal.
+    * Ctrl-C to kill.
+    * Using the `--rm` flag will delete the container when you kill it. Otherwise, it will stay around until you prune.
+
+ 1. For a more permanent setup, run the container in the background and add any options you want: `docker run -d --name rtl-ais --restart=unless-stopped --log-driver=local --network=host --device=/dev/bus/usb ghcr.io/bklofas/rtl-ais:latest ./rtl_ais -n -d 00000002 -h 127.0.0.1 -P 10110`
+    * -d: Start this container in daemon/background mode.
+    * --name: Name this anything you want.
+    * --restart=unless-stopped: Automatically restart the container if something happens (reboot, USB problem), unless you have manually stopped the container.
+    * --log-driver=local: By default, docker uses the json log driver which may fill up your harddrive, depending on how busy your station is. `local` log driver defaults to 100MB of saved logs, and automatically rotates them.
+    * --network=host: Allows the container to talk to the internet, if you are sending the packets to an online service.
+    * --device=: Allows the container to talk to the USB bus to access the RTL-SDR dongle.
+    * ./rtl_ais: Same command-line options as non-containerized.
+    * View the startup messages and decoded packets with `docker logs --follow rtl-ais`
+    * Stop the container with `docker stop rtl-ais`
+
+Building the container:
+
+ * Clone the repository with `git clone https://github.com/dgiardini/rtl-ais.git` , then from the folder `docker build -t rtl-ais .`
+ *  Or, build the container without cloning the repository: `docker build https://github.com/dgiardini/rtl-ais.git`
+
+Other tips and tricks:
+
+ * If you have the `-n` flag, view the decoded AIS packets in real-time with `docker logs --follow rtl-ais`
+ * If you are only sending packets to one internet service (such as marinetraffic.com), you can use the `-h` and `-P` options that they provide.
+ * You are encouraged to send your decoded packets to multiple online services. Check out AIS packet multiplexer [kplex](http://www.stripydog.com/kplex/), pre-built containers are available [here](https://ghcr.io/bklofas/kplex).
+
+
+Testing
+-------
+
+TODO: something like
+https://github.com/freerange/ais-on-sdr/wiki/Testing-AISDecoder#with-an-audio-file
+
+
+Known Issues
+------------
+* The `[-p ppm error]` parameter is essential for rtl_ais to work.
+  * The ppm error is the frequency deviation in parts per million from the desired tuning
+frequency, and the real tuned frequency due to the crystal oscillator deviation. This
+figure is different for each device, it's very important to know  this value and pass this parameter to rtl_ais.
+  * Some instructions for get the ppm error are here:
+    http://www.rtl-sdr.com/how-to-calibrate-rtl-sdr-using-kalibrate-rtl-on-linux
+  * and here (using SDR#):
+    http://www.atouk.com/SDRSharpQuickStart.html#adjusting
+  * and here (using HDSDR ad AIS traffic)
+    http://www.cruisersforum.com/forums/f134/new-rtlsdr-plugin-102929-11.html#post1844966

TODO

@@ -0,0 +1,6 @@
+----
+TODO
+----
+- Auto calibration mode
+- Compile as library
+- Add audio gain control