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)

Bases: object

Client for the Orbit web API

authenticate_with_api_token(api_token: str | None = None) → Response

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

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

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.

patch_resource(path: str, **kwargs) → Response

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

Parameters:

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

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library.

• UnauthenticatedClientError – indicates that the client is not authenticated properly.

Returns:

The response associated with the patch request.

delete_resource(path: str, **kwargs) → Response

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

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

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

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

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

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

Given a SiteWalk uuid, returns a SiteWalk on the specified instance.

Parameters:

• uuid – the ID associated with the SiteWalk.

• 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_archive_by_id(uuid: str, **kwargs) → Response

Returns SiteWalk as a zip archive which represents a collection of graph and mission data

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_elements(**kwargs) → Response

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

Given a SiteElement uuid, returns a SiteElement on the specified instance.

Parameters:

• uuid – the ID associated with the SiteElement.

• 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

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

Given a SiteDock uuid, returns a SiteDock on the specified instance.

Parameters:

• uuid – the ID associated with the SiteDock

• 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

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

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

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

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

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

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

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

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

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

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

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

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

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

Given a SiteWalk uuid, it exports the walks_pb2.Walk equivalent.

Parameters:

• site_walk_uuid – the ID associated with the SiteWalk.

• 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

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

Create a SiteElement. It also updates a pre-existing SiteElement 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

Create a SiteWalk. It also updates a pre-existing SiteWalk 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

Create a SiteElement. It also updates a pre-existing SiteDock 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

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 = None, time_ms: int | None = None, repeat_ms: int | None = None, mission_id: str | None = None, force_acquire_estop: bool | None = None, require_docked: bool | None = None, schedule_name: str | None = None, blackout_times: Iterable[Dict[str, int]] | None = None, disable_reason: str | None = None, event_id: str | None = None, **kwargs) → Response

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 SiteWalk).

• 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

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

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

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

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

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

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

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, skip_initialization: bool, **kwargs) → Response

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 SiteWalk) to dispatch.

• delete_mission – whether to delete the mission after playback.

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

• skip_initialization – whether to skip initialization when starting the return to dock 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_backup_task(include_missions: bool, include_captures: bool, **kwargs) → Response

Starts creating a backup zip file.

Parameters:

• include_missions – Specifies whether to include missions and maps in the backup.

• include_captures – Specifies whether to include all inspection data captures in the backup.

• **kwargs – Additional keyword arguments for the backup request.

Raises:

• RequestExceptions – Exceptions thrown by the Requests library.

• UnauthenticatedClientError – Indicates that the client is not authenticated properly.

Returns:

The response associated with the backup request.

Return type:

requests.Response

patch_bulk_close_anomalies(element_ids: list[str], **kwargs) → Response

Bulk close Anomalies by Element ID.

Parameters:

• element_ids – the element ids of each anomaly to be closed.

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library.

• UnauthenticatedClientError – indicates that the client is not authenticated properly.

Returns:

The response associated with the patch request.

Return type:

requests.Response

patch_anomaly_by_id(anomaly_uuid: str, patched_fields: dict, **kwargs) → Response

Patch an Anomaly by uuid.

Parameters:

• anomaly_uuid – The uuid of the anomaly to patch fields in.

• patched_fields – A dictionary of fields and new values to change in the specified anomaly.

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library.

• UnauthenticatedClientError – indicates that the client is not authenticated properly.

Returns:

The response associated with the patch request.

Return type:

requests.Response

delete_site_walk(uuid: str, **kwargs) → Response

Given a SiteWalk uuid, deletes the SiteWalk associated with the uuid on the specified instance.

Parameters:

• uuid – the ID associated with the desired SiteWalk

• 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

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

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

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

delete_backup(task_id: str, **kwargs)

Deletes the backup zip file from the Orbit instance.

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

bosdyn.orbit.client.create_client(options: argparse.Namespace) → bosdyn.orbit.client.Client

Creates a client object.

Parameters:

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

Returns:

‘bosdyn.orbit.client.Client’ object

Return type:

client