Robot

Settings common to a user’s access to one robot.

exception bosdyn.client.robot.RobotError

Bases: Error

General class of errors to handle non-response non-grpc errors.

exception bosdyn.client.robot.UnregisteredServiceError

Bases: RobotError

Full service definition has not been registered in the robot instance.

exception bosdyn.client.robot.UnregisteredServiceNameError(service_name)

Bases: UnregisteredServiceError

Service name has not been registered in the robot instance.

exception bosdyn.client.robot.UnregisteredServiceTypeError(service_type)

Bases: UnregisteredServiceError

Service type has not been registered in the robot instance.

class bosdyn.client.robot.Robot(name=None)

Bases: object

Settings common to one user’s access to one robot.

This is the main point of access to all client functionality. The ensure_client member is used to get any client to a service exposed on the robot. Additionally, many helpers are exposed to provide commonly used functionality without explicitly accessing a particular client object.

Note that any rpc call made to the robot can raise an RpcError subclass if there are errors communicating with the robot. Additionally, ResponseErrors will be raised if there was an error acting on the request itself. An InvalidRequestError indicates a programming error, where the request was malformed in some way. InvalidRequestErrors will never be thrown except in the case of client bugs.

See also Sdk and BaseClient

property host

setup_token_cache(token_cache=None, unique_id=None)

Instantiates a token cache to persist the user token.

If the user provides a cache, it will be saved in the robot object for convenience.

update_from(other)

Adds to this object’s processors, etc. based on other

ensure_client(service_name, channel=None, options=[], service_endpoint=None)

Ensure a Client for a given service. Note: If a new service has been registered with the directory service, this may raise UnregisteredServiceNameError when trying to connect to it until sync_with_directory() is called.

Parameters:

• service_name – The name of the service.

• channel – gRPC channel object to use. Default None, in which case the Sdk data is used to generate a channel. The channel will become associated with the client.

Raises:

• UnregisteredServiceNameError – The service is not known.

• UnregisteredServiceTypeError – The client type for this service was never registered.

• RpcError – There was an error communicating with the robot.

shutdown()

get_cached_robot_id(timeout=None)

Return the RobotId proto for this robot, querying it from the robot if not yet cached.

Raises:

RpcError – There as a problem communicating with the robot.

get_cached_hardware_hardware_configuration(timeout=None)

Return the HardwareConfiguration proto for this robot, querying it from the robot if not yet cached.

Raises:

RpcError – There as a problem communicating with the robot.

ensure_channel(service_name, options=[], service_endpoint=None)

Verify the right information exists before calling the ensure_secure_channel method.

Parameters:

service_name – Name of the service in the directory.

Returns:

Existing channel if found, or newly created channel if not found.

Raises:

• RpcError – There was a problem communicating with the robot.

• UnregisteredServiceNameError – service_name is unknown.

ensure_secure_channel(authority, options=[])

Get the channel to access the given authority, creating it if it doesn’t exist.

authenticate(username, password, timeout=None)

Authenticate to this Robot with the username/password at the given service.

Raises:

• InvalidLoginError – The username and/or password are not valid.

• token_cache.WriteFailedError – Authentication succeeded, but failed to update the local token_cache.

• RpcError – There was a problem communicating with the robot.

authenticate_with_token(token, timeout=None)

Authenticate to this Robot with the token at the given service.

Raises:

• InvalidTokenError – The token was incorrectly formed, for the wrong robot, or expired.

• token_cache.WriteFailedError – Authentication succeeded, but failed to update the local token_cache.

• RpcError – There was a problem communicating with the robot.

authenticate_from_cache(username, timeout=None)

Authenticate to this Robot with a cached token at the given service.

Raises:

• token_cache.NotInCacheError – No token found for this robot/username.

• token_cache.WriteFailedError – Authentication succeeded, but failed to update the local token_cache.

authenticate_from_payload_credentials(guid, secret, payload_registration_client=None, timeout=None)

Authenticate to this Robot with the guid/secret of the hosting payload.

This call is used to authenticate to a robot using payload credentials. If a payload is not yet authorized, it will block until the payload is authorized by an operator in the robot web page.

Raises:

• InvalidPayloadCredentialsError – The guid and/or secret are not valid.

• token_cache.WriteFailedError – Authentication succeeded, but failed to update the local token_cache.

• RpcError – There was a problem communicating with the robot.

update_user_token(user_token, username=None)

Update this Robot with a user token.

Raises:

token_cache.WriteFailedError – Error saving to the cache.

get_cached_usernames()

Return an ordered list of usernames queryable from the cache.

get_id(id_service_name='robot-id')

Get all the information that identifies the robot.

list_services()

Get all the available services on the robot.

sync_with_directory()

Update local state with all available services on the robot.

Returns:

Mapping of service name to service type

Return type:

Dict[string, string]

sync_with_services_list(services_list)

Alternate version of sync_with_directory() that takes the list of services directly and does not perform any rpcs.

Returns:

Mapping of service name to service type

Return type:

Dict[string, string]

register_payload_and_authenticate(payload, secret, timeout=None)

Register a payload with the robot and request a user_token.

This method will block until the payload is authorized by an operator in the robot webpage. :raises InvalidPayloadCredentialsError: The guid and/or secret are not valid. :raises InvalidPayloadCredentialsError: The payload was rejected on the robot web page. :raises token_cache.WriteFailedError: Authentication succeeded, but failed to update the local token_cache. :raises RpcError: There was a problem communicating with the robot.

start_time_sync(time_sync_interval_sec=None)

Start time sync thread if needed.

Parameters:

time_sync_interval_sec (float) – The interval (in seconds) that the time-sync estimate should be updated.

stop_time_sync()

Stop the time sync thread if needed.

property time_sync

Accessor for the time-sync thread. Creates and starts thread if not already started.

time_sec()

Get current robot time, seconds. Kicks off background time sync thread if not started.

Returns:

Current robot time, seconds.

Return type:

double

operator_comment(comment, timestamp_secs=None, timeout=None)

Send an operator comment to the robot for the robot’s log files.

Parameters:

• comment (string) – Operator comment text to be added to the log.

• timestamp_secs (float) – Comment time in seconds since the unix epoch (client clock). If set, this is converted to robot time when sent to the robot. If None and time sync is available, the current time is converted to robot time and sent as the comment timestamp. If None and time sync is unavailable, the logged timestamp will be the time the robot receives this message.

• timeout (float) – Number of seconds to wait for RPC response.

Raises:

• NotEstablishedError – timestamp_secs given, but time-sync has not been achieved.

• RpcError – A problem occurred sending the comment to the robot.

log_event(event_type, level, description, start_timestamp_secs, end_timestamp_secs=None, id_str=None, parameters=None, log_preserve_hint=1)

Add an Event to the Data Buffer.

Parameters:

• event_type (string) – The type of event.

• level (bosdyn.api.Event.Level) – The relative importance of the event.

• description (string) – A human-readable description of the event.

• start_timestamp_secs (float) – Start of the event, in local time.

• end_timestamp_secs (float) – End of the event. start_timestamp_secs is used if None.

• id_str (string) – Unique id for event. A uuid is generated if None.

• parameters ([bosdyn.api.Parameter]) – Parameters to attach to the event.

power_on(timeout_sec=20, update_frequency=1.0, timeout=None)

Power on robot. This function blocks until robot powers on.

Parameters:

• timeout_sec (float) – Max time this function will block for.

• update_frequency (float) – Frequency at which power status is checked.

• timeout – Number of seconds to wait for RPC response.

Raises:

• PowerResponseError – Problem with the power on sequence.

• RpcError – Problem communicating with the robot.

• power_client.CommandTimedOutError – The robot did not power on within timeout_sec

power_off(cut_immediately=False, timeout_sec=20, update_frequency=1.0, timeout=None)

Power off robot. This function blocks until robot powers off. By default, this will attempt to put the robot in a safe state before cutting power.

Parameters:

• cut_immediately (bool) – True to cut power to the robot immediately. False to issue a safe power off command to the robot.

• timeout_sec (float) – Max time this function will block for.

• update_frequency (float) – Frequency at which power status is checked.

• timeout – Number of seconds to wait for RPC response.

Raises:

• RpcError – Problem communicating with the robot.

• power_client.CommandTimedOutError – The robot did not power off within timeout_sec

• PowerResponseError – If cut_immediately, raised on problems with the power on sequence.

• RobotCommandResponseError – If not cut_immediately, raised on problems with the safe power off.

is_powered_on(timeout=None)

Check the power state of the robot.

Parameters:

timeout – Number of seconds to wait for RPC response.

Returns:

Returns True if robot is powered on, False otherwise.

Return type:

bool

Raises:

RpcError – A problem occurred trying to communicate with the robot.

is_estopped(timeout=None)

Check if the robot is estopped, usually indicating if an external application has not

registered and held an estop endpoint.

Parameters:

timeout – Number of seconds to wait for RPC response.

Returns:

Returns True if robot is estopped, False otherwise.

Return type:

bool

Raises:

RpcError – A problem occurred trying to communicate with the robot.

get_frame_tree_snapshot(timeout=None)

Get the current frame tree snapshot from the robot state client.

Parameters:

timeout – Number of seconds to wait for RPC response.

Returns:

An instance of the bosdyn.api.FrameTreeSnapshot that contains data from the latest robot state.

Raises:

RpcError – A problem occurred sending the comment to the robot.

has_arm(timeout=None)

Check if the robot has an arm attached.

Parameters:

timeout – Number of seconds to wait for RPC response.

Returns:

Returns True if robot has an arm, False otherwise.

Return type:

bool

Raises:

RpcError – A problem occurred trying to communicate with the robot.

update_secure_channel_port(secure_channel_port)

Update the port used for creating secure channels, instead of using the default 443.

Calling this method does not change existing channels. It only affects secure channels created after this method is called.

Parameters:

secure_channel_port – New port to use for creating secure channels.