Remote Engine Control API Developer Guide

Service Overview

Remote Engine Control is a telematics service that allows users to remotely start or stop the vehicle's engine through a mobile application.

Service Features

Remote engine start/stop control functionality
Pre-boarding vehicle interior environment preparation (linked with climate control)
Secure with automatic engine shutdown policy
Security and safety policy application
Compliance with country-specific regulations

Legal Requirements

Strong security policy required for vehicle physical control functionality
Compliance with personal information protection laws
Two-way authentication (between server and vehicle)
Command execution Audit Log recording
Compliance with country-specific remote start related laws

Key Scenarios

Scenario 1: Remote Engine Start Request and Execution

API Flow by Entity:

📱 App (User):

Engine Start Request: Request after Correlation ID generation
Command Reception: Receive 202 Accepted response
Push Notification: Receive engine control result push notification
UI Update: Update UI if response within 30 seconds, ignore if timeout

🚗 Vehicle (TCU):

Command Reception: Receive engine control command from ECARUS
Safety Verification: Verify safety conditions like door, gear, key status
Engine Control Execution: Start engine if conditions satisfied
Result Publication: Publish success/failure results to ECARUS

🏢 Call Center:

Proxy Request: Proxy request after Correlation ID generation
Command Reception: Receive 202 Accepted response
WebSocket Event: Real-time reception of engine control results

Scenario 2: Engine Control Failure and Safety Shutdown Processing

API Flow by Entity:

📱 App (User):

Command Request: Engine start/stop command request
Failure Notification: Receive failure reasons via push notification
Status Check: Check current engine status
Command Cancellation: Cancel executing command

🚗 Vehicle (TCU):

Safety Verification: Verify safety conditions like door open, driving status
Failure Processing: Generate failure reasons when safety violations occur
Result Publication: Publish failure results to ECARUS
Automatic Shutdown: Automatic engine shutdown when safety violations occur

🏢 Call Center:

History Query: Query failure history
Diagnostics Check: Check system diagnostics
Customer Support: Analyze failure causes and guide customers

Scenario 3: Engine Status Monitoring and Settings Management

API Flow by Entity:

📱 App (User):

Status Query: Real-time engine status check
History Query: Check engine control history
Real-time Monitoring: Monitor status changes via SSE stream
Command Cancellation: Cancel command if needed

🚗 Vehicle (TCU):

Status Collection: Real-time collection of engine status, fuel level, temperature
Status Transmission: Transmit collected status data to ECARUS
Settings Application: Apply user settings like maximum execution time
Automatic Events: Automatic publication of events like engine stop

🏢 Call Center:

Status Monitoring: Real-time vehicle engine status check
Settings Management: Manage remote start settings and Update environment settings
Diagnostics Management: Perform regular system diagnostics
Proxy Stop: Proxy engine stop in emergencies

Key Features

📱 Features to Implement in App

1. Remote Engine Control Function

Engine Start: Request remote engine start
Engine Stop: Request remote engine stop
Command Cancellation: Request cancellation of executing command

2. Status Monitoring Function

Status Query: Immediate engine status query
Real-time Updates: Real-time status monitoring via SSE stream

3. History Management Function

History Query: Query engine control history
Failure Analysis: Check failure causes and retry

4. Notification and UI Functions

Push Notifications: Receive engine control result push notifications
Timer Management: Response processing based on 30-second timeout
Correlation ID: Generate unique ID for request tracking

🏢 Features to Implement in Call Center

4. Customer Support Function

SSE Connection: Real-time event reception
Problem Solving: Support problem solving based on system diagnostics
Security Monitoring: Monitor abnormal access patterns

🚗 Functions Processed by Vehicle (TCU)

1. Command Execution Function

Engine Control: Control engine start/stop
Safety Verification: Verify execution conditions based on vehicle status
Result Publication: Publish execution results via MQTT

2. Status Management Function

Status Collection: Collect engine status, fuel level, temperature
Status Transmission: Transmit real-time status data
Automatic Events: Automatic publication of events like engine stop

3. Safety Function

Safety Verification: Verify door, gear, key status
Automatic Shutdown: Automatic engine shutdown when safety violations occur

Sequence Diagram

Remote Engine Control System Flow

Remote Engine Control

API Endpoints

Refer to the Common API Specifications for headers, response codes, and error formats.

Engine Start

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/start" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"targetTemperature": 24.0, "climateControl": true, "duration": 1800}'

Engine Stop

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/stop" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"force": false, "reason": "User stop", "preserveClimate": false}'

Engine Control Cancellation

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/cancel" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"correlationId": "uuid-12345678", "reason": "User cancellation", "force": false}'

Engine Control Status Query

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/status?includeDetails=true" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Engine Control History Query

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/history?period=24h&limit=50" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Engine Control Settings Query

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Engine Control Settings Update

bash

curl -X PUT "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"remoteStartEnabled": true, "maxRunTime": 1800, "autoStopEnabled": true, "securityRequired": true, "climateControl": true}'

Engine Diagnostics Query

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/diagnostics" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Engine Operation Status Real-time Query (SSE)

Note: Recommended to access via browser or use a dedicated SSE client

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/updates/stream" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Accept: text/event-stream"

Data Models

Engine Start Request

json

{
  "targetTemperature": 24.0,
  "climateControl": true,
  "duration": 1800
}

targetTemperature: Target temperature (°C)
climateControl: Air conditioner control flag
duration: Execution time (seconds, maximum 3600)

Engine Stop Request

json

{
  "force": false,
  "reason": "User stop",
  "preserveClimate": false
}

reason: User stop, Emergency, System error, Security violation
force: Force stop flag (default: false)
preserveClimate: Air conditioner maintenance flag

Engine Cancellation Request

json

{
  "correlationId": "uuid-12345678",
  "reason": "User cancellation",
  "force": false
}

reason: User cancellation, Emergency stop, System error, Timeout
force: Force cancellation flag (default: false)

Engine Status Request (Query Parameters)

includeDetails: true

includeDetails: Include detailed information flag

Engine Control Response

json

{
  "commandId": "cmd-uuid-12345",
  "vin": "KMHSH81C7LU123456",
  "status": "PENDING",
  "message": "Command received",
  "estimatedDuration": 5,
  "timestamp": "2026-01-12T08:30:00Z"
}

status: PENDING, IN_PROGRESS, SUCCESS, FAILED, TIMEOUT
estimatedDuration: Estimated execution time (seconds)

Engine Status Response

json

{
  "vin": "KMHSH81C7LU123456",
  "isRunning": true,
  "isRemoteStarted": true,
  "remainingTimeSec": 420,
  "startTime": "2026-01-12T08:30:00Z",
  "autoStopReason": null,
  "climateActive": true,
  "targetTemperature": 24.0,
  "currentTemperature": 18.5,
  "fuelLevel": 65.5,
  "engineTemperature": 85.2,
  "timestamp": "2026-01-12T08:33:00Z"
}

autoStopReason: DURATION_TIMEOUT, LOW_FUEL, HIGH_TEMPERATURE, USER_STOP, SECURITY_VIOLATION

Engine Control History Request (Query Parameters)

period: 24h
limit: 50
offset: 0
action: START

period: 1h, 24h, 7d, 30d
action: START, STOP, CANCEL, STATUS_CHECK

Engine Control History Response

json

{
  "vin": "KMHSH81C7LU123456",
  "history": [
    {
      "commandId": "cmd-uuid-12345",
      "action": "START",
      "status": "SUCCESS",
      "timestamp": "2026-01-12T08:30:00Z",
      "executionTime": 45,
      "duration": 585,
      "autoStopReason": "DURATION_TIMEOUT",
      "userId": "user-123",
      "source": "MOBILE_APP",
      "failureReason": null,
      "targetTemperature": 24.0
    }
  ],
  "total": 1,
  "hasMore": false
}

status: SUCCESS, FAILED, TIMEOUT, CANCELLED
source: MOBILE_APP, CALL_CENTER, WEB, VOICE_ASSISTANT

Engine Control Settings Response

json

{
  "vin": "KMHSH81C7LU123456",
  "remoteStartEnabled": true,
  "maxRunTime": 1800,
  "autoStopEnabled": true,
  "securityRequired": true,
  "climateControl": true,
  "defaultTemperature": 22.0,
  "lowFuelThreshold": 15.0,
  "highTemperatureThreshold": 105.0,
  "updatedTime": "2026-01-12T10:00:00Z"
}

maxRunTime: Maximum execution time (seconds)
lowFuelThreshold: Low fuel threshold (%)
highTemperatureThreshold: High temperature threshold (°C)

Engine Control Diagnostics Response

json

{
  "vin": "KMHSH81C7LU123456",
  "systemStatus": "NORMAL",
  "components": [
    {
      "id": "engine_control_01",
      "name": "Engine Control Module",
      "status": "ACTIVE",
      "health": 98,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "errorCodes": []
    },
    {
      "id": "remote_start_01",
      "name": "Remote Start Module",
      "status": "ACTIVE",
      "health": 95,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "errorCodes": []
    }
  ],
  "alerts": [],
  "lastCheck": "2026-01-12T08:30:00Z"
}

status: ACTIVE, INACTIVE, ERROR, MAINTENANCE_REQUIRED
health: 0-100 score

Engine Status Update (SSE)

json

{
  "type": "ENGINE_STATUS_UPDATE",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-12T08:33:00Z",
  "data": {
    "isRunning": true,
    "remainingTimeSec": 420,
    "climateActive": true,
    "changeType": "STARTED",
    "previousState": {
      "isRunning": false,
      "remainingTimeSec": 0
    },
    "currentTemperature": 18.5,
    "targetTemperature": 24.0
  }
}

type: ENGINE_STATUS_UPDATE, COMMAND_STATUS_UPDATE, SYSTEM_ALERT
changeType: STARTED, STOPPED, TIMEOUT_WARNING, LOW_FUEL_WARNING

Security and Privacy

Authentication and Authorization

User authentication token required (JWT/OAuth2)
Vehicle access permission verification
Remote start control permission verification

Data Security

All API communication encrypted with HTTPS/TLS
Command Signing to prevent command forgery
Two-way authentication (between server and vehicle)
mTLS-based communication security

Privacy Protection

Explicit consent for vehicle control history collection
Specify purpose of location information collection
Compliance with command execution history retention period policy

Access Control

VIN-based vehicle access permission verification
Multi-factor authentication requirement
Command Rate Limit application
Abnormal access pattern detection and blocking

Exception Handling

Connection Failure: Support offline mode, cache last status
Slow Response: Loading indicator, timeout handling
Server Down: Display error message, suggest retry

Vehicle Offline: Notify command transmission failure, queue processing
Condition Not Met: Reject command when safety conditions not satisfied
Engine Running: Limit engine control during driving

Authentication Failure: Request re-authentication, guide security enhancement
No Permission: Clearly display lack of permission reasons
Suspicious Access: Account lock and notification

Automatic Shutdown: Clearly display shutdown reasons
Timeout: Notify Command TTL expiration
Partial Success: Detailed guidance when only some functions operate

Test Setup

Base URL: https://api.ecarus.run/api/v1/remotecontrol
Authentication Token: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
Sample VIN: KMHSH81C7LU123456

Use Swagger UI for interactive API testing.

Deployment Considerations

App Store Registration

Request vehicle control permissions
Request biometric authentication permissions
Clear description of location information collection

Legal Regulation Compliance

Compliance with personal information protection laws
Check vehicle remote control related regulations
Compliance with country-specific remote start laws

Vehicle Compatibility

Support various vehicle models
Consider OEM-specific engine control method differences
Support internal combustion engine/electric/hybrid vehicles

Remote Engine Control API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: Remote Engine Start Request and Execution ​

Scenario 2: Engine Control Failure and Safety Shutdown Processing ​

Scenario 3: Engine Status Monitoring and Settings Management ​

Key Features ​

📱 Features to Implement in App ​

1. Remote Engine Control Function ​

2. Status Monitoring Function ​

3. History Management Function ​

4. Notification and UI Functions ​

🏢 Features to Implement in Call Center ​

1. Proxy Control Function ​

2. Settings Management Function ​

3. History and Diagnostics Function ​

4. Customer Support Function ​

🚗 Functions Processed by Vehicle (TCU) ​

1. Command Execution Function ​

2. Status Management Function ​

3. Safety Function ​

Sequence Diagram ​

Remote Engine Control System Flow ​

API Endpoints ​

Engine Start ​

Engine Stop ​

Engine Control Cancellation ​

Engine Control Status Query ​

Engine Control History Query ​

Engine Control Settings Query ​

Engine Control Settings Update ​

Engine Diagnostics Query ​

Engine Operation Status Real-time Query (SSE) ​

Data Models ​

Engine Start Request ​

Engine Stop Request ​

Engine Cancellation Request ​

Engine Status Request (Query Parameters) ​

Engine Control Response ​

Engine Status Response ​

Engine Control History Request (Query Parameters) ​

Engine Control History Response ​

Engine Control Settings Response ​

Engine Control Diagnostics Response ​

Engine Status Update (SSE) ​

Security and Privacy ​

Authentication and Authorization ​

Data Security ​

Privacy Protection ​

Access Control ​

Exception Handling ​

Network Related ​

Vehicle Status Related ​

Security Related ​

Command Execution Related ​

Test Setup ​

Deployment Considerations ​

App Store Registration ​

Legal Regulation Compliance ​

Vehicle Compatibility ​

Remote Engine Control API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: Remote Engine Start Request and Execution

Scenario 2: Engine Control Failure and Safety Shutdown Processing

Scenario 3: Engine Status Monitoring and Settings Management

Key Features

📱 Features to Implement in App

1. Remote Engine Control Function

2. Status Monitoring Function

3. History Management Function

4. Notification and UI Functions

🏢 Features to Implement in Call Center

1. Proxy Control Function

2. Settings Management Function

3. History and Diagnostics Function

4. Customer Support Function

🚗 Functions Processed by Vehicle (TCU)

1. Command Execution Function

2. Status Management Function

3. Safety Function

Sequence Diagram

Remote Engine Control System Flow

API Endpoints

Engine Start

Engine Stop

Engine Control Cancellation

Engine Control Status Query

Engine Control History Query

Engine Control Settings Query

Engine Control Settings Update

Engine Diagnostics Query

Engine Operation Status Real-time Query (SSE)

Data Models

Engine Start Request

Engine Stop Request

Engine Cancellation Request

Engine Status Request (Query Parameters)

Engine Control Response

Engine Status Response

Engine Control History Request (Query Parameters)

Engine Control History Response

Engine Control Settings Response

Engine Control Diagnostics Response

Engine Status Update (SSE)

Security and Privacy

Authentication and Authorization

Data Security

Privacy Protection

Access Control

Exception Handling

Network Related

Vehicle Status Related

Security Related

Command Execution Related

Test Setup

Deployment Considerations

App Store Registration

Legal Regulation Compliance

Vehicle Compatibility