nearby/presence/proto/presence_frame.proto

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto2";

package nearby.presence;

// import "storage/datapol/annotations/proto/semantic_annotations.proto";

option optimize_for = LITE_RUNTIME;
option java_package = "com.google.android.gms.nearby.presence";
option java_outer_classname = "PresenceFrameProtocol";

/**
 * Nearby Presence’s wire frame format
 */
message PresenceFrame {
  /** The version of the frame. */
  enum Version {
    UNKNOWN_VERSION = 0;
    VERSION_1 = 1;
  }

  /** The version 1 frame for Nearby Presence. */
  optional V1Frame v1_frame = 1;
}

/**
 * Nearby Presence’s v1 wire frame format
 */
message V1Frame {
  oneof Message {
    // Control messages for connection status update.
    ControlFrame control_frame = 1;

    // This frame will be shared by public and provisioned identities
    DeviceIdentityFrame device_identity_frame = 2;

    // First message from discovery device to broadcaster.
    ConnectionInitFrame connection_init_frame = 3;

    // Sent by broadcaster to notify discoverer its UWB capability.
    UwbControleeCapabilities uwb_controlee_capabilities_frame = 4;

    // Sent by discoverer to notify broadcaster the UWB ranging parameters.
    UwbConnectionInfo uwb_connection_info = 5;

    // Used for identity authentication.
    PresenceAuthenticationFrame authentication_frame = 6;
  }
}

/**
 * A frame contains the local device’s information, shared by public and
 * provisioned identities.
 */
message DeviceIdentityFrame {
  optional string device_name = 1;

  // Without this field, the device will not be connectable.
  optional bytes bluetooth_mac_address = 2;  // deprecated

  optional string device_image_url = 3;

  optional string model_id = 4;

  repeated int32 action = 5 [packed = true];  // deprecated

  optional string device_model_name = 6;

  optional int32 device_type = 7;
}

/**
 * A frame sent from discovery device to broadcast device when connection
 * initialized, or when UWB needs to be restarted, or when dedup hint rotates.
 */
message ConnectionInitFrame {
  // Discovery-side action list
  repeated int32 actions = 1 [packed = true];

  // Discovery-side identity type
  optional int32 identity_type = 2;

  // Should the broadcaster (re)-start UWB OOB process or not.
  optional bool uwb_enable = 3;

  // Used for device de-duplicate. Same device ID means the same physical
  // device. When dedup hint rotates, this will be updated and send again.
  optional int64 device_unique_id = 4;
}

/**
 * A frame that describes the controlee's UWB capabilities.
 */
message UwbControleeCapabilities {
  optional bytes controlee_address = 1;

  repeated int32 supported_config_ids = 2 [packed = true];

  repeated int32 supported_channels = 3 [packed = true];

  optional int32 min_ranging_interval_ms = 4;

  optional bytes sub_session_id = 5 /* type = ST_SESSION_ID */;

  optional bytes sub_session_key = 6
      /* type = ST_SECURITY_MATERIAL */;

  optional bool ranging_disabled = 7;

  // Used for device de-duplicate. Same device ID means the same physical
  // device.
  optional int64 device_unique_id = 8;

  optional bool is_distance_supported = 9 [default = true];
  optional bool is_azimuth_supported = 10 [default = true];
  optional bool is_elevation_supported = 11 [default = false];
  optional float min_slot_duration_ms = 12 [default = 2.0];
  repeated int32 supported_ntf_configs = 13 [packed = true];
  optional bool is_ranging_interval_reconfigure_supported = 14
      [default = false];
  repeated int32 supported_slot_durations = 15 [packed = true];
  repeated int32 supported_ranging_update_rates = 16 [packed = true];
  optional int32 chip_count = 17 [default = 1];
  repeated UwbMultiChipInfo multi_chip_info = 18;
  optional bool is_background_ranging_supported = 19 [default = false];
}

/* A frame containing info needed per chip in a multi-chip environment. */
message UwbMultiChipInfo {
  optional bytes controlee_address = 1;
  optional string chip_id = 2;
}

/**
 * A frame that describes the connection info of the UWB ranging session.
 */
message UwbConnectionInfo {
  optional bytes controller_address = 1;

  optional int32 channel = 2;

  optional int32 preamble_index = 3;

  optional int32 config_id = 4;

  optional int32 ranging_interval_ms = 5;

  optional int32 session_id = 6 /* type = ST_SESSION_ID */;

  optional bytes vendor_id = 7;

  optional bytes static_sts_iv = 8;

  optional bytes session_key = 9
      /* type = ST_SECURITY_MATERIAL */;

  optional bool ranging_disabled = 10;
}

/**
 * Control frames that used for connection status update.
 */
message ControlFrame {
  /** The defined Control type of the frame. */
  enum ControlType {
    UNKNOWN_TYPE = 0;

    // Keeps the connection alive.
    KEEP_ALIVE = 1;

    // Notifies the peer that the connection will be closed immediately.
    DISCONNECT = 2;
  }

  optional ControlType type = 1;
}

message PresenceAuthenticationFrame {
  // The version of this frame and protocol.
  optional int32 version = 1;

  // A signature signed by the private key in the LocalCredential.
  optional bytes private_key_signature = 2;

  // A hash of a shared credential's id. Used to prove ownership of shared
  // credentials used in discovery.
  optional bytes shared_credential_id_hash = 3;

  // A hash of a local credential's id. Used to expedite local credential
  // verification.
  optional bytes credential_id_hash = 4 [deprecated = true];
}