Relay configuration interface

api/ttn/lorawan/v3/end_device.proto

@@ -171,7 +171,7 @@ message ServedRelayParameters {
     // The end device will control when it uses the relay mode. This is the default mode.
     RelayEndDeviceControlledMode end_device_controlled = 3;
   }
-  // Number of uplinks to be sent without a wake on radio frame.
+  // Number of wake on radio frames to be sent without an acknowledgement before sending the uplink message directly.
   uint32 backoff = 4 [(validate.rules).uint32.lte = 63];
   // Second wake on radio channel configuration.
   RelaySecondChannel second_channel = 5;
@@ -202,6 +202,75 @@ message RelayParameters {
   }
 }
 
+message ServingRelaySettings {
+  option (thethings.flags.message) = {
+    select: true,
+    set: true
+  };
+
+  // Second wake on radio channel configuration.
+  RelaySecondChannel second_channel = 1;
+  reserved 2; // DEPRECATED: default_channel_index (uint32)
+  // Index of the default wake on radio channel.
+  // If unset, the default value from Network Server configuration will be used.
+  google.protobuf.UInt32Value default_channel_index = 6 [(validate.rules).uint32.lte = 255];
+  // Channel activity detection periodicity.
+  RelayCADPeriodicity cad_periodicity = 3 [(validate.rules).enum.defined_only = true];
+  // Configured uplink forwarding rules.
+  repeated RelayUplinkForwardingRule uplink_forwarding_rules = 4 [(validate.rules).repeated.max_items = 16];
+  // Configured forwarding limits.
+  // If unset, the default value from Network Server configuration will be used.
+  ServingRelayForwardingLimits limits = 5;
+}
+
+message ServedRelaySettings {
+  option (thethings.flags.message) = {
+    select: true,
+    set: true
+  };
+
+  oneof mode {
+    option (validate.required) = true;
+
+    // The end device will always attempt to use the relay mode in order to send uplink messages.
+    RelayEndDeviceAlwaysMode always = 1;
+    // The end device will attempt to use relay mode only after a number of uplink messages have been sent without
+    // receiving a valid a downlink message.
+    RelayEndDeviceDynamicMode dynamic = 2;
+    // The end device will control when it uses the relay mode. This is the default mode.
+    RelayEndDeviceControlledMode end_device_controlled = 3;
+  }
+  reserved 4; // DEPRECATED: backoff (uint32)
+  // Number of wake on radio frames to be sent without an acknowledgement before sending the uplink message directly.
+  // If unset, the default value from Network Server configuration will be used.
+  google.protobuf.UInt32Value backoff = 7 [(validate.rules).uint32.lte = 63];
+  // Second wake on radio channel configuration.
+  RelaySecondChannel second_channel = 5;
+
+  // End device identifier of the serving end device.
+  string serving_device_id = 6 [(validate.rules).string = {
+    pattern: "^[a-z0-9](?:[-]?[a-z0-9]){2,}$",
+    max_len: 36
+  }];
+}
+
+// RelaySettings represent the settings of a relay.
+// This is used internally by the Network Server.
+message RelaySettings {
+  option (thethings.flags.message) = {
+    select: true,
+    set: true,
+    semantical: true
+  };
+
+  oneof mode {
+    option (validate.required) = true;
+
+    ServingRelaySettings serving = 1;
+    ServedRelaySettings served = 2;
+  }
+}
+
 // MACParameters represent the parameters of the device's MAC layer (active or desired).
 // This is used internally by the Network Server.
 message MACParameters {
@@ -561,13 +630,13 @@ message MACSettings {
   // of downlink messages: data and MAC downlinks, and join accepts.
   BoolValue schedule_downlinks = 35;
 
-  // The relay parameters the end device is using.
+  // The relay settings the end device is using.
   // If unset, the default value from Network Server configuration or regional parameters specification will be used.
-  RelayParameters relay = 36;
+  RelaySettings relay = 36;
 
-  // The relay parameters the Network Server should configure device to use via MAC commands.
+  // The relay settings the Network Server should configure device to use via MAC commands.
   // If unset, the default value from Network Server configuration or regional parameters specification will be used.
-  RelayParameters desired_relay = 37;
+  RelaySettings desired_relay = 37;
 }
 
 // MACState represents the state of MAC layer of the device.

api/ttn/lorawan/v3/networkserver_relay.proto

@@ -0,0 +1,201 @@
+// Copyright © 2023 The Things Network Foundation, 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 ttn.lorawan.v3;
+
+import "google/api/annotations.proto";
+import "google/protobuf/field_mask.proto";
+import "ttn/lorawan/v3/end_device.proto";
+import "ttn/lorawan/v3/identifiers.proto";
+import "validate/validate.proto";
+
+option go_package = "go.thethings.network/lorawan-stack/v3/pkg/ttnpb";
+
+message CreateRelayRequest {
+  // End device identifiers of the relay.
+  EndDeviceIdentifiers end_device_ids = 1 [(validate.rules).message.required = true];
+
+  // Relay configuration.
+  RelaySettings settings = 2 [(validate.rules).message.required = true];
+}
+
+message CreateRelayResponse {
+  // Relay configuration.
+  RelaySettings settings = 1;
+}
+
+message GetRelayRequest {
+  // End device identifiers of the relay.
+  EndDeviceIdentifiers end_device_ids = 1 [(validate.rules).message.required = true];
+
+  // Field mask of the fields to return.
+  google.protobuf.FieldMask field_mask = 2;
+}
+
+message GetRelayResponse {
+  // Relay configuration.
+  RelaySettings settings = 1;
+}
+
+message UpdateRelayRequest {
+  // End device identifiers of the relay.
+  EndDeviceIdentifiers end_device_ids = 1 [(validate.rules).message.required = true];
+
+  // Relay configuration.
+  RelaySettings settings = 2 [(validate.rules).message.required = true];
+
+  // Field mask of the fields to update.
+  google.protobuf.FieldMask field_mask = 3;
+}
+
+message UpdateRelayResponse {
+  // Relay configuration.
+  RelaySettings settings = 1;
+}
+
+message DeleteRelayRequest {
+  // End device identifiers of the relay.
+  EndDeviceIdentifiers end_device_ids = 1 [(validate.rules).message.required = true];
+}
+
+message DeleteRelayResponse {}
+
+message CreateRelayUplinkForwardingRuleRequest {
+  // End device identifiers of the relay.
+  EndDeviceIdentifiers end_device_ids = 1 [(validate.rules).message.required = true];
+
+  // Index of the uplink forwarding rule.
+  uint32 index = 2 [(validate.rules).uint32.lte = 15];
+
+  // Uplink forwarding rule.
+  RelayUplinkForwardingRule rule = 3 [(validate.rules).message.required = true];
+}
+
+message CreateRelayUplinkForwardingRuleResponse {
+  // Uplink forwarding rule.
+  RelayUplinkForwardingRule rule = 1;
+}
+
+message GetRelayUplinkForwardingRuleRequest {
+  // End device identifiers of the relay.
+  EndDeviceIdentifiers end_device_ids = 1 [(validate.rules).message.required = true];
+
+  // Index of the uplink forwarding rule.
+  uint32 index = 2 [(validate.rules).uint32.lte = 15];
+
+  // Field mask of the fields to return.
+  google.protobuf.FieldMask field_mask = 3;
+}
+
+message GetRelayUplinkForwardingRuleResponse {
+  // Uplink forwarding rule.
+  RelayUplinkForwardingRule rule = 1;
+}
+
+message ListRelayUplinkForwardingRulesRequest {
+  // End device identifiers of the relay.
+  EndDeviceIdentifiers end_device_ids = 1 [(validate.rules).message.required = true];
+
+  // Field mask of the fields to return.
+  google.protobuf.FieldMask field_mask = 2;
+}
+
+message ListRelayUplinkForwardingRulesResponse {
+  // Uplink forwarding rules.
+  repeated RelayUplinkForwardingRule rules = 1;
+}
+
+message UpdateRelayUplinkForwardingRuleRequest {
+  // End device identifiers of the relay.
+  EndDeviceIdentifiers end_device_ids = 1 [(validate.rules).message.required = true];
+
+  // Index of the uplink forwarding rule.
+  uint32 index = 2 [(validate.rules).uint32.lte = 15];
+
+  // Uplink forwarding rule.
+  RelayUplinkForwardingRule rule = 3 [(validate.rules).message.required = true];
+
+  // Field mask of the fields to update.
+  google.protobuf.FieldMask field_mask = 4;
+}
+
+message UpdateRelayUplinkForwardingRuleResponse {
+  // Uplink forwarding rule.
+  RelayUplinkForwardingRule rule = 1;
+}
+
+message DeleteRelayUplinkForwardingRuleRequest {
+  // End device identifiers of the relay.
+  EndDeviceIdentifiers end_device_ids = 1 [(validate.rules).message.required = true];
+
+  // Index of the uplink forwarding rule.
+  uint32 index = 2 [(validate.rules).uint32.lte = 15];
+}
+
+message DeleteRelayUplinkForwardingRuleResponse {}
+
+// The NsRelayConfigurationService provides configuration management capabilities for relays.
+service NsRelayConfigurationService {
+  // Create a relay.
+  rpc CreateRelay(CreateRelayRequest) returns (CreateRelayResponse) {
+    option (google.api.http) = {
+      post: "/ns/applications/{end_device_ids.application_ids.application_id}/relays"
+      body: "*"
+    };
+  }
+  // Get a relay.
+  rpc GetRelay(GetRelayRequest) returns (GetRelayResponse) {
+    option (google.api.http) = {get: "/ns/applications/{end_device_ids.application_ids.application_id}/relays/{end_device_ids.device_id}"};
+  }
+  // Update a relay.
+  rpc UpdateRelay(UpdateRelayRequest) returns (UpdateRelayResponse) {
+    option (google.api.http) = {
+      put: "/ns/applications/{end_device_ids.application_ids.application_id}/relays/{end_device_ids.device_id}"
+      body: "*"
+    };
+  }
+  // Delete a relay.
+  rpc DeleteRelay(DeleteRelayRequest) returns (DeleteRelayResponse) {
+    option (google.api.http) = {delete: "/ns/applications/{end_device_ids.application_ids.application_id}/relays/{end_device_ids.device_id}"};
+  }
+
+  // Create an uplink forwarding rule.
+  rpc CreateRelayUplinkForwardingRule(CreateRelayUplinkForwardingRuleRequest) returns (CreateRelayUplinkForwardingRuleResponse) {
+    option (google.api.http) = {
+      post: "/ns/applications/{end_device_ids.application_ids.application_id}/relays/{end_device_ids.device_id}/uplink-forwarding-rules"
+      body: "*"
+    };
+  }
+  // Get an uplink forwarding rule.
+  rpc GetRelayUplinkForwardingRule(GetRelayUplinkForwardingRuleRequest) returns (GetRelayUplinkForwardingRuleResponse) {
+    option (google.api.http) = {get: "/ns/applications/{end_device_ids.application_ids.application_id}/relays/{end_device_ids.device_id}/uplink-forwarding-rules/{index}"};
+  }
+  // List uplink forwarding rules.
+  rpc ListRelayUplinkForwardingRules(ListRelayUplinkForwardingRulesRequest) returns (ListRelayUplinkForwardingRulesResponse) {
+    option (google.api.http) = {get: "/ns/applications/{end_device_ids.application_ids.application_id}/relays/{end_device_ids.device_id}/uplink-forwarding-rules"};
+  }
+  // Update an uplink forwarding rule.
+  rpc UpdateRelayUplinkForwardingRule(UpdateRelayUplinkForwardingRuleRequest) returns (UpdateRelayUplinkForwardingRuleResponse) {
+    option (google.api.http) = {
+      put: "/ns/applications/{end_device_ids.application_ids.application_id}/relays/{end_device_ids.device_id}/uplink-forwarding-rules/{index}"
+      body: "*"
+    };
+  }
+  // Delete an uplink forwarding rule.
+  rpc DeleteRelayUplinkForwardingRule(DeleteRelayUplinkForwardingRuleRequest) returns (DeleteRelayUplinkForwardingRuleResponse) {
+    option (google.api.http) = {delete: "/ns/applications/{end_device_ids.application_ids.application_id}/relays/{end_device_ids.device_id}/uplink-forwarding-rules/{index}"};
+  }
+}