Skip to content

Avular Programming Interface

Introduction

Vertex One uses Avular Programming Interface which is based on ROS 2 and its data and functionalities are exposed through ROS topics and service calls.

Robot Operating System (ROS)

For more information on ROS 2 please read here (External Link) Hereby a short summary of what ROS 2 offers. Source (External Link)

ROS 2 is a middleware based on an anonymous publish/subscribe mechanism that allows for message passing between different ROS processes.

Basic ROS Terminology

Term Description
ROS Graph At the heart of any ROS 2 system is the ROS graph. The ROS graph refers to the network of nodes in a ROS system and the connections between them by which they communicate.
Nodes A node is an entity that uses ROS to communicate with other nodes.
Messages ROS data type used when subscribing or publishing to a topic.
Topics Nodes can publish messages to a topic as well as subscribe to a topic to receive messages.
Discovery The automatic process through which nodes determine how to talk to each other.

How do Nodes Work?

A node is a participant in the ROS graph. ROS nodes use a ROS client library to communicate with other nodes. Nodes can publish or subscribe to Topics. Nodes can also provide or use Services and Actions. There are configurable Parameters associated with a node. Connections between nodes are established through a distributed discovery process. Nodes may be located in the same process, in different processes, or on different machines. These concepts will be described in more detail in the sections that follow.

ROS Client Libraries

ROS client libraries allow nodes written in different programming languages to communicate. There is a core ROS client library (RCL) that implements common functionality needed for the ROS APIs of different languages. This makes it so that language-specific client libraries are easier to write and that they have more consistent behavior.

The following client libraries are maintained by the ROS 2 team:

  • rclcpp (C++ client library)
  • rclpy (Python client library)

Additionally, other client libraries have been developed by the ROS community. See the ROS 2 Client Libraries article (External Link) for more details.

How Does Nodes Discovery Work?

Discovery of nodes happens automatically through the underlying middleware of ROS 2. It can be summarized as follows:

  1. When a node is started, it advertises its presence to other nodes on the network with the same ROS domain (set with the ROS_DOMAIN_ID environment variable). Nodes respond to this advertisement with information about themselves so that the appropriate connections can be made and the nodes can communicate.
  2. Nodes periodically advertise their presence so that connections can be made with new-found entities, even after the initial discovery period.
  3. Nodes advertise to other nodes when they go offline.

Nodes will only establish connections with other nodes if they have compatible Quality of Service (QoS) settings. For more info, see ROS 2 QoS settings documentation (External Link).

Example of basic Talker-Listener setup:

Running the C++ Talker node in one terminal will publish messages on a topic, and the Python Listener node running in another terminal will subscribe to messages on the same topic - You should see that these nodes discover each other automatically, and begin to exchange messages.

Extra ROS 2 documentation to this topic:

How is ROS Implemented on the Vertex One?

Vertex One implements Avular Programming Interface, which is customized API based on ROS 2. The Flight Controller can receive external commands from the Onboard Computing Module to trigger events. This page contains the behavior of the flight controller when receiving such commands, as well as details about the implementation.

Architecture Overview

There are two basic principles that are at the core of the implementation on Vertex One:

1. In all cases, the Flight Controller is responsible for the decision if a trigger is valid and accepted

2. The pilot can always take over manual control via the remote controller

ROS Topics Made Available by Avular Programming Interface

Note

To list all available ROS topics, execute: ros2 topic list.

  • The available supervisor commands and reference inputs are explained in section Input Topics

  • The available onboard data outputs from the Vertex One are explained in section Output Topics

  • The available sensor data outputs from the Vertex One are explained in section Sensor Topics

Nominal Operation of Vertex One

During nominal operation the following workflow is expected:

  1. The Vertex One is on the ground, LEDs indicate it is ready for a flight
  2. Pilot switches RC to manual position mode, LED indicators change
  3. Pilot switches RC to external position mode, LED indicators change
  4. Onboard Computing Module can send arm command or the pilot arms Vertex via RC
  5. Onboard Computing Module sends takeoff command, Vertex climbs to the pre-defined take-off height and hovers in position
  6. Onboard Computing Module sends a setpoint or waypoint, Flight Controller accepts and executes this command (e.g. flies in a straight line to the following waypoint)
  7. Waypoints are sent event-based (i.e when the waypoint is reached, the next waypoint is sent); consecutively, the complete mission is executed
  8. Mission is done, Vertex One stays hovering in place
  9. Onboard Computing Module sends land command, Vertex One descends and disarms when landing is detected. 
  10. At any time of the operation (but while in external position mode) the killswitch command can be used to turn the motors off. The pilot can always trigger the killswitch command by using the dedicated kill switch on the remote controller.
  11. At any time while the motors are are-armed, the emergency land command can be used to trigger an emergency landing which cannot be cancelled. Not even by the pilot via remote controller. Emergency landing will be executed in manual position mode, allowing pilot to control vertical descent velocity and horizontal position.

Specific Situations and Expected Behavior

Besides the workflow of nominal operations, different abnormal situations may occur. This table outlines the expected behavior of pre-programmed actions of the Flight Controller should these situations occur.

Situation Expected Behavior/Response
RC is in manual position/attitude mode All external Onboard Computing Module commands are ignored.
Pilot switches to automatic position mode, but is still in manual attitude mode Directly switching to automatic position mode may result in it being rejected. First verify that manual position mode is available before switching to automatic position mode.
Onboard Computing Module sends reference already during take-off Vertex One will continue take-off, last received reference will be followed after take-off is completed (Any XY references are ignored, different from manual position mode)
Onboard Computing Module sends disarm command in flight Flight Controller ignores command (It only listens to and accepts this command while in idle state.) Kill switch command must be used in flight to kill motors. Pilot can always disarm as usual via the remote controller.
Onboard Computing Module sends arm command in flight Flight Controller ignores command - no further action happens.
Onboard Computing Module sends take-off command during flight Flight Controller ignores command - no further action happens.
Onboard Computing Module sends land command while in take-off Vertex One will initiate landing procedure.
Onboard Computing Module sends changing waypoint/heading reference during landing mode All references are ignored during landing. Vertex holds last estimated position and heading and descends automatically. Changing reference requires aborting the landing (Any XY references are ignored, different from manual position mode).
No waypoint/heading references are received after take-off Vertex One will hover in place until references are received or other commands are given.
During any non-emergency state, the pilot switches from automatic position mode to manual position mode Vertex One hovers at last estimated position, any Onboard Computing Module commands are ignored.
Onboard Computing Module or Flight Controller triggers emergency landing Flight Controller changes MoO to manual position mode (if available) and ignores any Onboard Computing Module commands. Even if triggered by the Onboard Computing Module, emergency land can not be cancelled. Vertical velocity and position references from the RC are accepted as usual.
Pilot switches from automatic position mode to manual position mode while in flight. RC switch is however still in landing position. The Flight Controller only responds to the land/take-off command after exiting automatic position mode if the switch was equal to the current state. In practice: the pilot has to first switch to take-off mode before it can trigger land via the remote controller. This is to prevent unexpected landing behavior when switching from automatic position mode to a manual mode.
Remote control loss in automatic mode Flight Controller switches to manual position mode and goes into emergency land, no longer possible to go into automatic mode
Waypoint/heading references are flagged as incorrect before takeoff Vertex One hovers and holds position after takeoff