Hermes Vehicle Protocol

Introduction

The Hermes protocol is a communication protocol between a vehicle and an orchestrator. Vehicles report telemetry and command execution progress while the orchestrator notifies the vehicle about commands and errors, in a full-duplex exchange over a single gRPC stream.

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, please contact us.

Who is it for?

The protocol target users are: - 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

gRPC in a nutshell

The Hermes protocol is a flow of binary messages exchanged over gRPC. Messages are described using the Protocol Buffer (protobuf in short) specification format.

gRPC is a remote procedure call framework that uses protobuf as both its Interface Definition Language (IDL) and the underlying message interchange format. True to the RPC paradigm, gRPC allows defining service methods that can be called remotely with parameters and return types. Servers implement service interfaces and delegate lower-level handling of client calls, authentication, and messaging to the gRPC layer. Similarly, the client application uses a stub generated from the service definition to gain easy access to methods on the server.

In contrast to more traditional RPC frameworks, gRPC also offers full-duplex streaming semantics in method definitions - essentially turning a “method call” into a bidirectional message exchange. Hermes takes advantage of this ability to enable bidirectional asynchronous communication between the orchestrator and the vehicle.

gRPC clients and servers run and communicate across platforms and can be written in any of gRPC’s supported languages. For instance, a JVM gRPC server can interoperate with clients in Go, Python, or Ruby.

                                             +------------------------+
+-----------------------+                    |                        |
|    +-------------+    |   Proto response   |   +----------------+   |
|    |             +---------------------------->+                |   |
|    |             |    |                    |   |   gRPC stub    |   |
|    |             +<----------------------------+                |   |
|    |             |    |   Proto request    |   +----------------+   |
|    |             |    |                    |                        |
|    |             |    |                    |      Python client     |
|    |             |    |                    +------------------------+
|    |             |    |
|    |             |    |
|    |    gRPC     |    |
|    |   server    |    |
|    |             |    |
|    |             |    |
|    |             |    |                    +------------------------+
|    |             |    |                    |                        |
|    |             |    |   Proto response   |   +----------------+   |
|    |             +---------------------------->+                |   |
|    |             |    |                    |   |   gRPC stub    |   |
|    |             +<----------------------------+                |   |
|    |             |    |   Proto request    |   +----------------+   |
|    +-------------+    |                    |                        |
|                       |                    |        Go client       |
|    Java server        |                    +------------------------+
|                       |
+-----------------------+

General protocol overview

Vehicles experience network difficulties from time to time, so Hermes is designed for resilience from intermittent connectivity: - messages are not expected in a certain order or with certain timings - the protocol can recover from a temporary absence of communication

These properties derive from a very simple stateless design: a single, self-contained OrchestrationMessage carries the entire data required for vehicle operation downstream, and conversely, vehicles report their complete state periodically with a VehicleMessage upstream.

Once the gRPC stream is established, the vehicle is identified using the announce field in VehicleMessage. If the authentication is successful, messages exchange proceeds, otherwise an error is returned (OrchestrationMessage with OrchestrationError).

As mentioned above, a single full-duplex stream is used between the vehicle and the server: - downstream, OrchestrationMessage contains the set of commands to be executed next according to Bestmile vehicle plan, as well as possible errors - upstream, VehicleMessage reports telemetry data along with command execution status

Uploading telemetry for unmanaged vehicles

For cases in which orchestration isn’t required, Hermes supports uploading telemetry data directly with a single method call: the gRPC endpoint Telemetry.PostTelemetry accepts uploads of VehicleTelemetry messages, containing both vehicle identity and telemetry.

Next steps