Protocol Reference

Top

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

Top

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

Top

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

Top

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)

Top

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

Top

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)

Top

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

Top

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

Top

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

Top

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

Top

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

Top

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)

Top

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

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)
2.0.0*