Client

Scout Client is a client for a single Scout instance. The client uses the Scout web API to send HTTPs requests to a number of REStful endpoints using the Requests library.

class bosdyn.scout.client.ScoutClient(*args, **kwargs)

Bases: object

Client for Scout web API

Deprecated since version 4.0.0: Scout has been renamed to Orbit. Please, use bosdyn-orbit package instead of bosdyn-scout.

authenticate_with_password(username: str | None = None, password: str | None = None) → Response

Authorizes the client with username and password. Must call before using other client functions. If username and password are not provided, the function obtains credentials from either environment variables or terminal inputs.

Parameters:

• username – the username for the Scout instance

• password – the password for the Scout instance

Raises:

RequestExceptions – exceptions thrown by the Requests library

Returns::

requests.Response: the response associated with the login request

Deprecated since version 4.0.0: Please, use authenticate_with_api_token.

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

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

Parameters:

api_token – the API token obtained from the Scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout client is not authenticated properly

Returns:

The response associated with the post 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

• UnauthenticatedScoutClientError – indicates that the scout client is not authenticated properly

Returns:

The response associated with the delete request

get_scout_version(**kwargs) → Response

Retrieves info about a scout .

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout client is not authenticated properly

Returns:

the response associated with the get request

Return type:

requests.Response

get_scout_system_time(**kwargs) → Response

Returns scout’s current system time.

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout 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 scout instance.

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout 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 Scout instance

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout 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 scout instance

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout 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 site walk uuid, returns a site walk on the specified scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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 scout instance

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout 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 site element uuid, returns a site element on the specified scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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 scout instance

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout 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 site dock uuid, returns a site dock on the specified scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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 scout instance

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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 scout instance

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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 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

• UnauthenticatedScoutClientError – indicates that the scout 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 scout instance

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_site_element(**kwargs) → Response

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

• UnauthenticatedScoutClientError – indicates that the scout client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_site_walk(**kwargs) → Response

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

• UnauthenticatedScoutClientError – indicates that the scout client is not authenticated properly

Returns:

the response associated with the post request

Return type:

requests.Response

post_site_dock(**kwargs) → Response

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

• UnauthenticatedScoutClientError – indicates that the scout 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 scout instance

Parameters:

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

Raises:

• RequestExceptions – exceptions thrown by the Requests library

• UnauthenticatedScoutClientError – indicates that the scout 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 Scout 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 Scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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 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

• 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

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

Given a site walk uuid, deletes the site walk associated with the uuid on the specified scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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 scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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 scout 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

• UnauthenticatedScoutClientError – indicates that the scout 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 scout 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

• UnauthenticatedScoutClientError – indicates that the scout client is not authenticated properly

Returns:

the response associated with the delete request

Return type:

requests.Response

bosdyn.scout.client.create_scout_client(options: argparse.Namespace) → bosdyn.scout.client.ScoutClient

Creates a Scout client object.

Parameters:

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

Returns:

Scout client object.

Return type:

scout_client