Tutorial: How Anki Vector communicates?

Part 1: Protocol Buffers: How to connect distributed systems with secure connections and streaming data?

Introduction

One of the key features that the Anki Vector robot (now owned by Digital Dream Labs (DDL)) allows is the ability to connect to it and control it from a computer using the Anki Vector SDK. While this might seem simple, there is a lot of technology in the way a secure connection is maintained with the robot, commands issued, and responses received. This tutorial explores this technology in detail.

The main underlying technology that Vector uses is gRPC and Protocol Buffers. The main contribution of gRPC is that it provides a standardized framework for services in remote machines to talk to one another, even when the services are built on different languages/ platforms. As an example, consider the following illustration of what happens when a program in your computer connects to Anki Vector and asks it to move up its lift

Two different devices (the laptop and the Vector robot) running two different operating systems (Windows and Yocto Linux respectively) with programs written in two different languages (Python and Objective C respectively) are able to talk to each other. That is the magic of gRPC. This tutorial discusses how this is made to work! This tutorial comprises of the following parts:

Part 1: Protocol Buffers. These define the basic message syntax.

Part 2: Connections. We will discuss how secure connections are handled

Part 3: Messaging: We will discuss how everything is put together and understand how a message is sent from the python SDK to the robot and how the response is handled.

Part 1: Protocol Buffers

The first step of the process is to define a message format in which the communication would take place between the two systems. Just like humans need to speak in a well-defined common language to understand each other, machines need to agree on a prescribed formal in which they would communicate to understand each other. The message format is defined in a .proto file. In the case of the Anki Vector SDK, the message format is defined in the file messages.proto file. Specifically, for moving the lift, the message format is as follows:

// See the MoveLift rpc for more details.

message MoveLiftRequest {

  float speed_rad_per_sec = 1;

}

// See the MoveLift rpc for more details.

message MoveLiftResponse {

  // A generic status.

  ResponseStatus status = 1;

}

MoveLiftRequest contains a floating point datatype to express the speed at which the lift needs to be moved. The “= 1” identifies a unique tag which is used for binary encoding. Careful choice of tags are necessary to ensure efficient data compression, so the best is always to start from low numbers. Check out more details in this python tutorial for protocol buffers.

MoveLiftResponse contains a response status. Let us look at how ResponseStatus is defined.

message ResponseStatus {

  enum StatusCode {

    UNKNOWN = 0;

    // The message has completed as expected.

    RESPONSE_RECEIVED = 1;

    // The message has been sent to the robot.

    REQUEST_PROCESSING = 2;

    // The message has been handled successfully at the interface level.

    OK = 3;

    // The user was not authorizied.

    FORBIDDEN = 100;

    // The requested attribute was not found.

    NOT_FOUND = 101;

    // Currently updating values from another call.

    ERROR_UPDATE_IN_PROGRESS = 102;

  }

  // The generic status code to give high-level insight into the progress of a given message.

  StatusCode code = 1;

}  

In this case, a enum (enumerated) type is defined with enumerated options. Enumerated options are just a listing of the options and the corresponding error codes. The ResponseStatus contains one status code which can be used to encapsulate the result of the desired MoveLift operation.

Once these .proto files are defined, a protoc compiler can be used to generate python stub files. As an example, we need to run something like:

protoc messaging/messages.proto to compile and this generates the files:

messages_pb2.py	and messages_pb2_grpc.py

Another proto file messaging/external_interface.proto defines the Remote Procedure Calls (rpcs) that the Anki Vector robot supports. Compiling this file would generate:

external_interface_pb2.py	and external_interface_pb2_grpc.py

We will see how external_interface_pb2_grpc.py is used in the next article.

Now, that we understand what protocol buffers are, we will visit how a secure connection is created to the Anki robot in the next part.