Payload & Service Initialization

The files in this directory serve as an example of how a payload could register itself, register a service, and communicate to the service through the robot.

Payload Registration

Payloads are able to register themselves without the need for user credentials to be stored on the payload. A payload registration client can be used to communicate the details of the payload to the robot without need for authorization or authentication. All payloads registered this way must later be manually authorized by an admin via the Spot web UI. If the payload is attached to the robot, it should also be enabled on the webpage.

Once a payload has been authorized, its unique GUID & secret combination can be used as credentials to request a limited-access user token that wil grant permission to the auth, directory, and directory-registration services. The granted user token will be valid for 12 hours.

Payload registration & authorization needs to be done only once, as payload definitions will be kept on robot across reboots.

Service Registration

A new service can be registered in the robot directory, which requires a user token containing directory permissions. A user token can be requested by using the GUID & secret of an authorized payload. A directory registration client can be used to communicate the implementation and routing details of a service to the robot.

Service registration needs to be done after each power cycle, as the robot directory is reset when the robot is powered down.

Communication Between Client & Service

All endpoint details for routing requests to a service should have been provided at service registration time. When any client makes a request to the robot with an authority & service type matching a registered service, the request will be forwarded to the associated endpoint. It is assumed that a service will be running and available at the given endpoint to handle the request. Responses will be automatically routed back to the calling client. If no service is available, the request will time out.

CORE I/O

If you are working with a CORE I/O, this example demonstrates how you can set up a simple service on your CORE I/O and communicate to it through a client. Copy these example files onto the CORE I/O and set up the payload registration, service creation, and service registration there. Then, run the client on a laptop connected to the robot.

Set up

The proto definition files need to be compiled into python files before they can be used for this system. Following the gRPC documentation, these files can be generated by installing grpcio tools via python3 -m pip install grpcio-tools and then running python3 -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. announce.proto announce_service.proto.

Demo

The files in this directory can be used to set up the current computer as a payload, start up an announce service, register the announce service, and run a client to access the announce service through the robot. This section will walk the user through that process.

The explanation will follow the process laid out programmatically in the initialize_payload script, which automates this process. It is recommended that you go through the process manually first to gain an understanding of the process.

Select values

Setting up a payload and onboard services requires defining at least one payload, service, and endpoint. These definitions require multiple pieces of information properly represent the concept. Before beginning, select and record what values you want to use to populate these objects. Examples of valid values can be seen in the initialize_payload script.

Robot

  • ROBOT_IP - IP address the robot can be reached at.

Payload

  • GUID - GUID should be a uniquely generated GUID specific to a payload instance. The bosdyn.client.util.read_or_create_payload_credentials function can autogenerate a secure GUID and secret upon first-time payload registration such that these credentials can be reused on future registrations of the same payload on the same unit. If building a CORE I/O extension, we suggest writing this to a subdirectory of /data or /persist and mounting that file to your Extension’s Docker container.

  • Secret - Secret should be an arbitrary string unique to the payload instance. Human readability is not necessary.

  • Name - Name is a human-readable string used to identify a payload.

  • Description - Description is human-readable explanation of a payload.

  • Label_prefix - Label prefix is used to identify the type(s) of payload.

Service

  • Name - Unique name of this service instance.

  • Type - RPC service used to define communications with this service.

  • Authority - Authority to direct requests to.

  • User_token_required - Whether access to this service requires the user to have a token.

Endpoint

  • ENDPOINT_IP - IP address of the system running the service. Note, the command line utility provides a helper function for determining the correct IP address. This command must be run on the same computer that will be running the service:

python3 -m bosdyn.client {ROBOT_IP} self-ip

  • Port - A free port on the system to access to the service through.

Register the payload

self_register_payload.py can be used to register a single payload. The registered payload will be automatically set to unauthorized and disabled, until an admin updates it in the web console. The Python script will wait to exit until the registered payload is authorized. The payload added by the self_registered_payload.py script adds a payload with a preset configuration. When authorizing the payload in the admin page, the admin user can select the default configuration, or the preset configuration. See documentation on configuration of payload software for more information.

This example creates and persists the payload’s unique GUID/secret into a “payloads-credentials-file”. Simply choose a writeable, unique filename where you would like this to be stored upon first-time payload registration. For future registrations, if the payload GUID autogenerated into this file has already been registered, it will not be overwritten by additional registration requests.

python3 self_register_payload.py --payload-credentials-file <credentials-filename> --name <name_of_payload> --description <payload_description> ROBOT_IP

Start the announce service

announce_service.py can be used to start (and maintain) a very simple Python gRPC service. The service will accept announce requests with a message and return the message, in all caps, through an announce response. The service will continue to run until the user issues a keyboard interrupt or kills the PID. WARNING: The configured port must not be blocked by a firewall on the service hosting device.

python3 announce_service.py --port <endpoint_port>

Register the announce service

self_register_service.py can be used to register the announce service with the robot. Registering the service will tell the robot where to route Announce requests. In this case, we want these requests to be routed to the payload.

python3 self_register_service.py --payload-credentials-file <credentials-filename> --host-ip <endpoint_ip> --port <endpoint_port> ROBOT_IP

Access the announce service with a client

announce_client.py can be used to create an announce client and send a simple request to the announce service. If everything is set up correctly, the message sent to the service should be returned fully capitalized. The request will be routed through the robot, which will use the registered service description to forward the request to the payload. If the service name, type, or authority are incorrect, the request will fail to be routed.

python3 announce_client.py --payload-credentials-file <credentials-filename> --message <string_message> ROBOT_IP

Demo Script

The initialize_payload.sh script will automatically attempt to perform all steps listed above, as well as the compilation of the protobuf files. For the ease of getting started, most of the fields have been filled with adequate default values inside of the demo script. However, running the demo will still require manually setting the robot ip, endpoint ip, endpoint host, and a payload secret.

To use the demo, run:

chmod a+x initialize_payload.sh
./initialize_payload.sh <robot_ip> <endpoint_ip> <endpoint_port> <payload_credentials_file>

  • robot_ip - IP address the robot can be accessed at from the current system

  • endpoint_ip - IP address the current system can be accessed at from the robot

  • endpoint_port - An open port on the current system for the service to communicate through

  • payload_credentials_file - A file where the GUID and Secret for this instance are persistently written

Troubleshooting

If initialize_payload.sh fails to execute due to permission-related errors (e.g., Permission Denied), ensure the file has execute permissions, and if not, add them.

If initialize_payload.sh fails due to a bosdyn.client.exceptions.UnableToConnectToRobotError exception being raised, ensure that the robot is reachable at the supplied IP address and that your firewall is disabled.

If initialize_payload.sh fails due to a bosdyn.client.exceptions.TimedOutError exception being raised, ensure that the host is reachable at the supplied IP address and port and that your firewall is disabled.