Payload Software Interface¶
To log payload data and debug payload issues, payloads developed for the Spot platform should observe the following guidelines:
Payloads gather and generate their own log data.
Payloads generate and send their own text annotations to mark robot logs for preservation.
Each payload component provides access to its own debug data.
Logic on the payload determines what data to log and when to log it.
Payload API services¶
The API provides two services for managing and registering payloads and payload services:
Robot directory services are used to register services that a payload might offer so that they can be exposed on the robot.
RemoteMissionService RPCs are called by MissionService to communicate with a robot payload. The mission service uses these RPCs to communicate with a remote mission service.
|EstablishSession||Call this once at mission load time, per node.|
|Tick||Call this every time the RemoteGrpc node is ticked.|
|Stop||Call this every time the RemoteGrpc node was ticked in the previous cycle, but not ticked in this cycle.|
|TeardownSession||Tells the service it can forget any data associated with the given session.|
|GetServiceEntry||Get information about a specific service.|
|ListServiceEntries||List all known services at the time of the request.|
|RegisterService||Called by a system to announce, via the robot directory, a new service it is hosting.|
|UnregisterService||Called by a system to deregister a service from the robot directory.|
|UpdateService||Update the ServiceEntry for a system hosting a service.|
|ListPayloads||Query the robot for a list of currently-registered payloads.|
|RegisterPayload||Register a new payload with the robot.|
|GetPayloadAuthToken||Get an auth token to enable the payload.|
This code snippet example uses the API to communicate payload configuration settings to Spot. The example first registers a payload then lists all payloads on the robot, including the newly registered payload.
... # Authenticate robot before being able to use it robot.authenticate(config.username, config.password) # Create a payload registration client payload_registration_client = robot.ensure_client( PayloadRegistrationClient.default_service_name) # Create a payload payload = payload_protos.Payload() payload.GUID = '78b076a2-b4ba-491d-a099-738928c4410c' payload.name = 'Client Registered Payload Ex' payload.description = 'This payload was created and registered by the register_payload.py client example.' payload.label_prefix.append("test_payload") payload.is_authorized = False payload.is_enabled = False payload.is_noncompute_payload = False # Register the payload payload_registration_client.register_payload(payload) # Create a payload client payload_client = robot.ensure_client(PayloadClient.default_service_name) # List all payloads payloads = payload_client.list_payloads() print(payloads) ...
Refer to the Python payload registration code example in the Spot SDK for details.
The Payload Registration API gives developers the ability to deploy payloads that register themselves with the robot when they power on without the need to store an app token or user credentials on the payload.
The payload registration process completes after an admin operator accepts the payload using the robot’s admin console. If the payload has registered itself, it should appear in the Payload section of the admin console.
Payloads can register API services. Example: A LIDAR payload registers RemoteService callbacks to trigger scans during robot missions.
Payload and service registration do not require an app token or robot user credentials.
Once a payload has been authorized, its unique GUID and secret combination can be used as credentials to request a limited-access user token that will grant permission to the auth, directory, robot-state, and directory-registration services. The granted user token will be valid for 12 hours.
Payload and service registration examples¶
The Spot SDK Python code examples includes payload registration and service registration examples that provide sample scripts, protos, and a list of dependencies: Self-registration Python code examples in the Spot SDK.
Payload device network configuration¶
The robot’s default private IP address is 192.168.80.3. Users can configure these properties via the robot’s admin console. Use the network settings to change the robot’s network configuration from WiFi AP to WiFi client.
The robot’s rear ethernet port can be configured to a user desired IP address via the web interface. By default, its IP is set to 10.0.0.3.
Payload devices should use the following network configuration:
IP v4 host address 192.168.50.5 for the front payload, 192.168.50.6 for rear payload
Default gateway gateway will be set to 192.168.50.3
Devices on the payload network can reach the robot at 192.168.50.3 via port 443. Devices on the robot network can reach payload services as follows:
TCP traffic sent to the robot’s IP address on ports 20022, 20080, or 20443 will be forwarded to 192.168.50.5 on ports 22, 80, or 443.
TCP/UDP traffic sent to the robot’s IP address on ports 21000-22000 will be forwarded to 192.168.50.5 on that same port.
TCP traffic sent to the robot’s IP address on ports 30022, 30080, or 30443 will be forwarded to 192.168.50.6 on ports 22, 80, or 443.
TCP/UDP traffic sent to the robot on ports 31000-32000 will be forwarded to 192.168.50.6.
Payload port forwarding table¶
|Standard Forwards 1||20000 + [22, 80, 443]||192.168.50.5:[22, 80, 443]||TCP|
|Fixed Forwards 1||21000-22000||18.104.22.168:21000-22000||TCP/UDP|
|Standard Forwards 2||30000 + [22, 80, 443]||192.168.50.6:[22, 80, 443]||TCP|
|Fixed Forwards 2||31000-32000||22.214.171.124:31000-32000||TCP/UDP|
Configuring payload mass properties¶
In order to locomote properly, the robot needs to know the physical properties of any payload it is carrying. This includes the center of mass location relative to the base link of the robot, moments of inertia, and other values.
A payload self-registration service is available as part of the Spot 2.0 SDK.
The following payload configuration table shows configuration values for the Spot CORE payload as they would appear in the robot’s admin console GUI.
This table provides a reference when developing a client application using the the RegisterPayload RPC to register a Spot payload.
Total mass (kg)¶
Position of Center of Mass (m)¶
Moment of inertia tensor (kg-m2)¶
Bounding boxes: \ Center (m)¶
Bounding boxes: \ Orientation (radians) ZXY¶