{"id":13576789,"url":"https://github.com/szpajder/dumpvdl2","last_synced_at":"2025-04-05T08:33:17.782Z","repository":{"id":18052024,"uuid":"83237133","full_name":"szpajder/dumpvdl2","owner":"szpajder","description":"VDL Mode 2 message decoder and protocol analyzer","archived":false,"fork":false,"pushed_at":"2024-10-22T20:57:53.000Z","size":3282,"stargazers_count":211,"open_issues_count":1,"forks_count":39,"subscribers_count":37,"default_branch":"master","last_synced_at":"2024-11-05T13:42:02.739Z","etag":null,"topics":["acars","aviation","cpdlc","raspberry-pi","rtl-sdr","sdr","sdrplay","software-defined-radio","vdlm2"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/szpajder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-26T20:09:20.000Z","updated_at":"2024-10-30T22:33:22.000Z","dependencies_parsed_at":"2023-12-31T22:48:45.652Z","dependency_job_id":"b115f9f0-185c-4a81-a2a5-ac4041bf193f","html_url":"https://github.com/szpajder/dumpvdl2","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szpajder%2Fdumpvdl2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szpajder%2Fdumpvdl2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szpajder%2Fdumpvdl2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szpajder%2Fdumpvdl2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/szpajder","download_url":"https://codeload.github.com/szpajder/dumpvdl2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247312065,"owners_count":20918340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acars","aviation","cpdlc","raspberry-pi","rtl-sdr","sdr","sdrplay","software-defined-radio","vdlm2"],"created_at":"2024-08-01T15:01:14.178Z","updated_at":"2025-04-05T08:33:17.764Z","avatar_url":"https://github.com/szpajder.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# dumpvdl2\n\ndumpvdl2 is a VDL Mode 2 message decoder and protocol analyzer.\n\nCurrent stable version: 2.4.0 (released October 19, 2024)\n\n## Features\n\n- Runs under Linux (tested on: x86, x86-64, ARM) and MacOS (not tested very\n  well, feedback welcome)\n- Supports following SDR hardware:\n  - RTLSDR (via [rtl-sdr library](http://osmocom.org/projects/sdr/wiki/rtl-sdr))\n  - Mirics SDR (via [libmirisdr-4](https://github.com/f4exb/libmirisdr-4))\n  - SDRPlay RSP (native support through official driver version 2 and 3)\n  - SoapySDR (via [soapy-sdr project](https://github.com/pothosware/SoapySDR/wiki))\n  - prerecorded IQ data from a file\n- Decodes multiple VDL2 channels simultaneously\n- Automatically reassembles multiblock ACARS messages, MIAM file transfers,\n  fragmented X.25, CLNP and COTP packets.\n- Supports various outputs and output formats (see below)\n- Enriches logged messages with ground station details read from a text file\n  (MultiPSK format)\n- Enriches logged messages with aircraft data read from Basestation SQLite\n  database\n- Supports message filtering by type or direction (uplink, downlink)\n- Can store raw frames in a binary file for later decoding or archiving\n  purposes.\n- Produces decoding statistics using [Etsy StatsD](https://github.com/etsy/statsd) protocol\n\n## Supported output formats\n\n- Human readable text\n- JSON\n- Single-line ACARS format accepted by Planeplotter\n- Custom binary format (suitable for storing raw frames)\n\n## Supported output types\n\n- file (with optional daily or hourly file rotation)\n- reliable network messaging via [ZeroMQ](https://zeromq.org/)\n- UDP socket\n\n## Example\n\n![dumpvdl2 screenshot](example.png?raw=true)\n\n## Supported protocols\n\n- Aviation Link Control (AVLC)\n- ACARS over AVLC\n- ISO 8208 / X.25 DTE-DCE Interface\n- ISO 8473 / X.233 Connectionless Network Protocol (CLNP)\n- ISO 8073 / X.224 Connection Oriented Transport Protocol (COTP)\n- ISO 8327 / X.225 Session Protocol\n- ISO 8650 / X.227 Association Control Service Element (ACSE)\n- ISO 9542 End System to Intermediate System (ES-IS)\n- ISO 10747 Inter-Domain Routing Protocol (IDRP)\n- ATN-B1 Context Management\n- ATN-B1 Controller-Pilot Data Link Communications, version 1 (CPDLC)\n- ATN-B2 Automatic Dependent Surveillance - Contract, version 2 (ADS-C)\n- All applications and protocols handled by libacars library (full list [here](https://github.com/szpajder/libacars/blob/master/README.md#supported-message-types))\n\n## Installation\n\n### Dependencies\n\nMandatory dependencies:\n\n- gcc\n- make\n- cmake\n- pkg-config\n- git (unless you intend to use only packaged releases of dumpvdl2 and all\n  dependencies)\n- glib2\n- libacars 2.1.0 or later\n\nOptional dependencies:\n\n- SDR device drivers:\n  - librtlsdr\n  - libmirisdr-4\n  - SDRPlay binary driver\n  - SoapySDR\n- Dependencies for optional features:\n  - sqlite3 (for enriching messages with aircraft data read from SQB database)\n  - statsd-c-client (for Etsy StatsD statistics)\n  - libprotobuf-c 1.3.0 or later (for binary format support)\n  - libzmq 3.2.0 or later (for ZeroMQ networked output)\n\nInstall necessary dependencies (unless you have them already). Example for\nDebian / Raspbian:\n\n```\nsudo apt install build-essential cmake git libglib2.0-dev pkg-config\n```\n\nInstall `libacars` library - either:\n\n- download a stable release package from [here](https://github.com/szpajder/libacars/releases)\n- or clone the source repository with:\n\n```\ncd\ngit clone https://github.com/szpajder/libacars\ncd libacars\n```\n\nCompile and install the library:\n\n```\nmkdir build\ncd build\ncmake ../\nmake\nsudo make install\nsudo ldconfig\n```\n\n#### RTLSDR support (optional)\n\nTo use RTL dongles, install `librtlsdr` library (unless you have it already).\nRaspbian has a packaged version:\n\n```\napt install librtlsdr-dev\n```\n\nIf your distribution does not provide a package, then clone the source\nrepository and compile manually:\n\n```\napt install libtool autoconf libusb-1.0-0-dev\ncd\ngit clone git://git.osmocom.org/rtl-sdr.git\ncd rtl-sdr/\nautoreconf -i\n./configure\nmake\nsudo make install\nsudo ldconfig\nsudo cp $HOME/rtl-sdr/rtl-sdr.rules /etc/udev/rules.d/rtl-sdr.rules\n```\n\n#### Mirics support (optional)\n\nlibmirisdr-4 is an open-source alternative to SDRPlay binary driver (Mirics is\nthe chipset brand which SDRPlay RSPs are based on). However, as of December\n2017, it works properly with RSP1 only. For other RSP types (RSP2, RSP/1A) gain\ncontrol does not work too well, so the native closed source driver is a better\noption (see next section).  libmirisdr-4 is a good choice for RSP1 and various\nMirics-based DVB-T dongles which are detected as RSP1 device. An advantage over\nRSP binary API is lower CPU utilization in dumpvdl2 thanks to a lower sampling\nrate.\n\nInstall `libmirisdr-4` library:\n\n```\napt install libusb-1.0-0-dev\ncd\ngit clone https://github.com/f4exb/libmirisdr-4.git\ncd libmirisdr-4\n./build.sh\ncd build\nsudo make install\nsudo ldconfig\nsudo cp $HOME/libmirisdr-4/mirisdr.rules /etc/udev/rules.d/mirisdr.rules\n```\n\n#### SDRPLAY RSP support (optional)\n\nDownload and install API/hardware driver package from [here](\nhttp://www.sdrplay.com/downloads/).  Make sure you have selected the right\nhardware platform before downloading, otherwise the installer will fail.\ndumpvdl2 supports both version 2 and 3 of the driver. Version 3 is needed\nfor newer devices (like RSPdx). Older hardware works with both versions.\nYou can have both versions installed simultaneously and choose either one\nwhen running the program.\n\n#### SoapySDR support (optional)\n\nDownload and install the SoapySDR library from [here](https://github.com/pothosware/SoapySDR).\nThen install the driver module for your device. Refer to [SoapySDR wiki](https://github.com/pothosware/SoapySDR/wiki)\nfor a list of all supported modules.\n\n**Note:** The device must support a sampling rate of 2100000 samples per second\nto work correctly with dumpvdl2. It is therefore not possible to use devices\nwhich only support predefined, fixed sampling rates (notably Airspies). This\nlimitation will be removed in a future release of dumpvdl2.\n\n#### SQLite (optional)\n\nVDL2 message addressing is based on ICAO 24-bit hex codes (same as ADS-B).\ndumpvdl2 may use your basestation.sqb database to enrich logged messages with\naircraft data (registration number, operator, type, etc). If you want this\nfeature, install SQLite3 library:\n\n```\nsudo apt install libsqlite3-dev\nsudo ldconfig\n```\n\n#### Etsy StatsD statistics (optional)\n\nInstall `statsd-c-client` library from https://github.com/romanbsd/statsd-c-client:\n\n```\ncd\ngit clone https://github.com/romanbsd/statsd-c-client.git\ncd statsd-c-client\nmake\nsudo make install\nsudo ldconfig\n```\n\n#### Binary input/output format support (optional)\n\ndumpvdl2 can write raw AVLC frames into a binary file. Each frame is stored\ntogether with its metadata (ie. timestamp of reception, channel frequency,\nsignal level, noise level, etc). Frames stored in such a file can be later read\nback and decoded as if they were just received from the air.  To enable this\nfeature, install [protobuf-c](https://github.com/protobuf-c/protobuf-c) library.\nOn Debian/Rasbian Buster just do this:\n\n```\nsudo apt install libprotobuf-c-dev\n```\nIt won't work on Debian/Raspbian versions older than Buster, since protobuf-c\nlibrary shipped with these is too old.\n\n#### ZeroMQ networked output support (optional)\n\nZeroMQ is a library that allows reliable messaging between applications to be\nset up easily. dumpvdl2 can publish decoded messages on a ZeroMQ socket and\nother apps can receive them over the network using reliable transport (TCP).\nTo enable this feature, install libzmq library:\n\n```\nsudo apt install libzmq3-dev\n```\n\nIt won't work on Debian/Raspbian versions older than Buster, since libzmq\nlibrary shipped with these is too old.\n\n### Compiling dumpvdl2\n\n- Download a stable release package from [here](https://github.com/szpajder/dumpvdl2/releases) and unpack it...\n- ...or clone the repository:\n\n```\ncd\ngit clone https://github.com/szpajder/dumpvdl2.git\ncd dumpvdl2\n```\n\nConfigure the build:\n\n```\nmkdir build\ncd build\ncmake ../\n```\n\n`cmake` attempts to find all required libraries and SDR drivers. If a mandatory\ndependency is not installed, it will throw out an error. Missing optional\ndependencies cause relevant features to be disabled. At the end of the process\n`cmake` displays a short configuration summary, like this:\n\n```\n-- dumpvdl2 configuration summary:\n-- - SDR drivers:\n--   - librtsdr:                requested: ON, enabled: TRUE\n--   - mirisdr:                 requested: ON, enabled: TRUE\n--   - sdrplay v2:              requested: ON, enabled: TRUE\n--   - sdrplay v3:              requested: ON, enabled: TRUE\n--   - soapysdr:                requested: ON, enabled: TRUE\n-- - Other options:\n--   - Etsy StatsD:             requested: ON, enabled: TRUE\n--   - SQLite:                  requested: ON, enabled: TRUE\n--   - ZeroMQ:                  requested: ON, enabled: TRUE\n--   - Raw frame output:        requested: ON, enabled: TRUE\n-- Configuring done\n```\n\nHere you can verify whether all the optional components that you need were properly\ndetected and enabled. Then compile and install the program:\n\n```\nmake\nsudo make install\n```\n\nThe last command installs the binary named `dumpvdl2` to the default bin\ndirectory (on Linux it's `/usr/local/bin`). To display a list of available\ncommand line options, run:\n\n```\n/usr/local/bin/dumpvdl2 --help\n```\n\nor just `dumpvdl2 --help` if `/usr/local/bin` is in your `PATH`.\n\n### Build options\n\nBuild options can be configured with `-D` option to `cmake`, for example:\n\n```\ncmake -DRTLSDR=FALSE ../\n```\n\ncauses RTLSDR support in dumpvdl2 to be disabled. It will not be compiled in,\neven if librtlsdr library is installed.\n\nDisabling optional features:\n\n- `-DRTLSDR=FALSE`\n- `-DMIRISDR=FALSE`\n- `-DSDRPLAY=FALSE`\n- `-DSOAPYSDR=FALSE`\n- `-DSQLITE=FALSE`\n- `-DETSY_STATSD=FALSE`\n- `-DRAW_BINARY_FORMAT=FALSE`\n- `-DZMQ=FALSE`\n\nSetting build type:\n\n- `-DCMAKE_BUILD_TYPE=Debug` - builds the program without optimizations and\n  enables `--debug` command line option which enables debug messages (useful for\n  troubleshooting, not recommended for general use)\n- `-DCMAKE_BUILD_TYPE=Release` - debugging output disabled (the default)\n\n**Note:** Always recompile the program with `make` command after changing build\noptions.\n\n**Note:** `cmake` stores build option values in its cache. Subsequent runs of\n`cmake` will cause values set during previous runs to be preserved, unless they\nare explicitly overriden with `-D` option. So if you disable a feature with, eg.\n`-DRTLSDR=FALSE` and you want to re-enable it later, you have to explicitly use\n`-DRTLSDR=TRUE` option. Just omitting `-DRTLSDR=FALSE` will not revert the\noption value to the default.\n\n### Enabling and disabling optional features\n\nAs described in the \"Dependencies\" section, optional features (like SQLite\nsupport, binary format support, etc) are enabled automatically whenever\nlibraries they depend upon are found during cmake run. Results of library\nsearches are also stored in cmake's cache. If the program has initially been\nbuilt without a particular feature and you later change your mind and decide to\nenable it, you need to:\n\n- install the library required by the feature\n- remove cmake's cache file to force all checks to be done again:\n\n```\ncd build\nrm CMakeCache.txt\n```\n\n- rerun cmake and recompile the program as described in \"Compiling dumpvdl2\"\n  section.\n\n## Basic usage\n\n### RTL-SDR\n\nSimplest case on RTLSDR dongle - uses RTL device with index 0, sets the tuner\ngain to 40 dB and tuning correction to 42 ppm, listens to the default VDL2\nfrequency of 136.975 MHz, outputs to standard output:\n\n```\n./dumpvdl2 --rtlsdr 0 --gain 40 --correction 42\n```\n\nDevice ID numbers are not persistent - they depend on the USB device order and\nthe sequence which they were plugged in. You may specify the device by its\nserial number to get deterministic behavior:\n\n```\n./dumpvdl2 --rtlsdr 771111153 --gain 40 --correction 42\n```\n\nUse `rtl_test` utility to get serial numbers of your devices. dumpvdl2 prints\nthem to the screen on startup as well.\n\nIf you want to decode a different VDL2 channel than the default, just add its\nfrequency as a last parameter:\n\n```\n./dumpvdl2 --rtlsdr 0 --gain 40 --correction 42 136725000\n```\n\ndumpvdl2 can decode multiple VDL2 channels simultaneously. Just list their\nfrequencies at the end of the command line:\n\n```\n./dumpvdl2 --rtlsdr 0 --gain 40 --correction 42 136725000 136975000 136875000\n```\n\nIf your receiver has a large center spike, you can set the center frequency a\nbit to the side of the desired channel frequency, like this:\n\n```\n./dumpvdl2 --rtlsdr 0 --gain 40 --correction 42 --centerfreq 137100000 \u003cchannel freqs here...\u003e\n```\n\nFrequencies might be specified in Hertz (as integer numbers) or in kHz, MHz, GHz\n(as integer or floating-point numbers followed by any of the following suffixes:\nk, K, m, M, g, G).\n\n```\n./dumpvdl2 --rtlsdr 0 --gain 40 --centerfreq 136M 136.725M 136975k 0.136875G\n```\n\n### Mirics\n\nMirics is similar, however `libmirisdr-4` library currently lacks support for\nconfiguring correction in ppm. If your receiver needs a non-zero correction, you\ncan pass the appropriate value in Hertz, instead of ppm. **Note:** this value\nwill be subtracted from the center frequency, so if your receiver tunes a bit\ntoo low, the parameter value shall be negative:\n\n```\n./dumpvdl2 --mirisdr 0 --gain 100 --correction -2500\n```\n\nDevice serial number can be given instead of ID, the same way, as for RTLSDR\nreceivers.\n\n`libmirisdr-4` supports two types of hardware: generic Mirics (0 - the default)\nand SDRPlay (1).  SDRPlay users should add `--hw-type 1` option. It uses\nfrequency plans optimized for SDRPlay and reportedly gives better results than\nthe default mode.\n\nIf you get error messages about lost samples on Raspberry Pi, try adding\n`--usb-mode 1`.  This switches USB transfer mode from isochronous to bulk, which\nis usually enough to rectify this problem. If it does not help, it might be that\nyour Pi is overloaded or not powerful enough for the task. Try reducing the\nnumber of decoded VDL2 channels as a workaround.\n\n### SDRplay RSP native driver, version 2\n\nIn order to use SDRplay driver version 2, select the device with  `--sdrplay`\noption. The following devices are supported:\n\n- RSP1\n- RSP1A\n- RSP2\n- RSPduo\n\nThe following advanced configuration options are available:\n\n- switching antenna ports (RSP2)\n- bias-T (RSP2, RSP1A)\n- notch filter for AM/FM broadcast bands (RSP2, RSP1A, RSPduo)\n- tuner selection (RSPduo)\n- Automatic Gain Control\n\nType `./dumpvdl2 --help` to find out all the options and their default values.\n\nSDRPlay driver has a concept of \"gain reduction\", which is an amount of gain (in\ndecibels) that shall be deducted from the maximum gain. As a result, `--gain`\noption is not available with this driver - use `--gr` option to specify\nrequested end-to-end gain reduction instead.  The smallest possible value is 20.\nThe highest value depends on receiver type, but it's not that important, because\nin dumpvdl2 you will hardly be using a GR larger than 59 dB.\n\nAnother way to go is to skip the `--gr` option altogether. This will enable\nAutomatic Gain Control with a default set point of -30 dBFS, which shall\nconverge to a reasonable gain reduction value in a couple of seconds after the\nprogram starts. AGC set point can be changed with `--agc` option, but treat this\nas an \"expert mode\" knob, which is hardly ever needed.\n\nExample 1: use SDRplay device ID=0, with auto gain and three VDL2 channels:\n\n```\n./dumpvdl2 --sdrplay 0 136.975M 136.875M 136.775M\n```\n\nExample 2: use SDRplay device with serial number 35830222, set gain reduction to\n40 dB, use antenna A port, disable Bias-T, enable AM/FM notch filter, set\nfrequency correction to -1ppm:\n\n```\n./dumpvdl2 --sdrplay 35830222 --gr 40 --correction -1 --antenna A --biast 0 --notch-filter 1 136.975M\n```\n\n### SDRplay RSP native driver, version 3\n\nIn order to use SDRplay driver version 3, select the device with  `--sdrplay3`\noption. The following devices are supported:\n\n- RSP1\n- RSP1A\n- RSP2\n- RSPduo\n- RSPdx\n\nThe following advanced configuration options are available:\n\n- switching antenna ports (RSP2, RSPdx)\n- bias-T (RSP2, RSP1A, RSPdx)\n- notch filter for AM/FM broadcast bands (RSP2, RSP1A, RSPduo, RSPdx)\n- notch filter for DAB band (RSP1A, RSPduo, RSPdx)\n- tuner selection (RSPduo)\n- Automatic Gain Control\n\nType `./dumpvdl2 --help` to find out all the options and their default values.\n\nWhen version 3 of the driver is used, dumpvdl2 allows controlling each gain\nreduction component separately. `--gr` option is not available - there are two\noptions instead:\n\n- `--ifgr \u003cvalue_in_dB\u003e` - controls IF gain reduction (range: 20-59 dB)\n- `--lna-state \u003cvalue\u003e` - sets the gain reduction of the LNA (ie. the input RF\n  stage). The parameter is a non-negative integer from 0 (meaning: no gain\n  reduction) up to N, where N depends on the receiver type. The higher the\n  value, the higher the gain reduction (attenuation) in decibels. Refer to the\n  \"Gain Reduction Tables\" section in the [API documentation](https://www.sdrplay.com/docs/SDRplay_RSP_API_Release_Notes_V3.06.pdf) for a full list\n  of LNA states and their respective gain reductions for each receiver.\n\nif you want to set the gain reduction manually, specify both `--ifgr` and\n`--lna-state`. If either option is omitted, the other one is ignored and\nAGC is used instead.\n\n### SoapySDR library\n\n**Note:** The device must support a sampling rate of 2100000 samples per second.\n\nTested with the following devices:\n - SDRPLAY RSP2\n - RTLSDR\n\nUsing SoapySDRServer it is possible to access a SDR device connected to another\nmachine.\n\nFeatures supported by dumpvdl2:\n\n- switching antenna ports\n- setting device-specific configuration parameters\n- setting the gain globally or using individual gain components\n- automatic gain control\n\nType `./dumpvdl2 --help` to find out all the options and their default values.\n\nType `SoapySDRUtil --find` to find available devices.\n\nExample 1: use SDRPLAY device with Antenna B, AGC and biasT activated:\n\n```\n./dumpvdl2 --soapysdr soapy=0,driver=sdrplay --soapy-antenna \"Antenna B\" --device-settings biasT_ctrl=true 136975000 136875000 136775000\n```\n\nExample 2: use RTLSDR device with AGC\n\n```\n./dumpvdl2 --soapysdr soapy=0,driver=rtlsdr 136975000 136875000 136775000\n```\n\nExample 3: use SDRPLAY device with separate gain reduction for RFGR for LNA and\nnormal gain reduction IFGR\n\n```\n./dumpvdl2 --soapysdr soapy=0,driver=sdrplay --gain -1 --soapy-gain RFGR=0,IFGR=56 136975000 136875000 136775000\n```\n\nExample 4: Use a remote SDRPLAY with antenna B, Soapy server started with\ncommand line\n\n```\nSoapySDRServer --bind\n```\n\nThen you may run dumpvdl2 on any remote machine with:\n\n```\n./dumpvdl2 --soapysdr driver=remote,remote=tcp://\u003cip address\u003e:55132,remote:driver=sdrplay,remote:format=CS16 \\\n--gain -100 --soapy-antenna \"Antenna B\" 136975000 136875000 136775000\n```\n\n## Configuring outputs\n\n### Quick start\n\nBy default dumpvdl2 formats decoded messages into human readable text and prints\nit to standard output. You can direct the output to a disk file instead:\n\n```\n./dumpvdl2 --output decoded:text:file:path=/some/dir/vdl2.log [other_options]\n```\n\nIf you want the file to be automatically rotated on top of every hour, do\nthe following:\n\n```\n./dumpvdl2 --output decoded:text:file:path=/some/dir/vdl2.log,rotate=hourly [other_options]\n```\n\nThe file name will be appended with `_YYYYMMDDHH` suffix.  If file extension is\npresent, it will be placed after the suffix.\n\nIf you prefer daily rotation, change `rotate=hourly` to `rotate=daily`. The file\nname suffix will be `_YYYYMMDD` in this case. If file extension is present, it\nwill be placed after the suffix.\n\n### Output configuration syntax\n\nThe `--output` option takes a single parameter consisting of four fields\nseparated by colons:\n\n```\n    \u003cwhat_to_output\u003e:\u003coutput_format\u003e:\u003coutput_type\u003e:\u003coutput_parameters\u003e\n```\n\nwhere:\n\n- `\u003cwhat_to_output\u003e` specifies what data should be sent to the output. Two\n  values are supported:\n\n  - `decoded` - output decoded messages\n  - `raw` - output AVLC frames without decoding (as raw bytes)\n\n- `\u003coutput_format\u003e` specifies how the data should be formatted before sending\n  it to the output. The following formats are currently supported:\n\n  - `text`\n  - `json`\n  - `pp_acars` - a single-line ACARS format accepted by Planeplotter via UDP.\n    This format can only deal with ACARS, hence messages of all other types will\n    be filtered out (ie. not sent to this particular output).\n  - `binary`- a format suitable for archiving raw frames without decoding\n\n- `\u003coutput_type\u003e` specifies the type of the output. The following output types\n  are supported:\n\n  - `file` - output to a file\n  - `udp` - output to a remote host via UDP network socket\n  - `zmq` - output to a ZeroMQ publisher socket\n\n- `\u003coutput_parameters\u003e` - specifies options for this output. The syntax is\n  as follows:\n\n```\n    param1=value1,param2=value2,...\n```\n\nThe list of available formats and output types may vary depending on which\noptional features have been enabled during program compilation and whether\nnecessary dependencies are installed (see \"Dependencies\" subsection above).\nRun `dumpvdl2 --output help` to determine which formats and output types\nare available on your system. It also shows all parameters supported by\neach output type.\n\nBack to the above example:\n\n```\n--output decoded:text:file:path=/some/dir/vdl2.log,rotate=hourly\n```\n\nIt basically says: \"take decoded frames, format them as text and output the\nresult to a file\". Of course this output requires some more configuration - at\nleast it needs the path where the file is to be created. This is done by\nspecifying `path=/some/dir/vdl2.log` in the last field. The `file` output\ndriver also supports an optional parameter named `rotate` which indicates\nhow often the file is to be rotated, if at all.\n\nA few more remarks about how output configuration works:\n\n- Multiple simultaneous outputs are supported. Just specify `--output` option\n  more than once.\n\n- Not all combinations of `\u003cwhat_to_output\u003e` and `\u003coutput_format\u003e` are\n  supported. For example it does not make sense to specify `raw:pp_acars:....`\n  because Planeplotter formatter can only deal with decoded ACARS messages.\n  You will get an `Unsupported data_type:format combination: 'raw:pp_acars'`\n  error message on startup if you try that.\n\n- Not all combinations of `\u003coutput_format\u003e` and `\u003coutput_type\u003e` are supported.\n  For example, `udp` output only accepts `text`, `json` and `pp_acars` formats.\n  If you try using `binary` with that, you will get an `Unsupported\n  format:output combination: 'binary:udp'` error message on startup.\n\n- If dumpvdl2 is run without any `--output` option, it creates a default output\n  of `decoded:text:file:path=-` which causes decoded frames to be formatted as\n  text and printed to standard output.\n\n\n### Output drivers\n\n#### `file`\n\nOutputs data to a file.\n\nSupported formats: `text`, `json`, `binary`\n\nParameters:\n\n- `path` (required) - path to the output file. If it already exists, the data is\n  appended to it.\n\n- `rotate` (optional) - how often to rotate the file. Supported values: `daily`\n  (at midnight UTC or LT depending on whether `--utc` option is used) and `hourly`\n  (rotate at the top of every hour). Default: no rotation.\n\n#### `udp`\n\nSends data to a remote host over network using UDP/IP.\n\nSupported formats: `text`, `json`, `pp_acars`\n\nParameters:\n\n- `address` (required) - host name or IP address of the remote host\n\n- `port` (required) - remote UDP port number\n\n**Note:** UDP protocol does not guarantee successful message delivery (it works\non a \"fire and forget\" principle, no retransmissions, no acknowledgements, etc).\nIf you plan to use networked output for real, please use `zmq` driver. It works\non TCP and provides reliable transport regardless of the message size.\n\nThe primary purpose of `udp` driver is to feed Planeplotter with ACARS\nmessages using `pp_acars` format.\n\n#### `zmq`\n\nOpens a ZeroMQ publisher socket and sends data to it.\n\nSupported formats: `text`, `json`, `pp_acars`\n\nParameters:\n\n- `mode` (required) - socket mode. Can be `client` or `server`.  In the first\n  case dumpvdl2 initiates a connection to the given consumer. In the latter\n  case, dumpvdl2 listens on a port and expects consumers to connect to it.\n\n- `endpoint` (required) - ZeroMQ endpoint. The syntax is: `tcp://address:port`.\n  When working in server mode, it specifies the address and port where dumpvdl2\n  shall listen for incoming connections. In client mode it specifies the address\n  and port of the remote ZeroMQ consumer where dumpvdl2 shall connect to.\n\nExamples:\n\n- `mode=server,endpoint=tcp://*:5555` - listen on TCP port 5555 on all local\n  addresses.\n\n- `mode=server,endpoint=tcp://10.1.1.1:6666` - listen on TCP port 6666 on\n  address 10.1.1.1 (it must be a local address).\n\n- `mode=client,endpoint=tcp://host.example.com:1234` - connect to port 1234\n  on host.example.com.\n\n### Diagnosing problems with outputs\n\nOutputs may fail for various reasons. A file output may fail to write to the\ngiven path due to lack of permissions or lack of storage space, zmq output may\nfail to set up a socket due to incorrect endpoint syntax, etc. Whenever an\noutput fails, the program disables it and prints a message on standard error,\nfor example:\n\n```\nCould not open output file /etc/vdl2.log: Permission denied\noutput_file: could not write to '/etc/vdl2.log', output disabled\n```\n\nThe program will continue to run and write data to all other outputs, except\nthe failed one.\n\nAn output may also hang and stop processing messages (although this is\na \"shouldn't happen\" situation). Messages will then accumulate in that output's\nqueue. To prevent memory exhaustion, there is a high water mark limit on the\nnumber of messages that might be queued for each output. By default it is set\nto 1000 messages. If this value is reached, the program will not push any more\nmessages to that output before messages get consumed and the queue length drops\ndown. The following message is then printed on standard error for every dropped\nmessage:\n\n```\n\u003coutput_type\u003e output queue overflow, throttling\n```\nOther outputs won't be affected, since each one is running in a separate thread\nand has its own message queue.\n\nHigh water mark limit is disabled when dumpvdl2 is decoding data from a file\n(ie. eiter `--iq-file` or `--raw-frames-file` option is in use). This allows\nall queues to grow indefinitely, but it makes sure that no frames get dropped.\n\nThe high water mark threshold can be changed with `--output-queue-hwm` option.\nSet its value to 0 to disable the limit.\n\n### Additional options for text formatting\n\nThe following options work globally across all outputs with text format:\n\n- Add `--utc` option if you prefer UTC timestamps rather than local timezone in\n  output and filenames.\n\n- Add `--milliseconds` to print timestamps with millisecond resolution.\n\n- Add `--raw-frames` option to display payload of AVLC frames in raw hex for\n  debugging purposes.\n\n- Add `--dump-asn1` option to display full ASN.1 structure dumps of CPDLC and CM\n  messages.\n\n- Some ACARS and MIAM CORE messages contain XML data. Use `--prettify-xml`\n  option to enable pretty-printing of such content. XML will then be reformatted\n  with proper indentation for easier reading. This feature requires libacars\n  built with libxml2 library support - otherwise this option has no effect.\n\n- OHMA messages (ie. B737MAX diagnostics) contain XML data. Use\n  `--prettify-json` option to enable pretty-printing of such content. JSON will\n  be reformatted with proper indentation built for easier reading. This feature\n  requires libacars 2.2.0 or later, built with jansson library support -\n  otherwise this option has no effect.\n\n## Enriching messages with ground station data\n\nVDL2 messages formatted as text are normally logged like this:\n\n```\n[2020-01-10 00:02:40 CET] [136.775] [-31.8/-51.6 dBFS] [19.8 dB] [-1.2 ppm]\n06A0B7 (Aircraft, Airborne) -\u003e 29E0C5 (Ground station): Response\nAVLC type: S (Receive Ready) P/F: 0 rseq: 2\n```\n\ndumpvdl2 can optionally print more information about ground stations using data\nread from a text file. Each line in the file should have the following format:\n\n```\nhex_address [airport_icao_code ground_station_details] [ground_station_location]\n```\n\nExample:\n\n```\n29E0C5 [EDDB Berlin Schonefeld DE] [Berlin Schonefeld]\n```\n\nAdd the following option to dumpvdl2 command line:\n\n```\n--gs-file /path/to/ground_station_file.txt\n```\n\nProvide the correct path to the file, of course.\n\nVerbosity can be controlled with `--addrinfo` option, which takes three values:\n\n`--addrinfo normal` (the default):\n\n```\n[2020-01-10 00:02:40 CET] [136.775] [-31.8/-51.6 dBFS] [19.8 dB] [-1.2 ppm]\n06A0B7 (Aircraft, Airborne) -\u003e 29E0C5 (Ground station): Response\nGS info: EDDB, Berlin Schonefeld\nAVLC type: S (Receive Ready) P/F: 0 rseq: 2\n```\n\n`--addrinfo terse`:\n\n```\n[2020-01-10 00:02:40 CET] [136.775] [-31.8/-51.6 dBFS] [19.8 dB] [-1.2 ppm]\n06A0B7 (Aircraft, Airborne) -\u003e 29E0C5 (Ground station) [EDDB]: Response\nAVLC type: S (Receive Ready) P/F: 0 rseq: 2\n```\n\n`--addrinfo verbose`:\n\n```\n[2020-01-10 00:02:40 CET] [136.775] [-31.8/-51.6 dBFS] [19.8 dB] [-1.2 ppm]\n06A0B7 (Aircraft, Airborne) -\u003e 29E0C5 (Ground station): Response\nGS info: EDDB Berlin Schonefeld DE\nAVLC type: S (Receive Ready) P/F: 0 rseq: 2\n```\n\ndumpvdl2 reads the whole ground station data file on startup and caches it in\nmemory. Whenever you make changes to the file, you have to restart the program\nin order for the changes to take effect.\n\n## Enriching messages with aircraft data\n\nIf compiled with SQLite3 support, dumpvdl2 can read aircraft data from SQLite3\ndatabase in a well-known Basestation format used in various plane tracking\napplications. Such data can be printed along the header of each message. Use\n`--bs-db /path/to/basestation.sqb` option to enable the feature. `--addrinfo`\ncontrols aircraft data verbosity in the same way as for ground stations (see\nabove). Example with `--addrinfo` set to `normal`:\n\n```\n[2020-01-10 00:02:40 CET] [136.775] [-31.8/-51.6 dBFS] [19.8 dB] [-1.2 ppm]\n06A0B7 (Aircraft, Airborne) -\u003e 29E0C5 (Ground station): Response\nAC info: A7-BCS, B788, QTR\nGS info: EDDB, Berlin Schonefeld\nAVLC type: S (Receive Ready) P/F: 0 rseq: 2\n```\n\ndumpvdl2 reads data from `Aircraft` table. The following fields are used:\n\n- `--addrinfo terse`: Registration\n- `--addrinfo normal`: Registration, ICAOTypeCode, OperatorFlagCode\n- `--addrinfo verbose`: Registration, Manufacturer, Type, RegisteredOwners\n\nICAO hex code is read from ModeS field. All fields are expected to have a data\ntype `varchar`. ModeS field must be unique and non-NULL. Other fields are\nallowed to be NULL (the program substitutes each NULL value with a dash).\n\nEntries from the database are read on the fly, when needed. They are cached in\nmemory for 30 minutes and then re-read from the database or purged.\n\n## Decoding upper-level protocols in fragmented packets\n\nACARS messages, MIAM file transfers and X.25 packets are limited in size.\nWhenever there is a need to send a larger message than the protocol allows, it\nmust be split into smaller parts (fragments). dumpvdl2 automatically reassembles\nsuch messages. Individual fragments are logged too, as they arrive. Only when\nall parts of the message are successfully received, dumpvdl2 cat reassemble the\nmessage and log its payload in one piece.\n\nACARS messages, MIAM file transfers and X.25 packets often contain binary data\nof higher level protocols or applications, which dumpvdl2 can decode as well\n(for example: CPDLC, ADS-C, IDRP or MIAM CORE). Such protocols would only decode\ncorrectly when a complete payload is presented to the decoder. If the message is\nfragmented, there is no point in decoding higher level protocol in individual\nfragments, because this will often result in a partial decode with an\n``-- Unparseable \u003cprotocol name\u003e PDU`` error printed to the log file. To reduce log\nfile cluttering, dumpvdl2 does not decode higher level protocols in fragmented\npackets. Data contained in individual fragments are printed in hex, but this\ndoes not mean that the packet type is unknown - it's just not decodable yet.\nWhen all the fragments have been received and correctly reassembled, the packet\nwill be decoded and logged in full.\n\nBefore version 1.8.0, dumpvdl2 always attempted to decode higher level\nprotocols, regardless of whether the packet was a fragment of a larger packet or\nnot. You can enable the old behaviour by adding `--decode-fragments` command\nline option.\n\n## Integration with Planeplotter\n\ndumpvdl2 can send ACARS messages to Planeplotter, which in turn can extract\naircraft position information from them and display blips on the map. First,\nconfigure your Planeplotter as follows:\n\n- Stop data processing (press 'Stop' button on the toolbar)\n\n- Go to Options / I/O Settings...\n\n- Tick 'UDP/IP Data from net'\n\n- Set 'UDP/IP local port' to some value (default is 9742)\n\n- Close the settings window by clicking OK and restart data processing\n\nSupply dumpvdl2 with the address (or host name) and port where the Planeplotter\nis listening:\n\n```\n./dumpvdl2 --output decoded:pp_acars:udp:address=10.10.10.12,port=9742 [other_options]\n```\n\nThat's all. Switch to 'Message view' in Planeplotter and look for incoming\nmessages.\n\n## Message filtering\n\nBy default dumpvdl2 logs all decoded messages. You can use `--msg-filter` option\nto ignore things you don't want to see. If you do not want messages sent by\nground stations, run the program like this:\n\n```\n./dumpvdl2 --msg-filter all,-uplink [other_options]\n```\n\nOr if you want to filter out empty ACARS messages, because they are boring, use\nthis:\n\n```\n./dumpvdl2 --msg-filter all,-acars_nodata [other_options]\n```\n\nFor full list of supported filtering options, run:\n\n```\n./dumpvdl2 --msg-filter help\n```\n\nRefer to `doc/FILTERING_EXAMPLES.md` file for more examples and details.\n\n## Debugging output\n\nIf the program has been compiled with `-DCMAKE_BUILD_TYPE=Debug`, there is\n`--debug` option available. It controls debug message classes which should (or\nshould not) be printed to standard error. This works in the same way as message\nfilters described above. Run the program with `--debug help` to list all debug\nmessage classes available.\n\n## Statistics\n\nThe program does not calculate statistics by itself. Instead, it sends metric\nvalues (mostly counters) to the external collector using Etsy StatsD protocol.\nIt's the collector's job to receive, aggregate, store and graph them. Some\nexamples of software which can be used for this purpose:\n\n- [Collectd](https://collectd.org/) is a statistics collection daemon which\n  supports a lot of metric sources by using various [plugins](https://collectd.org/wiki/index.php/Table_of_Plugins).\n  It has a [StatsD](https://collectd.org/wiki/index.php/Plugin:StatsD) plugin which can\n  receive statistics emitted by dumpvdl2, aggregate them and write to various\n  time-series databases like RRD, Graphite, MongoDB or TSDB.\n\n- [Graphite](https://graphiteapp.org/) is a time-series database with powerful\n  analytics and aggregation functions. Its graphing engine is quite basic,\n  though.\n\n- [Grafana](http://grafana.org/) is a sophisticated and elegant graphing\n  solution supporting a variety of data sources.\n\nHere is an example of some dumpvdl2 metrics being graphed by Grafana:\n\n![Statistics](statistics.png?raw=true)\n\nMetrics are quite handy when tuning the antenna installation or receiver\nparameters (like gain or correction).\n\nTo enable statistics just give dumpvdl2 your StatsD collector's hostname (or IP\naddress) and UDP port number, for example:\n\n```\n./dumpvdl2 --statsd 10.10.10.15:1234 [other_options]\n```\n\n## Processing recorded IQ data from file\n\nThe syntax is:\n\n```\ndumpvdl2 --iq-file \u003cfile_name\u003e [--sample-format \u003csample_format\u003e] [--oversample \u003coversample_rate\u003e]\n  [--centerfreq \u003ccenter_frequency\u003e] [vdl_freq_1] [vdl_freq_2] [...]\n```\n\nSpecify `-` as the file name to read data from standard input.\n\nThe symbol rate for VDL2 is 10500 symbols/sec. dumpvdl2 internal processing rate\nis 10 samples per symbol. Therefore the file must be recorded with sampling rate\nset to an integer multiple of 105000. Specify the multiplier value with\n`--oversample` option. The default value is 10, which is valid for files sampled\nas 1050000 samples/sec. For example, if you have recorded your file at 2100000\nsamples/sec, then use `--oversample 20` (because 105000 * 20 = 2100000).\n\nThe program accepts raw data files without any header. Files produced by\n`rtl_sdr` and `miri_sdr` programs are perfectly valid input files. Different\nradios produce samples in different formats, though. dumpvdl2 currently supports\nfollowing sample formats:\n\n- `U8` - unsigned 8-bit samples. This is the format produced by `rtl_sdr`\n  utility.\n- `S16_LE` - 16-bit signed, little endian. Produced by `miri_sdr` utility (by\n  default).\n\nUse `--sample-format` option to set the format. The default format is `U8`.\n\nThe program assumes that the VDL2 channel is located at baseband (0 Hz), ie. the\ncenter frequency of your radio was set to the VDL2 channel frequency during\nrecording. If this is not the case, you have to provide correct center frequency\nand channel frequency. For example, if your receiver was tuned to 136.955 MHz\nduring recording and you want to decode the VDL2 channel located at 136.975 MHz,\nthen use this:\n\n```\ndumpvdl2 --iq-file \u003cfile_name\u003e --centerfreq 136955000 136975000\n```\n\nPutting it all together:\n\n```\ndumpvdl2 --iq-file iq.dat --sample-format S16_LE --oversample 13 --centerfreq 136.955M 136.975M 136.725M\n```\n\nprocesses `iq.dat` file recorded at 1365000 samples/sec using 16-bit signed\nsamples, with receiver center frequency set to 136.955 MHz. VDL2 channels\nlocated at 136.975 and 136.725 MHz will be decoded.\n\n## Decoding raw AVLC frames from a binary file\n\nRaw AVLC frames saved in a file with:\n\n```\ndumpvdl2 --output raw:binary:file:path=/some/dir/file.raw [...]\n```\n\ncan be decoded anytime later with:\n\n```\ndumpvdl2 --raw-frames-file /some/dir/file.raw --output [...]\n```\n\nAs there is no demodulation done in this case, there is no need to specify\nany radio-related options, like `--centerfreq` or channel frequencies.\n\nSpecify `-` as the file name to read data from standard input.\n\n## Launching dumpvdl2 in background on system boot\n\nThere is an example systemd unit file in `etc` subdirectory (which means you\nneed a systemd-based distribution, like Debian/Raspbian Jessie or newer).\n\nFirst, go to dumpvdl2 source directory and install the binary to `/usr/local/bin`:\n\n```\nsudo make install\n```\n\nCopy the unit file to the systemd unit directory:\n\n```\nsudo cp etc/dumpvdl2.service /etc/systemd/system/\n```\n\nCopy the example environment file to `/etc/default` directory:\n\n```\nsudo cp etc/dumpvdl2 /etc/default/\n```\n\nEdit `/etc/default/dumpvdl2` with a text editor (eg. nano). Uncomment the\n`DUMPVDL2_OPTIONS=` line and put your preferred dumpvdl2 option set there.\nExample:\n\n```\nDUMPVDL2_OPTIONS=\"--rtlsdr 0 --gain 39 --correction 0 --output decoded:text:file:path=/home/pi/vdl2.log,rotate=daily 136975000 136875000 136775000\"\n```\n\nReload systemd configuration:\n\n```\nsudo systemctl daemon-reload\n```\n\nStart the service:\n\n```\nsudo systemctl start dumpvdl2\n```\n\nVerify if it's running:\n\n```\nsystemctl status dumpvdl2\n```\n\nIt should show: `Active: active (running) since \u003cdate\u003e`. If it failed, it might\nbe due to an error in the `DUMPVDL2_OPTIONS` value. Read the log messages in the\nstatus output and fix the problem.\n\nIf everything works fine, enable the service, so that systemd starts it\nautomatically at boot:\n\n```\nsystemctl enable dumpvdl2\n```\n\n## Extras\n\nThere are a few additions to the program in the `extras` directory in the source\ntree. Refer to the README.md file in that directory for the current list of\nextras and their purpose.\n\n## Frequently Asked Questions\n\n### What is VDL Mode 2?\n\nVDL (VHF Data Link) Mode 2 is a communication protocol between aircraft and a\nnetwork of ground stations. It has a higher capacity than ACARS and a lot more\napplications. More information can be found on [Wikipedia](https://en.wikipedia.org/wiki/VHF_Data_Link)\nor [SigIdWiki](http://www.sigidwiki.com/wiki/VHF_Data_Link_-_Mode_2_(VDL-M2)).\n\n### Who uses it?\n\nLarge transport aircraft operators - civil airlines and some military.\n\n### What frequencies it runs on?\n\nThe most ubiquitous is 136.975 MHz (so called Common Signalling Channel). In\nsome areas where the capacity of a single channel is not enough, 136.725,\n136.775 or 136.875 is used as well.  Because they are closely spaced, dumpvdl2\ncan receive all of them simultaneously with a single receiver.\n\n### Is it used in my area?\n\nIt's quite probable. Launch your favorite SDR Console (like SDRSharp or\nGQRX), tune 136.975 MHz and place your antenna outside (or near the window, at\nleast). If you see short bursts every now and then, it's there.\n\n### What antenna shall I use?\n\nVDL2 runs on VHF airband, so if you already have a dedicated antenna for ACARS\nor airband voice, it will be perfect for VDL2. However VDL2 transmissions are\nnot very powerful, so do not expect thousands of messages per hour, if your\nantenna is located indoors. If you have already played with ADS-B, you know,\nwhat to do - put the antenna outside and high with unobstructed sky view, use\nshort and good quality feeder cable, shield your radio from external RF\ninterference.\n\n### Two hours straight and zero messages received. What's wrong?\n\nIt basically comes down to three things:\n\n#### The signal has to be strong enough (preferably 15 dB over noise floor, or better)\n\n- set your tuner gain quite high. I get good results with 40 dB for RTLSDR and\n  75 dB for Mirics dongles. Do not be tempted to crank the gain up to the max.\n  Keep your noise floor low because higher noise yields higher bit error rate and\n  may cause signal clipping when the transmission is strong (eg. the transmitting\n  aircraft is just overflying your antenna).  On SDRPlay it should be good enough\n  to use auto gain control.\n\n- observe the waterfall in your favorite SDR console app, using the same gain\n  setting - do you see data bursts clearly?  (they are very short, like pops).\n\n- if your DC spike is very high, set the center frequency manually to dodge it\n  (use `--centerfreq` option).\n\n- RTL dongles are cheap - some of them have higher noise figure than others. If\n  you have several dongles at hand, just try another one.\n\n#### Channel frequency must be correct\n\n- initially, just don't set it manually, use the default of 136.975 MHz. It is\n  used everywhere where VDL2 is available.\n\n#### PPM correction setting must be (more or less) accurate\n\n- oscillators in cheap receivers are not 100% accurate. It is usually necessary\n  to introduce manual correction to get precise tuning. There is no\n  one-size-fits-all correction value - it is receiver-specific. See next question.\n\n### How do I estimate PPM correction value for my dongle?\n\n**Method 1:** use `rtl_test` utility which comes with `librtlsdr` library. Run\nit with `-p` option and observe the output:\n\n### Where can I find a fresh basestation.sqb file?\n\nFor example in [this repository](https://github.com/varnav/BaseStation.sqb).\n\n```\nroot@linux:~ # rtl_test -p\nFound 1 device(s):\n  0:  Realtek, RTL2838UHIDIR, SN: 00000002\n\nUsing device 0: Generic RTL2832U OEM\nFound Rafael Micro R820T tuner\nSupported gain values (29): 0.0 0.9 1.4 2.7 3.7 7.7 8.7 12.5 14.4 15.7 16.6 19.7 20.7 22.9 25.4 28.0 29.7 32.8 33.8 36.4 37.2 38.6 40.2 42.1 43.4 43.9 44.5 48.0 49.6\n[R82XX] PLL not locked!\nSampling at 2048000 S/s.\nReporting PPM error measurement every 10 seconds...\nPress ^C after a few minutes.\nReading samples in async mode...\nreal sample rate: 2048207 current PPM: 101 cumulative PPM: 101\nreal sample rate: 2048159 current PPM: 78 cumulative PPM: 89\nreal sample rate: 2048137 current PPM: 67 cumulative PPM: 81\nreal sample rate: 2048184 current PPM: 90 cumulative PPM: 84\nreal sample rate: 2048163 current PPM: 80 cumulative PPM: 83\nreal sample rate: 2048165 current PPM: 81 cumulative PPM: 82\nreal sample rate: 2048140 current PPM: 69 cumulative PPM: 81\nreal sample rate: 2048178 current PPM: 87 cumulative PPM: 81\nreal sample rate: 2048168 current PPM: 82 cumulative PPM: 81\nreal sample rate: 2048117 current PPM: 57 cumulative PPM: 79\nreal sample rate: 2048202 current PPM: 99 cumulative PPM: 81\nreal sample rate: 2048173 current PPM: 85 cumulative PPM: 81\nreal sample rate: 2048164 current PPM: 80 cumulative PPM: 81\nreal sample rate: 2048135 current PPM: 66 cumulative PPM: 80\nreal sample rate: 2048179 current PPM: 88 cumulative PPM: 80\nreal sample rate: 2048170 current PPM: 83 cumulative PPM: 81\nreal sample rate: 2048167 current PPM: 82 cumulative PPM: 81\nreal sample rate: 2048155 current PPM: 76 cumulative PPM: 80\nreal sample rate: 2048160 current PPM: 78 cumulative PPM: 80\nreal sample rate: 2048159 current PPM: 78 cumulative PPM: 80\nreal sample rate: 2048154 current PPM: 75 cumulative PPM: 80\nreal sample rate: 2048155 current PPM: 76 cumulative PPM: 80\nreal sample rate: 2048181 current PPM: 89 cumulative PPM: 80\n```\n\nAfter a couple of minutes the cumulative PPM value converges to a stable\nreading. This is an approximate correction value for your dongle. Run dumpvdl2\nwith `--correction \u003cvalue\u003e` option. dumpvdl2 can compensate correction errors up\nto a certain amount. Once you have received some messages, look for the\nfrequency offset field which is printed in the header of each message (it's the\nvalue expressed in ppm). Your tuning is good, when this value is close to 0.  If\nyou see a systematic offset from 0, tweak your correction value to compensate\nit.\n\n### What do these numbers in the message header mean?\n\n```\n[2017-02-26 19:18:00 GMT] [136.975] [-18.9/-43.9 dBFS] [25.0 dB] [0.4 ppm]\n```\n\nFrom left to right:\n\n- date and time with timezone.\n\n- channel frequency on which the message has been received.\n\n- signal power level (averaged over all symbol sampling points in the burst).\n  Full scale is 0 dB.\n\n- noise floor power level. Full scale is 0 dB.\n\n- signal to noise ratio (ie. signal power level minus noise floor power level).\n\n- frequency offset of the received burst from the channel center frequency, in\n  parts per million.\n\nThere is an `--extended-header` command line option which enables additional\nfields:\n\n```\n[2017-02-26 19:18:00 GMT] [136.975] [-18.9/-43.9 dBFS] [25.0 dB] [0.4 ppm] [S:0] [L:34] [F:0] [#0]\n```\n\n- number of bit errors corrected in the VDL2 burst header (up to 2).\n\n- burst length in octets.\n\n- number of octets corrected by Reed-Solomon FEC.\n\n- number of frame in this particular transmission. Multiple AVLC frames\n  (messages) may be concatenated and sent as a single transmission burst. When a\n  multiframe burst is received, frames will be numbered incrementally.\n\n### I want colorized logs, like on the screenshot.\n\ndumpvdl2 does not have log colorization feature. But there is an app named\n[MultiTail](https://www.vanheusden.com/multitail/) which you can use to follow dumpvdl2 log file in real time, as it grows,\nwith optional colorization. It's just a matter of writing a proper colorization\nscheme (it tells the program what words or phrases to colorize and what color to\nuse). Refer to `multitail-dumpvdl2.conf` file in the `extras` subdirectory for\nan example. To use it:\n\n- Install the program:\n\n```\nsudo apt install multitail\n```\n\n- Copy the example colorization scheme to `/etc`:\n\n```\nsudo cp extras/multitail-dumpvdl2.conf /etc\n```\n\n- Include the color scheme into the main MultiTail configuration file:\n\n```\nsudo echo \"include:/etc/multitail-dumpvdl2.conf\" \u003e\u003e /etc/multitail.conf\n```\n\n- You can only colorize the file while it grows.  So assuming that dumpvdl2 is\n  running and writing its log into `vdl2.log` file in the current directory,\n  type the following:\n\n```\nmultitail -cS dumpvdl2 vdl2.log\n```\n\n`-cS dumpvdl2` option select the color scheme named `dumpvdl2`.\n\n### Can I concatenate several raw binary files into one?\n\nYes. There is no header in the file, just data. Concatenated file should\ntherefore decode correctly.\n\n### I want to extract raw data from a raw binary file. Where is the format specification?\n\nHere it is:\n\n```\n\u003clength\u003e\u003cframe_data\u003e\u003clength\u003e\u003cframe_data\u003e...\n```\n\nwhere:\n\n- `\u003clength\u003e` is an unsigned 16-bit value in network order (ie. most significant\n  byte first). It indicates the length of the following `\u003cframe_data\u003e` block\n  plus the length of the length field itself. So the length of `00 5b` indicates\n  that the following `\u003cframe_data\u003e` block is 89 bytes long (2+89 = 91 = 0x5b).\n\n- `\u003cframe_data\u003e` is a structure containing raw AVLC frame octets and its\n  metadata, encoded as a Google protocol buffer. Refer to the\n  `proto/dumpvdl2.proto` file for the specification of the structure.\n\nYou can learn how to deal with protocol buffers from [here](https://developers.google.com/protocol-buffers/docs/overview).\n\n### How to receive data from dumpvdl2 using ZeroMQ sockets?\n\nHere is how to do it in Python, assuming that you are running Raspbian Buster or later.\n\nFirst, install python3-zmq:\n\n```\napt install python3-zmq\n```\n\n**Scenario 1:** dumpvdl2 works as a client, Python script is a server:\n\n```python\nimport zmq, sys\ncontext = zmq.Context()\nsocket = context.socket(zmq.SUB)\nsocket.bind(sys.argv[1])\nsocket.setsockopt_string(zmq.SUBSCRIBE, '')\nwhile True:\n    string = socket.recv_string()\n    print(string)\n```\n\nSave the script in a file (for example, zmqserver.py) and run it like so:\n\n```\npython3 zmqserver.py tcp://*:5555\n```\n\nAssuming that the above script is running on a machine with an IP address of\n10.10.10.1, you can then run dumpvdl2 with `zmq` output set to client mode like\nthis:\n\n```\ndumpvdl2 --output decoded:text:zmq:mode=client,endpoint=tcp://10.10.10.1:5555 [...]\n```\n\n**Scenario 2:** dumpvdl2 works as a server, Python script is a client:\n\n```python\nimport zmq,sys\ncontext = zmq.Context()\nsocket = context.socket(zmq.SUB)\nsocket.connect(sys.argv[1])\nsocket.setsockopt_string(zmq.SUBSCRIBE, '')\nwhile True:\n    string = socket.recv_string()\n    print(string)\n```\n\nSo the only difference is that now the script calls `socket.connect()` instead\nof `socket.bind()`. Assuming that dumpvdl2 will be run on a machine with an IP\naddress of 10.10.10.2, save the script as `zmqclient.py` and run it as follows:\n\n```\npython3 zmqclient.py tcp://10.10.10.2:5555\n```\n\nThen start dumpvdl2 in ZeroMQ server mode:\n\n```\ndumpvdl2 --output decoded:text:zmq:mode=server,endpoint=tcp://*:5555\n```\n\nBoth scripts print arriving messages to standard output.\n\nThe advantage of the second scenario is that dumpvdl2 can serve multiple clients\nusing just a single `zmq` output. However the first scenario may come in handy\nif dumpvdl2 is running behind a firewall which does not permit connections from\nthe outside. In this case if the output is to be sent to multiple consumers,\neach one must be configured as a separate `zmq` output.\n\n### I collect data in JSON format over network from several receivers. Is there a way to determine which receiver each frame came from?\n\nUse `--station-id \u003cname\u003e` option to set the name of the receiver. This name will\nbe put into `station` attribute at top level of every JSON-formatted message.\n\n### Can you add support for [*my favourite SDR receiver type*]?\n\nMaybe. However do not expect me to purchase all SDRs available on the market\njust to make dumpvdl2 work with them. If your life absolutely depends on it,\nconsider donating, or at least lending me the hardware for some time for\ndevelopment and testing.\n\nAlternatively, if you can write code, you may do the work by yourself and submit\nit as a pull request. Most of the program code is hardware-agnostic anyway.\nAdding new device type basically comes down to the following:\n\n- `dumpvdl2.c`, `dumpvdl2.h` - add new input type and necessary command line\n  options.\n\n- `rtl.c`, `rtl.h` - this is the code specific to the RTLSDR hardware. Make a\n  copy and modify it to use the API of your SDR device. Or you can start off\n  from `mirics.c` and `mirics.h`, if you prefer.\n\n- `demod.c` - if your SDR device uses a sample format other than 8-bit unsigned\n  and 16-bit signed, it is necessary to write a routine which handles this\n  format and converts the samples to signed float in the \u003c-1;1\u003e range. Refer to\n  `process_buf_uchar()` and `process_buf_short()` routines for details.\n\n- `CMakeLists.txt` - copy the section containing `find_package(RTLSDR)` and\n  modify it, so that it finds all the necessary libraries and header file\n  locations and appends them to relevant build variables. Make sure that the\n  program still builds correctly when the library for your new SDR type is\n  not installed or has been disabled by the user. Add the appropriate\n  information to the configuration summary which is printed at the end.\n\n### Can you add support for Windows?\n\nMaybe. I may do it one day, but it's not currently top priority.\n\n## Contributing\n\nPlease submit your pull requests against the unstable branch - this is where\nall the new code goes first. master branch is only for making stable releases.\n\nIf you want to make large changes or implement a significant new feature, please\ncontact me first (via e-mail or open a discussion on Github) and explain your\nidea. It would be quite wasteful if you spent a lot of work on a part of the code\nwhich I plan to rework or discard eventually.\n\n## Credits and thanks\n\nI hereby express my gratitude to everybody who helped with the development and\ntesting of dumpvdl2. Special thanks go to:\n\n- Fabrice Crohas\n- Dick van Noort\n- acarslogger\n- Piotr Herko, SP5XSB\n- LamaBleu\n\n## License\n\nCopyright (c) 2017-2023 Tomasz Lemiech \u003cszpajder@gmail.com\u003e\n\nContains code from the following software projects:\n\n- libfec, (c) 2006 by Phil Karn, KA9Q\n\n- Rocksoft^tm Model CRC Algorithm Table Generation Program V1.0\n  by Ross Williams\n\n- DarwinPthreadBarrier, (c) 2015, Aleksey Demakov\n\n- librtlsdr-keenerd, (c) 2013-2014 by Kyle Keen\n\n- asn1c, (c) 2003-2017 by Lev Walkin and contributors\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n\n// vim: textwidth=80\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszpajder%2Fdumpvdl2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fszpajder%2Fdumpvdl2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszpajder%2Fdumpvdl2/lists"}