iridium-toolkit decodes Iridium satellite frames from raw bits

The chain starts outside this repository

The important constraint is stated in a warning at the top of the documentation, and it determines who this project is for. To use these tools you need raw iridium frames as received or extracted by iridium-extractor from the gr-iridium OOT gnuradio module. In other words, the toolkit starts at the point where a receiver chain has already demodulated the signal and produced a bit stream. The toolkit does not contain the radio, the antenna, the demodulator or the frame synchroniser. That is a large and deliberate scope decision, and it makes the project a companion to gr-iridium rather than a standalone receiver. The upstream gr-iridium module lives in a separate repository under the same organisation, and the toolkit repository is the part that works on the output. For someone who wants to see what an Iridium satellite is carrying, the practical sequence is a working receive setup, the extractor writing a .bits file, and then the parser and reassembler in this repository.

The parser turns bits into a line-based format

iridium-parser.py is the main tool, and it parses raw iridium bits into an ascii line-based representation of the information contained in each frame, with the output format described in a separate FORMAT.md document. The usage line is short, and it reads from a file or from stdin when no input file is given.

    iridium-parser.py [--options] in.bits > out.parsed

Two input conveniences are worth knowing. Files with the extensions .xz, .bz2 and .gz are decompressed automatically, which matters because captures of a downlink are large and compressing them before storage is the normal thing to do. Output goes to stdout, and the documentation shows the working example as a two step flow where the extractor output has been written to output.bits and is then decoded.

    python3 iridium-parser.py -p output.bits

If that step is slow, the documentation notes you can install pypy and run the same command under it for roughly a fifty percent speedup, which is a large change in iteration time when you are working through a long capture.

    pypy3 iridium-parser.py -p output.bits

The filter and format flags are how you work through a capture

The parser's most useful options are the ones that let you work on a subset of a capture rather than dumping everything. A filter option processes only lines matching a filter, and the documentation points out that this will run faster than grepping the output afterwards. The parameter is a classname with an optional attribute and an optional check, and two examples are given. One selects only IRA messages with an altitude above 100, and the other selects only IBC messages carrying iridium timestamps. A format option then outputs the specified fields, space separated, and is usually used together with a filter.

The documentation also shows how fields are named in that expression, with a list of five of them: globaltime, iri_time_ux, slot, sv_id and beam_id. A channelize option replaces the frequency field with a subband and frequency access pair, and the documentation gives the arithmetic to invert it, with the frequency equal to 1615604164 plus (FA plus 8 times SB) times 41667 plus the offset. That formula is worth writing down, because it converts a human readable channel label back into the raw number. The output option defaults to line and also accepts err, sat, plot and rxstats, and a plot option builds a two dimensional plot of numeric fields while honouring the filter.

Error handling options, and the SigMF annotation path

Because a demodulated capture contains noise, the parser's error options determine what you see. A good option outputs only lines with a confidence of at least ninety, and a confidence option takes a threshold of your choosing. An errorfree option keeps only lines without uncorrectable errors, and a perfect option keeps only lines with no errors at all, uncorrectable or correctable. An errorfile option diverts lines with uncorrectable errors into a separate file, and if you do not name a file it is generated from the input filename, which is a detail that saves time when you are running over a directory of captures. An errorstats option prints error statistics to stderr at the end of the output, and a stats option enables incremental statistics output to stderr so you can watch the parse progress.

The two options that cost time are the ones that buy accuracy. Enabling error correction in the uniq word increases processing time, and the harder option tries to decode packets with correctable bit errors at the beginning, which significantly increases processing time. The disable-freqclass option disables an optimisation in parsing simplex and duplex packets, and the documentation says it will increase processing time but may improve parsing if the frequencies in your bits file are incorrect. For a researcher whose frequency table is slightly wrong, that option is the difference between a parse and no parse.

There is also a SigMF annotation path, where a sigmf-annotate switch rewrites the sigmf-meta file to include annotations for all input bits, recording the iridium frame type or the reason why parsing failed, and including the debug id from the .bits file so a specific frame can be identified. Normal parser output is suppressed when that switch is used, and the annotated recording can be viewed in inspectrum for visual inspection of the signals. The documentation also lists two options under a heading of broken or undocumented, satclass and voice-dump, which is an honest label.

The reassembler builds higher level protocols back up

reassembler.py is the second stage, and it reconstructs higher level information from the parsed output. The modes are chosen with the -m option, and the list is long enough to show the scope of the project. The ida mode outputs Um Layer 3 messages as hex, and idapp does the same with light parsing and pretty printing. The lap mode outputs GSM compatible L3 messages as a GSMtap compatible .pcap file, which is the one that gets you into general purpose network analysis tooling. The page mode handles paging requests on the Ring Alert Channel, and msg handles pager messages. The burst mode assembles Global Data Burst messages out of pager messages, and sbd handles Short Burst Data messages, with acars giving parsed ACARS SBD messages on top. The ppm mode estimates the receiving SDR's frequency offset in parts per million, which is a practical tool for anyone whose demodulator is drifting.

There are also two live modes. The live-stats mode produces per ten minute statistics of received packet type in graphite format, and live-map maintains a sats.json file for an interactive satellite display. A satmap mode tries to map iridium satellite IDs to NORAD approved names, and it needs an appropriate TLE file placed at tracking/iridium-NEXT.tle. The usage line takes an input file and a mode.

    reassembler.py -i output.parsed -m <mode>

The documentation's worked example runs the idapp mode over output.parsed, and the acars mode with a nopings argument.

The supporting scripts, and the warning attached to them

The top level of the repository holds a wide set of scripts, and the documentation attaches an explicit warning to the ones outside the two main tools. It says these tools are not the main focus of this repository and may not be working out of the box for you. That warning applies to a substantial part of the tree. There are voice and data processing scripts such as play-iridium-ambe, play-iridium-vod, voc-cluster.py, vod-cluster.py and vod-stitcher.py, plus an ambe_emu directory and a nal-shout directory. There is positioning work in pseudoranging.py, ibc_position_interpolator.py, interp_circ.py and locator.py, and analysis helpers such as stats-parsed, stats-voc.py, stats.py, beam-plotter.py, beam-reception-plotter.py and bits_to_dfs.py. A pseudo-random sequence and coding toolkit sits in its own files, with bch.py, fec.py, rs.py, rs6.py, reedsolo.py and reedsolo6.py, and there is a 9601 directory, an iridium.txt data file, a meta-manager script, an mkkml script, an rtl-sdr directory, and directories named unmaintained_tools, check-sample, check-sample-vod, doc, html, tracking and tests. The licensing is worth noting separately, since it is stated with a caveat: unless otherwise noted in a file, everything is copyright Sec and schneider and licensed under the 2-Clause BSD License.

Legacy extractor code, and the dependencies that gate features

There is a legacy frame extraction implementation in the extractor-python subdirectory, and the documentation is blunt about it. It is a python2 implementation, it is no longer maintained since 2017, and you should use it at your own risk. It is kept as reference code, which is the honest framing, since the current extraction path is the gr-iridium module that lives in the other repository.

The runtime requirements are light. Python 3.7 or newer is required, with the note that it may work with older 3.x but that this is untested, and crcmod is the one other required module. The optional modules gate specific features rather than the whole toolkit. NumPy is for the reassembler, matplotlib is for the plot option and others, and astropy, skyfield, pymap3d and pyproj are listed for the position related work. Understanding which module gates which feature is the difference between a tool that runs on first try and one that fails on a missing import halfway through a long parse. The project also publishes a separate document set covering the format and the extension, including FORMAT.md, a doc directory, and a website directory, and the repository carries a .github directory for its automation.

Editorial conclusion

Adopt iridium-toolkit if you already capture Iridium downlink frames with a software defined radio and want to read what is in them, because the parser and reassembler together cover a lot of protocol layers that would otherwise mean writing your own. Do not adopt it as a communication tool, because it starts from demodulated bits rather than a radio and a receiver chain, and it does not transmit. Verify two things before you plan an afternoon with it: that your input really comes from the gr-iridium extractor rather than from a demodulator that produces a different bit format, since the parser is written against that extractor's output, and that the optional Python modules you need are installed, because NumPy, matplotlib, astropy, skyfield, pymap3d and pyproj each gate specific features. The practical first step is to run iridium-parser.py against a .bits file and read the output, then run reassembler.py with the help mode to see which reassembly modes are available.

Frequently asked questions

Official sources

1. Issues
2. muccc/iridium-toolkit on GitHub
3. README