vatbook - Ruby API

Another gem release: vatbook is Ruby API to the Vatbook service for reading and parsing Vatsim pilot and ATC bookings. Booking query requests are made by FIR and individual bookings are returned as objects, exposing a rich set of attributes. Supports excluding enroute pilot bookings. Supports pulling pilot and atc bookings separately or as a combined hash.

Usage

This gem provides one public method: vatbook, which can be applied to any string (or variable containing a string) representing a full or partial FIR ICAO code.

For example if you want to retrieve all active stations (ATC positions and pilots) for Bosnia-Herzegovina FIR (ICAO: LQSB), then you can use:

# Attaching the method directly to a string:
"LQSB".vatbook

# Attaching the method to a variable containing a string:
fir = "LQSB"
fir.vatbook

Anatomy of method returns

The vatbook method returns a hash of 2 elements: 1) the matching atc bookings, 2) all matching pilots bookings. Each of those is an array, cosnsisting of station objects. Each of these objects includes a number of attributes:

fir.vatbook # => {:atc => [a1, a2, a3 ...], :pilots => [p1, p2, p3, p4 ...]}

fir.vatbook[:atc] #=> [a1, a2, a3 ...]
fir.vatbook[:pilots] #=> [p1, p2, p3 ...]

fir.vatbook[:atc].first #=> a1
fir.vatbook[:pilots].first #=> p1

a1.callsign #=> "LQSA_APP"
a1.name #=> "Svilen Vassilev"
a1.cid #=> "1175035"
a1.start #=> "2012-10-08 08:00:00"
a1.end #=> "2012-10-08 10:00:00"

...

p1.callsign #=> "ACH217S"
p1.name #=> "Dragomir Andonovic"
p1.cid #=> "931960"
p1.dep #=> "LQSA"
p1.arr #=> "LDSP"
p1.route #=> "VRANA L5 KENEM"
p1.aircraft #=> "AT72"
...

Station attributes

Here's a complete list of the station object attributes that can be accessed:

Common attributes for atc and pilots:

• cid (VATSIM ID)
• callsign
• name
• role (atc or pilot)
• fir (the FIR ICAO used in the request)
• start (planned start time)
• end (planned end time)

Pilot specific attributes

• dep (planned departure airport)
• arr (planned destination airport)
• route (planned route)
• aircraft (planned aircraft type)
• enroute (boolean, whether or not the flight is enroute for the FIR)

Customizing the request

The vatbook method can be customized by passing in a hash-style collection of arguments. The currently supported arguments and their defaults are:

:enroute => true     # Possible values: true, false. Default: true

The :enroute => false option can be used to exclude all booked flights that
are enroute for the selected FIR, i.e. don't originate or end on one of the FIR's
airports. Example:

# Lets exclude all enroute pilot bookings for LQSB FIR and only display bookings
# that are outbound/inbound one of Bosnia-Herzegovina airports:

"LQSB".vatbook(:enroute => false) #=> [pilot1, pilot2, pilot3...]

Download links

As usual the compiled gem is available via rubygems and the source code and documentation are on github.

vACCBiH sector files for Euroscope and VRC

This bit concerns flight simulation and ATC services on the vatsim network.

I have released new and up-to-date packages of sector/ese/pof files for Bosnia-Herzegovina FIR (LQSB) for both popular ATC clients: Euroscope and VRC. Previous available renditions are now several years old and contain multiple inaccuracies regarding airspace, ground layouts, station information. Furthermore this is the first native Euroscope package for LQSB.

In line with the client capabilities, the Euroscope version is much more advanced and is the master version. The VRC version is a stripped down replica adjusted for VRC compatibility and limitations.

Both packages are periodically updated to include new data whenever there are AIRAC changes.

The files are publicly available on Github; pull requests welcome!

Download links

vACCBiH sector files for Euroscope
vACCBiH sector files for VRC

Auto-resizing Page Elements With Jquery Mobile

If you’ve been using jQuery Mobile from the start or if you’re just beginning to play with it (beta 3 is current at the time of this writing) you might have noticed that in recent versions auto-resizing of page elements does not work for all devices out of the box and this was not the case in earlier versions. The answer is simple, but not well documented (if at all): you need to add the viewport meta tag in your layout:

<meta name="viewport" content="width=device-width, initial-scale=1">

Cloning Remote Branches With Git

After cloning locally a remote git project with multiple branches, you will only get the default project branch, typically master. At this point executing git branch will show you the locally available branches in your repository:

    $ git branch
    * master

However if you add the -a option to git branch you’ll get a list, which also includes all the available remote branches, like this:

    $ git branch -a
    * master
     origin/HEAD
     origin/master
     origin/source
     origin/foobar

Using this list as a reference, we can now create a local tracking branch to work on, for example:

    git checkout -b source origin/source

The source branch will now be checked out and available locally, which we can see by running git branch once again:

    $ git branch
    master
    * source

That’s it! There’s also the git pull --all command which will fetch all the remote branches that have been tracked locally, however it will not create local tracking branches. There is no git native way of automatically creating local tacking branches of all remotes and this is perhaps not a good idea anyway, as they can get stale rather quick.

Latest gem updates

I made a few updates to some of my gems recently and here's a brief overview:

vatsim_online

The vatsim_online gem received some new atributes to the Station class:

• planned_altitude (or FL)
• transponder
• heading
• qnh_in (set QNH in inches Hg)
• qnh_mb (set QNH in milibars/hectopascals)
• flight_type (I for IFR, V for VFR, etc)
• cid
• latitude_humanized (e.g. N44.09780)
• longitude_humanized (e.g. W58.41483)

More importantly, this library now plays nicely with gcmapper. A new attribute is provided for the pilot stations: .gcmap which returns a great circle map image url, depicting the GC route of the aircraft, its origin and destination, its current position on the route, together with its current altitude and groundspeed.

Here's an example:

icao.vatsim_online[:pilots].first.gcmap #=> image url of the map

vatsim_online on rubygems.org

gcmapper

The gcmapper gem is updated for compatibility with vatsim_online. No user-facing changes here.

gcmapper on rubygems.org

airdata

The airdata Rails engine now includes default ordering for all 3 classes. Airports and waypoints are sorted alphabetically i.e. ordered by id, and the runways are ordered by their airport_id. Remember you can always override the default ordering by using Active Record's .reorder method

airdata on rubygems.org

Rails Installer minor update

I made a few minor changes to my Rails Installer script, most notably the install flows via curl and wget are simplified and reduced to one-liners, easy to copy and paste, but not very good looking (alas, that's shell, not Ruby):

# via `curl`
curl -L https://github.com/tarakanbg/railsinstaller/raw/master/ruby.sh > ruby.sh; chmod +x ruby.sh; ./ruby.sh; rm ruby.sh


# via `wget`
wget --no-check-certificate https://github.com/tarakanbg/railsinstaller/raw/master/ruby.sh -O - > ruby.sh; chmod +x ruby.sh; ./ruby.sh; rm ruby.sh

Of course it would be much cleaner to just pipe the downloaded buffer through sh like this:

curl -L https://github.com/tarakanbg/railsinstaller/raw/master/ruby.sh | sh

Unfortunately in that case the script won't wait for user input, so I opted for the verbose option.

Additionally RailsInstaller is now tested and (expectedly) compatible with Linux Mint 13 (Maya). Yes, I joined the growing ranks of Unity refugees :).

notams gem updated

Update released for the notams gem, completely refactoring the code into classes for flexibility and adding customization options.

The .notams method can now be customized by passing an optional hash of arguments.

The :objects => true option will cause the .notams method to return an array of notam objects instead of strings. Thus each notam is parsed and encapuslated in an instance of the Notam class and exposes a number of attributes:

icao = "lqsa"
icao.notams(:objects => true) # => returns an array of notam objects

notam = icao.notams.first # => returns the first notam as an object

# Notam object attributes

notam.raw       # => returns the raw (unprocessed) notam as a string
notam.icao      # => returns the icao code of the airport or area, covered by the notam;
                #    useful when iterating over multiple notams, covering a collection of airports or areas
notam.message   # => returns the actual information message of the notam as a string

airdata: rails engine for adding aviation navdata

Another gem release, and this time it's a rails engine, so it requires a rails application: airdata

It's a Rails engine for adding aviation related models and data to a web application.

It will add 3 Active Record models to your rails application: Airports, Runways and Waypoints (including navaids). It will add the corresponding database structure (migrations) and finally it will populate the corresponding tables of your database with [data](#data-stats) (currently based on AIRAC cycle 1208, but the data is updateable and the gem provides the tools to do so).

Installation within parent app

Add this gem AND the activerecord-import your application's Gemfile:

gem 'airdata'
gem "activerecord-import", "~> 0.2.9"  # Required for the data injection

And then execute:

$ bundle

Run the following commands in your app directory:

rake airdata:install:migrations
rake db:migrate
rake airdata:setup

Updating the data

You can get information about your currently installed AIRAC cycle and the latest available one by running:

rake airdata:cycle  # =>

  Currently instaled AIRAC cycle: 1208
  Latest available AIRAC cycle: 1208

  No update is necessary!

# Or if there's a newer verion available:
rake airdata:cycle  # =>

  There's a newer cycle available.
  You can update by running: rake airdata:update

If you want to do a data update to a newer AIRAC cycle, run the following rake task for clearing up the old data and re-injecting the current one:

rake airdata:update

Data stats

• Airports: 10775
• Runways: 28977
• Navaids: 16300

• Waypoints: 214400

• Total DB records: 270472

All data is derrived and compiled from public sources such as: OurAirports and OpenFlights

Lib classes

2 classes handle the heavy lifting of downloading, parsing and injecting the data within you local database: Airdata::DataDownloader and Airdata::DataInjector. Generally you won't need to deal with them directly. All the functionality you need to install is triggered via rake tasks and almost nothing there is considered public API, apart from the following public class methods:

  # Returns the currently installed AIRAC cycle:
  Airdata::DataDownloader.cycle # => 1206

  # Returns the latest available for download AIRAC cycle:
  Airdata::DataDownloader.latest_cycle # => 1208

Models and their attributes

These AR models and attribute sets will be available in your parent app, namespaced within the Airdata module and accessible like this:

 Airdata::Airports
 Airdata::Runways
 Airdata::Waypoints

Currently there are no special public methods/APIs available for these models,
the engine is tailored primarily for data storage and access.

Airports

Includes one-to-many association with the Runways class.

attr_accessible :elevation, :icao, :lat, :lon, :msa, :name, :ta

has_many :runways, :dependent => :destroy

• ICAO
• Name (city)
• Latitude
• Longitude
• Elevation
• Transition altitude
• Minimum safe altitude

Runways

Includes one-to-many association with the Airports models.

attr_accessible :airport_id, :course, :elevation, :glidepath, :ils, :ils_fac
attr_accessible :ils_freq, :lat, :length, :lon, :number

belongs_to :airport

• airport_id (association)
• number
• course
• elevation
• glidepath angle
• ILS (boolean)
• ILS final approach course
• ILS frequency
• latitude on the threshold
• longitude on the threshold
• length

Waypoints (includes Navaids)

Regular waypoints only include :ident, :lat, :lon, :country_code. The rest is for navaids.

attr_accessible :country_code, :elevation, :freq, :ident, :lat, :lon, :name, :range

• ident
• name
• frequency
• country code
• elevation
• latitude
• longitude
• range (in MSFS)

Rake tasks

Here's a lisk of all rake tasks that this gem adds:

rake airdata:install:migrations  # Copy migrations from airdata to application.
                                 # This is part of the initial install process.
rake airdata:setup               # Downloads and installs the latest navdata
rake airdata:cycle               # Compares your currently installed AIRAC cycle
                                 # agianst the latest available
rake airdata:truncate            # Truncate navadata tables, populated by Airdata.
                                 # Generally you don't need to run this separately,
                                 # it's automatically called during data updates
rake airdata:update              # Removes old Airdata and installs latest available
                                 # Essentially it runs the truncate task followed by the setup

Download

As always the packaged gem is available on rubygems and the source and documentation are on github.

vatsim_online updates

vatsim_online gem has been updated twice with new features and API changes, I apologize for the inconvenience to the early adopters. Here's the changelog:

v. 0.3 - 22 July 2012

• The hash returned by the vatsim_online method now includes 2 new arrays: arrivals and departures. These two are returned separately for convenience, in case you want to loop through them separately. The pilots array return is unchanged and contains all arrivals and departures.
• New station attributes: latitude, longitude
• Improved UTF-8 conversion process

So the method return now looks like this:

icao.vatsim_online # => {:atc => [a1, a2, a3 ...], :pilots => [p1, p2, p3, p4 ...],
                   #    :departures => [p1, p4 ...], :arrivals => [p2, p3...]}

icao.vatsim_online[:atc] #=> [a1, a2, a3 ...]
icao.vatsim_online[:pilots] #=> [p1, p2, p3 ...]
icao.vatsim_online[:departures] #=> [p1, p3 ...]
icao.vatsim_online[:arrivals] #=> [p2, p4 ...]

icao.vatsim_online[:atc].first #=> a1
icao.vatsim_online[:pilots].first #=> p1

a1.callsign #=> "LQSA_TWR"
a1.frequency #=> "118.25"
a1.name #=> "Svilen Vassilev"
...

p1.callsign #=> "ACH217S"
p1.departure #=> "LQSA"
p1.destination #=> "LDSP"
p1.remarks #=> "/V/ RMK/CHARTS"
...

v. 0.2 - 21 July 2012

• Station attribute departure is now renamed to origin
• UTF-8 is now enforced for all local caching and file/string manipulations, the original Vatsim data is re-encoded
• Station ATIS is now cleaned of invalid and obscure characters
• Improved documentation

vatsim_online: ruby gem for retrieving, parsing and displaying vatsim online stations data

Another aviation/simulation related library: vatsim_online: a Ruby gem for selectively pulling, parsing and displaying Vatsim online stations data. Essentially it's a "Who's online" library, capable of displaying online ATC and/or pilots for given airports, areas or globally. Stations are returned as objects, exposing a rich set of attributes. Vatsim data is pulled on preset intervals and cached locally to avoid flooding the servers.

A quote from the documentation:

This gem provides one public method: vatsim_online, which can be applied to any string (or variable containing a string) representing a full or partial ICAO code. The provided ICAO code or fragment will be used as a search criteria and
matched against the current vatsim data.

The vatsim_online method returns a hash of 2 elements: the matching atc stations and pilots stations. Each of those is an array, cosnsisting of station objects. Each of these objects includes a number of attributes:

icao.vatsim_online # => {:atc => [a1, a2, a3 ...], :pilots => [p1, p2, p3 ...]}

icao.vatsim_online[:atc] #=> [a1, a2, a3 ...]
icao.vatsim_online[:pilots] #=> [p1, p2, p3 ...]

icao.vatsim_online[:atc].first #=> a1
icao.vatsim_online[:pilots].first #=> p1

a1.callsign #=> "LQSA_TWR"
a1.frequency #=> "118.25"
a1.name #=> "Svilen Vassilev"
...

p1.callsign #=> "ACH217S"
p1.departure #=> "LQSA"
p1.destination #=> "LDSP"
p1.remarks #=> "/V/ RMK/CHARTS"
...

The vatsim online method can be customized by passing in a hash-style collection of arguments. The currently supported arguments and their defaults are:

• :atc => true (Possible values: true, false. Default value: true)
• :pilots => true (Possible values: true, false. Default value: true)

Both options can be used to exclude all ATC or pilots stations respectively from the request, in order to speed it up and avoid processing useless data.

Examples:

# Lets exclude all ATC from our request and get the pilots only
"LO".vatsim_online(:atc => false)[:pilots] #=> [p1, p2, p3...]

# Lets exclude all pilots from our request and get the ATC only
"LO".vatsim_online(:pilots => false)[:atc] #=> [a1, a2, a3...]

"LO".vatsim_online(:atc => false)[:pilots].first.callsign #=> "ACH0838"
"LO".vatsim_online(:pilots => false)[:atc].first.callsign #=> "LOVV_CTR"

Notes

• Vatsim status and data files are cached locally to reduce the load on vatsim servers. Random server is chosen to retrieve the data each time. By default the status file is updated once every 4 hours and the data file once every 3 minutes regardless of the number of incoming requests.
• The data is cached in your default TEMP directory (OS specific)
• All the data retrieval and caching logic is encapsulated in a separate class VatsimTools::DataDownloader which can be mixed in other applications and libraries too.
• The ICAO string used as a search criteria is not case sensitive
• Pilot stations returned are based on origin and destination airports, the current algorithm does not evaluate enroute flights.

Example of Ruby on Rails implementation

Finally, here's a possible scenario of using this gem in a Ruby on Rails application.
Verbosity is kept on purpose for clarity.

In your controller:

def index
  # We want to retrieve all Austrian online stations (ATC and pilots)
  icao = "LO"
  stations = icao.vatsim_online

  # Now we will assign the ATCs and the pilots to separate instance variables,
  # to be able to loop through them separately in the view
  @atc = stations[:atc]
  @pilots = stations[:pilots]
end

In your view (HAML is used for clarity):

- for atc in @atc
  %li
    = atc.callsign
    = atc.frequency
    = atc.rating
    = atc.name
    = atc.atis

- for pilot in @pilots
  %li
    = pilot.callsign
    = pilot.name
    = pilot.origin
    = pilot.destination
    = pilot.route
    = pilot.altitude
    = pilot.groundspeed
    = pilot.remarks

As always, the packaged gem is available on rubygems and the source code and documentation are on github.