READSB(1)

NAME
readsb - manual page for readsb version: 3.16 compiled on 250902

SYNOPSIS
readsb [OPTIONS...]

DESCRIPTION
readsb Mode-S/ADSB/TIS Receiver Build options: ENABLE_RTLSDR ENABLE_BLADERF ENABLE_PLUTOSDR ENABLE_SOAPYSDR SC16Q11_TABLE_BITS=8

  General options:

--lat=<lat>
    Reference/receiver surface latitude

--lon=<lon>
    Reference/receiver surface longitude

--no-interactive
    Disable interactive mode, print to stdout

--interactive-ttl=<sec>
    Remove from list if idle for <sec> (default: 60)

--modeac
    Enable decoding of SSR Modes 3/A & 3/C

--modeac-auto
    Enable Mode A/C if requested by a Beast connection

--max-range=<dist>
    Absolute maximum range for position decoding (in nm, default: 300)

--fix
    Enable CRC single-bit error correction (default)

--no-fix
    Disable CRC single-bit error correction

--no-fix-df
    Disable CRC single-bit error correction on the DF type to produce more DF17 messages (disabling reduces CPU usage)

--metric
    Use metric units

--show-only=<addr>
    Show only messages by given ICAO on stdout

--process-only=<addr>
    Process only messages by given ICAO

--filter-DF=<type>
    When displaying decoded ModeS messages on stdout only show this DF type

--device-type=<type>
    Select SDR type (this needs to be placed on the command line before any SDR type specific options)

--gain=<db>
    Set gain (default: auto gain, possible values for rtl-sdr devices: auto auto-verbose 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 58)

--freq=<hz>
    Set frequency (default: 1090 MHz)

--interactive
    Interactive mode refreshing data on screen. Implies --throttle

--raw
    Show only messages hex values

--preamble-threshold=<40-400>
    lower threshold --> more CPU usage (default: 58, pi zero / pi 1: 75, hot CPU 42)

--forward-mlat
    Forward received beast mlat results to beast output ports

--forward-mlat-sbs
    Forward received mlat results to sbs output ports

--stats
    Print stats at exit. No other output

--stats-range
    Collect/show range histogram

--stats-every=<sec>
    Show and reset stats every <sec> seconds (rounded to the nearest 10 seconds due to implementation, first inteval can be up to 5 seconds shorter)

--auto-exit=<sec>
    Run for X seconds, then exit (default: run indefinitely)

--range-outline-hours=<hours>
    Make the range outline retain data for the last X hours (float, default: 24.0)

--onlyaddr
    Show only ICAO addresses

--gnss
    Show altitudes as GNSS when available

--snip=<level>
    Strip IQ file removing samples < level

--debug=<flags>
    Debug mode (verbose), n: network, P: CPR, S: speed check

--devel=<mode>
    Development debugging mode, see source for options, can be specified more than once

--receiver-focus=<receiverId>
    only process messages from receiverId

--cpr-focus=<hex>
    show CPR details for this hex

--leg-focus=<hex>
    show leg marking details for this hex

--trace-focus=<hex>
    show traceAdd details for this hex

--quiet
    Disable output (default)

--write-json=<dir>
    Periodically write json output to <dir>

--write-prom=<file>
    Periodically write prometheus output to <file>

--write-globe-history=<dir>
    Write traces to this directory, 1 gz compressed json per day and airframe

--write-state=<dir>
    Write state to disk to have traces after a restart

--write-state-every=<seconds>
    Continuously write state to disk every X seconds (default: 3600)

--write-state-only-on-exit
    Don't continuously update state.

--heatmap-dir=<dir>
    Change the directory where heatmaps are saved (default is in globe history dir)

--heatmap=<interval in seconds>
    Make Heatmap, each aircraft at most every interval seconds (creates historydir/heatmap.bin and exit after that)

--dump-beast=<dir>,<interval>,<compressionLevel>
    Dump compressed beast files to this directory, start a new file evey interval seconds

--write-json-every=<sec>
    Write json output and update API json every sec seconds (default 1)

--json-location-accuracy=<n>
    Accuracy of receiver location: 0: no location / internal use only, 1: 2 decimals, 2: exact (default), 3: 1 decimals, 4: 0 decimals

--ac-hash-bits=<n>
    Main hash map size: 2^n entries (default: AIRCRAFT_HASH_BITS)

--write-json-globe-index
    Write specially indexed globe_xxxx.json files (for tar1090)

--write-receiver-id-json
    Write receivers.json

--json-trace-interval=<seconds>
    Interval after which a new position will guaranteed to be written to the trace and the json position output (default: 30)

--json-trace-hist-only=1,2,3,8
    Don't write recent(1), full(2), either(3) traces to /run, only archive via write-globe-history (8: irregularly write limited traces to run, subject to change)

--full-trace-dir=<dir>
    when using globe-index, write full traces to this directory instead of --write-json dir (typically /run/readsb), this can be used to reduce memory usage at the cost of roughly 100 IOPS for global traffic

--write-json-gzip
    Write aircraft.json also as aircraft.json.gz

--write-json-binCraft-only=<n>
    Use only binary binCraft format for globe files (1), for aircraft.json as well (2)

--write-binCraft-old
    write old gzipped binCraft files

--json-reliable=<n>
    Minimum position reliability to put it into json (default: 1, globe options will default set this to 2, disable speed filter: -1, max: 4)

--position-persistence=<n>
    Position persistence against outliers (default: 4), incremented by json-reliable minus 1

--jaero-timeout=<n>
    How long in minutes JAERO positions remain valid and on the map in tar1090 (default:33)

--db-file=<file.csv.gz>
    Default: "none" (as of writing a compatible file is available here: https://github.com/wiedehopf/tar1090-db/tree/csv)

--db-file-lt
    aircraft.json: add long type as field desc, add field ownOp for the owner, add field year

  Network options:

--net-connector=<ip,port,protocol>
    Establish connection, can be specified multiple times (e.g. 127.0.0.1,23004,beast_out) Protocols: beast_out, beast_in, raw_out, raw_in, sbs_in, sbs_in_jaero, sbs_out, sbs_out_jaero, vrs_out, json_out, gpsd_in, uat_in, uat_replay_out, planefinder_in, asterix_in, asterix_out (one failover ip/address,port can be specified: primary-address,primary-port,protocol,failover-address,failover-port) (any position in the comma separated list can also be either silent_fail or uuid=<uuid>)

--net
    Enable networking

--net-only
    Legacy Option, Enable networking, use --net instead

--net-bind-address=<ip>
    IP address to bind to (default: Any; Use 127.0.0.1 for private)

--net-bo-port=<ports>
    TCP Beast output listen ports (default: 0)

--net-bi-port=<ports>
    TCP Beast input listen ports (default: 0)

--net-ro-port=<ports>
    TCP raw output listen ports (default: 0)

--net-ri-port=<ports>
    TCP raw input listen ports (default: 0)

--net-uat-replay-port=<ports>
    UAT replay output listen ports (default: 0)

--net-uat-in-port=<ports>
    UAT input listen ports (default: 0)

--net-sbs-port=<ports>
    TCP BaseStation output listen ports (default: 0)

--net-sbs-in-port=<ports>
    TCP BaseStation input listen ports (default: 0)

--net-sbs-jaero-port=<ports>
    TCP SBS Jaero output listen ports (default: 0)

--net-sbs-jaero-in-port=<ports>
    TCP SBS Jaero input listen ports (default: 0)

--net-asterix-out-port=<ports>
    TCP Asterix output listen ports (default: 0)

--net-asterix-in-port=<ports>
    TCP Asterix input listen ports (default: 0)

--net-asterix-reduce
    Apply beast reduce logic and interval to ASTERIX outputs

--net-vrs-port=<ports>
    TCP VRS json output listen ports (default: 0)

--net-vrs-interval=<seconds>
    TCP VRS json output interval (default: 5.0)

--net-json-port=<ports>
    TCP json position output listen ports, sends one line with a json object containing aircraft details for every position received (default: 0) (consider raising --net-ro-size to 8192 for less fragmentation if this is a concern)

--net-json-port-interval=<seconds>
    Set minimum interval between outputs per aircraft for TCP json output, default: 0.0 (every position)

--net-json-port-include-noposition
    TCP json position output: include aircraft without position (state is sent for aircraft for every DF11 with CRC if the aircraft hasn't sent a position in the last 10 seconds and interval allowing)

--net-api-port=<port>
    TCP API listen port (in contrast to other listeners, only a single port is allowed) (update frequency controlled by write-json-every parameter) (default: 0)

--api-shutdown-delay=<seconds>
    Shutdown delay to server remaining API queries, new queries get a 503 response (default: 0)

--tar1090-use-api
    when running with globe-index, signal tar1090 use the readsb API to get data, requires webserver mapping of /tar1090/re-api to proxy_pass the requests to the --net-api-port, see nginx-readsb-api.conf in the tar1090 repository for details

--net-beast-reduce-out-port=<ports>
    TCP BeastReduce output listen ports (default: 0)

--net-beast-reduce-interval=<seconds>
    BeastReduce data update interval, longer means less data (default: 0.250, valid range: 0.000 - 14.999)

--net-beast-reduce-optimize-for-mlat
    BeastReduce output: keep all messages relevant to mlat-client

--net-beast-reduce-filter-dist=<distance in nmi>
    beast-reduce: remove aircraft which are further than distance from the receiver

--net-beast-reduce-filter-alt=<pressure altitude in ft>
    beast-reduce: remove aircraft which are above altitude

--net-sbs-reduce
    Apply beast reduce logic and interval to SBS outputs

--net-receiver-id
    forward receiver ID

--net-ingest
    primary ingest node

--net-garbage=<ports>
    timeout receivers, output messages from timed out receivers as beast on <ports>

--decode-threads=<n>
    Number of decode threads, either 1 or 2 (default: 1). Only use 2 when you have beast traffic > 200 MBit/s, expect 1.4x speedup for 2x CPU

--uuid-file=<path>
    path to UUID file

--net-ro-size=<size>
    TCP output flush size (maximum amount of internally buffered data before writing to network) (default: 1280)

--net-ro-interval=<seconds>
    TCP output flush interval in seconds (maximum delay between placing data in the output buffer and sending)(default: 0.05, valid values 0.0 - 1.0)

--net-ro-interval-beast-reduce=<seconds>
    TCP output flush interval in seconds for beast-reduce outputs (default: value from --net-ro-interval, valid values 0.0 - 1.0)

--net-connector-delay=<seconds>
    Outbound re-connection delay (default: 15)

--net-heartbeat=<rate>
    TCP heartbeat rate in seconds (default: 60 sec; 0 to disable)

--net-buffer=<n>
    control some buffer sizes: 8KB * (2^n) (default: n=1, 16KB)

--net-verbatim
    Forward messages unchanged

--sdr-buffer-size=<KiB>
    SDR buffer / USB transfer size in kibibytes (default: 256 which is equivalent to around 54 ms using rtl-sdr, option might be ignored in future versions)

RTL-SDR options:

use with --device-type rtlsdr

--device=<index|serial>
    Select device by index or serial number

--enable-agc
    Enable digital AGC (not tuner AGC!)

--ppm=<correction>
    Set oscillator frequency correction in PPM

BladeRF options:

use with --device-type bladerf

--device=<ident>
    Select device by bladeRF 'device identifier'

--bladerf-fpga=<path>
    Use alternative FPGA bitstream ('' to disable FPGA load)

--bladerf-decimation=<N>
    Assume FPGA decimates by a factor of N

--bladerf-bandwidth=<hz>
    Set LPF bandwidth ('bypass' to bypass the LPF)

HackRF options:

use with --device-type hackrf

--device=<ident>
    Select device by serial number

--hackrf-enable-ampgain
    Enable amp gain (RF stage) (~11 dB) (default: disabled)

--hackrf-vgagain=<db>
    Set gain (baseband stage) (default: 48, valid: 0-62, 2 dB steps)

  Modes-S Beast options, use with --device-type modesbeast:

--beast-serial=<path>
    Path to Beast serial device (default /dev/ttyUSB0)

--beast-df1117-on
    Turn ON DF11/17-only filter

--beast-mlat-off
    Turn OFF MLAT time stamps

--beast-crc-off
    Turn OFF CRC checking

--beast-df045-on
    Turn ON DF0/4/5 filter

--beast-fec-off
    Turn OFF forward error correction

--beast-modeac
    Turn ON mode A/C

--beast-baudrate=<baud>
    Override Baudrate (default rate 3000000 baud, try 1000000 / 921600 as alternatives)

GNS HULC options, use with --device-type gnshulc:

Beast binary and HULC protocol input with hardware handshake enabled.

--beast-serial=<path>
    Path to GNS HULC serial device (default /dev/ttyUSB0)

  ifile-specific options, use with --device-type ifile:

--ifile=<path>
    Read samples from given file ('-' for stdin)

--iformat=<type>
    Set sample format (UC8, SC16, SC16Q11)

--throttle
    Process samples at the original capture speed

ADALM-Pluto SDR options:

use with --device-type plutosdr

--pluto-uri=<USB uri>
    Create USB context from this URI.(eg. usb:1.2.5)

--pluto-network=<hostname or IP>
    Hostname or IP to create networks context. (default pluto.local)

SoapySDR options:

use with --device-type soapysdr

--soapy-device=<ident>
    Select device by SoapySDR key pair (ex. driver=lime)

--soapy-antenna=<channel>
    Select an antenna

--soapy-bandwidth=<bandwith>
    Select bandwidth

--soapy-enable-agc
    enable AGC

--soapy-gain-element=<gain>
    set SoapySDR gain element

  Help options:

--help
    Give this help list

--usage
    Give a short usage message

Credits: antirez (original dump1090) Malcom Robb (work on his dump1090 fork) mutability (forked to dump1090-mutability and further to dump1090-fa) Mictronics (readsb as a fork of dump1090-fa) wiedehopf (this fork of Mictronics readsb)

REPORTING BUGS
Report bugs to Matthias Wirth <matthias.wirth@gmail.com>