Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/NVlabs/alpasim/llms.txt

Use this file to discover all available pages before exploring further.

The Controller Service (VDCService) provides vehicle dynamics simulation and control. It propagates vehicle state forward in time using a controller and vehicle model.

​
Service Definition

service VDCService {
  rpc get_version(common.Empty) returns (common.VersionId);
  rpc start_session (VDCSessionRequest) returns (common.SessionRequestStatus);
  rpc close_session (VDCSessionCloseRequest) returns (common.Empty);
  rpc run_controller_and_vehicle(RunControllerAndVehicleModelRequest)
      returns (RunControllerAndVehicleModelResponse);
  rpc shut_down(common.Empty) returns (common.Empty);
}

​
Methods

​
start_session

Initialize a controller session with vehicle configuration.
​
session_uuid
string
required
Unique identifier for this session
​
vehicle_and_controller_params
VehicleAndControllerParams
required
Vehicle and controller configuration
​
status
SessionRequestStatus
Empty message indicating session started successfully

​
run_controller_and_vehicle

Propagate vehicle state forward in time using the controller and vehicle model.
​
session_uuid
string
required
Session identifier from start_session
​
state
StateAtTime
required
Current vehicle state
  • state.pose: Active transform local→rig (rig frame origin)
  • Angular and linear rates resolved in rig frame
​
planned_trajectory_in_rig
Trajectory
required
Desired trajectory expressed in rig frame at the timestamp of the first pose. Each pose is relative to the rig origin.
​
future_time_us
int64
required
Target timestamp (microseconds) at the end of propagation
​
coerce_dynamic_state
bool
During initialization/replay phase, match dynamic state in vehicle model to prevent drift. Set to true during the priming phase at simulation start.
​
pose_local_to_rig
PoseAtTime
Ground-truth active transform local→rig after propagation
​
pose_local_to_rig_estimated
PoseAtTime
Estimated active transform local→rig after propagation (may include sensor noise)
​
dynamic_state
DynamicState
Ground-truth velocity and acceleration in rig frame after propagation
​
dynamic_state_estimated
DynamicState
Estimated velocity and acceleration in rig frame (may include sensor noise)

​
close_session

Release resources associated with a session.
​
session_uuid
string
required
Session identifier to close

​
Usage Example

From alpasim_runtime/services/controller_service.py: 
from alpasim_grpc.v0 import controller_pb2, controller_pb2_grpc
from alpasim_grpc.v0.common_pb2 import StateAtTime, Trajectory

# Initialize session
session_request = controller_pb2.VDCSessionRequest(
    session_uuid="my-session-uuid",
    vehicle_and_controller_params=controller_pb2.VDCSessionRequest.VehicleAndControllerParams(
        rig_file="/path/to/rig.yaml",
        amend_files=[]
    )
)
status = controller_stub.start_session(session_request)

# Propagate vehicle state
request = controller_pb2.RunControllerAndVehicleModelRequest(
    session_uuid="my-session-uuid",
    state=current_state,
    planned_trajectory_in_rig=desired_trajectory,
    future_time_us=future_timestamp,
    coerce_dynamic_state=False
)

response = controller_stub.run_controller_and_vehicle(request)
print(f"New pose: {response.pose_local_to_rig}")
print(f"Dynamic state: {response.dynamic_state}")

# Clean up
controller_stub.close_session(
    controller_pb2.VDCSessionCloseRequest(session_uuid="my-session-uuid")
)

​
Configuration

The rig file specifies vehicle parameters such as:
  • Vehicle mass and inertia
  • Wheel parameters
  • Controller gains (MPC parameters)
  • Actuator limits
See the source repository’s configs/ directory for example rig files.

​
Coordinate Frames

The rig frame origin is at the mid-bottom rear edge of the vehicle bounding box.
  • X: Forward (vehicle heading)
  • Y: Left
  • Z: Up
The controller operates in this frame for vehicle dynamics calculations.