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.
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.
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 timeout.
If you are working with a Spot CORE, this example demonstrates how you can set up a simple service on your Spot CORE and communicate to it through a client. Copy these example files onto the Spot CORE and set up the payload registration, service creation, and service registration there. Then run the client on a laptop connected to the robot.
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.
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 programatically 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 proces.
Setting up a payload and onboard services requires defining at least one payload, service, and endpoint. These definitons 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.
IP - IP address the robot can be reached at.
GUID - GUID should be a uniquely generated GUID specefic to a payload instance.
Secret - Secret should be an arbitrary string. Human readability is not necessary.
Name - Name is a human-readable string used to identify a payload.
Description - Description is humand-readable explanation of a payload.
Label_prefix - Label prefix is used to identify the type(s) of payload.
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.
IP - IP address of the system running the service.
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. If the payload GUID has already been registered, it will not be overwritten by additional registration requests. 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.
python3 self_register_payload.py --guid <payload_guid> --secret <payload_secret> --name <payload_name> --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 --guid <payload_guid> --secret <payload_secret> --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 --guid <payload_guid> --secret <payload_secret> --message <string_message> ROBOT_IP
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
initialize_payload.sh <robot_ip> <endpoint_ip> <endpoint_port> <payload_secret>
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_secret - A private 16 character string unique to this payload instance