Elias Groot

Founding Member, Ex-Software Lead and Ex-Project Administrator

Debugging and Tuning

Debugging is the process of receiving data captured from a service's write stream and sending it to a roverctl-web instance.

Tuning is the process of modifying a service's variables during its runtime. Values can be tuned remotely from roverctl, which we call Over-the-Air (OtA) tuning. Tuning is not the same as modifying service.yaml parameters and tuned values are not persisted among service restarts.

Requirements

To allow for debugging and tuning, various components of the ASE framework work together:

• The Rover pipeline must have the transceiver service enabled
  • This service is enabled by default when you enable debug mode in roverctl
• A proxy webRTC server must be set up to take data from the transceiver running on the car, and pass it on to one or more roverctl-web clients
  • This is enabled by default when you start up roverctl with the --debug flag
• roverd must inject a bootspec into the transceiver's runtime with as inputs the outputs of all other enabled services in the pipeline
• All enabled services must receive the tuning object in their bootspec. This describes where they can listen to tuning updates.

Communication Pattern

When tuning and debugging is enabled, tuning state messages are sent as follows:

Debugging

Data flows from a Rover to a client (e.g. a laptop)

1. A service outputs a sensor output message on one of its write streams
2. The transceiver service captures this message, encapsulates it in debug metadata and forwards it to the roverctl webRTC proxy
3. The roverctl webRTC proxy forwards the message to all connected roverctl-web clients
4. The roverctl-web client plots or shows the data in the web interface, depending on its format

Tuning

Data flows from a client (e.g. a laptop) to a Rover

1. The roverctl-web client creates a tuning state message and sends it to the roverctl webRTC proxy
2. The roverctl webRTC proxy forwards the message to to the transceiver service running on the Rover
3. The transceiver service forwards the tuning state to all services over its tuning write stream
4. All services parse the tuning state (done by the roverlib) and update the internal variables if applicable

tunable variables

In a service.yaml configuration field, it is possible to specify whether or not a value is tunable. It is up to the service to discard or accept new tuning states based on this property. The transceiver will forward any tuning state, even if a field is considered not to be tunable.

Conventions

To make tuning and debugging work, the following conventions are in place:

1. Any service with name (not alias!) transceiver will be treated differently by roverd. When generating the bootspec, roverd will inject all outputs from other services as the inputs for the transceiver service
2. Services can use the tuning field in the bootspec to determine whether the transceiver service is enabled and set up a read stream if so. On this read stream they will receive tuning state messages which are parsed and managed by the roverlib
3. Only rovercom protobuf outputs can be debugged. Other output messages will be discarded. (For example if you are sending raw bytes for service communication)
4. A webRTC proxy can only have one connected transceiver service, but multiple connected roverctl-web clients (one-to-many from the Rover perspective)