Client

The client uses a web API to send HTTPs requests to a number of REStful endpoints using the Requests library.

class bosdyn.orbit.client.Client(hostname: str, verify: bool = True, cert: str | None = None)[source]

Bases: object

Client for the Orbit web API

authenticate_with_api_token(api_token: str | None = None) Response[source]

Authorizes the client using the provided API token obtained from the instance. Must call before using other client functions.

Parameters:

api_token – the API token obtained from the instance

Raises:

RequestExceptions – exceptions thrown by the Requests library

get_resource(path: str, **kwargs) Response[source]

Base function for getting a resource in /api/v0/

Parameters:
  • path – the path appended to /api/v0/

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

post_resource(path: str, **kwargs) Response[source]

Base function for posting a resource in /api/v0/

Parameters:
  • path – the path appended to /api/v0/

  • kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

The response associated with the post request

delete_resource(path: str, **kwargs) Response[source]

Base function for deleting a resource in /api/v0/

Parameters:
  • path – the path appended to /api/v0/

  • kwargs – a variable number of keyword arguments for the delete request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

The response associated with the delete request

get_version(**kwargs) Response[source]

Retrieves version info.

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_system_time(**kwargs) Response[source]

Returns the current system time.

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_robots(**kwargs) Response[source]

Returns robots on the specified instance.

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_robot_by_hostname(hostname: str, **kwargs) Response[source]

Returns a robot on given a hostname of a specific robot.

Parameters:
  • hostname – the IP address associated with the desired robot on the instance

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_site_walks(**kwargs) Response[source]

Returns site walks on the specified instance

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_site_walk_by_id(uuid: str, **kwargs) Response[source]

Given a site walk uuid, returns a site walk on the specified instance

Parameters:
  • uuid – the ID associated with the site walk

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_site_elements(**kwargs) Response[source]

Returns site elements on the specified instance

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_site_element_by_id(uuid: str, **kwargs) Response[source]

Given a site element uuid, returns a site element on the specified instance

Parameters:
  • uuid – the ID associated with the site element

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_site_docks(**kwargs) Response[source]

Returns site docks on the specified instance

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_site_dock_by_id(uuid: str, **kwargs) Response[source]

Given a site dock uuid, returns a site dock on the specified instance

Parameters:
  • uuid – the ID associated with the site dock

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_calendar(**kwargs) Response[source]

Returns calendar events on the specified instance

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_run_events(**kwargs) Response[source]

Given a dictionary of query params, returns run events

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_run_event_by_id(uuid: str, **kwargs) Response[source]

Given a runEventUuid, returns a run event

Parameters:
  • uuid – the ID associated with the run event

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_run_captures(**kwargs) Response[source]

Given a dictionary of query params, returns run captures

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_run_capture_by_id(uuid: str, **kwargs) Response[source]

Given a runCaptureUuid, returns a run capture

Parameters:
  • uuid – the ID associated with the run capture

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_runs(**kwargs) Response[source]

Given a dictionary of query params, returns runs

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_run_by_id(uuid: str, **kwargs) Response[source]

Given a runUuid, returns a run

Parameters:
  • uuid – the ID associated with the run

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_run_archives_by_id(uuid: str, **kwargs) Response[source]

Given a runUuid, returns run archives

Parameters:
  • uuid – the ID associated with the run

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_image(url: str, **kwargs) urllib3.response.HTTPResponse[source]

Given a data capture url, returns a decoded image

Parameters:
  • url – the url associated with the data capture in the form of https://hostname + RunCapture[“dataUrl”].

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the decoded response associated with the get request

Return type:

urllib3.response.HTTPResponse

get_image_response(url: str, **kwargs) Response[source]

Given a data capture url, returns an image response

Parameters:
  • url – the url associated with the data capture in the form of https://hostname + RunCapture[“dataUrl”]

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the image response associated with the get request

Return type:

requests.Response

get_webhook(**kwargs) Response[source]

Returns webhook on the specified instance

Parameters:

kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_webhook_by_id(uuid: str, **kwargs) Response[source]

Given a uuid, returns a specific webhook instance

Parameters:
  • uuid – the ID associated with the webhook

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_robot_info(robot_nickname: str, **kwargs) Response[source]

Given a robot nickname, returns information about the robot

Parameters:
  • robot_nickname – the nickname of the robot

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_export_as_walk(site_walk_uuid: str, **kwargs) Response[source]

Given a site walk uuid, it exports the walks_pb2.Walk equivalent

Parameters:
  • site_walk_uuid – the ID associated with the site walk

  • kwargs – a variable number of keyword arguments for the get request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_import_from_walk(**kwargs) Response[source]

Given a walk data, imports it to the specified instance

Parameters:

kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_site_element(**kwargs) Response[source]

Create a site element. It also updates a pre-existing Site Element using the associated UUID.

Parameters:

kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_site_walk(**kwargs) Response[source]

Create a site walk. It also updates a pre-existing Site Walk using the associated UUID.

Parameters:

kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_site_dock(**kwargs) Response[source]

Create a site element. It also updates a pre-existing Site Dock using the associated UUID.

Parameters:

kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_robot(**kwargs) Response[source]

Add a robot to the specified instance

Parameters:

kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_calendar_event(nickname: str = None, time_ms: int = None, repeat_ms: int = None, mission_id: str = None, force_acquire_estop: bool = None, require_docked: bool = None, schedule_name: str = None, blackout_times: ~collections.abc.Iterable[dict[slice(<class 'str'>, <class 'int'>, None)]] = None, disable_reason: str = None, event_id: str = None, **kwargs) Response[source]
This function serves two purposes. It creates a new calendar event on using the following arguments

when Event ID is not specified. When the Event ID associated with a pre-existing calendar event is specified, the function overwrites the attributes of the pre-existing calendar event.

Parameters:
  • nickname – the name associated with the robot

  • time_ms – the first kickoff time in terms of milliseconds since epoch

  • repeat_ms – the delay time in milliseconds for repeating calendar events

  • mission_id – the UUID associated with the mission( also known as Site Walk)

  • force_acquire_estop – instructs the system to force acquire the estop when the mission kicks off

  • require_docked – determines whether the event will require the robot to be docked to start

  • schedule_name – the desired name of the calendar event

  • blackout_times – a specification for a time period over the course of a week when a schedule should not run specified as list of a dictionary defined as {“startMs”: <int>, “endMs” : <int>} with startMs (inclusive) being the millisecond offset from the beginning of the week (Sunday) when this blackout period starts and endMs (exclusive) being the millisecond offset from beginning of the week(Sunday) when this blackout period ends

  • disable_reason – (optional) a reason for disabling the calendar event

  • event_id – the auto-generated ID for a calendar event that is already posted on the instance. This is only useful when editing a pre-existing calendar event.

  • kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_calendar_events_disable_all(disable_reason: str, **kwargs) Response[source]

Disable all scheduled missions

Parameters:
  • disable_reason – Reason for disabling all scheduled missions

  • kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_calendar_event_disable_by_id(event_id: str, disable_reason: str, **kwargs) Response[source]

Disable specific scheduled mission by event ID

Parameters:
  • event_id – eventId associated with a mission to disable

  • disable_reason – Reason for disabling a scheduled mission

  • kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_calendar_events_enable_all(**kwargs) Response[source]

Enable all scheduled missions

Parameters:

kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_calendar_event_enable_by_id(event_id: str, **kwargs) Response[source]

Enable specific scheduled mission by event ID

Parameters:
  • event_id – eventId associated with a mission to enable

  • kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_webhook(**kwargs) Response[source]

Create a webhook instance

Parameters:

kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_webhook_by_id(uuid: str, **kwargs) Response[source]

Update an existing webhook instance

Parameters:
  • uuid – the ID associated with the desired webhook instance

  • kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_return_to_dock_mission(robot_nickname: str, site_dock_uuid: str, **kwargs) Response[source]

Generate a mission to send the robot back to the dock

Parameters:
  • robot_nickname – the nickname of the robot

  • site_dock_uuid – the uuid of the dock to send robot to

  • kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_dispatch_mission_to_robot(robot_nickname: str, driver_id: str, mission_uuid: str, delete_mission: bool, force_acquire_estop: bool, **kwargs) Response[source]

Dispatch the robot to a mission given a mission uuid

Parameters:
  • robot_nickname – the nickname of the robot

  • driver_id – the current driver ID of the mission

  • mission_uuid – uuid of the mission(also known as Site Walk) to dispatch

  • delete_mission – whether to delete the mission after playback

  • force_acquire_estop – whether to force acquire E-stop from the previous client

  • kwargs – a variable number of keyword arguments for the post request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

delete_site_walk(uuid: str, **kwargs) Response[source]

Given a site walk uuid, deletes the site walk associated with the uuid on the specified instance

Parameters:
  • uuid – the ID associated with the desired site walk

  • kwargs – a variable number of keyword arguments for the delete request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the delete request

Return type:

requests.Response

delete_robot(robot_hostname: str, **kwargs) Response[source]

Given a robot hostname, deletes the robot associated with the hostname on the specified instance

Parameters:
  • robot_hostname – the IP address associated with the robot

  • kwargs – a variable number of keyword arguments for the delete request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the delete request

Return type:

requests.Response

delete_calendar_event(event_id: str, **kwargs) Response[source]

Delete the specified calendar event on the specified instance

Parameters:
  • event_id (string) – the ID associated with the calendar event

  • kwargs – a variable number of keyword arguments for the delete request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the delete request

Return type:

requests.Response

delete_webhook(uuid: str, **kwargs) Response[source]

Delete the specified webhook instance on the specified instance

Parameters:
  • uuid – the ID associated with the desired webhook

  • kwargs – a variable number of keyword arguments for the delete request

Raises:
  • RequestExceptions – exceptions thrown by the Requests library

  • UnauthenticatedClientError – indicates that the client is not authenticated properly

Returns:

the response associated with the delete request

Return type:

requests.Response

bosdyn.orbit.client.create_client(options: argparse.Namespace) bosdyn.orbit.client.Client[source]

Creates a client object.

Parameters:

options – User input containing hostname, verification, and certification info.

Returns:

‘bosdyn.orbit.client.Client’ object

Return type:

client