Project Requirement Document: Automotive IVI System

Version: 2.0 Date: 2025-10-20

1. Project Overview

This document outlines the functional and non-functional requirements for an advanced, containerized In-Vehicle Infotainment (IVI) system. The system is composed of two primary components: a Frontend (FE) for user interaction and a Backend (BE) for business logic, hardware control, and data services. This version expands the system's capabilities to include a full suite of modern infotainment features: Core Vehicle Functions: Reverse camera, 3D model, HVAC, and engine dashboard. Multimedia & Infotainment: Local media playback (USB), Bluetooth audio streaming, and AM/FM Radio. Third-Party Streaming Services: Integration of YouTube and Netflix with appropriate safety interlocks. Phone Projection Technologies: Support for Apple CarPlay and Android Auto. Both components will be built and run as separate Docker containers, communicating over a robust and well-defined gRPC interface. 2. General System Requirements

Containerization: Both frontend and backend applications must be built using a Dockerfile, utilizing multi-stage builds for optimization. A docker-compose.yml file shall be provided to orchestrate the launch of all services (FE, BE, Kuksa Databroker) for a complete development and testing environment. Communication Protocol: The primary communication protocol between the frontend and backend shall be gRPC. All API contracts must be defined in .proto files, serving as the single source of truth for communication. Configuration: Service endpoints and other configurations must be injectable via environment variables. 3. System Architecture

The architecture is designed to be modular, separating concerns between UI rendering, business logic, and hardware access. 3.1. High-Level Architecture Diagram mermaid

graph TD subgraph User Interaction A[Frontend UI Container
(Qt/C++/QtWebEngine)] P[Connected Phone
(USB/Wi-Fi)] end

subgraph System Services
    B[Backend Logic Container <br/>(C++)]
    C[Kuksa Databroker <br/>(Container)]
end

subgraph Hardware Layer
    D[Camera]
    E[Speaker/Audio System]
    F[Vehicle CAN Bus]
    G[Bluetooth Module]
    H[USB Ports]
    I[AM/FM Tuner]
end

%% Data Flows
A -- gRPC API Requests --> B
B -- gRPC Data Streams --> A
B -- Connect/Subscribe/Publish --> C
C -- VSS Signals --> F

%% Hardware Abstraction
B -- HAL --> D
B -- HAL --> E
B -- HAL --> G
B -- HAL --> H
B -- HAL --> I

%% Phone Projection Flow
P -- Projection Protocol (USB/Wi-Fi) --> B
B -- Decoded Video Stream --> A
A -- Input Events --> B
B -- Input Events --> P

style A fill:#cde4ff
style B fill:#d5e8d4
style C fill:#e1d5e7
style P fill:#f8cecc

4. Frontend (FE) Project Requirements

4.1. Technical Stack Language: C++ (C++17 or newer) Framework: Qt 6 (or newer) Key Modules: Qt Core, Qt GUI, Qt QML, Qt WebEngine (for streaming apps) Build System: CMake Containerization: Docker 4.2. Functional Requirements Main Application & Feature Launcher: A main dashboard dynamically lists all available features. The user can launch and switch between features seamlessly. Reverse Camera Streaming: Displays a low-latency (<150ms) video stream from the backend when the vehicle is in reverse. 3D Car Model Viewer: Renders an interactive 3D model of the vehicle, capable of reflecting state changes (lights on/off, doors open/closed). HVAC Control & Vehicle Dashboard: Provides UI for climate control and displays real-time vehicle data (speed, RPM, light status) sourced from the backend. Multimedia Player UI: Provides a unified interface for all media sources. Bluetooth Audio: UI for device pairing, connection management, and displaying track information (via AVRCP). Provides playback controls (play/pause, next/previous). USB Media: A file browser to navigate directories on a connected USB drive. Supports audio and video file playback. AM/FM Radio: A classic radio interface with frequency display, seek/scan buttons, and presets. Third-Party Streaming Apps (YouTube/Netflix): The UI shall provide launch icons for YouTube and Netflix. These applications will run as web applications inside an integrated Qt WebEngine view. Safety Interlock: Video playback in these applications must be automatically paused or blanked when the vehicle speed exceeds a predefined threshold (e.g., 5 km/h). The audio may continue. The UI should display a message indicating that video is disabled while driving. Phone Projection UI (Apple CarPlay & Android Auto): The UI must detect when a compatible phone is connected and prompt the user to start a projection session. When a session is active, the frontend must dedicate a screen area to render the video stream from the phone. All touch inputs within this area must be captured and sent to the backend to be forwarded to the phone. 5. Backend (BE) Project Requirements

5.1. Technical Stack Language: C++ (C++17 or newer) Key Libraries: gRPC, Kuksa C++ library, libraries for Bluetooth (e.g., BlueZ), USB access (e.g., libusb), and projection protocols. Build System: CMake Containerization: Docker 5.2. Functional Requirements Efficient gRPC Server: An asynchronous, multi-threaded server to handle all frontend requests without blocking. Feature & Resource Management: Manages the state and resource allocation for all features (e.g., releasing the camera device when not in use). Hardware Abstraction Layer (HAL): A modular HAL that isolates logic from specific drivers. Expanded Interfaces: Camera Interface (V4L2) Audio Interface (ALSA/PulseAudio for routing and playback) Bluetooth Interface: Manages device scanning, pairing, and A2DP/AVRCP profiles. USB Interface: Detects, mounts, and reads media from USB mass storage devices. Radio Tuner Interface: Controls the physical AM/FM radio hardware. Kuksa Databroker Integration: Connects to Kuksa Databroker to subscribe to and publish vehicle signals. New Subscriptions: Must subscribe to Vehicle.Speed to enforce the video playback safety interlock. Multimedia Service: Provides a unified API for all media sources. Manages playback state (play, pause, shuffle, repeat). Scans USB devices for media files and builds a library. Forwards Bluetooth metadata (song title, artist) to the frontend. Phone Projection Service (CarPlay/Android Auto): This is a critical service responsible for the entire projection lifecycle. Device Discovery & Session Management: Detects phones connected via USB or Wi-Fi and handles the complex handshake and authentication protocols required by Apple CarPlay and Android Auto. Protocol Handling: Implements the core logic for encoding/decoding data packets for video, audio, and control messages. Video Forwarding: Receives the H.264 video stream from the phone, decodes it (or forwards it for hardware decoding), and streams the raw frames to the frontend via gRPC. Input Forwarding: Receives input coordinates from the frontend and translates them into the format expected by the projection protocol to be sent to the phone. Audio Routing: Manages the audio focus, ensuring that audio from the phone (navigation, music) is correctly routed to the vehicle's speakers. 6. API Specification (gRPC services.proto )

This extended definition includes services for the new features. protobuf syntax = "proto3";

package automotive.api;

// --- Core Services --- // Service for managing features service FeatureService { // Get a list of all available features rpc GetFeatures(Empty) returns (FeatureList); // Enable or disable a specific feature rpc ToggleFeature(FeatureToggleRequest) returns (FeatureState); } // Service for handling camera streams service CameraService { // Request the reverse camera video stream rpc StreamReverseCamera(Empty) returns (stream VideoFrame); }

// --- Expanded and New Services --- service VehicleDataService { rpc SubscribeVehicleState(Empty) returns (stream VehicleState); rpc SetHvacCommand(HvacCommand) returns (Empty); }

service MultimediaService { // Get available media sources (USB, Bluetooth, Radio) rpc GetMediaSources(Empty) returns (MediaSourceList); // Browse files on a source (e.g., USB) rpc Browse(BrowseRequest) returns (MediaItemList); // Control playback rpc PlaybackControl(PlaybackCommand) returns (Empty); // Get current playback status rpc SubscribePlaybackState(Empty) returns (stream PlaybackState); }

service ProjectionService { // Get status of projection services (e.g., "Disconnected", "Connecting", "Active") rpc SubscribeProjectionStatus(Empty) returns (stream ProjectionStatus); // Stream video from an active projection session rpc StreamProjectionVideo(Empty) returns (stream VideoFrame); // Send touch/input events from the UI to the phone rpc SendInputEvent(InputEvent) returns (Empty); }

// --- Message Definitions ---

message Empty {}

message VehicleState { // ... existing fields ... float vehicle_speed_kmh = 7; // For safety interlock }

message HvacCommand { optional int32 target_fan_speed_percent = 1; optional float target_temp_celsius = 2; }

message VideoFrame { bytes data = 1; // Raw or compressed frame data (e.g., MJPEG) int64 timestamp_us = 2; // Microsecond timestamp of the frame capture int32 width = 3; int32 height = 4; string format = 5; // e.g., "MJPEG", "RAW_RGB" } // ... other core messages ...

// --- Multimedia Messages --- message MediaSource { string id = 1; // e.g., "usb-1", "bt-device-mac", "fm-radio" string name = 2; // "USB Drive", "My Phone", "FM Radio" enum SourceType { USB = 0; BLUETOOTH = 1; RADIO = 2; } SourceType type = 3; } message MediaSourceList { repeated MediaSource sources = 1; } message PlaybackCommand { /* ... / } message PlaybackState { / ... / } message BrowseRequest { / ... / } message MediaItemList { / ... */ }

// --- Projection Messages --- message ProjectionStatus { enum Type { NONE = 0; ANDROID_AUTO = 1; APPLE_CARPLAY = 2; } Type active_type = 1; string device_name = 2; bool is_active = 3; }

message InputEvent { enum EventType { TOUCH_DOWN = 0; TOUCH_UP = 1; TOUCH_MOVE = 2; } EventType type = 1; int32 x = 2; int32 y = 3; } 7. Security and Certification Considerations

Container Security: All previous requirements (non-root user, minimal base images) still apply. API Security: mTLS for gRPC communication is now highly recommended due to the increased complexity and data handling. Content Protection (DRM): Integrating services like Netflix requires a Digital Rights Management (DRM) solution, typically Google Widevine. This requires a secure media path and certified software. The Qt WebEngine must be built with proprietary CDM (Content Decryption Module) support, which adds significant complexity and licensing requirements. This is a major project risk that must be investigated. Phone Projection Certification: Commercial use of Apple CarPlay requires enrolling in Apple's MFi (Made for iPhone/iPad) Program, which involves strict hardware, software, and user experience guidelines. Similarly, shipping a product with Android Auto requires a partnership with Google and passing their certification suite. Development can begin with open-source libraries, but a commercial product must use official, certified SDKs. 8. Testing Strategy

The testing strategy must be expanded to cover the new features. Unit Testing: Mock the new HAL interfaces for Bluetooth, USB, and Radio. Integration Testing: Multimedia: Create tests that place a sample media file on a virtual USB device (mounted into the BE container) and verify that the FE can browse and play it. Safety Interlock: Write an integration test that simulates Vehicle.Speed updates from Kuksa and verifies that the FE receives a command to disable video. End-to-End (E2E) Testing: CarPlay/Android Auto: This is difficult to fully automate. It will require manual testing with physical reference phones to verify session stability, video quality, and input responsiveness.

Gemini 2.5 Pro continue Thought for 21s Excellent. Let's complete the detailed requirements document by incorporating sections on the development pipeline, logging, documentation, and crucially, the risks and acceptance criteria associated with these advanced features. 9. Development & CI/CD Pipeline Requirements

To manage the increased complexity, a robust and automated pipeline is mandatory. Source Code Management: All code must reside in a Git repository with a clear branching strategy (e.g., GitFlow). All changes must be submitted via Pull Requests and require peer review. Continuous Integration (CI): A CI pipeline must automatically trigger on every push to lint, build, and test the code. Pipeline Stages: Code Analysis: Static analysis (e.g., cppcheck) and format checking (e.g., clang-format). Unit Test: Build and execute all unit tests for both FE and BE, reporting code coverage (target: >80%). Build Docker Images: Compile the applications and build the final, optimized Docker images. Integration Test: Use docker compose to launch the full application stack (FE, BE, mocked Kuksa) and run automated integration tests against the gRPC API. Push to Registry: On success, tag and push the Docker images to a secure container registry. Dependency Management: The pipeline must handle fetching external dependencies, including any proprietary SDKs for phone projection, which may require secure artifact storage. 10. Logging and Monitoring

Structured Logging: All services must log to stdout in a structured JSON format. Each log entry must include a timestamp, log level, service name, and a descriptive message to facilitate aggregation and searching. Health Checks: The Backend container must implement a HEALTHCHECK that verifies its gRPC server is responsive and its connection to Kuksa Databroker is active. The Frontend container's HEALTHCHECK should verify that the main Qt process and the QtWebEngine subprocess are running. Correlation IDs: For easier debugging of complex workflows (e.g., a UI touch event -> BE -> Projection -> Phone), requests should include a correlation ID that is passed and logged across services. 11. Documentation Requirements

README.md: Each project must have a comprehensive README.md covering its purpose, build instructions, and configuration. Code Documentation: Public APIs, classes, and complex functions must be documented using a Doxygen-compatible format to allow for automatic documentation generation. API Documentation: The .proto files, being the contract, must be well-commented. They are the definitive source of truth for the FE/BE API. Integration Guide: A separate document must be created detailing the steps for system integration, testing, and feature configuration (e.g., Bluetooth pairing, Wi-Fi setup for projection). Certification Artifacts: All design choices, test results, and documentation required for Apple MFi and Android Auto certification must be diligently collected and maintained throughout the project lifecycle. 12. Risks, Assumptions, and Mitigation

The introduction of streaming and projection features brings significant technical and business risks that must be addressed. 12.1. Assumptions Hardware Availability: The project assumes access to target-representative hardware with a compatible GPU (for video decoding), certified Bluetooth/Wi-Fi modules, and necessary peripherals (CAN interface, audio codec). Legal & Licensing: It is assumed that the project has the legal approval and budget to pursue official licensing and certification from Apple (MFi), Google (Android Auto), and potentially DRM providers (Widevine). Network Connectivity: The vehicle is assumed to have an external internet connection (e.g., LTE modem) for streaming services. The modem's management is outside the scope of this project. 12.2. Key Risks and Mitigation Strategies Risk ID Risk Description Probability Impact Mitigation Strategy R-01 Certification Failure: The system fails to meet the strict technical and user experience requirements for Apple CarPlay or Android Auto, blocking product launch. High Critical 1. Engage with Apple/Google programs early. 2. Procure official development kits and reference hardware. 3. Dedicate resources specifically to compliance and pre-certification testing. R-02 DRM Complexity: Integrating a DRM solution (e.g., Widevine) for Netflix is highly complex, requiring a secure media pipeline and potentially a Trusted Execution Environment (TEE) on the hardware. High High 1. Conduct an immediate Proof-of-Concept (PoC) to validate DRM playback on the target hardware. 2. Evaluate and select hardware with TEE capabilities. 3. Consider partnering with a specialized DRM integration company. R-03 Performance Bottlenecks: The SoC (System on a Chip) is unable to handle the combined load of the UI, web engine, and real-time video decoding for phone projection, leading to a poor user experience. Medium High 1. Define a reference hardware target early and conduct continuous performance profiling. 2. Offload video decoding to hardware accelerators (e.g., VA-API, V4L2 M2M). 3. Optimize all rendering paths and background processes. R-04 Third-Party Dependencies: Open-source libraries used for initial development (e.g., for projection protocols) may contain bugs, security flaws, or become unmaintained. Medium Medium 1. Choose libraries with active communities. 2. Fork key repositories to ensure control over the codebase. 3. Allocate development time for fixing upstream bugs and performing regular security vulnerability scans. 13. Acceptance Criteria

The project will be considered complete when the following high-level criteria are met and demonstrated. 13.1. Core System ✅ The FE and BE containers build successfully via the CI pipeline. ✅ The full system starts via docker compose and the main UI is responsive within 5 seconds. ✅ The reverse camera stream appears automatically when the Vehicle.Chassis.Transmission.CurrentGear VSS signal is set to reverse and has less than 150ms latency. ✅ The HVAC UI correctly reflects and controls the corresponding VSS signals in Kuksa. 13.2. Multimedia & Infotainment ✅ A user can pair an Android/iOS device via Bluetooth and stream audio. Track metadata (artist, title) is displayed on the UI. ✅ A user can connect a USB drive, browse its folders, and successfully play MP3 audio and MP4 video files (when stationary). ✅ The radio UI can scan for, tune to, and store AM/FM radio stations. 13.3. Streaming Services ✅ A user can launch the YouTube/Netflix web application from the main dashboard. ✅ Video playback in these applications is verifiably paused/blanked when Vehicle.Speed > 5 km/h, and resumes when the vehicle stops. (Dependency: Successful completion of DRM PoC for Netflix). 13.4. Phone Projection ✅ When an iPhone is connected via USB, the user is prompted, and the Apple CarPlay interface is successfully launched and displayed on the screen. ✅ When a compatible Android phone is connected, the user is prompted, and the Android Auto interface is successfully launched. ✅ Touchscreen inputs within the projection view are correctly passed to the phone (verified by launching and using an app like Maps). ✅ Audio from the projection session (e.g., navigation prompts, music) is correctly routed through the vehicle's audio system.