Protocol Reference
com/bestmile/vehicle/model/v2/id.proto
HERMES common IDs definitions
OpenAccessID
Open access identifier
Field | Type | Label | Description |
---|---|---|---|
value | string | UUID |
RideID
Ride identifier
Field | Type | Label | Description |
---|---|---|---|
value | string | UUID |
VehicleID
Vehicle identifier
Field | Type | Label | Description |
---|---|---|---|
value | string | UUID |
com/bestmile/vehicle/model/v2/unit.proto
HERMES common units
Kelvins
Field | Type | Label | Description |
---|---|---|---|
value | double | Kelvins |
Meters
Field | Type | Label | Description |
---|---|---|---|
value | double | Meters |
MetersPerSecond
Field | Type | Label | Description |
---|---|---|---|
value | double | MetersPerSecond |
MetersPerSecondSquared
Field | Type | Label | Description |
---|---|---|---|
value | double | MetersPerSecondSquared |
Radians
Field | Type | Label | Description |
---|---|---|---|
value | double | Radians |
RadiansPerSecond
Field | Type | Label | Description |
---|---|---|---|
value | double | RadiansPerSecond |
Watts
Field | Type | Label | Description |
---|---|---|---|
value | double | Watts |
com/bestmile/vehicle/model/v2/telemetry.proto
HERMES telemetry definitions
DoorState
State of a door.
The door is identified by the side of the vehicle and its position on the side. Examples: - 3 doors bus front-right door: { side: RIGHT, position: 1 }
- 3 doors bus middle-right door: { side: RIGHT, position: 2 }
- 3 doors bus rear-left door: { side: LEFT, position: 3 }
- car trunk: { side: BACK, position: 1 }
Field | Type | Label | Description |
---|---|---|---|
state | DoorState.State | State of the door | |
side | DoorState.Side | Side of the door | |
position | int32 | Position of the door relative to the side |
DrivingMode
Vehicle driving mode
Field | Type | Label | Description |
---|---|---|---|
mode | DrivingMode.Mode | Driving mode |
EnergyState
Field | Type | Label | Description |
---|---|---|---|
ratio | double | Proportional state of charge [0…1] | |
joules | double | Absolute charge [Joules] | |
charging | bool | True if the vehicle is being charged, false otherwise | |
charging_power | Watts | Amount of power available for charging |
Location
A Location is specified by the longitude and latitude as specified by WGS84
Field | Type | Label | Description |
---|---|---|---|
latitude | double | Latitude component | |
longitude | double | Longitude component | |
altitude | Meters | Altitude component [Optional] | |
gnss_state | Location.GnssState | Positioning mechanism |
PassengerOccupancy
Measured vehicle occupancy
Field | Type | Label | Description |
---|---|---|---|
barrier_timestamp | string | ||
barrier_location | string | ||
passenger_from_after_barrier | uint32 | ||
passenger_from_before_barrier | uint32 |
ServiceMode
Service mode
Field | Type | Label | Description |
---|---|---|---|
service | ServiceMode.Service | Service mode |
SoftwareState
Vehicle firmware state
Field | Type | Label | Description |
---|---|---|---|
version | string | Firmware version | |
hit_ratio | SoftwareState.HitRatio | Firmware hit ratio |
SoftwareState.HitRatio
Field | Type | Label | Description |
---|---|---|---|
value | double |
Steering
Current vehicle steering
Field | Type | Label | Description |
---|---|---|---|
angle | Radians | Steering angle clockwise from true north | |
rate | RadiansPerSecond | Rate of vehicle angle change |
SupervisionMode
Supervision mode
Field | Type | Label | Description |
---|---|---|---|
supervision | SupervisionMode.Supervision | Supervision mode |
Telemetry
Vehicle telemetry
Field | Type | Label | Description |
---|---|---|---|
location | Location | Vehicle location | |
speed | MetersPerSecond | Vehicle speed | |
heading | Radians | Front heading angle clockwise from true north | |
passenger_occupancy | PassengerOccupancy | Measured vehicle occupancy | |
energy | EnergyState | Vehicle energy status | |
driving_mode | DrivingMode | Driving mode | |
door_state | DoorState | repeated | State of vehicle doors |
odometer | Meters | Distance in meters traveled since the vehicle was manufactured | |
acceleration | MetersPerSecondSquared | Vehicle acceleration | |
temperature | Temperature | Vehicle temperature | |
service_mode | ServiceMode | Vehicle service mode | |
supervision_mode | SupervisionMode | Vehicle supervision mode | |
vehicle_mode | VehicleMode | Vehicle usage mode | |
software_state | SoftwareState | Vehicle firmware state | |
steering | Steering | Current vehicle steering |
Temperature
Vehicle temperature
Field | Type | Label | Description |
---|---|---|---|
interior | Kelvins | Interior temperature | |
exterior | Kelvins | Exterior temperature |
VehicleMode
Vehicle usage mode
Field | Type | Label | Description |
---|---|---|---|
vehicle | VehicleMode.Vehicle | Vehicle mode |
DoorState.Side
Name | Number | Description |
---|---|---|
UNKNOWN_SIDE | 0 | Unknown door side |
FRONT | 1 | Front of the vehicle |
RIGHT | 2 | Right of the vehicle |
BACK | 3 | Back of the vehicle |
LEFT | 4 | Left of the vehicle |
DoorState.State
Name | Number | Description |
---|---|---|
UNKNOWN_STATE | 0 | Unknown door state |
OPEN | 1 | Door is open |
CLOSED | 2 | Door is closed |
OPENING | 3 | Door is opening |
CLOSING | 4 | Door is closing |
DrivingMode.Mode
Name | Number | Description |
---|---|---|
UNKNOWN | 0 | Unknown mode |
AUTOMATIC | 1 | Vehicle is driving autonomously |
MANUAL | 2 | Operator is driving the vehicle |
Location.GnssState
Name | Number | Description |
---|---|---|
UNKNOWN | 0 | Unknown positioning mechanism |
INVALID | 1 | Indicates that there is no satellite signal being received or there are not enough satellites available for proper location determination |
GPS_FIX | 2 | Standard GPS signal, or Standard Positioning Service (SPS) is being used |
DGPS_FIX | 3 | Differential GPS is being used to proved increased accuracy over SPS |
PPS_FIX | 4 | Precise Positioning System, encrypted for government use is being used by the receiver |
REAL_TIME_KINEMATICS | 5 | Real time kinematics (RTK) satellite navigation is a technique used in land survey based on the use of carrier phase measurements of the GPS, GLONASS and/or Galileo signals where a single reference station provides the real-time corrections of even to a centimeter level of accuracy |
FLOAT_RTK | 6 | Float real time kinematics (Float RTK) is very similar to the fixed RTK method of calculating location, but is not as precise, typically around 20 cm to 1 meter accuracy range |
ESTIMATED | 7 | Dead reckoning is the determination of a location based on computations of position given an accurately known point of origin and measurements of speed, heading and elapsed time |
MANUAL_INPUT_MODE | 8 | Location has been manually entered into the GPS receiver, and is not based on the satellite system |
SIMULATION_MODE | 9 | This mode is not always called simulation mode on the different models. On the some models it is called "demo mode" or "gps off" while others call it "Use Indoors" or "gps off". |
ServiceMode.Service
Name | Number | Description |
---|---|---|
UNKNOWN | 0 | Unknown service mode |
METRO | 1 | Metro mode |
BUS | 2 | Bus mode |
ON_DEMAND | 3 | On-demand mode |
SupervisionMode.Supervision
Name | Number | Description |
---|---|---|
UNKNOWN | 0 | Unknown supervision mode |
STANDALONE | 1 | Absent supervision, vehicle is on its own |
MANUFACTURER | 2 | Manufacturer-based supervision |
ORCHESTRATOR | 3 | Orchestration-based supervision |
VehicleMode.Vehicle
Name | Number | Description |
---|---|---|
UNKNOWN | 0 | Unknown vehicle mode |
STANDBY | 1 | Standby mode |
USE | 2 | Active mode |
SAFETY | 3 | Safety mode |
com/bestmile/vehicle/model/v2/command_details.proto
HERMES definitions related to vehicle management and commands
CommandDetails
Additional data relevant to execution of the command
Field | Type | Label | Description |
---|---|---|---|
drive | DriveDetails | Additional data relevant to a drive | |
pickup | PickupDetails | Additional data relevant to a pickup | |
dropoff | DropoffDetails | Additional data relevant to a dropoff | |
open_access | OpenAccessDetails | Additional data relevant to open-access |
DriveDetails
Additional data relevant to drive commands
Field | Type | Label | Description |
---|---|---|---|
route | Route | Calculated route to destination |
DropoffDetails
Additional data relevant to dropoff commands
Field | Type | Label | Description |
---|---|---|---|
phases | RideActionPhases | Allotted times for each phase of the dropoff | |
location | Location | Dropoff location |
OpenAccessDetails
Additional data relevant to open access
Field | Type | Label | Description |
---|---|---|---|
location | Location | Open-access location |
PickupDetails
Additional data relevant to pickup commands
Field | Type | Label | Description |
---|---|---|---|
phases | RideActionPhases | Allotted times for each phase of the pickup | |
location | Location | Pickup location |
RideActionPhases
Duration allotted for each phase of the pickup or dropoff actions in the plan
Field | Type | Label | Description |
---|---|---|---|
proceedingsBefore | google.protobuf.Duration | Allotted time before passenger entry or exit | |
passengerFlow | google.protobuf.Duration | Allotted time for passenger entry or exit | |
proceedingsAfter | google.protobuf.Duration | Allotted time after passenger entry or exit |
Route
List of waypoints forming a route
Field | Type | Label | Description |
---|---|---|---|
destination | Location | Route destination | |
steps | Location | repeated | Steps of the route (not including destination) |
com/bestmile/vehicle/model/v2/command_signature.proto
HERMES definitions related to vehicle management and commands
CommandSignature
Contains the minimal data to define and identify the command
Field | Type | Label | Description |
---|---|---|---|
drive | DriveSignature | Defines and identifies a drive uniquely | |
pickup | PickupSignature | Defines and identifies a pickup uniquely | |
dropoff | DropoffSignature | Defines and identifies a dropoff uniquely | |
open_access | OpenAccessSignature | Defines and identifies an open-access uniquely |
DriveSignature
Specific signature component for drive command
Field | Type | Label | Description |
---|---|---|---|
startTime | google.protobuf.Timestamp | Drive start time | |
destination | Location | Drive destination |
DropoffSignature
Specific signature component for dropoff command
Field | Type | Label | Description |
---|---|---|---|
startTime | google.protobuf.Timestamp | Dropoff start time | |
ride_id | RideID | Ride identifier |
OpenAccessSignature
Specific signature component for open access command
Field | Type | Label | Description |
---|---|---|---|
startTime | google.protobuf.Timestamp | Open access start time | |
id | OpenAccessID | Open access unique identifier |
PickupSignature
Specific signature component for pickup command
Field | Type | Label | Description |
---|---|---|---|
startTime | google.protobuf.Timestamp | Pickup start time | |
ride_id | RideID | Ride identifier |
com/bestmile/vehicle/model/v2/command_status.proto
HERMES definitions related to vehicle management and commands
CommandStatus
Command progress status
Field | Type | Label | Description |
---|---|---|---|
pending | Pending | Command has been received but execution has not started yet | |
starting | Starting | Command execution is starting (for a Pickup or Dropoff this corresponds to proceedings before ) |
|
ongoing | Ongoing | Command execution has started (for a Pickup or Dropoff, this corresponds to passenger flow ) |
|
finishing | Finishing | Command execution is finishing (for a Pickup or Dropoff this corresponds to proceeding after ) |
|
done | Done | Command has completed successfully | |
failed | Failed | Command execution failed |
Done
Command has completed successfully
Failed
Command execution failed
Field | Type | Label | Description |
---|---|---|---|
reason | string | cause for the command execution failure |
Finishing
Command execution is finishing (for a Pickup or Dropoff this corresponds to proceeding after
)
Ongoing
Command execution has started (for a Pickup or Dropoff, this corresponds to 'passenger flow`)
Pending
Command has been received but execution has not started yet
Starting
Command execution is starting (for a Pickup or Dropoff this corresponds to proceedings before
)
com/bestmile/vehicle/model/v2/command_report.proto
HERMES definitions related to vehicle management and commands
CommandReport
Report from the vehicle about the execution status for a command
Field | Type | Label | Description |
---|---|---|---|
signature | CommandSignature | Signature allows identification of the command | |
status | CommandStatus | Command execution status |
com/bestmile/vehicle/model/v2/command.proto
HERMES definitions related to vehicle management and commands
Command
Defines an expected behavior from the vehicle
Field | Type | Label | Description |
---|---|---|---|
signature | CommandSignature | Identifies the command uniquely | |
details | CommandDetails | Additional command data which does not participate in the signature | |
status | CommandStatus | Current command status |
com/bestmile/vehicle/model/v2/connection.proto
HERMES definitions related to vehicle management and commands
ConnectionStatus
Connection status
Field | Type | Label | Description |
---|---|---|---|
vehicle | ConnectionStatus.StatusType | Vehicle connection status |
ConnectionStatus.StatusType
Name | Number | Description |
---|---|---|
UNKNOWN | 0 | Unknown connection status |
ONLINE | 1 | Connection is online |
OFFLINE | 2 | Connection is offline |
com/bestmile/vehicle/model/v2/request.proto
HERMES definitions related to vehicle management and commands
RequestIdentity
Request authentication details
Field | Type | Label | Description |
---|---|---|---|
vehicle_id | VehicleID | Vehicle identifier |
com/bestmile/vehicle/model/v2/response.proto
HERMES definitions related to vehicle management and commands
ResponseStatus
Request response status
Field | Type | Label | Description |
---|---|---|---|
type | ResponseStatus.StatusType | Response status type | |
message | string | Optional message to explain the status |
ResponseStatus.StatusType
Name | Number | Description |
---|---|---|
UNDEFINED | 0 | Undefined response status |
OK | 1 | OK response |
AUTHENTICATIONFAILURE | 2 | Authentication failure |
com/bestmile/vehicle/service/v2/orchestration.proto
HERMES orchestration service
OrchestrationError
Orchestration error
Field | Type | Label | Description |
---|---|---|---|
error | OrchestrationError.Error | Error code | |
message | string | Error message |
OrchestrationMessage
Downstream message from Bestmile orchestration platform
Field | Type | Label | Description |
---|---|---|---|
errors | OrchestrationError | repeated | Some error occurred as result of the previous upstream VehicleMessage |
commands | com.bestmile.vehicle.model.v2.Command | repeated | List of commands to execute as soon as relevant. The list is windowed to the upcoming/ongoing dwell. |
timestamp | google.protobuf.Timestamp | Message timestamp (server time) |
VehicleAnnounce
Vehicle authentication details
Field | Type | Label | Description |
---|---|---|---|
vehicle_id | com.bestmile.vehicle.model.v2.VehicleID | Vehicle identifier |
VehicleMessage
Upstream vehicle message
Field | Type | Label | Description |
---|---|---|---|
announce | VehicleAnnounce | Vehicle authentication information | |
telemetry | com.bestmile.vehicle.model.v2.Telemetry | Vehicle telemetry | |
reports | com.bestmile.vehicle.model.v2.CommandReport | repeated | Progress reports for command execution |
OrchestrationError.Error
Name | Number | Description |
---|---|---|
UNKNOWN | 0 | Unknown error |
AUTHENTICATION_NOT_DONE | 1 | Authentication missing |
AUTHENTICATION_WRONG_API_KEY | 2 | Incorrect API key (deprecated since JWT token introduction) |
AUTHENTICATION_VEHICLE_NOT_ALLOWED_BY_API_KEY | 3 | Vehicle not supported by this API key (deprecated since JWT token introduction) |
AUTHENTICATION_NO_VEHICLE_ID_PROVIDED | 4 | Vehicle identifier missing |
AUTHENTICATION_FAILED | 5 | Authentication failed |
COMMAND_SIGNATURE_MISMATCH | 6 | Received a command report with unexpected signature |
INVALID_STATUS_TRANSITION | 7 | Status transition invalid in report (e.g. activity last reported as Finishing and then reported as Starting) |
EMPTY_COMMANDS | 8 | List of commands to execute is empty (but we received some reports) |
Orchestration
Vehicle orchestration service
Method Name | Request Type | Response Type | Description |
---|---|---|---|
VehicleStream | VehicleMessage stream | OrchestrationMessage stream | Orchestration stream, with downstream orchestration messages (commands and errors) and upstream vehicle messages (authentication, telemetry and reports) |
com/bestmile/vehicle/service/v2/telemetry.proto
HERMES telemetry service
PassengerChanges
Passenger counting details
Field | Type | Label | Description |
---|---|---|---|
nb_travelers_in | uint32 | Number of entering passengers | |
nb_travelers_out | uint32 | Number of exiting passengers | |
location | com.bestmile.vehicle.model.v2.Location | Location of the vehicle at the counting point |
PostPassengerChangesResponse
Passenger counting result
Field | Type | Label | Description |
---|---|---|---|
status | com.bestmile.vehicle.model.v2.ResponseStatus | Response status |
PostTelemetryRequest
Telemetry upload message
Field | Type | Label | Description |
---|---|---|---|
identity | com.bestmile.vehicle.model.v2.RequestIdentity | Authentication details | |
telemetry | com.bestmile.vehicle.model.v2.Telemetry | Vehicle telemetry data | |
connection | com.bestmile.vehicle.model.v2.ConnectionStatus | Current vehicle connection status |
PostTelemetryResponse
Telemetry upload result
Field | Type | Label | Description |
---|---|---|---|
status | com.bestmile.vehicle.model.v2.ResponseStatus | Response status |
TelemetryUpload
Telemetry upload service
Method Name | Request Type | Response Type | Description |
---|---|---|---|
PostPassengerChanges | PassengerChanges | PostPassengerChangesResponse | Upload passenger-related information |
PostTelemetry | PostTelemetryRequest | PostTelemetryResponse | Upload vehicle telemetry |