READSB(1)

📦
version 3.16 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 readsb(1) — User Commands 💖

okay bestie, pull up a chair 🫶 because this is the manual page for readsb, version 3.16, compiled on 260209. it's giving "aircraft go brrr" and honestly? we're obsessed. 💅

✨ NAME ✨

readsb — the manual page for readsb version: 3.16 compiled on 260209 💖

🌈 SYNOPSIS 🌈

readsb [OPTIONS...]

🦋 DESCRIPTION 🦋

readsb is your Mode-S/ADSB/TIS Receiver, periodt. 👑

Build options that got baked into this build: ENABLE_RTLSDR ENABLE_BLADERF ENABLE_PLUTOSDR ENABLE_SOAPYSDR ✨

okay so real talk, bestie: every option is listed below, and you're gonna wanna read the ones with defaults because those defaults are doing a lot of heavy lifting. no cap.

🎀 General options: 🎀

  • --lat=<lat> — the reference/receiver surface latitude. where you at, literally. 📍
  • --lon=<lon> — the reference/receiver surface longitude. the other half of where you at. 📍
  • --no-interactive — disable interactive mode, just print to stdout.
  • --interactive-ttl=<sec> — remove an aircraft from the list if it's been 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> — the absolute maximum range for position decoding (in nm, default: 300).
  • --fix — enable CRC single-bit error correction (this is the default, bestie).
  • --no-fix — disable CRC single-bit error correction.
  • --no-fix-df — disable CRC single-bit error correction on the DF type so you produce more DF17 messages (and yeah, disabling it reduces CPU usage).
  • --metric — use metric units. 🌍
  • --show-only=<addr> — show only messages by the given ICAO on stdout.
  • --process-only=<addr> — process only messages by the given ICAO.
  • --filter-DF=<type> — when displaying decoded ModeS messages on stdout, only show this DF type.
  • --device-type=<type> — select the SDR type. ⚠️ this one needs to be placed on the command line before any SDR type specific options, so don't be chaotic about it.
  • --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 whatsoever.
  • --stats-range — collect/show the range histogram.
  • --stats-every=<sec> — show and reset stats every <sec> seconds (rounded to the nearest 10 seconds due to implementation, first interval 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 the 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, and it 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 so you 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 the globe history dir).
  • --heatmap=<interval in seconds> — make Heatmap, each aircraft at most every interval seconds (creates historydir/heatmap.bin and exits after that). 🔥
  • --dump-beast=<dir>,<interval>,<compressionLevel> — dump compressed beast files to this directory, start a new file every 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 decimal, 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 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 the --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 a connection, and yeah it 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>). she's flexible. 💅
  • --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 to 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.

okay and we're not done yet bestie, this page keeps going 💀 — more parts coming. 🦋

  • --net-beast-reduce-filter-alt=<pressure altitude in ft> — the beast-reduce filter that yeets any aircraft flying above that altitude out of the feed. bye bestie 💅
  • --net-sbs-reduce — applies the beast reduce logic and interval to SBS outputs too ✨
  • --net-receiver-id — forward the receiver ID 🎀
  • --net-ingest — marks this node as the primary ingest node 👑
  • --net-garbage=<ports> — times out receivers, and spits out messages from those timed-out receivers as beast on <ports> 💀
  • --decode-threads=<n> — how many decode threads you want, and it's either 1 or 2 (default: 1). Only reach for 2 when you're pushing beast traffic > 200 MBit/s — you get expect 1.4x speedup for 2x CPU 🫠
  • --uuid-file=<path> — path to the UUID file 🦋
  • --net-ro-size=<size> — TCP output flush size, aka the maximum amount of internally buffered data before it gets written to the network (default: 1280) 🌸
  • --net-ro-interval=<seconds> — TCP output flush interval, in seconds — the maximum delay between data landing in the output buffer and it actually being sent (default: 0.05, valid values 0.0 - 1.0) ⏰
  • --net-ro-interval-beast-reduce=<seconds> — same deal, TCP output flush interval in seconds, but for beast-reduce outputs (default: whatever value came 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> — controls some buffer sizes: 8KB * (2^n) (default: n=1, 16KB) 🧺
  • --net-verbatim — forwards messages unchanged, no edits no notes, straight through 📨
  • --sdr-buffer-size=<KiB> — SDR buffer / USB transfer size in kibibytes (default: 256, which is equivalent to around 54 ms using rtl-sdr — heads up, this option might be ignored in future versions) 🙈

✨ RTL-SDR options ✨

use with --device-type rtlsdr

  • --device=<index|serial> — pick your device by index or serial number 💫
  • --enable-agc — enable digital AGC (not tuner AGC, keep those vibes separate bestie) 🎚️
  • --ppm=<correction> — set the oscillator frequency correction in PPM 🎯

🌈 BladeRF options 🌈

use with --device-type bladerf

  • --device=<ident> — pick your device by bladeRF 'device identifier' 🦋
  • --bladerf-fpga=<path> — use an alternative FPGA bitstream ('' to disable FPGA load) 🧩
  • --bladerf-decimation=<N> — assume the 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> — pick your 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 the 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 the 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 the given file ('-' for stdin) 📂
  • --iformat=<type> — set the 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 a 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> — pick your 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 🫶

No cap, this thing stands on the shoulders of absolute legends, and we are obsessed:

  • 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 😭

Found a bug? Do not suffer in silence bestie, report bugs to Matthias Wirth <matthias.wirth@gmail.com> 💌

okay that's the whole page, we ate and left no crumbs 💅 readsb version 3.16, compiled... February 2026, and it goes by READSB(1) if you need to cite it in your essay 🎀 byeee 🫶

📦 where this page comes from