gRPC API Overview

Overview of AlpaSim’s gRPC service architecture for autonomous vehicle simulation

AlpaSim uses gRPC for inter-service communication, enabling distributed simulation of autonomous vehicles. The gRPC API is defined using Protocol Buffers and consists of several specialized services.

Architecture

The simulation runtime coordinates multiple services via gRPC:

┌──────────────────┐
│  AlpaSim Runtime │
└────────┬─────────┘
         │
         ├──────► SensorSim Service (rendering)
         ├──────► Traffic Service (background actors)
         ├──────► Physics Service (ground interaction)
         ├──────► Controller Service (vehicle dynamics)
         └──────► Driver Service (ego behavior)

Core Services

Controller Service

Vehicle dynamics controller and propagation

Driver Service

Autonomous driving policy and planning

Physics Service

Ground intersection and collision detection

SensorSim Service

Camera and LiDAR rendering

Traffic Service

Background vehicle simulation

Common Types

All services share common message types defined in common.proto:

Pose

Represents a 3D pose with translation and rotation.

vec · Vec3

Translation vector (x, y, z in meters)

quat · Quat

Rotation quaternion (w, x, y, z)

Trajectory

A sequence of poses over time.

poses · PoseAtTime[]

Array of timestamped poses

DynamicState

Velocity and acceleration information.

angular_velocity · Vec3

Angular velocity (rad/s)

linear_velocity · Vec3

Linear velocity (m/s)

linear_acceleration · Vec3

Linear acceleration (m/s²)

angular_acceleration · Vec3

Angular acceleration (rad/s²)

Coordinate Systems

All services follow consistent coordinate frame conventions:

• Local frame: World/map coordinate system
• Rig frame: Vehicle body-fixed frame (origin at rear axle center)
• AABB frame: Bounding box center frame

Transforms are specified as “active transforms” (e.g., local->rig transforms points from local to rig frame).

See CONTRIBUTING.md in the source repository for detailed coordinate system documentation.

Session Management

Most services support session-based workflows:

1. Start Session: Initialize service with configuration
2. Execute Operations: Perform rendering, simulation, etc.
3. Close Session: Clean up resources

# Example session workflow
status = service.start_session(session_request)
# ... perform operations ...
service.close_session(close_request)

Version Compatibility

All services implement get_version() returning:

version_id · string

Semantic version (e.g., “0.3.0”)

git_hash · string

Git commit hash of the service

grpc_api_version · APIVersion

gRPC API version (major, minor, patch)

Protocol Buffer Files

Proto definitions are located at:

src/grpc/alpasim_grpc/v0/
├── common.proto       # Shared types
├── controller.proto   # Vehicle dynamics
├── egodriver.proto    # Autonomous driver
├── physics.proto      # Ground physics
├── sensorsim.proto    # Sensor rendering
└── traffic.proto      # Traffic simulation

Code Generation

Generate Python stubs from proto files:

./setup_local_env.sh  # Compiles protos automatically

Generated code is available in the alpasim_grpc package:

from alpasim_grpc.v0 import common_pb2
from alpasim_grpc.v0 import controller_pb2_grpc