Driver Service

Autonomous driving policy and trajectory planning API

The Driver Service (EgodriverService) implements the autonomous driving policy. It receives sensor observations and produces planned trajectories for the ego vehicle.

Service Definition

service EgodriverService {
    rpc start_session (DriveSessionRequest) returns (common.SessionRequestStatus);
    rpc close_session (DriveSessionCloseRequest) returns (common.Empty);
    rpc submit_image_observation (RolloutCameraImage) returns (common.Empty);
    rpc submit_egomotion_observation (RolloutEgoTrajectory) returns (common.Empty);
    rpc submit_route (RouteRequest) returns (common.Empty);
    rpc submit_recording_ground_truth (GroundTruthRequest) returns (common.Empty);
    rpc drive (DriveRequest) returns (DriveResponse);
    rpc get_version (common.Empty) returns (common.VersionId);
    rpc shut_down (common.Empty) returns (common.Empty);
}

Methods

start_session

Initialize a driving session with vehicle and scene configuration.

session_uuid · string · required

Unique identifier for this driving session

random_seed · uint64 · required

Random seed for reproducible behavior

rollout_spec · RolloutSpec · required

Vehicle specification

Show RolloutSpec.VehicleDefinition

available_cameras · AvailableCamera[]

List of cameras available on the vehicle with intrinsics and extrinsics

debug_info · DebugInfo

Debug information (not present in benchmark runs)

Show DebugInfo

scene_id · string

Scene identifier for debugging

submit_image_observation

Provide camera images to the driver for perception.

session_uuid · string · required

Session identifier

camera_image · CameraImage · required

Show CameraImage

frame_start_us · uint64

Frame capture start timestamp (microseconds)

frame_end_us · uint64

Frame capture end timestamp (for rolling shutter)

image_bytes · bytes

Encoded image data (PNG/JPEG)

logical_id · string

Camera identifier (e.g., “camera_front_wide_120fov”)

submit_egomotion_observation

Provide estimated ego vehicle trajectory (localization output).

session_uuid · string · required

Session identifier

trajectory · Trajectory · required

Estimated ego rig pose as active transform local→rig_est.

This can diverge from the true local→rig transform when error models are enabled.

dynamic_state · DynamicState · required

Estimated velocities and accelerations at current timestamp in rig frame. May include noise when error models are active.

submit_route

Provide high-level route waypoints to the driver.

session_uuid · string · required

Session identifier

route · Route · required

Show Route

timestamp_us · uint64

Timestamp at which the route is valid

waypoints · Vec3[]

Waypoints expressed in rig frame at the provided timestamp

submit_recording_ground_truth

Provide ground truth trajectory from recording (for testing/validation).

session_uuid · string · required

Session identifier

ground_truth · GroundTruth · required

Show GroundTruth

timestamp_us · uint64

Timestamp at which the ground truth is valid

trajectory · Trajectory

Ground-truth trajectory from recording (actual path followed). Each pose is expressed in rig frame at the provided timestamp.

drive

Request a planned trajectory from the driver.

session_uuid · string · required

Session identifier

time_now_us · uint64 · required

Current simulation time (microseconds)

time_query_us · uint64 · required

Time for which trajectory is requested

renderer_data · bytes

Optional arbitrary data from renderer for advanced use cases

trajectory · Trajectory

Planned trajectory as active transform local→rig_est produced by the driver

debug_info · DebugInfo

Show DebugInfo

unstructured_debug_info · bytes

Binary debug data with custom serialization

sampled_trajectories · Trajectory[]

Alternative trajectories considered by planner

close_session

Release resources for a session.

session_uuid · string · required

Session identifier to close

Usage Example

From alpasim_runtime/services/driver_service.py:

from alpasim_grpc.v0 import egodriver_pb2, egodriver_pb2_grpc
import grpc

# Connect to driver service
channel = grpc.insecure_channel('localhost:50051')
driver_stub = egodriver_pb2_grpc.EgodriverServiceStub(channel)

# Start session
session_request = egodriver_pb2.DriveSessionRequest(
    session_uuid="my-session",
    random_seed=42,
    rollout_spec=egodriver_pb2.DriveSessionRequest.RolloutSpec(
        vehicle=egodriver_pb2.DriveSessionRequest.RolloutSpec.VehicleDefinition(
            available_cameras=camera_specs
        )
    )
)
driver_stub.start_session(session_request)

# Submit observations
driver_stub.submit_image_observation(
    egodriver_pb2.RolloutCameraImage(
        session_uuid="my-session",
        camera_image=egodriver_pb2.RolloutCameraImage.CameraImage(
            frame_start_us=t_start,
            frame_end_us=t_end,
            image_bytes=image_data,
            logical_id="camera_front_wide_120fov"
        )
    )
)

driver_stub.submit_egomotion_observation(
    egodriver_pb2.RolloutEgoTrajectory(
        session_uuid="my-session",
        trajectory=ego_trajectory,
        dynamic_state=ego_state
    )
)

# Request driving plan
response = driver_stub.drive(
    egodriver_pb2.DriveRequest(
        session_uuid="my-session",
        time_now_us=current_time,
        time_query_us=query_time
    )
)

planned_trajectory = response.trajectory
print(f"Planned {len(planned_trajectory.poses)} poses")

# Clean up
driver_stub.close_session(
    egodriver_pb2.DriveSessionCloseRequest(session_uuid="my-session")
)

Data Flow

The driver service follows this typical workflow:

1. Session Initialization: Configure vehicle and scene
2. Observation Loop:
   • Receive camera images via submit_image_observation
   • Receive localization via submit_egomotion_observation
   • Receive route via submit_route
3. Planning: Generate trajectory with drive
4. Session Cleanup: Close session when done

Related

• SensorSim Service - Generates camera images
• Controller Service - Executes planned trajectories
• Runtime Module - Orchestrates driver service calls