FlightBox Integration Guide

Byssokol

FlightBox Integration Guide

NOTE: This is a work in progress. If you are an EFB developer, please contact us for assistance.

NMEA Output

FlightBox Autopilot Interface

Overview

The FlightBox NMEA output system allows real-time position and navigation data to be sent over an RS232 serial interface to various aircraft systems including:

  • Autopilots
  • Emergency Location Transmitters
  • Fuel Computers
  • MFDs

The data is transmitted in industry-standard NMEA format at user-selectable baud and refresh rates. The connection is very simple, requiring only a single data line and a ground. Under most circumstances, a single NMEA output can feed multiple systems.

To use the NMEA output, your FlightBox needs to be equipped with an Open Flight Solutions NMEA Serial Output adapter. This $35 device connects to a USB port on the FlightBox.

Open Flight Solutions also offers FlightLink AP, a stand-alone interface for users who don’t need the additional features of FlightBox.

Please Note: If your FlightBox currently has a remote (wired) USB GPS, you will need an inexpensive non-powered USB hub to connect both the GPS and the serial output adapter. If your FlightBox has an internal USB GPS you will need to replace it with a remote USB GPS.

NMEA Sentences

FlightBox can output all of the most commonly used position and navigation sentences. The current list includes:

$GPRMC
$GPRMB
$GPGGA
$GPWPL
$GPRTE

Upcoming additions include:

$GPAPB
$GPBOD
$GPGSA
$GPGSV

 

Operating Modes

By default, FlightBox operates in a basic GPS mode that provides the connected system with location, ground speed, ground track, and altitude (GPRMC and GPGGA).

NAV Mode – If a flight plan is loaded and active, the system can operate in NAV mode, adding waypoint navigation output in the form of the GPRMB message and, optionally, the GPAPB or GPBOD message.

About GPS Mode

Basic GPS mode continuously outputs the standard NMEA messages for position, ground track, ground speed, GPS altitude, and date/time. This information is used by many devices for various purposes. Modern 406 MHz ELTs use the location data to broadcast your coordinates in the event of an emergency. Fuel computers use the ground speed information to calculate range. Autopilots use it to maintain a course.

Basic mode is the default for a FlightBox with an NMEA output adapter connected. As soon as the FlightBox gets an acceptable GPS lock it begins sending out basic data. When not in either of the active modes (NAV, CRS), the system always reverts to basic mode.

 

About NAV Mode

Navigation mode allows an EFB application or EFIS to send a flight plan to the FlightBox. Once loaded and activated, FlightBox will use its WAAS GPS and integrated navigation algorithms to execute the flight plan, sending the appropriate NMEA signals to an autopilot.

Once the flight plan has been sent to FlightBox, it handles everything. The EFB application can monitor the status, but this is optional. If the EFB app is shut down or moved into the background, FlightBox will continue to fly the plan. Status information provided by the FlightBox allows the app to instantly synchronize when it restarts or is moved back into the foreground.

To use this feature you will need an autopilot that can accept navigation data in NMEA format. If you have an older analog autopilot or wing leveler that can accept input from a VOR you can use a converter like the Porcine Systems GPS Smart Coupler to convert the NMEA output into analog CDI signal format.  

 

GPS Roll Steering

While many modern autopilots include GPS steering capabilities, most require an IFR navigator with an ARINC 429 interface to anticipate a turn. To overcome this limitation, the FlightBox navigation system includes an internal GPS steering algorithm. It automatically adjusts the output, allowing the aircraft to intercept a course line and anticipate a turn.

EFB and EFIS Compatibility

Note that NAV output is a new feature for most EFB applications. Open Flight Solutions has created an open specification for loading, activating, monitoring, and adjusting a flight plan. If your favorite EFB application does not currently support the Open Flight Plan Format (OFPF), please  send them a copy of this document. In the interim, you can use our free FlightBox PFD application.

Integration Guide

The following section is intended for developers who wish to add support for the FlightBox navigation capabilities to their applications.

Developer Overview

At its simplest, the NMEA output feature in FlightBox requires nothing more than initial configuration. Once the baud rate has been set, the system will begin sending out basic NMEA data automatically. This is useful, but the power of the FlightBox system comes much more readily apparent when the system is set placed in navigation mode.

Integration with the system is accomplished using a basic HTTP interface (aka “REST”) and, optionally, a WebSocket. The REST interface allows the developer to:

  • Load and activate a flight plan
  • Query the status of the navigation system
  • Select a new active leg / waypoint in the flight plan
  • Cancel and delete the flight plan

The WebSocket allows the application to monitor and synchronize with the FlightBox.

System Mode

The system has two modes: GPS and NAV. The system defaults to GPS mode on boot-up. To use NAV mode, you must load a flight plan using the REST interface.

Status Query

An EFB application or EFIS may query the current navigation status by using the GET method on the /nav/getStatus endpoint. The system will return a status code of 200 (ok) and a JSON structure providing the status information. See below for details on the status data format.

Status WebSocket

FlightBox publishes navigation status information at approximately 1 Hz on a WebSocket. The socket is available at:

ws://{FlightBox IP}/navio

The data sent over the socket is a JSON structure containing the current navigational status. See below for details on the status data format.

Every status message includes:

{
   "Mode": "NAV",
   "ActivePlan": {
       "UUID": "66d704a7-ca85-4bea-807d-f532c89bf596",
       "Course": [
           {
               "ID": "0N0",
               "Type": "apt",
               "Lat": 39.289539,
               "Lon": -94.442493
           },
           {
               "ID": "KLXT",
               "Type": "apt",
               "Lat": 38.959829,
               "Lon": -94.373897
           },
           {
               "ID": "KFLV",
               "Type": "apt",
               "Lat": 39.367928,
               "Lon": -94.914415

           },
           {
               "ID": "0C1",
               "Type": "apt",
               "Lat": 39.487357,
               "Lon": -94.78129
           }
       ],
       "Distance": 64.6355198273975
   },

   "ActiveLeg": {
       "StartId": "0N0",
       "StartPoint": {
           "lat": 39.289539,
           "lng": -94.442493
       },
       "EndId": "KLXT",
       "EndPoint": {
           "lat": 38.959829,
           "lng": -94.373897
       },
       "TotalDistance": 20.05211955290399,
       "DistanceFromStart": 2.299859679737417,
       "DistanceToEnd": 17.757413891287495,
       "BearingToEnd": 170.34569860719085,
       "Active": true,
       "Complete": false,
       "OnCourse": false,
       "XTE": 0.2681899652630914
   },
   "Location": {
       "lat": 39.25141906738281,
       "lng": -94.43768310546875
   },
   "Track": 0,
   "Speed": 0.40500225
}

The top level structure includes:

“Mode” – the current system mode, which is either “GPS” or “NAV”
“ActivePlan” – the currently active flight plan. If no plan is active, this field is null.
“ActiveLeg” – the currently active leg of the flight plan. If no plan is active, this field is null.
“Location” – the aircraft’s current latitude and longitude
“Track” – the aircraft’s current ground track in degrees
“Speed” – the aircraft’s current ground speed in knots

 

The ActivePlan structure includes:

“UUID” – the system-assigned unique identifier for the plan
“Course” – an array containing all waypoints in the plan
“Distance” – the total distance covered by the course, in nautical miles

 

The ActiveLeg structure includes:

“StartId” – the text identifier for the starting waypoint
“StartPoint” – the latitude and longitude of the start point
“EndId” – the text identifier for the ending waypoint
“EndPoint” – the latitude and longitude of the end point
“TotalDistance” – the distance from start to end in nautical miles
“DistanceFromStart” – the aircraft’s current distance from the start waypoint
“DistanceFromEnd” – the aircraft’s current distance from the end waypoint
“BearingToEnd” – the true bearing to the end waypoint
“Active” – the leg is currently active
“Complete” – the leg has been flown
“OnCourse” – the aircraft is currently within 2 nautical miles of the course line and has a ground track that is within +/- 10° of the bearing to the end waypoint
“XTE” – cross track error (distance) in nautical miles

 

Loading A Flight Plan

Flight plan data is passed to a FlightBox over HTTP as a POST message. The URL for the message is:

{
	"course": [
	{
		"ID": "KMCI",
		"Type": "apt",
		"Lat": 39.297612,
		"Lon": -94.715986
	},
	{
		"ID": "KDRO",
		"Type": "apt",
		"Lat": 37.203135,
		"Lon": -107.869215,
	},
	{
		"ID": "KLAX",
		"Type": "apt",
		"Lat": 33.941589,
		"Lon": -118.408530
	}
	]
}

The URL to which this should be posted it:

http://{flightbox IP}/nav/loadFlightPlan

The body of the POST contains the flight plan as a JSON structure. The JSON structure is composed of a KVP, with the key being “flightplan” and the value being an array of waypoints.

Plan Format

{“course”: [{waypoint}, {waypoint}]}

The top JSON structure is made up of a top-level KVP with “course” as the name and an array composed of waypoint objects as the value.

Every waypoint object must include key/value pairs for ID, Type, Lat, and Lon.

The ID value is arbitrary and should be no more than 5 characters. Letters and numbers only. This is typically the FAA or ICAO identifier for system-defined waypoints. For user-defined waypoints you should use something like “WPT1”, “WPT2”, etc.

Waypoints can be of type “APT” (airport), “NAV” (navigation aid), “FIX” (published fix or intersection), or “WPT” (generic / user-defined waypoint). Waypoint type is not used by the navigation functions but can be useful for display.

A flight plan requires at least two waypoints, an origin and a destination. In the case of a “direct-to” plan, the origin waypoint name (wpt) value may be any arbitrary string up to five characters.

 

Invalid Post

When a flight plan is posted, the system attempts to parse the JSON structure. If the system is unable to parse the JSON it responds with a 400 (bad request) response code and a text error string of “Invalid JSON”.

Once the JSON has been parsed, the system validates each of the associated values it contains. If any of these fail the validation, the system will respond with a 400 response code and a text error string describing the issue.

Successful Post

If the JSON is parsed and validated then the system responds with a 200 (ok) response code and a text value containing the unique ID for the plan (UUID). The unique ID is generated by the FlightBox and remains active until the flight plan is completed or cancelled.

The unique ID will be sent in response to any status queries and in any status messages provided by the navigation status web socket. EFB and EFIS applications should compare the unique ID provided with the last unique ID to monitor for changes in the flight plan affected by another EFIS / EFB.

Plan Lifespan

Once loaded, the flight plan remains in memory until completed, cancelled, or the system is rebooted. Flight plans are NOT held across reboots, so in the event that the FlighBox is restarted mid-flight, the EFB will need to re-send the plan once the FlightBox is active.

Plan Activation

Plans are activated automatically upon load. As soon as the plan has been validated and loaded into memory, the system will begin generating NMEA output.

Each time a flight plan is received it is treated as new, even if it is exactly the same as the previous plan. Sending a plan repeatedly is not necessary and is recommended against under most circumstances.

When a valid flight plan is loaded, the system selects an initial leg. Under most circumstances that will be the first leg in the sequence of waypoints provided. In some cases, the system may opt to use a different leg as the initial leg (typically when a plan is loaded mid-flight). It will then execute each additional leg in the plan in order unless it receives a command activating a different leg.

 

Changing The Active Waypoint / Leg

If the user wishes to change the active leg, the EFB or EFIS application may POST to the /nav/activateLeg endpoint, passing the start and end waypoint identifiers using the keys “startpoint” and “endpoint”. (Use standard “x-www-form-urlencoded” format for the post.)

If the waypoint value is recognized as a valid waypoint, the system will respond with 200 (ok). If not, the system will respond with 400 (error).

 

Cancelling The Flight Plan

A plan may be cancelled by posting to the /nav/clearFlightPlan endpoint. This will result in the system reverting to basic mode.

If a plan is active, the system will cancel it and respond with 200 (ok). If not, the system will respond with 400 (error).

 

Arrival At A Waypoint

Under normal circumstances, the system will automatically begin navigating to the next waypoint in a muti-point plan when the aircraft reaches or crosses the current point. Arrival at the point need not be exact – the system deems a leg to be complete when bearing to the waypoint is more than 90° from the current heading.

The exception to this is if the onboard GPS Steering system is enabled. With GPSS enabled, the system uses the ground speed, distance from the waypoint, close rate and cross-track error to anticipate the turn. In this case the FlightBox will execute the turn at the appropriate point to cleanly intercept the course line for the next leg.

NOTE: if your autopilot has integrated GPS steering (also called “roll steering” or simply GPSS) that operates based on RS232 serial input, then you do not want to use the FlightBox GPS steering feature as it will conflict.

 

Arrival At The Destination Endpoint

Once the aircraft arrives at the final waypoint (again, determined by being within one course-width of the waypoint or having passed it) the flight plan will be considered complete and will cease sending navigation messages to the autopilot. At this point the FlightBox NMEA output will revert to basic mode.