1Dump1090 README 2=== 3 4Dump 1090 is a Mode S decoder specifically designed for RTLSDR devices. 5 6The main features are: 7 8* Robust decoding of weak messages, with mode1090 many users observed 9 improved range compared to other popular decoders. 10* Network support: TCP30003 stream (MSG5...), Raw packets, HTTP. 11* Embedded HTTP server that displays the currently detected aircrafts on 12 Google Map. 13* Single bit errors correction using the 24 bit CRC. 14* Ability to decode DF11, DF17 messages. 15* Ability to decode DF formats like DF0, DF4, DF5, DF16, DF20 and DF21 16 where the checksum is xored with the ICAO address by brute forcing the 17 checksum field using recently seen ICAO addresses. 18* Decode raw IQ samples from file (using --ifile command line switch). 19* Interactive command-line-interfae mode where aircrafts currently detected 20 are shown as a list refreshing as more data arrives. 21* CPR coordinates decoding and track calculation from velocity. 22* TCP server streaming and receiving raw data to/from connected clients 23 (using --net). 24 25While from time to time I still add / fix stuff in my fork, I target 26minimalism of the implementation. However there is a 27[much more feature complete fork](https://github.com/MalcolmRobb/dump1090) 28available, developed by MalcolmRobb. 29 30Installation 31--- 32 33Type "make". 34 35Normal usage 36--- 37 38To capture traffic directly from your RTL device and show the captured traffic 39on standard output, just run the program without options at all: 40 41 ./dump1090 42 43To just output hexadecimal messages: 44 45 ./dump1090 --raw 46 47To run the program in interactive mode: 48 49 ./dump1090 --interactive 50 51To run the program in interactive mode, with networking support, and connect 52with your browser to http://localhost:8080 to see live traffic: 53 54 ./dump1090 --interactive --net 55 56In interactive mode it is possible to have a less information dense but more 57"arcade style" output, where the screen is refreshed every second displaying 58all the recently seen aircrafts with some additional information such as 59altitude and flight number, extracted from the received Mode S packets. 60 61Using files as source of data 62--- 63 64To decode data from file, use: 65 66 ./dump1090 --ifile /path/to/binfile 67 68The binary file should be created using `rtl_sdr` like this (or with any other 69program that is able to output 8-bit unsigned IQ samples at 2Mhz sample rate). 70 71 rtl_sdr -f 1090000000 -s 2000000 -g 50 output.bin 72 73In the example `rtl_sdr` a gain of 50 is used, simply you should use the highest 74gain availabe for your tuner. This is not needed when calling Dump1090 itself 75as it is able to select the highest gain supported automatically. 76 77It is possible to feed the program with data via standard input using 78the --ifile option with "-" as argument. 79 80Additional options 81--- 82 83Dump1090 can be called with other command line options to set a different 84gain, frequency, and so forth. For a list of options use: 85 86 ./dump1090 --help 87 88Everything is not documented here should be obvious, and for most users calling 89it without arguments at all is the best thing to do. 90 91Reliability 92--- 93 94By default Dump1090 tries to fix single bit errors using the checksum. 95Basically the program will try to flip every bit of the message and check if 96the checksum of the resulting message matches. 97 98This is indeed able to fix errors and works reliably in my experience, 99however if you are interested in very reliable data I suggest to use 100the --no-fix command line switch in order to disable error fixing. 101 102Performances and sensibility of detection 103--- 104 105In my limited experience Dump1090 was able to decode a big number of messages 106even in conditions where I encountered problems using other programs, however 107no formal test was performed so I can't really claim that this program is 108better or worse compared to other similar programs. 109 110If you can capture traffic that Dump1090 is not able to decode properly, drop 111me an email with a download link. I may try to improve the detection during 112my free time (this is just an hobby project). 113 114Network server features 115--- 116 117By enabling the networking support with --net Dump1090 starts listening 118for clients connections on port 30002 and 30001 (you can change both the 119ports if you want, see --help output). 120 121Port 30002 122--- 123 124Connected clients are served with data ASAP as they arrive from the device 125(or from file if --ifile is used) in the raw format similar to the following: 126 127 *8D451E8B99019699C00B0A81F36E; 128 129Every entry is separated by a simple newline (LF character, hex 0x0A). 130 131Port 30001 132--- 133 134Port 30001 is the raw input port, and can be used to feed Dump1090 with 135data in the same format as specified above, with hex messages starting with 136a `*` and ending with a `;` character. 137 138So for instance if there is another remote Dump1090 instance collecting data 139it is possible to sum the output to a local Dump1090 instance doing something 140like this: 141 142 nc remote-dump1090.example.net 30002 | nc localhost 30001 143 144It is important to note that what is received via port 30001 is also 145broadcasted to clients listening to port 30002. 146 147In general everything received from port 30001 is handled exactly like the 148normal traffic from RTL devices or from file when --ifile is used. 149 150It is possible to use Dump1090 just as an hub using --ifile with /dev/zero 151as argument as in the following example: 152 153 ./dump1090 --net-only 154 155Or alternatively to see what's happening on the screen: 156 157 ./dump1090 --net-only --interactive 158 159Then you can feed it from different data sources from the internet. 160 161Port 30003 162--- 163 164Connected clients are served with messages in SBS1 (BaseStation) format, 165similar to: 166 167 MSG,4,,,738065,,,,,,,,420,179,,,0,,0,0,0,0 168 MSG,3,,,738065,,,,,,,35000,,,34.81609,34.07810,,,0,0,0,0 169 170This can be used to feed data to various sharing sites without the need to use another decoder. 171 172Antenna 173--- 174 175Mode S messages are transmitted in the 1090 Mhz frequency. If you have a decent 176antenna you'll be able to pick up signals from aircrafts pretty far from your 177position, especially if you are outdoor and in a position with a good sky view. 178 179You can easily build a very cheap antenna following the istructions at: 180 181 http://antirez.com/news/46 182 183With this trivial antenna I was able to pick up signals of aircrafts 200+ Km 184away from me. 185 186If you are interested in a more serious antenna check the following 187resources: 188 189* http://gnuradio.org/data/grcon11/06-foster-adsb.pdf 190* http://www.lll.lu/~edward/edward/adsb/antenna/ADSBantenna.html 191* http://modesbeast.com/pix/adsb-ant-drawing.gif 192 193Aggressive mode 194--- 195 196With --aggressive it is possible to activate the *aggressive mode* that is a 197modified version of the Mode S packet detection and decoding. 198THe aggresive mode uses more CPU usually (especially if there are many planes 199sending DF17 packets), but can detect a few more messages. 200 201The algorithm in aggressive mode is modified in the following ways: 202 203* Up to two demodulation errors are tolerated (adjacent entires in the magnitude 204 vector with the same eight). Normally only messages without errors are 205 checked. 206* It tries to fix DF17 messages trying every two bits combination. 207 208The use of aggressive mdoe is only advised in places where there is low traffic 209in order to have a chance to capture some more messages. 210 211Debug mode 212--- 213 214The Debug mode is a visual help to improve the detection algorithm or to 215understand why the program is not working for a given input. 216 217In this mode messages are displayed in an ASCII-art style graphical 218representation, where the individial magnitude bars sampled at 2Mhz are 219displayed. 220 221An index shows the sample number, where 0 is the sample where the first 222Mode S peak was found. Some additional background noise is also added 223before the first peak to provide some context. 224 225To enable debug mode and check what combinations of packets you can 226log, use `mode1090 --help` to obtain a list of available debug flags. 227 228Debug mode includes an optional javascript output that is used to visualize 229packets using a web browser, you can use the file debug.html under the 230'tools' directory to load the generated frames.js file. 231 232How this program works? 233--- 234 235The code is very documented and written in order to be easy to understand. 236For the diligent programmer with a Mode S specification on his hands it 237should be trivial to understand how it works. 238 239The algorithms I used were obtained basically looking at many messages 240as displayed using a trow-away SDL program, and trying to model the algorithm 241based on how the messages look graphically. 242 243How to test the program? 244--- 245 246If you have an RTLSDR device and you happen to be in an area where there 247are aircrafts flying over your head, just run the program and check for signals. 248 249However if you don't have an RTLSDR device, or if in your area the presence 250of aircrafts is very limited, you may want to try the sample file distributed 251with the Dump1090 distribution under the "testfiles" directory. 252 253Just run it like this: 254 255 ./dump1090 --ifile testfiles/modes1.bin 256 257What is --strip mode? 258--- 259 260It is just a simple filter that will get raw IQ 8 bit samples in input 261and will output a file missing all the parts of the file where I and Q 262are lower than the specified <level> for more than 32 samples. 263 264Use it like this: 265 266 cat big.bin | ./dump1090 --snip 25 > small.bin 267 268I used it in order to create a small test file to include inside this 269program source code distribution. 270 271Contributing 272--- 273 274Dump1090 was written during some free time during xmas 2012, it is an hobby 275project so I'll be able to address issues and improve it only during 276free time, however you are incouraged to send pull requests in order to 277improve the program. A good starting point can be the TODO list included in 278the source distribution. 279 280Credits 281--- 282 283Dump1090 was written by Salvatore Sanfilippo <antirez@gmail.com> and is 284released under the BSD three clause license. 285