ANVEL Application Programming Interface

From ANVEL Wiki
Jump to: navigation, search


The External Application Programming Interface (External API) allows users to interact with and control ANVEL simulations with an exposed set of functions with many different programming languages. ANVEL utilizes the Thrift framework because Thrift supports scalable cross-language services development.

Thrift uses an Interface Definition Language (IDL) file to create bindings (language specific functionality) for C++, C#, Java, Python, PHP, TypeScript/JavaScript (both client-side in a browser and server-side with Node.js) and several other languages. ANVEL Core is written in C++, but Thrift allows users to use the External API in any language that Thrift supports.

The services exposed through the External API are also available through the web server.

Note: While Python is supported through the External API via Thrift generated Python bindings, this is distinctly different from ANVEL's built-in Python interpreter.

The External API balances functionality and ease-of-use to facilitate the development of third party applications that use ANVEL. The External API allows users to easily:

  • Load environments, save simulations, create objects, and initialize properties for every object in the simulation
  • Start, step, and pause the simulation timer with a choice of timing modes, including synchronized step and real-time simulation
  • Query and manipulate object properties
  • Query vehicle dynamics parameters and set control inputs
  • Retrieve lidar, camera, and sensor data

How it Works

The External API consists of multiple components spanning the interface between a remote application and ANVEL.

An IDL file provides a clear description of the External API's capabilities by defining:

The IDL file forms the basic contract for the ANVEL interface and is independent of the specific language used for the remote application.

Language-specific software for adapting each of the supported languages to the IDL runs locally on the remote application's side of the interface and is automatically generated by Thrift based on the IDL file. Depending on the language, the generated software takes the form of compiled/interpreted libraries or source code. The appropriate language folder(s) within the standard External API directory must be included in the remote application build project or path as required for the language. If the application will run on a host other than ANVEL, the language-specific software may need to be copied from the ANVEL installation folders as well.

One or more remote, user-developed applications may interact with ANVEL. ANVEL is configured to act as a Thrift server for one or more remote client applications. Any number of remote applications can be connected simultaneously; their calls are handled by ANVEL based on the order in which they are received. Remote applications can run on the same host as ANVEL (utilizing a loopback connection) or on different hosts which communicate with ANVEL through the network.

The AnvelApi plugin implements the interface on the ANVEL side. This plugin is included with the ANVEL installation and is automatically loaded when ANVEL starts. AnvelApi exposes the core ANVEL internals and works in conjunction with ThriftInterface for serializing/deserializing and network transport. Thrift handles the serialization/deserialization and binary transport protocol of all communication between ANVEL and remote applications over a TCP/IP connection as outlined below:

Thrift Communication

API exceptions that occur on the ANVEL Core side are treated like return data and are effectively thrown on the remote application side once received through the network interface.

Network Configuration

Depending on configuration requirements, ANVEL can run on the same hardware as an External API application and communicate over loopback or on different hardware and utilize non-default host/port parameters for various services. For more information, see Remotely Connecting to Multiple Instances of ANVEL

By default, unless specific launch configuration parameters are set, the External API will be disabled. If enabled with only the '--api' parameter, the connection will need to be established (localhost at port 9094). Other flags are necessary to connect to different IPs and/or ports.

Network config options ANVEL.png

See instructions for setting and querying environment variables in Windows and Linux. Note that after modifying either environment variable, ANVEL must be restarted for the modifications to take effect.

When using ANVEL in Headless mode (with and without Rending), managing multiple instances, or using a multi-machine setup, we recommend making use of the services exposed through the ANVEL Service Management Interface (SMI).

Language-specific Instructions

Setup instructions and examples for supported languages.

The External API reference documentation (including data types, enumerations, exceptions, and services) applies to all remote application languages.

Performance and Optimization

Use of Thrift for the interface definition and binary communications protocol of the API provides significant flexibility in the remote application's language and operating system. The cost of this flexibility is the overhead inherent in serializing/deserializing data and network-based transport between ANVEL and the remote application. For most integrated applications, including many real-time applications, API performance is sufficient on modern hardware. Complex simulations, dense sensor data, and/or low-performance networks may require more careful application design to achieve suitable performance with the API.

Specific use cases may vary, but adherence to the following guidelines generally results in the best overall API performance:

Use a loopback connection between ANVEL and the remote application when making large numbers of API calls or retrieving significant volumes of sensor data. The API can be configured to operate over loopback or a standard network connection. Loopback connections provide dramatically higher available bandwidth and lower latency because they bypass actual network hardware. A loopback configuration does require both the ANVEL instance and remote application to run on the same host computer and share resources. Modern CPUs typically handle the two main ANVEL threads and a lightly-threaded remote application fairly well.

If a loopback connection is not possible, ensure the underlying network performance can support the application. Each API call by the remote application will block execution by the sum of:

  1. Application Processing Time
  2. ANVEL Processing Time
  3. Round-Trip Network Latency

For real-time applications, network performance can be the limiting factor. For example, a network latency of 15 ms is sufficiently high to prevent real-time simulation with even a single API call for each 10 ms world step interval.

Use "batch" calls wherever supported. A number of API operations include "batch" variants that support performing the same operation or query for multiple objects of the same type. These can result in designs with much higher performance than designs that loop through a list of similar objects in the remote application and make separate API calls for each. This is especially true for non-loopback connections with significant network latency because a "batch" call is delayed by a single round-trip communication while looped calls suffer from latency that increases proportionately with the length of the loop.

Simulations with high resolution lidar or camera data can present a challenge to performance. Modern sensors with high beam density and image resolution and fast updates rates require significant computational and network resources to serialize, deserialize, and transport. This is equally true for simulations with multiple, lower-density sensors. For applications that require large volumes of sensor data, a custom sensor plugin may be necessary to achieve sufficient performance.