ogn_client-ruby
OGN broadcasts aircraft positions as APRS/APRS-IS messages. This gem hooks into this stream of data and provides the necessary classes to parse the raw message strings into meaningful objects.
- Homepage: https://github.com/svoop/ogn_client-ruby
- Author: Sven Schwyn
Thank you for supporting free and open-source software by sponsoring on GitHub or on Donorbox. Any gesture is appreciated, from a single Euro for a ☕️ cup of coffee to 🍹 early retirement.
Installation
Security
This gem is cryptographically signed in order to assure it hasn't been tampered with. Unless already done, please add the author's public key as a trusted certificate now:
gem cert --add <(curl -Ls https://raw.github.com/svoop/ogn_client-ruby/master/certs/svoop.pem)
Bundler
Add the following to the Gemfile or gems.rb of your Bundler powered Ruby project:
gem 'ogn_client-ruby', require: 'ogn_client'
And then install the bundle:
bundle install --trust-policy MediumSecurity
Standalone
If you're only going to use the executables:
gem install ogn_client-ruby --trust-policy MediumSecurity
Usage
Subscribe to OGN
Choose a valid callsign and appropriate filters, then start listening to the broadcasted raw messages:
require 'ogn_client'
OGNClient::APRS.start(callsign: "ROCT#{rand(1000)}", filter: 'r/47/2/500') do |aprs|
while raw = aprs.gets
puts raw # do more interesting stuff here
end
end
Parse Raw Message Strings
:point_up: Refer to the wiki for an introduction to OGN flavoured APRS messages.
In the above example, each aprs.gets
returns a raw message string. To decode this string, just pass it to the message parser:
OGNClient::Message.parse(aprs.gets)
:point_up: Raw APRS messages as returned by aprs.gets
are "ASCII-8BIT" encoded and may contain tailing whitespace. The parser removes this whitespace and converts the string to "UTF-8".
The factory method OGNClient::Message.parse
will return one an instance of OGNClient::Sender
, OGNClient::Receiver
, OGNClient::Comment
or raise an error. When this happens, either the message is crippled, the OGN specifications have changed or you have found a bug in the parser code.
In production, you may want to rescue from these errors and ignore the message. You should, however, log the offending messages messages, file a bug and replay them once the bug has been fixed.
:point_up: Raw APRS messages do not contain the date, but assume the current day. This may cause trouble around midnight, however, the parser deals with such edge cases gracefully. Things are a little different when parsing raw APRS messages recorded in the past e.g. with ognlogd
. Since the parser has no means to detect the date the APRS messages have been sent, you have to pass it as an option:
raw_aprs = File.open('2017-06-24.log', &:gets)
OGNClient::Message.parse(raw_aprs, date: '2017-06-24')
OGNClient::SenderBeacon
Sender beacons are usually coming from aircraft equipped with FLARM (anti-collision warning system) or similar devices which broadcast position data as RF beacons.
The data is converted into the metric system since OGN is primarily made for gliders which mostly use the metric system for ground speed, climb rate and so forth.
Attributes:
- callsign - origin callsign
- receiver - receiver callsign
- time - zulu/UTC time with date
- longitude - WGS84 degrees from -180 (W) to 180 (E)
- latitude - WGS84 degrees from -90 (S) to 90 (N)
- altitude - WGS84 meters above mean see level QNH
- heading - degrees from 1 to 360
- ground_speed - kilometers per hour
- sender_type - see SENDER_TYPES
- address_type - see ADDRESS_TYPES
- id - device ID
- stealth_mode - boolean (should always be false)
- no_tracking - boolean
- flight_level - 100 feet QNE
- climb_rate - meters per second
- turn_rate - revolutions per minute
- signal_power - power ratio in dBm
- signal_quality - signal to noise ratio in decibel
- errors - number of CRC errors
- frequency_offset - kilohertz
- gps_accuracy - array [vertical meters, horizontal meters]
- flarm_software_version - version as "major.minor"
- flarm_hardware_version - version as integer
- flarm_id - FLARM device ID
- proximity - array of FLARM device ID tails
OGNClient::ReceiverBeacon
Receivers are little RF boxes which pick up the RF beacons from aircraft and relay them to the OGN servers as messages. They send their own beacons on a regular basis.
Attributes:
- callsign - origin callsign
- receiver - receiver callsign
- time - zulu/UTC time with date
- longitude - WG84 degrees from -180 (W) to 180 (E)
- latitude - WG84 degrees from -90 (S) to 90 (N)
- altitude - WG84 meters above mean sea level QNH
- heading - degrees from 1 to 360
- ground_speed - kilometers per hour
Please note: These receiver beacons contained status information up until version 0.2.5.
OGNClient::ReceiverStatus
Receivers of version 0.2.6 and higher send status messages on a regular basis:
Attributes:
- callsign - origin callsign
- receiver - receiver callsign
- time - zulu/UTC time with date
- version - software version as "major.minor.patch"
- platform - e.g. :arm
- cpu_load - as reported by "uptime"
- cpu_temperature - in degrees celsius
- ram_free - megabytes
- ram_total - megabytes
- ntp_offset - milliseconds
- ntp_correction - parts-per-million
- voltage - board voltage in V
- amperage - board amperage in A
- rf_correction_manual - manual frequency correction as per configuration
- rf_correction_automatic - automatic frequency correction based on GSM
- senders - number of senders received within the last hour
- visible_senders - number of visible senders withint the last hour
- invisible_senders - number of invisible senders ("no-track" on device or "invisible" in database)
- signal_quality - signal-to-noise ratio in decibel
- senders_signal_quality - average signal-to-noise ratio across all senders
- senders_messages - number of messages analyzed to calculate the above
- good_senders_signal_quality - average signal-to-noise ratio in decibel of good senders (transmitting properly) within the last 24 hours
- good_and_bad_senders - number of good and bad senders within the last 24 hours
- good_senders - number of good senders (transmitting properly) within the last 24 hours
- bad_senders - number of bad senders (not transmitting properly) within the last 24 hours
OGNClient::Comment
Comments are sent on a regular basis to keep the connection alive.
Attribute:
- comment - raw message with the comment marker stripped
Errors
The following domain specific errors may be raised:
- OGNClient::MessageError - errors during the parsing of a message
- OGNClient::ReceiverError - errors during the parsing of a receiver message
They all inherit from OGNClient::Error
. An fault-tolerant subscription could therefore look as follows:
require 'ogn_client'
require 'logger'
logger = Logger.new('/tmp/ogn_client.log')
= { callsign: "ROCT#{rand(1000)}", filter: 'r/47/2/500' }
loop do
OGNClient::APRS.start() do |aprs|
while raw = aprs.gets
begin
= OGNClient::Message.parse aprs.gets
rescue OGNClient::Error => error
logger.error error.
next
end
puts .raw # do more interesting stuff here
end
end
end
:point_up: Receiver versions ("major.minor.patch") are will only raise an error when the offending version has a higher major or minor version digit. Patch level differences will only trigger a warning.
Executables
ognlogd
A simple daemon to log raw APRS messages to daily files.
ognlogd --help
ogn2kml and ogn2geojson
Convert raw APRS messages (e.g. from ognlogd
) to KML or GeoJSON.
ogn2kml --help
ogn2geojson --help
Community Support
- Look for developers and users on Gitter.
- Ask your questions on Stackoverflow.
- Annotated source code on omniref
- Bug reports, feature and pull requests are welcome on GitHub.
- Donations are welcome as welll. If you prefer to sponsor a feature, please create an issue on GitHub first and state your intentions.
Development
To install the development dependencies and then run the test suite:
bundle install bundle exec rake # run tests once bundle exec guard # run tests whenever files are modified
The test suite may run against live OGN data if you set the SPEC_SCOPE
environment variable, by default, these tests are skipped.
export SPEC_SCOPE=all
Please submit issues on:
https://github.com/svoop/ogn_client-ruby/issues
To contribute code, fork the project on Github, add your code and submit a pull request:
https://help.github.com/articles/fork-a-repo
Feature Brainstorming
- registration lookups
- configuration option to switch between metric and aeronautical units
- more data sources such as ADS-B
License
The gem is available as open source under the terms of the MIT License.