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: bosdyn.client.exceptions.ResponseError

General class of errors for directory registration responses.

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

Bases: bosdyn.client.directory_registration.DirectoryRegistrationResponseError

The service already exists on the robot.

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

Bases: bosdyn.client.directory_registration.DirectoryRegistrationResponseError

The specified service does not exist on the robot.

class bosdyn.client.directory_registration.DirectoryRegistrationClient[source]

Bases: bosdyn.client.common.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, application_token_required=False, 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.

  • application_token_required – Deprecated - Do not use.

  • liveness_timeout_secs – Number of seconds without directory heartbeat before timeout fault.

Raises
update(name, service_type, authority, host_ip, port, user_token_required=True, application_token_required=False, 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.

  • Deprecated - Do not use. (application_token_required) –

  • liveness_timeout_secs – Number of seconds without directory heartbeat before timeout fault.

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

Remove a service routing with the robot.

Parameters

name – The name of the service to be removed.

Raises
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 exists, the exception will be surpressed 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:

  1. The payload, or the payload-hosted service, is restarted.

  2. The robot is restarted.

  3. 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