Add gateway mapping services

v1alpha1/enums.proto

@@ -65,3 +65,19 @@ enum MessageDeliveryState {
   // The message has been processed by the receiver.
   PROCESSED = 3;
 }
+
+enum TerrestrialAntennaPlacement {
+  // Unknown antenna placement.
+  UNKNOWN = 0;
+  // Indoor antenna placement.
+  INDOOR = 1;
+  // Outdoor antenna placement.
+  OUTDOOR = 2;
+}
+
+enum Modulation {
+  // LoRa modulation.
+  LORA = 0;
+  // FSK modulation.
+  FSK = 1;
+}

v1alpha1/mapping.proto

@@ -0,0 +1,130 @@
+// Copyright © 2019 The Things Industries B.V.
+//
+// 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
+//
+//     http://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 = "proto3";
+
+package org.packetbroker.v1alpha1;
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/wrappers.proto";
+import "packetbroker/api/v1alpha1/enums.proto";
+import "packetbroker/api/v1alpha1/location.proto";
+
+option go_package = "go.packetbroker.org/api/v1alpha1;packetbroker";
+
+message GatewayVisibility {
+  // Show location.
+  bool location = 1;
+  // Show antenna placement (indoor/outdoor).
+  bool antenna_placement = 2;
+  // Show antenna count.
+  bool antenna_count = 3;
+  // Show whether the gateway produces fine timestamps.
+  bool fine_timestamps = 4;
+  // Show contact information.
+  bool contact_information = 5;
+  // Show status (online/offline).
+  bool status = 6;
+  // Show receive and transmission counters.
+  bool counters = 7;
+  // Show frequency plan.
+  bool frequency_plan = 8;
+}
+
+message GatewayFrequencyPlan {
+  // Region of the frequency plan.
+  Region region = 1;
+
+  message Channel {
+    // Frequency (Hz).
+    uint64 frequency = 1;
+    // Minimum data rate.
+    uint32 min_data_rate = 2;
+    // Maximum data rate.
+    uint32 max_data_rate = 3;
+    // Modulation.
+    Modulation modulation = 4;
+  }
+  repeated Channel uplink_channels = 2;
+}
+
+message Gateway {
+  // LoRa Alliance NetID of the Forwarder Member.
+  uint32 forwarder_net_id = 1;
+  // Forwarder identifier issued by the Forwarder Member.
+  string forwarder_id = 2;
+  // Unique identifier of the gateway.
+  uint64 eui = 3;
+  // Timestamp when the gateway was last updated.
+  google.protobuf.Timestamp updated_at = 4;
+
+  message Terrestrial {
+    // Location of the (first) antenna.
+    // Subscribing Home Networks receive this value if the Gateway Visibility has location set.
+    Location location = 1;
+    // Antenna placement (indoor/outdoor).
+    // Subscribing Home Networks receive this value if the Gateway Visibility has antenna_placement set.
+    TerrestrialAntennaPlacement antenna_placement = 2;
+    // Number of antennas.
+    // Subscribing Home Networks receive this value if the Gateway Visibility has antenna_count set.
+    google.protobuf.UInt32Value antenna_count = 3;
+    // Indicates whether the gateway produces fine timestamps.
+    // Subscribing Home Networks receive this value if the Gateway Visibility has fine_timestamps set.
+    google.protobuf.BoolValue fine_timestamps = 4;
+  }
+  message Satellite {
+    // Ground location.
+    // Subscribing Home Networks receive this value if the Gateway Visibility has location set.
+    Location location = 1;
+    // Field of view (meters).
+    // Subscribing Home Networks receive this value if the Gateway Visibility has location set.
+    double field_of_view = 2;
+    // Trajectory, typically containing the recent past and projected path.
+    // Subscribing Home Networks receive this value if the Gateway Visibility has location set.
+    repeated TimedLocation trajectory = 3;
+  }
+  oneof location {
+    Terrestrial terrestrial = 5;
+    Satellite satellite = 6;
+  }
+
+  // Contact name.
+  // Subscribing Home Networks receive this value if the Gateway Visibility has contact_information set.
+  string contact_name = 7;
+  // Contact email address.
+  // Subscribing Home Networks receive this value if the Gateway Visibility has contact_information set.
+  string contact_email = 8;
+  // Contact URL.
+  // Subscribing Home Networks receive this value if the Gateway Visibility has contact_information set.
+  string contact_url = 9;
+
+  // Indicates whether the gateway is online.
+  // Subscribing Home Networks receive this value if the Gateway Visibility has status set.
+  google.protobuf.BoolValue online = 10;
+
+  // Total number of received messages.
+  // Subscribing Home Networks receive this value if the Gateway Visibility has counters set.
+  google.protobuf.UInt32Value rx_count = 11;
+  // Number of transmitted messages.
+  // Subscribing Home Networks receive this value if the Gateway Visibility has counters set.
+  google.protobuf.UInt32Value tx_count = 12;
+
+  // Frequency plan of the gateway.
+  // Subscribing Home Networks receive this value if the Gateway Visibility has frequency_plan set.
+  GatewayFrequencyPlan frequency_plan = 13;
+}
+
+message Gateways {
+  repeated Gateway gateways = 1;
+}

v1alpha1/mapping_services.proto

@@ -0,0 +1,139 @@
+// Copyright © 2019 The Things Industries B.V.
+//
+// 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
+//
+//     http://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 = "proto3";
+
+package org.packetbroker.v1alpha1;
+
+import "google/protobuf/empty.proto";
+import "packetbroker/api/v1alpha1/mapping.proto";
+
+option go_package = "go.packetbroker.org/api/v1alpha1;packetbroker";
+
+message GetDefaultGatewayVisibilityRequest {
+  // LoRa Alliance NetID of the Forwarder Member.
+  uint32 forwarder_net_id = 1;
+  // Forwarder identifier issued by the Forwarder Member.
+  string forwarder_id = 2;
+}
+
+message SetDefaultGatewayVisibilityRequest {
+  // LoRa Alliance NetID of the Forwarder Member.
+  uint32 forwarder_net_id = 1;
+  // Forwarder identifier issued by the Forwarder Member.
+  string forwarder_id = 2;
+  // New default Gateway Visibility.
+  GatewayVisibility visibility = 3;
+}
+
+message GetHomeNetworkGatewayVisibilityRequest {
+  // LoRa Alliance NetID of the Forwarder Member.
+  uint32 forwarder_net_id = 1;
+  // Forwarder identifier issued by the Forwarder Member.
+  string forwarder_id = 2;
+  // LoRa Alliance NetID of the Home Network Member.
+  uint32 home_network_net_id = 3;
+}
+
+message SetHomeNetworkGatewayVisibilityRequest {
+  // LoRa Alliance NetID of the Forwarder Member.
+  uint32 forwarder_net_id = 1;
+  // Forwarder identifier issued by the Forwarder Member.
+  string forwarder_id = 2;
+  // LoRa Alliance NetID of the Home Network Member.
+  uint32 home_network_net_id = 3;
+  // New Gateway Visibility for the Home Network Member.
+  GatewayVisibility visibility = 4;
+}
+
+message GetGatewayVisibilityResponse {
+  GatewayVisibility visibility = 1;
+}
+
+service GatewayVisibilityManager {
+  // Get the Default Gateway Visibility.
+  rpc GetDefaultVisibility(GetDefaultGatewayVisibilityRequest) returns (GetGatewayVisibilityResponse);
+  // Set the Default Gateway Visibility.
+  rpc SetDefaultVisibility(SetDefaultGatewayVisibilityRequest) returns (google.protobuf.Empty);
+  // Get the Gateway Visibility with the Home Network.
+  rpc GetHomeNetworkVisibility(GetHomeNetworkGatewayVisibilityRequest) returns (GetGatewayVisibilityResponse);
+  // Set the Gateway Visibility with the Home Network.
+  rpc SetHomeNetworkVisibility(SetHomeNetworkGatewayVisibilityRequest) returns (google.protobuf.Empty);
+}
+
+message UpdateForwarderGatewayRequest {
+  // LoRa Alliance NetID of the Forwarder Member.
+  uint32 forwarder_net_id = 1;
+  // Forwarder identifier issued by the Forwarder Member.
+  string forwarder_id = 2;
+  // Gateway to update.
+  Gateway gateway = 3;
+}
+
+service ForwarderMapper {
+  // Update a gateway.
+  rpc UpdateGateway(UpdateForwarderGatewayRequest) returns (google.protobuf.Empty);
+}
+
+message ListHomeNetworkGatewaysRequest {
+  // LoRa Alliance NetID of the Home Network Member.
+  uint32 home_network_net_id = 1;
+  // Limit the number of results per page. Use 0 for the default limit of the Mapper.
+  uint32 limit = 2;
+  // Page number for pagination. 0 is interpreted as 1.
+  uint32 page = 3;
+}
+
+message GetHomeNetworkGatewayRequest {
+  // LoRa Alliance NetID of the Home Network Member.
+  uint32 home_network_net_id = 1;
+  // LoRa Alliance NetID of the Forwarder Member.
+  uint32 forwarder_net_id = 2;
+  // Forwarder identifier issued by the Forwarder Member.
+  string forwarder_id = 3;
+  // Unique identifier of the gateway.
+  uint64 eui = 4;
+}
+
+message SubscribeHomeNetworkGatewaysRequest {
+  // LoRa Alliance NetID of the Home Network Member.
+  uint32 home_network_net_id = 1;
+
+  message ForwarderEUIs {
+    // LoRa Alliance NetID of the Forwarder Member.
+    uint32 forwarder_net_id = 1;
+    // Forwarder identifier issued by the Forwarder Member.
+    string forwarder_id = 2;
+    // Set of unique identifiers of gateways.
+    // Leave empty to subscribe to all gateways of the Forwarder Member.
+    repeated uint64 euis = 3;
+  }
+  // Set of gateways to subscribe to.
+  // Leave empty to subscribe to all gateways.
+  repeated ForwarderEUIs gateways = 2;
+
+  // Shared subscription group (optional).
+  // Queue durability depends on the Mapper configuration.
+  string group = 3;
+}
+
+service HomeNetworkMapper {
+  // List gateways.
+  // This rpc sets the total number of gateways in the x-total-count header.
+  rpc ListGateways(ListHomeNetworkGatewaysRequest) returns (Gateways);
+  // Get a gateway.
+  rpc GetGateway(GetHomeNetworkGatewayRequest) returns (Gateway);
+  // Subscribe to gateway updates.
+  rpc SubscribeGateway(SubscribeHomeNetworkGatewaysRequest) returns (stream Gateway);
+}

v1alpha1/messages.proto

@@ -125,7 +125,7 @@ message GatewayMetadataLocalization {
     repeated Antenna antennas = 1;
   }
   message Satellite {
-    // Ground location.
+    // Satellite location.
     Location location = 1;
   }
   oneof value {