From f9026feb7f1a80044f623735f1b824724c858a63 Mon Sep 17 00:00:00 2001 From: Nick Foster Date: Fri, 15 Jun 2012 18:50:56 -0700 Subject: [PATCH] Brand new README file. --- README | 183 ++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 141 insertions(+), 42 deletions(-) diff --git a/README b/README index 29c1e99..76e68bb 100644 --- a/README +++ b/README @@ -1,50 +1,149 @@ -# -# Copyright 2005, 2006 Free Software Foundation, Inc. -# -# This file is part of GNU Radio -# -# GNU Radio is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 3, or (at your option) -# any later version. -# -# GNU Radio is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with GNU Radio; see the file COPYING. If not, write to -# the Free Software Foundation, Inc., 51 Franklin Street, -# Boston, MA 02110-1301, USA. -# +======================================================================== +Copyright 2010, 2011, 2012 Nick Foster -This directory (and the resulting tarball) contains a build tree with -examples, Makefiles, etc that demonstrate how to write signal -processing blocks for the GNU Radio system. This directory is -intentionally distributed separately from the unified tarball of the -rest of GNU Radio in order to avoid problems for people who have begun -to write blocks with a modified copy of gr-howto-write-a-block. +Quaternion.py copyright 2009 Smithsonian Astrophysical Observatory + Released under New BSD / 3-Clause BSD License + All rights reserved -This package requires that gnuradio-core is already installed. It -also depends on some GNU Radio prerequisites, such as boost. +This file is part of gr-air-modes + +gr-air-modes is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 3, or (at your option) +any later version. + +gr-air-modes is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with gr-air-modes; see the file COPYING. If not, write to +the Free Software Foundation, Inc., 51 Franklin Street, +Boston, MA 02110-1301, USA. -To build the examples from the tarball use the normal recipe: +======================================================================== +AUTHOR - $ ./configure - $ make - $ make check +Nick Foster -If you're building from CVS, you'll need to use this sequence, since -CVS doesn't contain configure or the generated Makefiles. +======================================================================== +OVERVIEW - $ ./bootstrap - $ ./configure - $ make - $ make check +gr-air-modes implements a software-defined radio receiver for Mode S +transponder signals, including ADS-B reports from equipped aircraft. +Mode S is the transponder protocol used in modern commercial aircraft. +A Mode S-equipped aircraft replies to radar interrogation by either +ground radar (secondary surveillance) or other aircraft ("Traffic +Collision Avoidance System", or TCAS). The protocol is an extended +version of the Mode A/C protocol used in transponders since the 1940s. +Mode S reports include a unique airframe identifier (referred to +as the "ICAO number") and altitude (to facilitate separation control). +This receiver listens to the 1090MHz downlink channel; interrogation +requests at 1030MHz are not received or decoded by this program. -The doc directory is not built by default. This is to avoid spurious -build problems on systems that don't have xmlto installed. If you -have xmlto and its dependencies installed, you can build the html -version of the howto article by cd'ing to doc and invoking make. +Automatic Dependent Surveillance-Broadcast (ADS-B) is a communication +protocol using the Extended Mode S transport layer. There are other +implementations (VDL Mode 2 and UAT, for instance) but Mode S remains +the primary ADS-B transport for commercial use. The protocol is: + +* Automatic: it requires no pilot input +* Dependent: it is dependent on altimeter, GPS, and other aircraft + instrumentation for information +* Surveillance: it provides current information about the transmitting + aircraft +* Broadcast: it is one-way, broadcast to all receivers within range. + +ADS-B-equipped aircraft broadcast ("squitter") their position, velocity, +flight number, and other interesting information to any receiver within +range of the aircraft. Position reports are typically generated once per +second and flight indentification every five seconds. + +Implementation of ADS-B is mandatory in European airspace as well as +in Australia. North American implementation is still voluntary, with +a mandate arriving in 2020 via the FAA's "NextGen" program. + +The receiver uhd_modes.py is written for use with Ettus Research USRP +devices, although the "RTLSDR" receivers are also supported via the +Osmocom driver. In addition, any receiver which outputs complex +samples at at least 2Msps should work via the file input or UDP input +options, or by means of a Gnuradio interface. Multiple output formats +are supported: + +* Raw (or minimally processed) output of packet data +* Parsed text +* SQLite database +* KML for use with Google Earth +* SBS-1-compatible output for use with e.g. PlanePlotter or Virtual + Radar Server +* FlightGear multiplayer interface for real-time display of traffic + within the simulator + +Most of the common ADS-B reports are fully decoded per specification. +Those that are not are generally ones which are not commonly used. + +In particular, should you receive a large number of reports which result +in "not implemented" or "No handler" messages, please use the -w option +to save raw data and forward it to the author. To save time, note that +receiving a small number of spurious reports is expected; false reports +can be excluded by looking for multiple reports from the same aircraft +(i.e., the same ICAO 6-digit hexadecimal number). + +======================================================================== +REQUIREMENTS + +gr-air-modes requires: + +* Python >= 2.5 (written for Python 2.7, Python 3.0 might work) +** NumPy and SciPy are required for the FlightGear output plugin. +* Gnuradio >= 3.5.0 +* Ettus UHD >= 3.4.0 +* SQLite 3.7 or later + +======================================================================== +USAGE + +The main application is apps/uhd_modes.py. For a complete list of +options, run: + +$ apps/uhd_modes.py --help + +For use with Ettus UHD-compatible devices, the defaults should suffice +to receive reports and print to the screen. + +In particular, the --location option should be used to set the receiving +location's GPS coordinates. This provides better decoding of position +reports and enables range and bearing calculations. + +======================================================================== +FILES + +Interesting files and libraries included with the package: + +* apps/uhd_modes.py: The main application. +* apps/get_correlated_records.py: Demonstration program for computing + multilaterated time error for two unsynchronized receiver stations. +* lib/air_modes_int_and_dump.cc: Unused integrate-and-dump filter for + demodulating Mode S waveforms. +* lib/air_modes_preamble.cc: Mode S preamble detector. +* lib/air_modes_slicer.cc: Bit slicer (1 vs 0) and packet aggregator. +* lib/modes_crc.cc: Computes parity check for Mode S packets. +* python/altitude.py: Mode S altitude encoding/decoding routines +* python/cpr.py: Compact Position Reporting encoder/decoder +* python/modes_flightgear.py: FlightGear (open-source flight simulator) + plugin which inserts live traffic into the simulator via the + multiplayer interface. +* python/mlat.py: Multilateration algorithms for determining position of + non-ADS-B-equipped or non-cooperative aircraft using multiple + receivers. +* python/modes_kml.py: KML output plugin for Google Earth. +* python/modes_parse.py: Mode S/ADS-B packet parsing routines. +* python/modes_print.py: Human-readable printout plugin +* python/modes_raw_server.py: UDP output plugin for raw data output +* python/modes_sbs1.py: SBS-1-compatible output plugin for use with + Virtual Radar Server, PlanePlotter, or other compatible programs. +* python/modes_sql.py: SQLite interface for storing reports in a + database. +* python/Quaternion.py: Quaternion library used to calculate + orientation of aircraft for FlightGear plugin.