The InOrbit agent is a small Python-based software that connects robots to the cloud to enable reliable and low footprint bi-directional communication with InOrbit cloud services.

Debian Package Installation

We provide debian packages, currently supporting only Ubuntu Xenial with ROS Kinetic, Ubuntu Bionic with ROS Melodic, Ubuntu Focal with ROS Noetic, Ubuntu Focal without ROS and Ubuntu Jammy with ROS 2 Humble.

These packages are intended for mature installations and deployments at a larger scale. For smaller or development installations you may prefer to follow the instructions at Add a Robot.

The main aspects of this installation are:

• It installs dependencies, runs in its own virtualenv and gets started automatically via systemd.
• Runs under a new user "inorbit" (default) or under a user id provided beforehand
• It installs the "binary files" (dist directory) under /usr/local/inorbit 
• The configuration files go into /home/<userid>/.inorbit/local 

Since in this installation method the binary files are installed with root permissions, the agent remote updater doesn't work if this installation method is used.

Configuring the InOrbit Ubuntu repository 

The InOrbit agent is provided as the inorbit-agent Debian package, available from the InOrbit repository. Please follow these instructions to set-up the repository.

1. Setup your sources.list

   Setup your computer to install software from the InOrbit repository:

   Ubuntu 16.04 + ROS Kinetic

   sudo sh -c 'echo "deb https://artifacts.inorbit.ai/debian/ xenial-main main" > /etc/apt/sources.list.d/inorbit-agent.list' 

   Ubuntu 18.04 + ROS Melodic

   sudo sh -c 'echo "deb https://artifacts.inorbit.ai/debian/ bionic-main main" > /etc/apt/sources.list.d/inorbit-agent.list' 

   Ubuntu 20.04 + ROS Noetic

   sudo sh -c 'echo "deb https://artifacts.inorbit.ai/debian/ focal-main main" > /etc/apt/sources.list.d/inorbit-agent.list' 

   Ubuntu 20.04 without ROS

   sudo sh -c 'echo "deb https://artifacts.inorbit.ai/debian/ focal-nonros main" > /etc/apt/sources.list.d/inorbit-agent.list' 

   Ubuntu 22.04 + ROS2 Humble

   sudo sh -c 'echo "deb https://artifacts.inorbit.ai/debian/ jammy-ros2 main" > /etc/apt/sources.list.d/inorbit-agent.list' 

2. Setup APT keys
   
   sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C45E9A6F71F2903944292BF7650F5571511D225F 
   
   
3. Install the following apt packages:
   sudo apt-get install -y apt-transport-https apt-utils
   
   
4. Make sure your Debian package index is up-to-date:
   
   sudo apt update 

Installation

The expected flow is that the package is installed as root using apt-get, and then in a separate step, a configuration file is added to make the system work.

Installing InOrbit’s agent package

Please make sure you configure your Ubuntu repositories first. Then you can install InOrbit’s agent via apt-get with the following command:

sudo apt install inorbit-agent 

Customized installation

To install InOrbit’s agent with non-default installation options (e.g.: customizing the userid to run under), we recommend using the following command:

sudo DEBIAN_FRONTEND=readline DEBIAN_PRIORITY=low apt-get install inorbit-agent 

This will cause the Debian package manager to ask the user for installation options interactively.

Customized unattended installation

If unattended installation of the InOrbit agent with non-default installation options are required, we recommend following the instructions under Unattended Package Installation in the debconf documentation.

In summary:

• Do a pre-configuration first on a development computer to create the configuration options file, i.e.:

  sudo apt-get download inorbit-agent 

  cp /var/cache/debconf/config.dat /tmp/config.dat.before 

  sudo dpkg-preconfigure inorbit-agent-<version>.deb -p low # configure options 

  diff /var/cache/debconf/config.dat /tmp/config.dat.before > inorbit.config.dat 

• Deliver that configuration file together with the Debian installer and use it as a fallback DB option during installation to use the pre-created configuration options:

  sudo DEBCONF_DB_FALLBACK='File{/tmp/inorbit.config.dat}' 

  dpkg -i inorbit-agent-<version>.deb 

  Once this setup is ready, you can proceed with the steps described on the next section (Configuring the agent). Note that in case you disable systemd, you will need to start the agent manually and keep it alive within a loop.

Configuring the agent

The configuration file goes in /home/inorbit/.inorbit/local/agent.env.sh  and has the following form, with the appropriate value for each variable:

export INORBIT_ROS="noetic"
export INORBIT_ID="<ROBOT_ID>"
export INORBIT_KEY="<API_KEY>"
export INORBIT_URL="https://control.inorbit.ai/"
export INORBIT_VARIANT="main" 

Note: For ROS2 environments you will also need to set the ROS_DOMAIN_ID value above.

The user is responsible for provisioning a file like this to each robot with the corresponding Robot ID and API Key. You can ask InOrbit’s support team for the API Key or otherwise get it from InOrbit control. For the latter, click the ‘Add a Robot’ button on Fleet Status: the API key is the final parameter on the URL displayed.

curl https://control.inorbit.ai/liftoff/<API KEY> | sh

Please see Advanced agent configuration for further information on customizing the agent by setting additional options in agent.env.sh.

You can augment InOrbit’s default robot data with your own custom settings to view specific information/robot attributes you want to see on InOrbit Control.

As described in A look at InOrbit Control, when you add a new robot, InOrbit Control displays default data/information for a robot, such as CPU Usage, HDD Usage, and RAM. These are called “Built-in” attributes.

You can configure InOrbit to capture other desired attributes of particular interest to you, such as system or robot metrics, sensor readings, software component details, and application-specific values. You customize your robot data via the Settings menus in InOrbit Control. A custom attribute applies to all robots in your entire fleet. Custom attributes can then be used for real-time monitoring, to visualize values over time directly in InOrbit Control, to track overall fleet status or to trigger notifications on events or when something is not within expected tolerances.

Background: Data Sources

InOrbit supports the following data sources. These data sources are obtained from the Robot Operating System (ROS) installed by the InOrbit agent on each robot. (For more information about ROS itself, see the ROS Wiki.) InOrbit also supports additional non-ROS data sources. For assistance in configuring non-ROS data sources, contact InOrbit via email at support@inorbit.ai.

Type of Data	Description
System metrics	CPU usage, RAM usage, specific HDD partitions, or network interfaces.
ROS Diagnostics	If you use ROS and have nodes that publish values in the /diagnostics or /diagnostics_agg topics, InOrbit can be configured to work with this data.
Custom key/value pairs	If you use ROS and want to view a specific data value from your robot, you can publish a std_msgs/String message with the form key=value to the /inorbit/custom_data/0 topic on the agent; for example, apples=10.

 

What You Need

• The InOrbit agent installed on the robot whose data you want to customize
• The Owner or Administrator role in InOrbit Control

Steps for Custom Robot Data

Viewing custom data involves two steps:

• defining a customer robot attribute
• displaying that attribute in InOrbit Control

We illustrate this on a specific robot attribute for viewing: usage of the eth0 network interface on your robot.

Part 1: Define the eth0 (example) custom robot attribute

1. As Owner or Administrator, login to InOrbit Control.
2. From the menu in the upper right, select Settings.
   Result: You are positioned on the Robot Data tab, which is divided into sections: Data Sources, Status, and Dashboards.
3. To add the new data source, under the Data Sources heading, click the sign.
   Result: A new empty slot for the custom attribute is displayed.
4. Define the attribute you want to add in either of two ways:
1. Select the pulldown menu at the right of the new slot to view predefined system attributes.
2. In the empty slot, begin typing the name of the attribute you want to add. InOrbit displays matching data source names that it discovers from your robots such as the different network interfaces, HDD partitions, ROS Diagnostics tools or custom key/value pairs.
5. As an example, we want to see the eth0 data source. From the pulldown menu, find and select eth0. The custom attribute is added to the list of Data Sources
   
   
   
   
6. To add a more user-friendly name for the attribute, scroll to New Data source entry in the Data Sources list and enter the user-friendly name in the first field, e.g., “Network interface - eth0”. The user-friendly name is updated for any configured visualization widget.
   
   
   
   
   Result: You have defined the new custom eth0 attribute, renamed “Network interface - eth0”, and InOrbit automatically saves the new configuration.

Part 2: View the eth0 custom robot attribute on InOrbit Control and change its position

Add a new robot status to Fleet Status widget

You can add a new data source to the Fleet Status widget based on the new custom attribute defined in Data Sources. For this, go to Settings > Robot Data > Status and click on the icon for the new data source, “Network interface - eth0” in our example.

 

To see the new status, go to InOrbit Control and select the ‘Fleet’ dashboard.

Add a new data source to Vitals or Timeline widgets

To configure the visualization of the new attribute in a Vitals or Timeline widget:

1. Go to Settings > Robot Data > Dashboards.
2. Select the Dashboard you’d like to add this attribute to.
3. Expand the Section where you’d like to add this attribute. You can also create a new section if needed.
4. To add the data to an existing widget, expand the Vitals or Timeline configuration and add the new attribute. Note that Vitals widget can only have four data sources. When adding a Timeline widget, the min number of lines must be set to at least 1.

 

To change the position of the attribute within a widget or Timeline on InOrbit Control:

1. Go to Settings > Robot Data > Dashboards
2. Select the tab for the Dashboard you’d like to update. Find the attribute in the Widget within the corresponding Section..
3. Grab the = handle to the left of the attribute.
4. Drag the attribute up or down in the Visualization list to the desired display position.

Result: Return to InOrbit Control to see the attribute in the new position.

When you create your account (see Quick start), InOrbit will start with a default configuration, which tracks only a few attributes from your robots, such as CPU Usage, HDD Usage and Network Rate.

You can configure InOrbit to capture more relevant attributes for your particular operation, such as additional system or robot metrics, sensor readings, software component vitals or application-specific values.

Any attributes you configure can then be used for real-time monitoring, to visualize their values over time, to track overall fleet status and to trigger alerts based on events or when something is not within expected values.

These configurations are managed in the Data Sources section of the settings screen, accessible through Settings:

InOrbit currently supports the following data sources:

1. System metrics
   You can monitor CPU usage, RAM usage, specific HDD partitions and network interfaces.
2. ROS Diagnostics values
   If you use ROS and have nodes that publish values in the /diagnostics or /diagnostics_agg topics, InOrbit can be configured to pick up any of these values.
3. Custom key/value pairs
   If you are using ROS and want to publish an arbitrary value from your robot, you can publish a std_msgs/String message with the form key=value (e.g; apples=10) to the /inorbit/custom_data/0 topic on the agent.
4. Other types / non-ROS
   InOrbit also supports additional and non-ROS data sources, which can be enabled per customer request. Please let us know about your needs by writing to us at support@inorbit.ai.

In order to make it easier to configure, InOrbit lets you search over the data sources that it can discover from your robots. Simply start typing in the box to filter between the different network interfaces, HDD partitions, ROS Diagnostics tools or custom key/value pairs:

NOTE: In order for InOrbit to be able to discover the available data sources on your robot, it is important that the agent be running before you attempt data source configuration.

 

InOrbit allows configuring custom Actions you can use to send commands to any robot. These actions can be used to quickly and efficiently resolve issues or incidents that occur as part of operating your robot fleet, as well as allowing users to nudge a robot towards the desired behavior.

Overview

InOrbit currently supports five distinct methods of triggering specific robot behaviors and other interactions. These methods can easily be configured with minimal technical knowledge, quickly enabling users to send commands with the click of a button. See also the Robot Lock premium feature. 

These actions can be made available for execution in the ROBOTS section of InOrbit Control through the Robot Actions widget,

The widget allows you to display actions organized in groups, that you can define in Settings > Insights. Each row shows the group name, the number of actions associated with this group and also a button to expand the section. When this button is clicked, all the actions in the group are shown.

Actions can be also tied to specific incidents for execution through InOrbit Control in-app notifications or Slack.

Integration with other incident management systems such as Opsgenie and custom systems is also available as a premium offering.

Setting up Actions

There are many ways to define an action on InOrbit:

• Publish on a ROS topic
  Publish a configurable string value through the/inorbit/custom_commands topic on the robot.
• Run script on agent
  Run a shell script on the robot. Scripts must be placed in the ${HOME}/.inorbit/local/user_scripts directory.
• Jump to InOrbit page
  Bring the operator to a specified page in InOrbit Control, such as the localization and navigation screen for a robot. Useful to allow you to dive deeper into a problem and perform the most effective resolution action.
• Open URL
  Take the operator to the configured URL on a Web browser window. Useful to direct your operator to an internal system to continue the resolution protocol for a given incident.
• Execute a ROS service (coming soon)
  Execute a ROS service on the robot.

To configure actions:

1. Go to Settings > Insights > Actions
2. Click the (+) icon to add a new action or select an existing action
3. For the name field, enter the name for the new action, e.g., NEW ACTION
   
   
4. For the type field,  select the desired action, e.g., Run script on agent
   
   
5. Each action is listed in a section, which is a grouping of similar actions
6. Navigate to the newly created action and select an existing section or create a new section
   
   
   
   
7.  Select the Confirm execution checkbox if you want the action to require user confirmation before executing the command. If the premium Robot Lock feature is enabled, you may optionally select Requires Lock to ensure there are no conflicting commands from multiple users. 
   
   
   
   
8. Use the embedded dropdown to select which widgets should include this action - note that the selection of the action will cause the section to be included in the action dropdown in the selected widget
   
9. Select whether the action is Always available, if it should be available Only in collections that are specified by you, or if it should be available only when it's Not in collections that you select
10. Each action can be configured with a specific parameter that can be changed or set as needed, including parameters that can be provided by the end user when executing the action

 

About on-robot shell scripts

On-robot shell scripts you can run after an incident are Linux scripts that you yourself write and are completely under your control.

As an example, you might write a script that lists the top 10 running processes on the robot and saves the list to a file. This could potentially be useful for debugging a robot with high CPU utilization. Such a script could look like the following:
# !/usr/bin/bash
# where to save the script output
export SAVEFILE="/tmp/top10cpu.txt"
# list top 10 processes' percentage of CPU, PID, username,
# and running program with arguments, sorted by percentage of CPU,
# and saved to a file
ps -eo pcpu,pid,user,args | sort -k1 -r -n | head -10 \
> $SAVEFILE

• Store the script in ${HOME}/.inorbit/local/user_scripts.
• Make note of the name of the script on the robot because you need to specify the name when you define the action.

Collections

As your fleet grows, InOrbit allows you to organize your robots according to different criteria, such as hardware iteration, customer deployment or location. This allows you to filter or group robots in InOrbit Control based on these different criteria.

Each grouping of robots is called a collection; each robot may be part of one or more collections. All robots are members of the default collection called Fleet.

You can customize the collections and robot membership in each collection by going to Settings > Organization in InOrbit Control.

Manage Collections

Locations

Locations enable robots to be associated with a geographic location (a city or address that can be displayed on a map).

Locations have tags associated with them, like any other collection, but that tag has an underlying physical location. Adding that tag to any robot will enable grouping by location and easily associating robots with individual or common sites. A Location widget can be added to dashboard sections with Fleet scope. Once robots are associated with a physical location, they may be displayed on an interactive, zoomable map to go from a world view all the way down to an individual robot map at a given site.

Configure locations for your account

1. Use the Locations tab in Settings > Organization to define all the locations or sites you want to track. To add a new location, click the circled + sign. All locations are part of a collection type called Locations.
   
   
2. Select a unique name (tag) for the location; this can be whatever you need it to be, from a city to something that makes sense within your system, such as Store #1234. Add an address to enable displaying the location on a world map. Note that these locations are assumed to be fixed. Optionally add notes to help you with location management. You can also choose to have robots added to a given location by default.
   
   
3. Now use the Robots tab in Settings > Organization and assign robots to this location.  Note: InOrbit also supports automatically assigning robots to locations if the location can be distilled from a data source, which is recommended as a fleet scale.
   For example:
   
   Add an address to enable displaying the location on a world map. Note that these locations are assumed to be fixed. Optionally add notes to help you with location management. You can also choose to have robots added to a given location by default.
   
   
4. To see the locations on a world map, go to the Locations section in the Executive dashboard

Modes

Modes is a special collection type that can be used to indicate the state or mode in which a robot is operating (e.g. Charging, Idle, or Mission). This value can change dynamically and is assumed to be MECE (Mutually Exclusive and Collectively Exhaustive), i.e. each robot can be in one and only one mode at any given time.

Modes map to a color in the block below the robot name in the Fleet Status widget.

You can group or filter the robots by mode in the Fleet dashboard using the Options control.

Modes are reported in a custom data source. It is up to your application code to report these modes; any modes reported in the data source that do not match the modes defined here will be reported as Other.

Configure modes for your account

1. Go to Settings > Organization > Modes.
2. Select the data source that will determine the mode a robot is in (e.g., Mission Status):
   
3. Now start adding the different values a mode might take. Click the ‘+’ button and add these one by one
   
   
   
   Note: The tag field is the visible name the mode will have, which doesn’t need to match the actual data source’s values for the mode. Tags are unique.
   
   If values are not specified, it is assumed that the tag matches the value that the data source will take. So if, Mission Status can be any of Mission, Idle, Charging, Inventory or Error, the configuration should look like this
   
   
   
   You can also change the order of modes to match the robot behavior; for example, if your robots usually change from Charging to Idle to Mission and back to Charging, you may organize them in that order. Colors are automatically assigned to each mode.
   
   If, for example, the Mission mode is triggered when Mission Status matches any of a set of values (e.g., mission, in_mission, running) or a value different from the tag, you can specify these using the values field:
   
   
   
   
4. Done! Now you’ll just need the robot to publish Mission Status=<status> and if the mission status is any of the values defined above, the robot will appear in that mode
5. If the status is not on that list, the mode will be “Other”. For example:
   
   

Regular collections

All other collections can be defined in the Collections tab in Settings > Organization. You can add your own collection by clicking the circled + sign. Choose a type such as Customer or Hardware.

Enter a unique name, and optionally add notes and check the box to automatically add new robots to that collection

Depending on the nature of the data source, collections can be either static or dynamic.

Static

Static collections have fixed tags, manually generated, as the members are solely based on tags rather than data sources. Robots need to be explicitly assigned to a static collection by applying a particular tag to it. By default, several collections, including Deployment, Hardware, Customer and Other, are static.

Configure static collections for your account

1. Go to Settings > Organization > Collections
2. Click on the circled + sign, and a new row will be displayed for you to add a new collection.
   
3. Now you’ll need to create Tags for this collection.
   1. Go to Settings > Organization > Tags
   2. Select the tab for the Collection for which you would like to add a tag, and click on the circled + sign. This will present a new row where you can configure the new tab
      
      
   3. Enter the tag name, which should be unique
      
      
   4. Now use the Robots tab in Settings > Organization and assign robots to this tag. For example, If you want to update tags for a robot named ‘Kepler’, you’ll need to click on the dropdown next to the robot name and select the tags it belongs to.
      
      
      
      
   5. Then for the rest of the tags you can simply select the existing collection tab and add a new tag for it. Note that if the data source takes a value which doesn’t have a tag defined, a robot going into that state will have the tag “Unassigned”.

Dynamic

Dynamic collections are collections that are based on known data sources and thus membership can change as values change in the selected underlying data source. These are useful for enabling robots to be filtered or grouped by attributes that reflect the current state of that robot, such as the software version. Modes are an example of a dynamic collection that is built into the InOrbit platform.

Configure dynamic collections for your account

1. Go to Settings > Organization > Collections
2. Click on the circled + sign, and a new row will be displayed for you to add a new collection
   
   
3. Give this new collection a name (e.g., Software Version).
4. You will see a new field on the right, which is the data source selector. The value of this data source on a robot will determine its associated tag.
   
5. Now you’ll need to create Tags for this collection. You can either do it:
   1. Manually as described above for Static Collections.
   2. Automatically
   3. Click the Auto create tags checkbox on the Collections config. This will automatically create new tags based on the values that the associated data source takes, which will be reflected in the Tags section.
      
      
      Note: clicking on the robot count for a tag will redirect you to Control, with the fleet status filter set to the specific tag, so only those robots will appear.

You can edit an already created collection (change its name, switch between static and dynamic, update a data source for dynamic collections) by clicking on a row within the Collections tab in Settings > Organization. This will enable edit mode.

You can also delete collections or tags with the trash button. To delete a collection, you must first delete all its tags. To delete a tag, first make sure there are no robots on it. 

Group by collections

Once you have a collection, you can group or filter by collections in the Fleet dashboard. For example:

Group by ‘Mode’:

Filter by a particular customer:

Filter by a component (e.g.,  battery errors):

 

As an Owner or Administrator, login to InOrbit Control. Click on the icon at the upper right and select Settings, where you can set up your robots, data, incidents, actions, dashboards and more.

Create a new dashboard

Navigate to the Dashboards section under the Robot Data tab. This area lets you edit and create dashboards.

Click the button to create a new dashboard.

Any dashboard can be renamed by typing the new name into the “dashboard title” field.

Change visibility of each dashboard

Visibility of dashboards lets a company limit access to specific capabilities of InOrbit Control. Creating specific dashboards intended for different roles or tasks can avoid screen clutter, letting the user focus on their responsibilities. By default, dashboards are hidden from all roles. Make sure to select roles that should have visibility of the new dashboard.

In the example below, the Executive dashboard is set to be visible to Owner, Administrator, Manager, Engineer and Operator roles, but not visible to people with the User role.

In our example New Dashboard, we are going to set visibility to Operator only. 

Add a section in a dashboard

Dashboards consist of sections and widgets. Sections are like named folders that can contain a set of widgets.

Click on the button to create a new section in this dashboard.

You've just created a new section. Select thearrow on the right to expand the new section for editing. You can rename this section by typing in the “section title” field.

Set section scope

Sections can contain different widgets based on their scope, Fleet or Robot. We have created two new sections in the image below to demonstrate each scope type.

Click the section scope dropdown menu and select Fleet or Robot, depending on what you want to monitor or control in a dashboard section. 

Add widgets in each section

With the section scope set, you can add widgets.

Each section scope type has different widgets available for visualizations. Click on the button at the bottom of each new section to select widgets for that section (you can add multiple widgets per section).

These are the widgets available for fleet scope sections:

These are the widgets available for robot scope sections:

There is currently a single special-purpose widget for navigation sections:

What are the control widgets?

There are 2 control widgets available: Fleet Control and Robot Control. These should definitely be added to any new dashboards where you want to be able to select within the fleet or focus on a particular robot.

Fleet Control lets you filter your robot fleet by a collection (tag) and/or an attribute status. It also allows grouping robots by a collection, or sorting by status or alphabetical order.

Robot Control lets you search for a robot that you have access to and set it as your selected robot to monitor. The widget also has handy shortcuts, such as a button to restart the InOrbit agent, or another that opens the Navigation dashboard.

 

InOrbit’s agent can subscribe to ROS image topics (with messages of type Image and CompressedImage) and send samples of those images to the cloud. The images are compressed as JPEG, throttled and down-sampled. 

This image snapshot based approach is designed to provide the user enough information about the robot’s environment when monitoring or operating it, while minimizing CPU and network usage on the robot. There is a tradeoff between image quality, size and frame rate, as we’ll see in the configuration section.

Video encoding and streaming is available as a separate offering. Please contact support@inorbit.ai for more information.

Configuration

If you go to Settings > Navigation > Cameras, you’ll find a ‘Configuration preset’ dropdown with 3 options:

Each preset represent a different configuration for processing and transmitting camera images from the agent to the cloud:

	Higher Frequency	Bandwidth Intensive	Higher Quality
Encoding	mono	RGB	RGB
JPEG compression quality	10	15	30
Size	380x240	380x240	720x380
Frame Rate [Hz]	2	1	0.2
Message size [kB]	3	4.5	12

 

These are the combinations we offer in terms of quality / size / frame rate balance, though we'd recommend using 'Higher Frequency' to preserve bandwidth if you don't need a high definition. With the default account set-up, if you make resolution and frequency too high, you may start to experience lag (latency), which is not a desired effect.

Customizing camera views

If you need to focus on the images from a given camera widget, you can enlarge it by clicking within it:

You can further customize the view of a camera widget by clicking on the camera label (‘C’, ‘L’ or ‘R’ in the example below). The label acts like a switch that allows you to alternate between: 

• zoom images
• turn off a camera
• full images

Turning cameras off is a useful way to save resources during regular operations, when camera images are not strictly needed.

If you need to re-enable a camera for a moment, then you can easily turn it back on by clicking on the label.

Please note that, in order to preserve bandwidth, InOrbit’s agent sends images to the cloud only if a user from a company (at least one) has a Navigation Dashboard open and the camera on. 

High-resolution mode

InOrbit offers an advanced option to display the featured camera in an alternative resolution for  a limited time (it currently times out after 1 minute), using the Hi-rez switch. This enables you to deeply optimize bandwidth usage by only transmitting full quality images when an active operator needs that quality to discern a detail, such as an aisle or zone number. 

The Hi-Rez mode provides high quality images, achieving the goal of being able to see details for a brief period of time. The update frequency is trimmed down to 0.1 Hz to preserve bandwidth. Just click the Hi-rez switch to toggle it on/off.

Advanced settings

Besides the default presets, it is possible to select any arbitrary configuration that you prefer (for both the regular image snapshots and Hi-rez mode). For that, you will need to provide the following parameters to our Customer Success team:

• Encoding (mono or rgb)
• JPEG compression quality
• Image size
• Frame rate [Hz]

After setting up that configuration, cameras will start streaming with the desired resolution and frequency that you choose, along with the preset options in the dropdown menu.

When autonomy fails and other means of resolution fall short, InOrbit Control offers powerful Intervention capabilities that allow you to temporarily take manual control of your robots and teleoperate them back to safety and autonomy.

This ability gives the human operator using InOrbit a greater power over the physical presence of the robot so it must be used with caution.

Overview

Relocalization and Teleoperation are available when opening the Navigation screen for a particular robot. The controls for both relocalization and teleoperation can be found on the right side of the Navigation dashboard.

InOrbit Control offers flexible layouts to display more detail across maps and cameras. 

The “map/camera” button, between the map selector and the settings button,  toggles between views that feature the map and the primary selected camera.. 

Cameras are ordered based on the order of cameras in Settings > Navigation > Camera. You can select the primary camera by clicking on the image within any camera view. Similarly, you can feature the map by clicking on the small map view when a camera is featured. You can turn off a camera (good for reducing bandwidth) by clicking on the label in the upper right of any camera view.

This is an example of featuring the primary camera.

To improve the video quality, InOrbit offers an advanced option to display the featured camera in high resolution for  a limited time (it currently times out after 1 minute), using the Hi-rez switch. This enables you to deeply optimize bandwidth usage by only transmitting full quality images when an active operator needs that quality to discern a detail, such as an aisle or zone number. 

Updates will be significantly slower while in Hi-Rez mode based on the additional data transmission, but the primary goal is to be able to see details for a brief period of time. Just click the Hi-rez switch to toggle it on/off.

Relocalization

To ensure that the robot is properly localized to accurately track and control the robot navigation, the map displays lidar dots reflecting how the robot is currently recognizing obstacles. If the lidar dots are not properly oriented with features on the map, navigation becomes more unreliable.

Relocalization may be all that is required to restore proper navigation by the robot, or it may be the first step before taking over navigation via teleoperation.

First activate relocalization by clicking the Relocalize button.

It is easy to relocalize a robot with two controls:

• Clicking and dragging the rotation control above the robot avatar enables rotating the map features
  
  
• Clicking and dragging on the robot avatar enables translating the map in xy space to align the lidar dots with the features
  
  

Click on the check mark in the lower right to confirm relocalization. If you decide to cancel or start over, click the Relocalize button again to abort the ongoing action.

Teleoperation

To provide flexible options for different needs/preferences, there are currently two  modes available for Teleoperation:

• Open - send a very simple velocity or movement command to the robot to move in a certain way without invoking the robot’s navigation stack
• Waypoint - send a command to the robot to move to a specific target location, using its internal navigation stack

See the Security measures section below for important information about how InOrbit restricts teleoperation to ensure the safest possible operating conditions.

Open Teleop

Selecting Open Teleop activates a d-pad with arrow buttons in the lower right corner. Clicking on the up or down arrows send commands to the robot to move a single step forward or backward, relative to the current robot position and orientation, respectively. Clicking on the right and left arrows send commands to the robot to rotate clockwise or counterclockwise by a fixed angle, respectively, again relative to the robot.

Above the arrows are meters to show the linear velocity and angular velocity when the robot is moving, and a network gauge to ensure that the roundtrip latency is sufficiently low to safely carry out the command.

Since this can be a risky mode to be in (as it bypasses the navigation stack that avoids obstacles), the d-pad highlights in orange to make it very clear when the robot is in Open Teleop mode. You can deactivate Open Teleop by toggling off the Open Teleop button.

To set a new distance or angle of the increment for each step:

1. Starting from the menu of three vertical dots at upper right, select Settings > Navigation > Teleop.
2. Optional - Select whether this change should apply to the Fleet or an individual robot with the selector in the upper left.
3. Adjust the default Distance or Angle using the sliders.
4. Exit Settings and select the Navigation dashboard to resume Teleop.

Waypoint Teleop

Selecting Waypoint Teleop enables selecting a target pose that will send a command to the robot to which it should move. Select the target position by clicking on an arbitrary point on the map or by dragging the pin icon that appears on the current robot avatar to the new target position. Refine the target pose by clicking within the circle indicating the target and dragging to orient the robot avatar to the desired final orientation.

Click the check mark at the bottom to send the command for the robot to move to the waypoint using its navigation stack. Once the robot’s navigation stack computes the path, it will be displayed and the robot will navigate to the target. The gauges on the right display the velocity, network rate and angular velocity. 

You can abandon setting a waypoint by toggling off the Open Teleop button.

If you have already triggered a waypoint navigation, InOrbit offers an optional feature to cancel the navigation goal in progress. By clicking on the “Cancel navigation goal” button you’ll be able to forcibly stop the interaction while the robot is moving. Please contact support@inorbit.ai if you would like this activated on your account.

Step-by-step mode

Open Teleop has  two options,  step-by-step and  continuous mode, which respectively only issue a single command at a time or allow holding down a control to send a series of commands.

The default and recommended mode of operation gives you the ability to “nudge” the robot one step forward, one step backwards or rotating a fraction of a spin to the left or right.

This ability is intended to allow you to use discrete, safe movements to move the robot past an obstacle that its autonomous navigation algorithm can’t resolve on its own.

This enables a basic level of human intervention to apply in adverse network conditions to support re-establishing autonomous operations without the need for physical assistance.

Continuous mode (Experimental)

InOrbit includes an experimental feature to allow continuous teleoperation, similar to that found on remote control tools.

In order to enable continuous teleoperation mode:

1. As Administrator, login to InOrbit Control.
2. Starting from the menu of three vertical dots at upper right, select Settings > Navigation > Teleop.
3. Turn the Step-by-Step mode switch off.

After this is done, the following functions become available:

• You can click on a direction arrow repeatedly to achieve a seemingly smooth movement. NOTE: the robot will move an entire foot in the given direction after the last click is pressed.
• You can switch to use a virtual joystick by clicking on an icon that appears in the bottom right of the teleop control.

For Open Teleop, we highly recommend step-by-step mode for safety reasons since the navigation stack is not involved to prevent collisions with obstacles.

For Precision Teleop, the continuous mode only affects the process of specifying the action by, for example, holding down the arrow to change the distance in fixed increments before sending the final command, so it is a convenience rather than a risk.

Security measures

As teleoperation is a dangerous operation, InOrbit includes several safety measures to avoid unintended robot movements:

• Teleoperation is disabled by default, to avoid accidental clicks. In order to start teleoperating a robot, you must press the button for one of the active Teleop modes to expressly enable active teleoperation.
• Teleoperation will be automatically disabled if the network round trip time to the robot is higher than 15 seconds. The currently measured round trip time value is displayed at the top of the teleoperation control.
• Even while performing teleoperation, if the message sent from the user interface is delayed for any reason and the robot receives it more than one second after it was sent, the command will be discarded on the robot side, preventing an unintended delayed movement.

In addition, teleoperation will be blocked unless the following conditions are met:

• Odometry information is being published by the robot and InOrbit can decode it properly
• Robot movement as indicated by robot odometry matches the amount of distance intended by InOrbit’s teleoperation commands

Experimental features

If you are interested in trying out any additional experimental feature or have any input or questions, please contact our support team at support@inorbit.ai.

 

Understanding the environment and behavior of a robot at a given point in time is critical to solving some of the more difficult problems that AMRs face today.  InOrbit Time Capsule makes this easier by efficiently capturing, storing, and visualizing the critical information relevant to a robot’s behavior:  

• Maps annotated with path, position, and incident detail
• Audit log details relevant to a selected robot and time range
• Timeline charts of system and network performance data
• Mission durations within the selected timeframe

Creating your Time Capsule Dashboard

InOrbit provides a preconfigured dashboard widget for use with Time Capsule.  To enable it, follow these steps:

• Select Settings > Robot Data > Dashboards
• Select or create the dashboard to hold your Time Capsule
• Remember to validate Dashboard visibility for the dashboard that will contain your Time Capsule widget, so people in the applicable roles have access
• Create a new Section within the dashboard for the Time Capsule widget
• Time Capsule is available in the Section Scope dropdown menu.
• After selecting the Time Capsule scope for your Section, no additional widgets may be added to this section
• Select the preconfigured layout for your Time Capsule section
  
• Basic:  Map, Audit Log, System Performance and Network Performance Widgets
• Full:  All Basic layout widgets plus the Mode widget
• Experimental: At InOrbit, one of our core values is to Always Be Learning.  The Experimental layout is one example of how we apply this value.  Currently the Experimental layout includes all Full layout widgets as well as a Key-value Sources widget.  In this layout, we will continue to experiment with different combinations of widgets to bring you the most value possible from your InOrbit Time Capsules.  

 

Using the Time Capsule control widget

The Time Capsule control widget contains several options you can choose between to customize your visualization.  

• Robot picker:  This dropdown inherits the selected robot from your other dashboards while also providing the option to switch between robots without leaving your Time Capsule dashboard. 
• Date Range picker:  Select the start and end datetimes for your Time Capsule to cover.  
• Visualization picker:  This dropdown allows you to select the map overlay you want to see for the selected robot and datetime range. 
  
  The overlay options are:
• Position shows the exact location of the selected robot at different points in time within your defined time range.  
• Position (heatmap) highlights with colors the areas on the map where the robot spent the most time within your defined time range.  Warmer colors (yellow, orange, red) indicate more time while cooler colors (green, blue) indicate less time.  
• Path shows the specific path(s) a robot took during the time range.  
• Incidents highlights points on the map where incidents were logged by the robot during the time range.  
• Map picker - This dropdown allows you to select the map over which you want to see your data visualized.  The options available in this dropdown will be specific to the robot and datetime range you have selected.  
  
  

Reviewing an incident with Time Capsule

Opening a Time Capsule directly from your incident widget is as easy as a single click.  To explore an incident in Time Capsule:

• Expand an incident found in your incident widget
  
• Click on Open Time Capsule
• You’ll be taken to your Time Capsule dashboard with the appropriate robot selected and a time range starting 5 minutes before the incident and ending 5 minutes after the incident.

Exploring a Time Capsule

Every Time Capsule is an opportunity to explore the environment in which your robot was operating.  The data in each of the widgets shown is correlated with other widgets in your Time Capsule dashboard.  As you hover over an entry in the Robot Log or the Timeline widgets, you can observe any correlating entries in the other widgets on the screen.  

Options for setting the datetime range

When exploring different Time Capsule datetime ranges, you have several options:

• You can set the start and end datetimes as specified above
• Selecting an entry in the Mode widget (found in Full and Experimental layouts) will automatically adjust the time range to the interval associated with that entry
• Selecting or dragging on a timeline widget will automatically adjust to the selected datetime range 

Clicking Open Time Capsule from the incident widget will set the time range to 5 minutes before and 5 minutes after the incident.

Any additional options or environment variables required by scripts meant to be executed by the InOrbit agent should be included in the agent.env.sh file in order to become available to the InOrbit agent executable. 

The default location of this file is ${HOME}/.inorbit/local/agent.env.sh . This will be different in case you have customized the userid to run under or if you have set INORBIT_HOME .

The InOrbit agent supports the following environment variables:

ROS_CUSTOM_PATH

Introduced in 1.11.0

Allows specifying a custom location for ROS when it is installed, for example:

export ROS_CUSTOM_PATH=/opt/mybot 

HTTP_PROXY

Introduced in 3.0.0

This variable allows configuring the InOrbit agent to connect through a non-transparent HTTP proxy such as NTLM.

When this variable is set, the agent will configure the MQTT client to use websockets transport through a proxy server. This environment variable needs to be defined with the IP address of the proxy server, for example:

export HTTP_PROXY="http://localhost:445"

NOTE: the agent assumes that HTTP_PROXY  is using SSL.

INORBIT_HOME

Introduced in 3.5.0

Allows specifying a custom location to use as a data directory to store agent logs and other configuration and runtime data. For example:

export INORBIT_HOME="/mount/data/inorbit" 

By default, the agent uses the ${HOME}/.inorbit  directory within the home directory of the user under which it runs.

INORBIT_ENABLE_WATCHDOG

Introduced in 3.8.0

Allows enabling an agent watchdog script, which checks INORBIT's agent status and kills

it if it finds its MQTT connection socket stuck in  CLOSE_WAIT state for more than 60 seconds. To enable the watchdog, the value of this parameter must be set to “yes”, for example:

export INORBIT_ENABLE_WATCHDOG="yes" 

The watchdog will be disabled by default when this parameter is not set or if it is explicitly set to "no".

INORBIT_LOG_LEVEL

Introduced in 3.8.0

Allows setting the logging level of inorbit_agent.log to any of the levels supported by Python’s logging module:

• “critical”
• “error”
• “warning”
• “info”
• “debug”

The logging level is “info” by default:

export INORBIT_LOG_LEVEL="info" 

INORBIT_ACTIONS_PATH

Introduced in 3.20.0

Allows configuring the directory where the agent will look for the action scripts. If the agent detects it and confirms that the path is valid*, it will use that directory instead of the default ~/.inorbit/local/user_scripts/.  .

An example is:

export INORBIT_ACTIONS_PATH="/home/myrobot/inorbit_actions" 

*Please make sure that the path exists and that the user under which InOrbit’s agent is installed has execution permission for the action scripts.

INORBIT_ROS_UNREGISTER_PUBLISHERS

Introduced in 3.21.0

As of agent version 3.21.0, the InOrbit agent will avoid unregistering publishers when agentlets unload in order to work around a long-standing rospy known issue.

This variable, when set to TRUE , allows falling back to the previous behavior where each time an agentlet that has a publisher unloads, the publisher will be unregistered from the ROS system.

NOTE: This may cause repetitive warning messages in /rosout and inorbit.log

Introduction

The results of mission execution are the main determinant of autonomous robots’ usefulness. Data around mission performance also provides a feedback mechanism to pinpoint issues that affect individual robots or fleets and target opportunities to improve performance and reliability.

Missions vary considerably across applications, and could involve picking a specific item, scanning an aisle for inventory, or cleaning an area, as examples. Missions represent the work the robot does, and thus what your company or your customers are counting on when investing in robots.

As a platform, InOrbit offers different configurations to support different customer scenarios, processing mission data from wherever it is available, whether that is on the robots themselves or from the cloud or an edge server.

InOrbit consolidates information from monitoring and controlling missions to help bolster your understanding of your robot’s activity and overall performance (observability/operation) and identifies areas for improvement (optimization).

Missions can be started, cancelled, or otherwise managed via dedicated actions or through the API as in the examples below. The focus of this document is on mission tracking and its ability to provide visibility into the performance of selected sets of missions as well as the progress and data throughout any given mission

Product Offering

Mission Tracking is part of Enterprise Edition and can also be enabled separately as an Add-On. Standard Edition includes the same Mission Tracking capabilities with a lightweight version of Missions reporting.

When missions are enabled in InOrbit, mission information is available throughout the platform. Focusing on the default dashboards in InOrbit Control, missions are visible in several places:

• The Fleet and Robot dashboards have a Missions widget available with listings of current missions and filtering options to explore past missions.

• Time Capsule allows replaying a mission with all of its key data from that time interval.
• The Missions dashboard consists of several dedicated widgets
  • Mission control - Group, sort, filter missions to select the set to explore
  • Mission KPIs - Configurable KPIs for the primary metrics that reflect mission performance
  • Mission details - A table showing all selected missions with key data fields, including mission-specific data and the ability to launch Time Capsule

•  

Basic data required to represent a mission

Customers have different ways and terminology for  describing and representing missions. They could be quite broad (e.g., perform a multi-hour navigation of a region) or more akin to straightforward tasks (e.g., pick an object). InOrbit has created a flexible model to accommodate a wide range of scenarios, where Missions can fit whatever scale your “mission” is.

InOrbit provides a generalized data model, with mostly optional fields to map to your structures and terminology. There are some critical fields for accurate tracking, and others that can enhance the monitoring feedback, and in some cases it can be derived if your system does not explicitly report it.

For example, missions have scheduled start times (whether they are performed ad hoc or through a scheduler) and actual start and end times to determine whether a robot was on that mission at a particular time. Even the Mission name is optional, but it is easy and recommended to specify a name, which generally makes it easier to do correlations when monitoring multiple missions in real-time or reviewing past missions.

Missions also have a single current state at any given time. This is a freeform (customizable) label, although we offer a pre-defined set of states, such as Scheduled, In-Progress, Late, and Abandoned. Missions also have a current status, which is normally derived from the state, but could also be specified from your system. This is either OK, Warning, or Error. This is similar to overall data status in the InOrbit Platform, enabling consistent presentation and mission-based tracking, alerts, and potentially manual or automated actions for interventions.

Generally all labels and mappings are configurable, and we are happy to help you set up whatever unique structure you require. The platform also includes optional metadata for your specific scenario (e.g., number of picked items, payload, completed scans, signal strength).

Activating your data to be processed as missions

Robot missions can have widely differing scenarios, particularly in how they are triggered and where information is stored. InOrbit can track data directly from robots or integrate with your infrastructure, depending on where the information is made available. In some cases the robot itself determines that it is starting a mission based on some input (e.g., a front panel activated by a local operator). In other cases, there can be a cloud component (e.g., a scheduler or  controller) coordinating missions and ordering robots to start them.  It is possible that the robot does not know about the scope of the mission, or there isn’t a centralized component that knows about the missions.InOrbit provides a flexible API to accommodate these scenarios. The main entry point for missions is a REST Mission Tracking API, but in many cases it is not necessary to invoke this API directly; this is explained below

Mission data on robots

If mission data is best reported from the robots, the metadata can be published through the InOrbit agent. This involves publishing data sources (like any other data in InOrbit) and configuring them to tie to Mission data. For example, in a ROS environment, it is common to publish some “robot state” as “starting mission” or “going back to dock”; along with other metadata such as “delivery door number” or “route ID to execute”. By configuring these data sources in InOrbit cloud, the API calls are implicit (e.g., you can configure that publishing “robot status=starting mission” implies a call to the start of a mission).

As an advanced scenario that some customers prefer, you can also configure a pre-authenticated channel from the robot to the Missions API by publishing JSON-encoded data which will be mapped directly to API calls. This comes down to how you prefer to manage data on your robots for external communication.

These two scenarios are configured through Mission Tracking Config API, and correspond to “derived” and “api” values processingTypes. Refer to the API specs for details on how to configure each specific mission field and various options for Mission processing.

Mission data from servers or the cloud

If you have your own server- or cloud-based orchestrator or scheduler, you can call the Missions API directly via REST calls.

Missions controlled by human operators

If there is no centralized controller and the robot is directed by individual operators, your system can make direct calls to the API from a remote device, such as a mobile device or laptop, for instance based on a button selection by an operator on that device.

Missions Data Model

The Mission data model consists of “Mission” objects. They have a few basic properties, a number of optional properties, and placeholders for user-provided data. This data can be fed explicitly through APIs (e.g., via JSON objects), or inferred by the mission tracking service, as described below.

Schema

The Mission object structure is captured in the Mission Tracking API document, with details on creating and updating the mission along with the overall schema. Additional calls are available for querying (with filters), terminating, and retrieving information about missions.

The object is broken down as follows:

• missionId: a unique identifier for the mission
• robotId: the robot running (or to run) this mission
• Timestamps:
  • startTs, endTs: correspond to the mission start and end time. Any of them can be missing. For example when a mission is created and not running (as scheduled), they are not set.
  • scheduledTs: to set a planned execution timestamp.
  • updatedTs: a last-update timestamp, set by the system.
• State/Status:
  • inProgress: a boolean value for if the mission is currently executing. 
  • state: a string representing the state of the mission. See below for built-in states. 
  • status: one of the platform statuses: Ok, Warning or Error. It is used as an overall flag of the mission status. Related to the robot status in terms of values and colors used throughout the platform 
  • When updating a state, the services can guess the status and inProgress flags of the mission.
  • Color codings are available to represent mission status (+state) flags.

• Contents and progress:
  • completedPercent: An estimated percentage of completion. This can be set by a user invoking the APIs, as well as inferred  by the system. For example if there are 4 tasks and the user sets currentTaskId to the second one, a value 25 is guessed. If the tasks each contain an estimatedDurationSecs, the completion percentage calculation is more accurate.
  • estimatedDurationSecs: User-set estimated duration (or: calculated by the system as the sum of tasks’ estimatedDurationSecs).
  • currentTaskId: The task currently in execution
• Mission Metadata
  • arguments: free-form object with mission parameters, e.g. route id, room id, package ids, etc.
  • data: (reserved for collecting mission data during the run)

State and Statuses

The built-in mission states that are supported include:

State	Status (default)	Description
Scheduled	OK	Scheduled but not started
In progress	OK	Currently executing
Completed	OK	Successfully completed (can also have custom semantics)
Cancelled	ERR	Intentionally cancelled
Abandoned	ERR	Cancelled due to an error
Lost	ERR	Robot lost (mislocalized)
Paused	WARN	Paused (not necessarily late yet)
Late	WARN	Didn’t start on time or late beyond a threshold
Stale	WARN	Latest data exceeds a time threshold since update

Any number of user-defined states can be used. They can be associated with any status. See Mission Tracking configuration.

In ROS environments, it is also common to use ActionLib and report goal statuses. These can also be mapped to mission states. Contact us at at support@inorbit.ai for more details.

Mission Dashboard

The Missions dashboard is the primary place to explore missions in InOrbit Control. By default, this dashboard consists of 3 sections.

Mission KPIs

KPIs (Key Performance Indicators) provide a glanceable view of the real-time data that most matters to you about your selected set of missions. Sparklines are included in the display to provide appropriate recent trends for each KPI. InOrbit Control includes the following Mission KPIs by default:

• Mission success rate (%)
• Mission frequency (e.g., per day per robot)
• Average mission duration (hours:minutes:seconds)
• Average mission distance (e.g., meters)
• Average incidents per mission

KPIs also include an aggregate count of the selected set (e.g., missions and robots, as appropriate) included in the overall set, or in individual groups when selecting a grouping category. As mentioned above, this also enables very efficient comparison of sets of missions across the KPIs that are active.

The KPI set is fully extensible to automate any KPIs that our customers value (e.g., specific number of missions of different types, coverage, uptime), as long as InOrbit has access to that data for processing. Please contact us at support@inorbit.ai for any specific KPIs you would like to enable for your application, as we are happy to assist our customers with the process of customizing these.

Mission Control widget

As with the Fleet and Robot dashboards, there is a Mission Control widget for missions. This widget enables selecting sets of missions to focus on throughout the rest of the dashboard, with options for grouping, along with several types of filtering.

Grouping enables simple comparison of the aggregate data for different sets of missions (e.g., Location, Robot Type) for direct comparison. Filters are available for combinations of arbitrary sets of robots, tags, or mission states. There are also selectors for time and date range to easily go back a specific number of hours, days, or months or only include missions for a given date range.

Mission Details table

The Mission Details table provides high level detail on the individual missions that comprise the selected set. The table provides real-time and historic State information along with other basic data around the mission, including the Robot and Start and End time. Every mission can be expanded to see the data values that you select that best represents that mission for your purposes, along with a button to activate Time Capsule for that mission for deeper review of how it went and all of the critical time-series data associated with it.

Examples

While we have been focusing on the interactive selection and presentation of missions, here are some basic examples of using the API to access mission data and inform the mission tracking.

REST API calls

In this first example, we mark the start of a mission, send a mission update and complete it using REST API calls. 

First, we call the createMission API for a robot with id ID1234 and some basic data including a mission payload field direction.

curl --location --request POST 'https://api.inorbit.ai/missions' \

--header 'Content-Type: application/json' \

--header 'x-auth-inorbit-app-key: YOUR-APP-KEY \

--data-raw '{

   "robotId": "ID1234",

   "label": "Aisles 123-456",

   "arguments": {

       "direction": "North"

   }

 

}'

Note: In this example we used CURL to make explicit every HTTP header and payload that gets sent. We recommend testing the APIs with a similar tool or through a testing tool (e.g. Postman), although a production system will call these APIs programmatically. In the following examples we will omit such details and focus on the JSON payloads only.

The call above creates a mission. The API call receives back a JSON response with the mission data. Note that several fields are derived (in this case a state, several timestamps, and a missionId).

{

   "robotId": "gont-noetic",

   "label": "Aisles 123-456",

   "arguments": {

       "direction": "North"

   },

   "inProgress": false,

   "state": "scheduled",

   "status": "OK",

   "createdTs": 1640173104711,

   "updatedTs": 1640173104711,

   "scheduledTs": 1640173104711,

   "missionId": "37049929-8e15-4419-8a0d-2c14e3b5a90c"

}

This mission was created as “scheduled”, since no explicit state flag was set, and the inProgress flag was not set either. This could be a call from a mission planner or scheduler, pre-creating the mission. Next we will simulate starting it, this time calling the updateMission API (via HTTP PUT), with this payload:

{

   "inProgress": true,

   "completedPercent": 0.66

}

The API response includes the updated mission object with the new field values (and updated timestamps), omitted here for brevity.

Finally, we end the mission by setting the inProgress flag, and giving it a new state.

{

   "inProgress": true,

   "state": "completed",

   "completedPercent": 1.0

  

}

Dynamic Updates using Data Sources

The previous example assumes a scenario where the user can set up a component to communicate about missions to InOrbit. This can be from a mission planner, some ETL, or any cloud component based on the customer infrastructure.

In a different setting, the robots’ agents can be set up to propagate mission updates, knowing that in most cases the robots are aware of their own missions (start, end, status, mission metadata). For this scenario, the Missions Tracking support needs to be configured to connect some data sources to act as mission triggers. They can include:

A data source to act as a mission “delimiter”, with specific values to imply the start of a mission. This is normally related to Modes. For example a key-value data source such as “mode=delivery” can trigger the start of a mission.

Other data sources can be mapped to the mission label, the status and state flags, or any payload in the data field.

In this scenario, the same example as above could be accomplished via the following sequence (assuming a ROS agent publishing to InOrbit’s data sources topic):

• Publish mission=delivery  (At this point the mission is already marked as started, with no further data)
• Publish mission-target=Aisles 123-456 (sets the mission label)
• Publish scan-completion=0.66 (sets some progress)
• …
• Publish mission=docking (Ends the mission)

The advantage of this scenario is simplicity of implementation: It only requires that the robot implementation can broadcast mission-related information (for example with a republisher), and takes advantage of the secure, optimized data connection between the InOrbit agent and the cloud.

Advanced Configuration

As explained, there are several ways to configure and use InOrbit Mission Tracking. There are even more variants not covered in this document, including the possibility to time out missions after inactivity, selecting default values for some fields and preventing fields from overwriting each other when multiple concurrent updates happen. 

If you are missing any feature around Missions Tracking, chances are that the InOrbit team can configure them for you. Do not hesitate to contact us at at support@inorbit.ai for help.

InOrbit supports 2-way synchronization with Opsgenie, a platform for on-call and alert management used by DevOps teams. Through this premium integration:

• Incidents in InOrbit trigger alerts in Opsgenie
• Resolving incidents in InOrbit resolves the associated alerts in Opsgenie.
• Alerts created in Opsgenie can trigger incidents in InOrbit.
• Closing an alert originated in Opsgenie, resolves the incident in InOrbit.

In all cases, alerts in Opsgenie are enriched with data from InOrbit, including the latest events from the audit log, robot status and collections.

Enabling the integration:

1. Create API key in Opsgenie
2. In Opsgenie go the the integrations list and add Rest API HTTPS over JSON. Copy the generated API key.
   
   
   
3. Configure Opsgenie integration
   As administrator, login to InOrbit Control; in the upper right, click Settings in the 3 vertical dots menu, select the Admin tab and on the left menu click on integrations. Turn on Opsgenie and enter the API key from Step
4. Configure Opsgenie webhook 
   
   1. In Opsgenie go the the integrations list and add Webhook API
   2. Configure a custom header “x-opsgenie-webhook-token” using the value shown in InOrbit.
      
      
      
      
   3. This value can be obtained from InOrbit in the Opsgenie configuration section, “Opsgenie webhook token”:
      
      
   4. Check “Add Alert Description to Payload” and “Add Alert Details to Payload”
      
      
      
   5. Enter the Webhook URL obtained from InOrbit in the Opsgenie configuration section, “Opsgenie webhook URL”
      
      

Using Opsgenie as alert channel for an incident

Go to the incidents definitions page at Settings → Insights → Incidents. Edit or create an incident definition and select Opsgenie as the alert channel.

 

Next time the incident triggers, an alert will be created in Opsgenie.

 

Triggering an InOrbit incident from an Opsgenie alert

You can create an alert in Opsgenie specifying a robot name or id as the Entity.

This will automatically create an incident in InOrbit

 

InOrbit supports integration to any incident management platform or internal systems via webhooks and a REST API.

In order to receive events from InOrbit, your incident management system must provide a webhook. InOrbit then sends events to your webhook according to what you have configured, including when an incident is triggered. Webhook events are sent by InOrbit as POST requests to your webhook.

Setting up your Webhook

Setting up a callback URL for webhook events requires verification that you control or own the domain that hosts your application.

When you provide the webhook URL in Settings > Admin >Integrations, you will be sent a GET request including the header X-InOrbit-Key (a fixed value, randomly generated), which will contain the API key you see on the screen. Your server should respond with a status code of 200 and the API key that was sent.

Webhook Events

You will receive one webhook event per instance of an incident occurring.

For example, if you configured a Warning to be triggered when the Battery Level goes under 30%, you will receive a POST request when that happens.

{

  alertId: <Alert ID>,

  entity: {

     id: <Entity ID>,

     type: <Entity Type>,

     name: <Entity Name>,

  },

  message: <Message of the alert>,

  description: <Description, usually more detailed than message>,

  actions: <Possible actions that can be executed for the given alert>,

  componentId: <Component ID where the alert was triggered>,

  status: <Status, could be "new", "resolved">,

  ts: <Timestamp when the alert was triggered>,

  priority: <Severity of the current alert>

}

 

Incidents REST API

If you use an external incident management system to receive service requests, you may also trigger a corresponding incident within InOrbit by using the REST API. Incidents created and resolved using the API will be shown in InOrbit.

To enable the API, go to Settings > Admin > Integrations and turn on the toggle.

 

You can find the API specification at https://api.alpha.inorbit.ai/docs/robots.html. To obtain your API Key, select the green Authorize button.