1dump1090(1)                  Simple Mode S decoder                 dump1090(1)
2
3
4
5   SYNOPSIS
6       /usr/bin/dump1090 [--longoption ...]
7
8   DESCRIPTION
9       Install  this  to use your RTL-SDR to track commercial aircraft in your
10       area.
11
12       The main features are:
13
14       • Robust decoding of weak messages, with mode1090 many  users  observed
15         improved range compared to other popular decoders.
16
17       • Network support: TCP30003 stream (MSG5...), Raw packets, HTTP.
18
19       • Embedded HTTP server that displays the currently detected aircraft on
20         Google Map.
21
22       • Single bit errors correction using the 24 bit CRC.
23
24       • Ability to decode DF11, DF17 messages.
25
26       • Ability to decode DF formats like DF0, DF4, DF5, DF16, DF20 and  DF21
27         where  the  checksum  is xored with the ICAO address by brute forcing
28         the checksum field using recently seen ICAO addresses.
29
30       • Decode raw IQ samples from file (using –ifile command line switch).
31
32       • Interactive command-line interface mode where aircraft currently  de‐
33         tected are shown as a list refreshing as more data arrives.
34
35       • CPR coordinates decoding and track calculation from velocity.
36
37       • TCP server streaming and receiving raw data to/from connected clients
38         (using –net).
39
40   USAGE
41       To capture traffic directly from your RTL device and show the  captured
42       traffic  on  standard  output,  just run the program without options at
43       all:
44
45              ./dump1090
46
47       To just output hexadecimal messages:
48
49              ./dump1090 --raw
50
51       To run the program in interactive mode:
52
53              ./dump1090 --interactive
54
55       To run the program in interactive mode, with  networking  support,  and
56       connect with your browser to http://localhost:8080 to see live traffic:
57
58              ./dump1090 --interactive --net
59
60       In interactive mode it is possible to have a less information dense but
61       more “arcade style” output, where the screen is refreshed every  second
62       displaying  all the recently seen aircrafts with some additional infor‐
63       mation such as altitude and flight number, extracted from the  received
64       Mode S packets.
65
66   Using files as source of data
67       To decode data from file, use:
68
69              ./dump1090 --ifile /path/to/binfile
70
71       The  binary file should be created using rtl_sdr like this (or with any
72       other program that is able to output 8-bit unsigned IQ samples at  2Mhz
73       sample rate).
74
75              rtl_sdr -f 1090000000 -s 2000000 -g 50 output.bin
76
77       In  the example rtl_sdr a gain of 50 is used, simply you should use the
78       highest gain availabe for your tuner.  This is not needed when  calling
79       Dump1090  itself as it is able to select the highest gain supported au‐
80       tomatically.
81
82       It is possible to feed the program with data via standard  input  using
83       the –ifile option with “-” as argument.
84
85   Additional options
86       Dump1090 can be called with other command line options to set a differ‐
87       ent gain, frequency, and so forth.  For a list of options use:
88
89              ./dump1090 --help
90
91       Everything is not documented here should be obvious, and for most users
92       calling it without arguments at all is the best thing to do.
93
94   Reliability
95       By  default Dump1090 tries to fix single bit errors using the checksum.
96       Basically the program will try to flip every bit  of  the  message  and
97       check if the checksum of the resulting message matches.
98
99       This  is indeed able to fix errors and works reliably in my experience,
100       however if you are interested in very reliable data I  suggest  to  use
101       the –no-fix command line switch in order to disable error fixing.
102
103   Performances and sensibility of detection
104       In  my  limited  experience Dump1090 was able to decode a big number of
105       messages even in conditions where I encountered  problems  using  other
106       programs,  however no formal test was performed so I can’t really claim
107       that this program is better or worse compared  to  other  similar  pro‐
108       grams.
109
110       If  you can capture traffic that Dump1090 is not able to decode proper‐
111       ly, drop me an email with a download link.  I may try  to  improve  the
112       detection during my free time (this is just an hobby project).
113
114   Network server features
115       By  enabling the networking support with –net Dump1090 starts listening
116       for clients connections on port 30002 and 30001 (you  can  change  both
117       the ports if you want, see –help output).
118
119   Port 30002
120       Connected clients are served with data ASAP as they arrive from the de‐
121       vice (or from file if –ifile is used) in the raw format similar to  the
122       following:
123
124              *8D451E8B99019699C00B0A81F36E;
125
126       Every entry is separated by a simple newline (LF character, hex 0x0A).
127
128   Port 30001
129       Port 30001 is the raw input port, and can be used to feed Dump1090 with
130       data in the same format as specified above, with hex messages  starting
131       with a * and ending with a ; character.
132
133       So for instance if there is another remote Dump1090 instance collecting
134       data it is possible to sum the output to a local Dump1090 instance  do‐
135       ing something like this:
136
137              nc remote-dump1090.example.net 30002 | nc localhost 30001
138
139       It  is  important  to note that what is received via port 30001 is also
140       broadcasted to clients listening to port 30002.
141
142       In general everything received from port 30001 is handled exactly  like
143       the normal traffic from RTL devices or from file when –ifile is used.
144
145       It  is  possible  to  use  Dump1090  just  as  an hub using –ifile with
146       /dev/zero as argument as in the following example:
147
148              ./dump1090 --net-only
149
150       Or alternatively to see what’s happening on the screen:
151
152              ./dump1090 --net-only --interactive
153
154       Then you can feed it from different data sources from the internet.
155
156   Port 30003
157       Connected clients are served with messages in SBS1  (BaseStation)  for‐
158       mat, similar to:
159
160              MSG,4,,,738065,,,,,,,,420,179,,,0,,0,0,0,0
161              MSG,3,,,738065,,,,,,,35000,,,34.81609,34.07810,,,0,0,0,0
162
163       This can be used to feed data to various sharing sites without the need
164       to use another decoder.
165
166   Antenna
167       Mode S messages are transmitted in the 1090 Mhz frequency.  If you have
168       a decent antenna you’ll be able to pick up signals from aircrafts pret‐
169       ty far from your position, especially if you are outdoor and in a posi‐
170       tion with a good sky view.
171
172       You can easily build a very cheap antenna following the istructions at:
173
174              http://antirez.com/news/46
175
176       With  this  trivial  antenna I was able to pick up signals of aircrafts
177       200+ Km away from me.
178
179       If you are interested in a more serious antenna check the following re‐
180       sources:
181
182http://gnuradio.org/data/grcon11/06-foster-adsb.pdf
183
184http://www.lll.lu/~edward/edward/adsb/antenna/ADSBantenna.html
185
186http://modesbeast.com/pix/adsb-ant-drawing.gif
187
188   Aggressive mode
189       With –aggressive it is possible to activate the aggressive mode that is
190       a modified version of the Mode S packet detection  and  decoding.   THe
191       aggresive  mode  uses  more  CPU  usually (especially if there are many
192       planes sending DF17 packets), but can detect a few more messages.
193
194       The algorithm in aggressive mode is modified in the following ways:
195
196       • Up to two demodulation errors are tolerated (adjacent entires in  the
197         magnitude  vector with the same eight).  Normally only messages with‐
198         out errors are checked.
199
200       • It tries to fix DF17 messages trying every two bits combination.
201
202       The use of aggressive mdoe is only advised in places where there is low
203       traffic in order to have a chance to capture some more messages.
204
205   Debug mode
206       The  Debug  mode is a visual help to improve the detection algorithm or
207       to understand why the program is not working for a given input.
208
209       In this mode messages are displayed in  an  ASCII-art  style  graphical
210       representation, where the individial magnitude bars sampled at 2Mhz are
211       displayed.
212
213       An index shows the sample number, where 0 is the sample where the first
214       Mode  S peak was found.  Some additional background noise is also added
215       before the first peak to provide some context.
216
217       To enable debug mode and check what combinations  of  packets  you  can
218       log, use mode1090 --help to obtain a list of available debug flags.
219
220       Debug mode includes an optional javascript output that is used to visu‐
221       alize packets using a web browser, you can use the file debug.html  un‐
222       der the `tools' directory to load the generated frames.js file.
223
224   How this program works?
225       The  code  is very documented and written in order to be easy to under‐
226       stand.  For the diligent programmer with a Mode S specification on  his
227       hands it should be trivial to understand how it works.
228
229       The  algorithms I used were obtained basically looking at many messages
230       as displayed using a trow-away SDL program, and trying to model the al‐
231       gorithm based on how the messages look graphically.
232
233   How to test the program?
234       If  you  have  an  RTLSDR  device and you happen to be in an area where
235       there are aircrafts flying over your head, just  run  the  program  and
236       check for signals.
237
238       However  if  you  don’t  have  an RTLSDR device, or if in your area the
239       presence of aircrafts is very limited, you may want to try  the  sample
240       file  distributed  with the Dump1090 distribution under the “testfiles”
241       directory.
242
243       Just run it like this:
244
245              ./dump1090 --ifile testfiles/modes1.bin
246
247   What is –strip mode?
248       It is just a simple filter that will get raw IQ 8 bit samples in  input
249       and  will output a file missing all the parts of the file where I and Q
250       are lower than the specified for more than 32 samples.
251
252       Use it like this:
253
254              cat big.bin | ./dump1090 --snip 25 > small.bin
255
256       I used it in order to create a small test file to include  inside  this
257       program source code distribution.
258
259   Contributing
260       Dump1090  was  written during some free time during xmas 2012, it is an
261       hobby project so I’ll be able to address issues  and  improve  it  only
262       during  free  time, however you are incouraged to send pull requests in
263       order to improve the program.  A good starting point can  be  the  TODO
264       list included in the source distribution.
265
266   OPTIONS
267--device-index <index>
268       Select RTL device (default: 0).
269
270--gain <db>
271       Set gain (default: max gain.  Use -100 for auto-gain).
272
273--enable-agc
274       Enable the Automatic Gain Control (default: off).
275
276--freq <hz>
277       Set frequency (default: 1090 Mhz).
278
279--ifile <filename>
280       Read data from file (use `-' for stdin).
281
282--loop
283       With –ifile, read the same file in a loop.
284
285--interactive
286       Interactive mode refreshing data on screen.
287
288--interactive-rows <num>
289       Max number of rows in interactive mode (default: 15).
290
291--interactive-ttl <sec>
292       Remove from list if idle for (default: 60).
293
294--raw
295       Show only messages hex values.
296
297--net
298       Enable networking.
299
300--net-only
301       Enable just networking, no RTL device or file used.
302
303--net-ro-port <port>
304       TCP listening port for raw output (default: 30002).
305
306--net-ri-port <port>
307       TCP listening port for raw input (default: 30001).
308
309--net-http-port <port>
310       HTTP server port (default: 8080).
311
312--net-sbs-port <port>
313       TCP listening port for BaseStation format output (default: 30003).
314
315--no-fix
316       Disable single-bits error correction using CRC.
317
318--no-crc-check
319       Disable messages with broken CRC (discouraged).
320
321--aggressive
322       More CPU for more messages (two bits fixes, ...).
323
324--stats
325       With –ifile print stats at exit.  No other output.
326
327--onlyaddr
328       Show only ICAO addresses (testing purposes).
329
330--metric
331       Use metric units (meters, km/h, ...).
332
333--snip <level>
334       Strip IQ file removing samples < level.
335
336--debug <flags>
337       Debug mode (verbose), see README for details.
338
339--help
340       Print usage summary.
341
342   Debug mode flags:
343       d = Log frames decoded with errors
344       D = Log frames decoded with zero errors
345       c = Log frames with bad CRC
346       C = Log frames with good CRC
347       p = Log frames with bad preamble
348       n = Log network debugging info
349       j = Log frames to frames.js, loadable by debug.html.
350
351   FILES
352       /usr/share/dump1090/gmap.html
353
354
355
356                                                                   dump1090(1)
Impressum