Style Guide

The Bluetooth test interfaces uses protocol buffers v3 as Interfaces Definition Language.

All guidelines from the protocol buffers style guide apply to them.

Additional guidelines

A few additional guidelines apply to the Bluetooth test interfaces to guarantee consistency and improve readability.

Use proto3 syntax

The protobuf compiler currently supports proto2 and proto3 syntax, but proto3 should be used, as it is the latest version.

Use names from the Bluetooth specification nomenclature

This avoids adding confusion to naming, even if the names used in the Bluetooth specification are not consistent across profiles (Gateway, Target, Controller, Server, Client, ...).

service A2DP {
    rpc OpenServer(Empty) returns (Empty); // ✗ Avoid
    rpc OpenSource(Empty) returns (Empty); // ✓ OK
}

Name services without prefixes or suffixes

This helps to keep short names, if you need name-spacing you should use a package instead.

service A2DP {} // ✓ OK

service Host {} // ✓ OK

service A2DPServer {} // ✗ Avoid

service BluetoothHost {} // ✗ Avoid

Avoid long package names

This makes the usage of the gRPC interface harder in some generated language where long package names are uncommon, for instance in rust and python.

package test.interfaces.bluetooth.bredr.l2cap; // ✗ Avoid
package l2cap; // ✓ OK

Use standards protocol buffers types

Protocol buffers includes a lot of well-known types, so use them instead of redefining your owns.

rpc L2CAP {
    Send(MyData) returns (MyEmpty); // ✗ Avoid
    Send(google.protobuf.BytesValue) returns (google.protobuf.Empty); // ✓ OK
}

Describe expected errors with oneof fields

This allows using the protocol buffers type system to describe the possible outcomes of the request. You don't need to describe all errors, you should only specify the ones that are needed by the tests.

We use the gRPC standard error model to send the other non specified errors (like implementation specific errors).

message ConnectResponse {
    oneof result {
        Connection connection = 1;
        DeviceNotFoundError device_not_found = 2;
        ...
    }
}

Avoid gRPC streaming if possible

There is only a few legitimate usages for gRPC streaming (such as audio streaming) and you should avoid it otherwise.

Use typed tokens to represent a resource

This allows the implementation to wrap their internal format for representing the resource inside an opaque message instead of converting them.

// ✗ Avoid
service Host {
    rpc Connect(BdAddr) returns (Handle);
}

message Handle {
    int16 handle = 1;
}

// ✓ OK
service Host {
    rpc Connect(BdAddr) returns (Connection);
}

message Connection {
    // Internal (opaque) representation
    // of the connection by the server
    bytes cookie = 1;
}