Bestmile

Not displayed (see CSS customizations)

Not displayed (see CSS customizations)

Getting Started with Hermes V2 (BETA)

Hermes is an open source communication protocol allowing vehicles to communicate with a supervision entity.

Introduction

Hermes is a Communication Protocol defined using Google Protocol Buffer

The Hermes protocol is used to establish the communication between a vehicle
and a supervisor. It allows the vehicle to report its state and the supervisor
to send commands to the vehicle.

Access to Hermes Protobuf source code is restricted

Hermes Protobuf Definition source code is available on GitHub. Currently, we only share access to the Hermes source code to selected partners. You will see a 404 Page not found error if you try to access it while not having the proper rights. If you want to receive access, go to the Hermes Protocol access request form.

Who is it for?

The protocol is intended to be used either by:

  • Vehicle manufacturers who want to be compatible with the Bestmile platform
  • Fleet monitoring software providers who wish to benefit from Bestmile's fleet orchestration services

General Transport Overview (gRPC overview)

The Hermes protocol is a flow of binary messages exchanged over gRPC. Messages are described by a Protocol Buffer specification.

Hermes messages can be exchanges through a gRPC connection as it uses protocols buffers as both its Interface Definition Language (IDL) and as its underlying message interchange format (https://grpc.io).

In gRPC a client application can directly call methods on a server application on a different machine as if it was a local object, making it easier for you to create distributed applications and services. As in many RPC systems, gRPC is based around the idea of defining a service, specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls. On the client side, the client has a stub (referred to as just a client in some languages) that provides the same methods as the server.

gRPC clients and servers can run and talk to each other in a variety of environments and can be written in any of gRPC’s supported languages. So, for example, you can easily create a gRPC server in Java with clients in Go, Python, or Ruby.

General protocol overview

We may expect vehicles to experience network difficulties from time to time, so Hermes was designed to be resilient to such intermittent connection. The assumption is that no information is missed even if some messages are lost. To ensure that, messages are constructed so that they reflect the actual state of what is actually happening or what is needed. So if a message is lost, the next one will bring the information that the peer needs.

First thing after the gRPC stream is established, the vehicle needs to identify itself. To do that, it sends a VehicleMessage with only a VehicleAnnounce in it. If the authentication is correct, the normal flow of message can proceed, otherwise an error (SupervisorMessage with SupervisorError is sent in reply).

The normal flow of messages takes places in both direction:

  • From Bestmile to the vehicle: consists of a plan of actions to execute
  • From the vehicle to Bestmile: reports telemetry data and the plan execution progress

See next page for the protocol details.

Sending vehicles telemetry for unmanaged vehicles

There are cases where sending only the telemetry data of vehicles is enough. For those cases HermesV2 provides a way to post telemetry without having to establish a permanent stream per vehicle.

A gRPC endpoint Telemetry.PostTelemetry is provided for this purpose. The telemetry message VehicleTelemetry is added with an identity message RequestIdentity to a PostTelemetryMessage in order to provide both authentication, identification and telemetry data. It allows a service provider to send multiple requests for mutliple vehicles.


What's Next

Dig into the protocol

Protocol details

Getting Started with Hermes V2 (BETA)


Hermes is an open source communication protocol allowing vehicles to communicate with a supervision entity.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.