This post contains notes on a common and simplified airspace management interface that interacts with services and features offered by UAV service suppliers (USS).

The entry comments how a USS Web-API can be encapsulated in a "driver", and managed by a USS generic client to be replaced, updated or extended by other "drivers" of the same or different provider easily.

This approach adds new use cases related to the management of USS clients and their economy.

Where does the USS client component fit?

As mentioned in the previous post, the NASA-UTM model uses the acronym USS in reference to UAS Service Suppliers. The USS plays the role of main interface among UAS, operators and the rest of actors in the framework.

Although the concept of USS appears directly related to UAS and operators in the architecture, this relationship can be intermediated and decoupled by another components.

In our case, we are interested in having a component that intermediated this relationship in the client part of the service, and adds more functionality than a direct consumption of the USS Web-API.

The AirMap Web-API

Taking a look at the offer of UAV airspace management and USS Web-API it seems that all companies are following a similar approach in terms of product and service development.

The offer usually contemplates different levels of integration and functionality ranging from applications for the main platforms of smartphones, control and tracking dashboards, specific support in terms of flight regulation to real-time data services.

Among these companies, AirMap seems to be one of the suppliers with high visibility in the industry, at least from a technical and tangible point of view. It is one of the few providers that today have an open, functional and operational Web-API available for developers and integrators.

This post uses the AirMap API implementation to explore and conduct how we can integrate with a USS Web-API beyond the particularities and technical details of the particular provider.

The information for development and documentation of the AirMap Web-API is publicly available here. The documentation covers the set of abstractions and model selected by AirMap to represent the flight of a drone.

In detail, AirMap provides multiple APIs grouped into three categories (discover, plan and fly) that span the entire flight lifecycle. Not all APIs are necessary to contemplate a basic flight. Some of them provide added value but they are not fundamental.

There is an API breakdown by category in the following resource. This breakdown is as follows:


  • Map. Visually interact with the airspace on your maps
  • Advisory API. Check weather conditions and airspace advisories
  • Airspace API. View geometries and properties of airspace advisories
  • Ruleset API. Identify rules pertaining to each drone operation


  • Flight plan API. Submit a flight plan with altitude, range, duration, and more
  • Pilot API. Store user preferences and aircraft in a pilot profile
  • Aircraft API. Query details about drone models for easy reference


  • Flight API. Publish flight plans to the platform to receive flight authorization
  • Telemetry API. Maintain positioning and health data with real-time telemetry
  • Traffic alerts API. Receive real-time alerts of nearby manned and unmanned traffic

The use cases that involve AirMap real-time services are interesting to identify the minimum set of APIs to be used, as well as the workflow between the different actions required by the API and dependencies.

Two of these real-time services for which AirMap shares code examples are the case of sending telemetry and reception of traffic alerts.

Phases and activities of the flight

To explore interfaces, responsibilities, behaviors, etc. of the USS client component we need to consider it within a middleware where it plays a very specific role.

In our case we want to implement, as mentioned above, the experience of a complete flight with support for two real-time services during the course of it: send telemetry and receive traffic alerts.

The first thing we can comment on are the categories defined by AirMap. Our model will not consider them as flight categories. Instead, we will use the flight phase concept and will reduce them to three: pre-flight, in-flight and post-flight.

In addition, the activities that take place in each of these phases can be relocated; that is, we are interested in the activities been executed not only in the UAV, but also in a possible cloud backend that allows to control and orchestrate the operations.

Thus the logic of the flight considered from a point of view of activities supported by phase of flight would be the following:

We see that in the case of AirMap we would be using the authorization APIs, pilot, plan, telemetry, traffic alerts, etc.

The figure also illustrates the dependencies between these activities. For AirMap, the activities or tasks that are executed in pre-flight are sequential and each activity usually needs information obtained in the execution of the previous activity. For example, the creation of a flight plan returns the flight identifier, which is used to "create" a flight on the backend in the subsequent activity.

The activities contained in pre-flight and post-flight are considered sequential. Any error in them would stop the process.

We would be interested in having these errors recorded and notified appropriately. In practice, it can be considered that any error coming from the authentication, flight plan, etc. it is managed and validated in the backend by another component or operator; and the UAV "loads" valid information when these phases are executed.

The in-flight activities have a different nature. They can be executed simultaneously and/or parallelized; and they require, in general, to send or receive data regularly according to time thresholds. These activities are associated with a specific flight and, therefore, may also require information that comes from an pre-flight activity.

The in-flight activities, although associated with the same flight, are independent services. This allows us at the level of management, error, etc. 'suspend/resume/cancel' any of them.

Finally, we have the post-flight activities. The diagram only includes the activity 'End flight' that indicates the end of flight and, therefore, the destruction of the flight in the AirMap backend. Other complementary activities may make sense in this phase, such as cleaning and uploading the activity record of the component itself to our cloud backend, etc.

The role of our cloud backend and USS communications

Once the flight activities have been reviewed, we can move on to the different scenarios that we would like to support, based on the fact that the AirMap API documentation contemplates a basic integration "UAV - USS provider" only.

In this scenario it is implicitly assumed that the USS client runs in the UAV, reports telemetry to a single USS backend and consumes traffic alerts sent.

On the other side, we also want to support more complex communication scenarios. Specifically, we want to include our own backend that provides control and management services for a possible drone fleet.

Thus, the first possible scenario is defined by the active links '1' and '2' where our backend manages and controls one or several UAVs that can report telemetry or consume traffic alerts from one or several USS.

Another possible scenario is that of the active links '1' and '3'. Here our backend manages and controls one or several UAVs that report telemetry to the backend itself, and it is our backend that sends the telemetry of each of the UAVs to the different USS. It also receives traffic alerts to be sent to each of the UAVs.

The link '2' represents an interesting case, it is a possible fall-back scenario when the UAVs can not reach our backend, or when the backend can not connect to the USS; in this case the telemetry and alerts are carried out through this link. This scenario coincides with the original starting scenario in which a UAV communicates directly with a USS.

With these scenarios in mind decoupling the USS client logic from vehicles is an alternative, where we transfer the responsibility and challenges of USS communications of vehicles to our cloud backend.

The USS client

The following piece of code comes from one of the examples of the AirMap documentation written in Java for the Android platform.

AirMapFlightPlan flightPlan = new AirMapFlightPlan();

It is code that encapsulates the concept of "flight plan" for the Web-API. The code creates this object and configures it appropriately with a total of eight method calls that receive different variables with the appropriate values.

This implementation will work with the AirMap API only. In our case, this type of code is encapsulated within a specific client of AirMap that interacts with the Web-API of AirMap directly in what we call an 'AirMap USS driver'

A USS driver can be instantiated through a factory pattern by its name, next to a configuration object that contains the information that the 'driver' will need. This Python code instances a USS client together with an AirMap USS driver:

from ussreporter.client import USSClient
from ussreporter.client import IPCManager
from ussreporter.client_except import USSClientException

conf = { 'api_key' : 'api_key_val',
         'user_id' : 'user_id_val',
         'flight_plan' : {
         'takeoff_latitude'  : 33.85505651142062,
         'takeoff_longitude' : -118.37099075317383,
         'pilot_id '  :  None,
         'start_time' : 'now',
         'end_time'   : 'now',
         'max_altitude_agl' : 100,
         'buffer' : 1,
         'geometry': { 'type': 'Polygon',
                       'coordinates': [
                            [ [ -118.37099075317383, 33.85505651142062  ],
                              [ -118.37305068969727, 33.85502978214579  ],
                              [ -118.37347984313963, 33.854673391015496 ],
                              [ -118.37306141853333, 33.85231226221667  ],
                              [ -118.37193489074707, 33.85174201755203  ],
                              [ -118.36997151374815, 33.85176874785573  ],
                              [ -118.36995005607605, 33.8528112231754   ],
                              [ -118.37099075317383, 33.85505651142062  ] ]]


   cid = 'client_id'

   uss = USSClient.get_uss_by_name('AirMap', conf, client_id=cid)

   fp = uss.get_flight_phases()


   ipcm = IPCManager(cid)

   uss.run_flight_phase(fp[1], manager=ipcm)


except USSClientException as e:

except Exception as e:

The code uses the concept of flight phase as main abstraction. Internally, the driver implementation knows which activities belong to each phase, stores the configuration, maintains the status and communicates with the USS backend directly.

The whole USS client runs on a single thread within a process. The in-flight activities are coroutines that work cooperatively throughout this phase.

The I/O of the driver also requires some type of communication mechanism between processes. In our implementation the I/O is carried out through a software bus and the USS driver accesses it through an IPCManager object.

All errors for any USS client at this level can be captured in a generic way through the USSClientException.

To obtain more detailed information about the error, and even manage it, we can capture exceptions derived from this class. In the AirMap case, the exception available to capture would be AirMapUSSClientException.

The USS client controller

The USS client controller contains the management and driving logic of the USS clients.

In order to launch one or several USS clients through the factory, the controller receives the necessary information through the C&C bus in the form of an event. This event contains the client and driver identifiers as well as the driver's own configuration.

The controller then creates a new thread that it uses to launch the USS client as a new process on which it sleeps. The thread is also used as a signaling mechanism to know the termination, abrupt or not, of the process.

For the synchronization with the flight phases, events are also used in the C&C bus that signal the beginning of each one of the flight phases (pre-flight, in-flight, post-flight)

The controller manages the different USS clients through their identifiers. The test cases implemented allow to launch and cancel a USS client; as well as suspend, resume or cancel both telemetry activities and traffic alerts independently.

There is also the action of forcing a client to finish and release their resources in a controlled manner.

The controller also supports a shell that serves as an interface between an operator and the bus. The shell allows writing and reading events on the C&C bus as well as the management of the different USS clients manually.

Wrapping up

As reviewed in the previous entry, there are several collaborative efforts to develop the concept of UTM between the public and private sectors.

Two of the most interesting initiatives at present are NASA-UTM and U-SPACE, for which ambitious roadmaps have been defined. Both projects are in exploratory and testing phases with the intention of carrying out controlled and incremental deployments over the next few years.

Among the participants and collaborators of these projects are those known as airspace management providers, which are expected to constitute a federated network of service providers, to which a drone can be connected to consume different services and digital products (tracking, traffic alerts, flight permits, pilot identification, etc.)

Throughout this entry we refer to these providers as UAV Service Suppliers (USS)

This entry develops a USS client in Python for a full flight with support for two fundamental services: telemetry and traffic alerts. The proof of concept is based on the services offered by AirMap, one of the few USS that currently has a public and documented Web-API available for developers and integrators.

On top of the basic functionality of the client, new capabilities are added to manage and consume the services offered at the USS level independently of a specific provider. This provides an abstract control of the flight cycle at the system level, and a degree of control at the finest service level provided by the provider through a "driver".

The latter provides great flexibility in service consumption. Scenarios are thus created in which the core of the USS client does not have to be running in a specific vehicle and may be doing it from the cloud backend. This has numerous advantages in managing and controlling the traffic of a fleet of UAVs for example.

The ability to run several USS clients coordinated in parallel under a simple and common interface also allows to switch between different USS or consume specific services from one or the other provider according to certain criteria (technical, economic, etc.)

From a point of view of economic growth and social benefits, a more flexible design in the USS client and the controller have a market impact in aspects such as provider lock-in and switching-costs in UAV companies. Having the possibility to change the USS provider at any time, within a future federated network of suppliers, should also contribute to a more competitive market.

Given the early phase in which we find ourselves in the two main UTM projects and the lack of providers that provide open and documented Web-APIs, the focus with this post remained on the concept of abstract USS client, USS client "driver", USS client controller and integration with a generic software bus in a test environment.

Features such as reporting to the bus instead of a file, testing support, etc. were not implemented.

Fault tolerance for continuous service or the ability to update a USS client during the flight, in whole or in part, are viable and interesting use cases.


comments powered by Disqus

Recent Entries