Directory Registration

Client for the directory registration service.

A DirectoryRegistrationClient allows a client to modify information about other API services available on a robot.

exception bosdyn.client.directory_registration.DirectoryRegistrationResponseError(response, error_message=None)[source]

Bases: ResponseError

General class of errors for directory registration responses.

exception bosdyn.client.directory_registration.ServiceAlreadyExistsError(response, error_message=None)[source]

Bases: DirectoryRegistrationResponseError

The service already exists on the robot.

exception bosdyn.client.directory_registration.ServiceDoesNotExistError(response, error_message=None)[source]

Bases: DirectoryRegistrationResponseError

The specified service does not exist on the robot.

class bosdyn.client.directory_registration.DirectoryRegistrationClient[source]

Bases: BaseClient

Write off-robot services and modify their information.

default_service_name = 'directory-registration'

service_type = 'bosdyn.api.DirectoryRegistrationService'

register(name, service_type, authority, host_ip, port, user_token_required=True, liveness_timeout_secs=0, **kwargs)[source]

Register a service routing with the robot.

If service name already registered, no change will be applied and will raise ServiceAlreadyExistsError. Every request received by the robot will serve as a heartbeat and update the service last_update field.

Parameters:

name – The name of the service. Must be unique.
service_type – The GRPC service definition defining the calls to/from this service. (authority, service_type) must be unique in the directory.
authority – The authority used to direct calls to this service. (authority, service_type) must be unique in the directory.
host_ip – The ip address of the system that the service is being hosted on.
port – The port number the service can be accessed through on the host system.
user_token_required – If a user token should be verified to access the service.
liveness_timeout_secs – Number of seconds without directory heartbeat before timeout fault.

Raises:

RpcError – Problem communicating with the robot.
ServiceAlreadyExistsError – The service already exists.
DirectoryRegistrationResponseError – Something went wrong during the directory registration.

update(name, service_type, authority, host_ip, port, user_token_required=True, liveness_timeout_secs=0, **kwargs)[source]

Update a service definition of an existing service that matches the service name.

If service name is not registered, will raise ServiceDoesNotExistError. Every request received by the robot will serve as a heartbeat and update the service last_update field.

Parameters:

name – The name of the service to be updated.
service_type – The GRPC service definition defining the calls to/from this service. (authority, service_type) must be unique in the directory.
authority – The authority used to direct calls to this service. (authority, service_type) must be unique in the directory.
host_ip – The ip address of the system that the service is being hosted on.
port – The port number the service can be accessed through on the host system.
user_token_required – If a user token should be verified to access the service.
liveness_timeout_secs – Number of seconds without directory heartbeat before timeout fault.

Raises:

RpcError – Problem communicating with the robot.
ServiceDoesNotExistError – The service does not exist.
DirectoryRegistrationResponseError – Something went wrong during the directory registration.

unregister(name, **kwargs)[source]

Remove a service routing with the robot.

Parameters:

name – The name of the service to be removed.

Raises:

RpcError – Problem communicating with the robot.
ServiceDoesNotExistError – The service does not exist.
DirectoryRegistrationResponseError – Something went wrong during the directory registration.

bosdyn.client.directory_registration.reset_service_registration(directory_registration_client, name, service_type, authority, host_ip, port, user_token_required=True, liveness_timeout_secs=0)[source]

Reset a service registration by unregistering the service and then re-registering it.

This is useful when a program wants to register a new service but there may be an old entry in the robot directory from a previous instance of the program. If the service does not already exist, the exception will be suppressed and a new registration will still be performed. Unregistering the service has the advantage of clearing all service faults, if any existed.

class bosdyn.client.directory_registration.DirectoryRegistrationKeepAlive(dir_reg_client, logger=None, rpc_timeout_seconds=None, rpc_interval_seconds=30)[source]

Bases: object

Helper class to keep a directory entry updated.

Assuming the directory itself is hosted on the robot, and the service being registered in the directory is on a payload, use of this class streamlines the following cases:

The payload, or the payload-hosted service, is restarted.
The robot is restarted.
On-robot processes clear out the directory. This can happen in rare cases.

This class will also maintain liveness status with the robot directory, if enabled for this service, by sending a registration/update request at the specified interval.

Parameters:

dir_reg_client – Client to the directory registration service.
logger – logging.Logger object to log with. Defaults to None, in which case one with the class name is acquired.
rpc_timeout_seconds – Number of seconds to wait for a dir_reg_client RPC. Defaults to None, for no timeout.
rpc_interval_seconds – Interval at which to request service registrations.

start(directory_name, service_type, authority, host, port, liveness_timeout_secs=None, user_token_required=True, reset_service=True)[source]

Register, optionally update, and then kick off thread.

Can not be restarted with this method after a shutdown.

Parameters:

directory_name – See directory.proto for details.
service_type – See directory.proto for details.
authority – See directory.proto for details.
host – See directory.proto for details.
port – See directory.proto for details.
liveness_timeout_secs – See directory.proto for details. Defaults to 2.5x rpc_interval_seconds.
user_token_required – See directory.proto for details.
reset_service – Fully reset the service registration before the periodic registrations.

Raises:

RpcError – Problem communicating with the robot.

is_alive()[source]

Are we still periodically re-registering?

Returns:: A bool stating if still alive

shutdown()[source]: Stop the background thread.

unregister()[source]

Remove service from the directory.

Raises:

RpcError – Problem communicating with the robot.
ServiceDoesNotExistError – The service does not exist.