Protocol Buffers

Protocol Buffers are a way of serialising data with a predefined schema. It is a format developed by Google and used internally to communicate their services.

It is very small and very fast (up to 10 times) compared with the other serialisation formats supported. However the server needs to know in advance the schema (i.e. the developer must share a .proto file).

📘
At this moment, only premium accounts can use protocol buffers. Contact us to activate the feature.

You can use protocol buffers in combination of each protocol supported by thethings.iO (http/s, MQTT/s) to communicate your things with the cloud. For example, you can send protobuf with http just changing the body and doing the same api calls as you would do in JSON.

The .proto to be shared with thethings.iO has a predefined format with some customisable parts. The customisable parts are in Value.resource object where you define your resources/keys as you would do in JSON.

The thing is intended to send Query messages and the server will answer with Result messages.

Notice there aren't required fields, so it's easy to maintain backwards compatibility with your things if new features/resources are added.

message Geo {
  optional float lat = 1;
  optional float long = 2;
}

message Description {
  optional bool active = 1;
  optional string name = 2;
}

message MeasureT{
  repeated sint32 array = 1;
}

message Value {
  optional sint32 timestamp = 1;
  optional Geo geo = 2;
  oneof resource {
      sint32 temperature = 3;
      double humidity = 4;
      Description description = 5;//You can create custom types
      sint32 large_name = 6;
      MeasureT measure = 7;
      //...your resources go here...//
  }
}

message Query {
  enum Action{
    WRITE = 1;
    READ = 2;
    SUBSCRIBE = 3;
    ACTIVATE = 4;
    LINK_ID = 5;
    TIME = 6;
  }
  repeated Value values = 1;
  optional string activation_code = 2;//could be bytes
  optional string link_id = 3;
  optional string thing_token = 4;//this is ignored in http
  optional Action action = 5;//this is ignored in http
  optional ReadQuery query = 6;
}

message Error {
  enum ErrorCode {
    THING_NOT_FOUND_ERROR = 1;
    ACTIVATION_ERROR = 2;
    PROTOBUF_PARSE_ERROR = 3;
    UNRECOGNISED_ACTION = 4;
  }
  optional ErrorCode code = 1;
  optional string error_message = 2;
}

message Result {
  enum StatusCode {
    SUCCESS = 1;
    ERROR = 2;
  }
  optional StatusCode status = 1;
  repeated Value values = 2;
  optional string thing_token = 3;
  optional sint32 server_time = 4;
  optional Error error = 5;
}

 message ReadQuery {
   optional string resource = 1;
   optional sint32 limit = 2;
   optional sint32 start_date = 3;
   optional sint32 end_date = 4;
 }