feat: SOME/IP ↔ gRPC gateway (service-oriented cloud integration)

[vtz]

Summary

Implement a bidirectional gateway between SOME/IP (via opensomeip) and gRPC, enabling seamless integration between in-vehicle SOME/IP services and cloud/backend gRPC microservices. Both protocols are RPC-centric, making this a natural and clean mapping.

Motivation

The problem

Vehicle SOME/IP services need to communicate with cloud backends for OTA updates, remote diagnostics, digital twin synchronization, and data analytics. Cloud microservice architectures overwhelmingly use gRPC for inter-service communication. Bridging these requires translating between SOME/IP's binary RPC and gRPC's protobuf-based RPC.

The solution

┌─────────────────────────┐              ┌─────────────────────┐
│  In-Vehicle Network      │              │  Cloud Backend       │
│                          │              │                      │
│  ┌────────┐ ┌────────┐  │              │  ┌────────────────┐  │
│  │ ECU A  │ │ ECU B  │  │    gRPC      │  │  Digital Twin   │  │
│  │ SOMEIP │ │ SOMEIP │  │   (HTTP/2)   │  │  Service        │  │
│  └───┬────┘ └────┬───┘  │◄────────────►│  ├────────────────┤  │
│      │           │       │              │  │  OTA Update     │  │
│      ▼           ▼       │              │  │  Service        │  │
│  ┌───────────────────┐   │              │  ├────────────────┤  │
│  │  SOME/IP ↔ gRPC   │   │              │  │  Analytics      │  │
│  │  Gateway           │   │              │  │  Pipeline       │  │
│  └───────────────────┘   │              │  └────────────────┘  │
└─────────────────────────┘              └─────────────────────┘

Why this gateway matters

• Natural semantic mapping: Both SOME/IP and gRPC are RPC-oriented — request/response, service/method semantics map directly
• Protobuf efficiency: gRPC uses Protocol Buffers for serialization — compact, schema-driven, with excellent code generation and backward compatibility
• HTTP/2 transport: gRPC runs over HTTP/2, providing multiplexing, flow control, and TLS — ideal for vehicle-to-cloud over cellular
• Streaming: gRPC supports server-streaming and bidirectional streaming, mapping well to SOME/IP events
• Ecosystem: gRPC is supported in every major cloud platform (GCP, AWS, Azure) and every programming language

Technical Design

Communication Model Mapping

SOME/IP Concept	gRPC Concept	Mapping Strategy
Service (ServiceID)	gRPC Service	1:1 mapping via .proto service definition
Method (MethodID)	RPC Method	1:1 mapping: service.Method()
Event (publish)	Server-Streaming RPC	SOME/IP event → gRPC server stream push
Event (subscribe)	Server-Streaming RPC	gRPC client opens stream → gateway subscribes to SOME/IP event group
Request/Response	Unary RPC	Direct mapping
Fire-and-forget	Unary RPC (no response)	Map to unary with empty response

Proto Definition Pattern

Each bridged SOME/IP service gets a corresponding .proto definition:

syntax = "proto3";
package vehicle.gateway;

// Maps to SOME/IP Service 0x1234
service RadarService {
  // Maps to SOME/IP Method 0x0001 (request/response)
  rpc GetRadarData (RadarRequest) returns (RadarResponse);

  // Maps to SOME/IP Method 0x0002 (request/response)
  rpc CalibrateRadar (CalibrateRequest) returns (CalibrateResponse);

  // Maps to SOME/IP Event Group 0x0001 (server streaming)
  rpc StreamRadarObjects (StreamRequest) returns (stream RadarObjectUpdate);
}

message RadarRequest {
  uint32 range_meters = 1;
  float angle_degrees = 2;
}

message RadarResponse {
  repeated RadarObject objects = 1;
  uint64 timestamp_ns = 2;
}

message RadarObjectUpdate {
  RadarObject object = 1;
  uint64 sequence_number = 2;
}

Architecture

┌──────────────────────────────────────────────────────────────┐
│                    Gateway Process                            │
│                                                              │
│  ┌──────────────────────┐    ┌─────────────────────────────┐ │
│  │  SOME/IP Side         │    │  gRPC Side                   │ │
│  │                       │    │                              │ │
│  │  ┌─────────────────┐ │    │  ┌────────────────────────┐ │ │
│  │  │ opensomeip       │ │    │  │ gRPC Server             │ │ │
│  │  │ RpcClient/Server │ │    │  │ (exposes vehicle        │ │ │
│  │  │ EventPub/Sub     │ │    │  │  services to cloud)     │ │ │
│  │  │ SdClient/Server  │ │    │  ├────────────────────────┤ │ │
│  │  └────────┬──────────┘ │    │  │ gRPC Client             │ │ │
│  │           │           │    │  │ (calls cloud services   │ │ │
│  └───────────┼───────────┘    │  │  on behalf of vehicle)  │ │ │
│              ▼                │  └──────────┬─────────────┘ │ │
│  ┌───────────────────────┐    └──────────────┼──────────────┘ │
│  │   Translation Layer    │                   │               │
│  │                        │◄──────────────────┘               │
│  │  ┌──────────────────┐ │                                    │
│  │  │ Proto ↔ SOMEIP    │ │                                    │
│  │  │ Payload Mapper    │ │                                    │
│  │  │ (generated code)  │ │                                    │
│  │  └──────────────────┘ │                                    │
│  └───────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

Dual-Role Gateway

The gateway operates in two roles simultaneously:

1. gRPC Server (vehicle → cloud direction): Exposes in-vehicle SOME/IP services as gRPC endpoints. Cloud clients call gRPC methods → gateway translates to SOME/IP RPC calls to the actual ECU.

2. gRPC Client (cloud → vehicle direction): Subscribes to cloud gRPC services and translates responses/streams into SOME/IP events or method calls into the vehicle network.

Payload Translation

Two approaches, configurable per service:

Mode	Description	Use Case
Schema-driven	.proto definitions describe the payload; generated code handles serialization/deserialization	Production: type-safe, versioned, efficient
Generic/opaque	SOME/IP payload bytes wrapped in a generic protobuf message (bytes payload)	Prototyping: no per-service .proto needed

// Generic wrapper for opaque mode
message GenericSomeipMessage {
  uint32 service_id = 1;
  uint32 method_id = 2;
  uint32 client_id = 3;
  uint32 session_id = 4;
  uint32 return_code = 5;
  bytes payload = 6;
}

Configuration

# gateway-grpc.yaml
gateway:
  name: "someip-grpc-bridge"
  log_level: info

  grpc:
    server:
      listen_address: "0.0.0.0:50051"
      tls:
        cert: "/etc/gateway/server.pem"
        key: "/etc/gateway/server.key"
        ca: "/etc/gateway/ca.pem"
        mutual_tls: true
      max_concurrent_streams: 100
      keepalive_time_ms: 30000

    client:
      # Cloud services the gateway can call
      targets:
        - name: "ota_service"
          address: "ota.cloud.example.com:443"
          tls: true

  someip:
    interface: "eth0"
    sd_multicast: "239.255.255.250"
    sd_port: 30490

  service_mappings:
    - someip:
        service_id: 0x1234
        instance_id: 0x0001
      grpc:
        service: "vehicle.gateway.RadarService"
        proto_file: "protos/radar.proto"
      mode: schema_driven
      direction: someip_to_grpc  # Expose SOMEIP service as gRPC

    - someip:
        service_id: 0x5000
        instance_id: 0x0001
      grpc:
        service: "cloud.ota.UpdateService"
        target: "ota_service"
      mode: schema_driven
      direction: grpc_to_someip  # Cloud gRPC → vehicle SOMEIP

Error Mapping

SOME/IP Return Code	gRPC Status Code	Notes
E_OK	OK	Success
E_NOT_OK	INTERNAL	Generic failure
E_UNKNOWN_SERVICE	NOT_FOUND	Service not registered
E_UNKNOWN_METHOD	UNIMPLEMENTED	Method not found
E_NOT_READY	UNAVAILABLE	Service not ready
E_NOT_REACHABLE	UNAVAILABLE	ECU unreachable
E_TIMEOUT	DEADLINE_EXCEEDED	Request timed out
E_WRONG_PROTOCOL_VERSION	FAILED_PRECONDITION	Version mismatch
E_MALFORMED_MESSAGE	INVALID_ARGUMENT	Bad request

Dependencies

• opensomeip — SOME/IP protocol stack
• gRPC C++ — gRPC framework
• Protocol Buffers — Serialization (bundled with gRPC)
• yaml-cpp — Configuration parsing

Tasks

Phase 1: Unary RPC Bridge

• Set up gateway-grpc/ directory structure with CMakeLists.txt
• Integrate gRPC C++ as a CMake dependency
• Define generic protobuf wrapper (GenericSomeipMessage) for opaque mode
• Implement unary RPC bridge: gRPC client → gateway → SOME/IP method call (and response back)
• Implement reverse: SOME/IP method call → gateway → gRPC server endpoint
• Implement SOME/IP ↔ gRPC error code mapping
• Implement YAML configuration parsing
• Add TLS/mTLS support
• Add unit tests for payload mapping and error translation
• Add integration test with a mock gRPC service

Phase 2: Streaming & Events

• Implement server-streaming: SOME/IP events → gRPC server stream
• Implement client-streaming: gRPC client stream → SOME/IP fire-and-forget
• Implement bidirectional streaming for continuous data exchange
• Add schema-driven mode with code generation pipeline (.proto → C++ mapping code)
• Add SD bridge (SOME/IP offers → gRPC reflection / health check)
• Add integration tests for streaming scenarios

Phase 3: Production Hardening

• Connection management (reconnect, load balancing, circuit breaker)
• Performance benchmarking (latency, throughput, concurrent streams)
• Metrics integration (Prometheus-compatible: request counts, latency histograms, error rates)
• gRPC health checking and readiness probes
• Comprehensive documentation with deployment guide
• Example: vehicle digital twin with gRPC cloud service

Acceptance Criteria

• Unary RPC bridge works: gRPC call → SOME/IP method → response back to gRPC (and reverse)
• Server-streaming works: SOME/IP events → gRPC stream
• Error codes are correctly mapped between SOME/IP and gRPC
• TLS/mTLS works for secure connections
• Both opaque and schema-driven modes work
• Configuration file controls service mapping without recompilation
• All tests pass in CI
• Documentation includes architecture diagram, .proto examples, configuration reference

Related

• opensomeip#173 — Umbrella gateway initiative
• #1 — Repository initialization
• gRPC documentation
• gRPC C++ quickstart

[vtz]

Progress Update

Initial implementation complete in f045e7f.

Phase 1 Status

• gateway-grpc/ directory structure with CMakeLists.txt
• Generic protobuf wrapper (gateway.proto) for opaque mode
• SOME/IP ReturnCode ↔ gRPC StatusCode error mapping (bidirectional)
• Dual-role architecture (gRPC server + client)
• Unary RPC bridge stubs
• Server-streaming for SOME/IP events (stubs)
• TLS configuration support
• Unit tests (error code mapping, config, translation round-trip)
• Example: grpc_digital_twin (radar service, error mapping demo)
• opensomeip API usage: Message, Serializer, RpcClient, RpcServer, EventSubscriber, SdClient, SdServer, E2EProtection

Remaining (Phase 2+)

• Link against gRPC C++ and Protobuf (HAVE_GRPC)
• Full server-streaming implementation
• Schema-driven mode with per-service .proto code generation
• Health checking and readiness probes
• Performance benchmarking