Merge pull request #6678 from TheThingsNetwork/feature/relay

LoRaWAN Relay implementation

api/ttn/lorawan/v3/end_device.proto

@@ -88,6 +88,108 @@ message BoolValue {
   bool value = 1;
 }
 
+message ServingRelayParameters {
+  option (thethings.flags.message) = {
+    select: true,
+    set: true
+  };
+
+  // Second wake on radio channel configuration.
+  RelaySecondChannel second_channel = 1;
+  // Index of the default wake on radio channel.
+  uint32 default_channel_index = 2 [(validate.rules).uint32.lte = 255];
+  // Channel activity detection periodicity.
+  RelayCADPeriodicity cad_periodicity = 3 [(validate.rules).enum.defined_only = true];
+  message UplinkForwardingRule {
+    // Bucket configuration for the served end device.
+    // If unset, no individual limits will apply to the end device, but the relay global limitations will apply.
+    RelayUplinkForwardLimits limits = 1;
+    // Last wake on radio frame counter used by the served end device.
+    uint32 last_w_f_cnt = 2;
+
+    // End device identifier of the served end device.
+    string device_id = 3 [(validate.rules).string = {
+      pattern: "^[a-z0-9](?:[-]?[a-z0-9]){2,}$",
+      max_len: 36,
+      ignore_empty: true
+    }];
+    // Session key ID of the session keys used to derive the root relay session key.
+    bytes session_key_id = 4;
+  }
+  // Configured uplink forwarding rules.
+  repeated UplinkForwardingRule uplink_forwarding_rules = 4 [(validate.rules).repeated.max_items = 16];
+  message ForwardingLimits {
+    // Reset behavior of the buckets upon limit update.
+    RelayResetLimitCounter reset_behavior = 1;
+    // Bucket configuration for join requests.
+    // If unset, no individual limits will apply to join requests, but the relay overall limitations will apply.
+    RelayForwardLimits join_requests = 2;
+    // Bucket configuration for unknown device notifications.
+    // If unset, no individual limits will apply to unknown end device notifications, but the relay overall
+    // limitations will still apply.
+    RelayForwardLimits notifications = 3;
+    // Bucket configuration for uplink messages across all served end devices.
+    // If unset, no individual limits will apply to uplink messages across all served end devices, but the relay
+    // overall limitations will still apply.
+    RelayForwardLimits uplink_messages = 4;
+    // Bucket configuration for all relay messages.
+    // If unset, no overall limits will apply to the relay, but individual limitations will still apply.
+    RelayForwardLimits overall = 5;
+  }
+  // Configured forwarding limits.
+  // If unset, the default value from Network Server configuration will be used.
+  ForwardingLimits limits = 5;
+}
+
+message ServedRelayParameters {
+  option (thethings.flags.message) = {
+    select: true,
+    set: true,
+    semantical: 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;
+  }
+  // Number of uplinks to be sent without a wake on radio frame.
+  uint32 backoff = 4 [(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
+  }];
+}
+
+// RelayParameters represent the parameters of a relay.
+// This is used internally by the Network Server.
+message RelayParameters {
+  option (thethings.flags.message) = {
+    select: true,
+    set: true,
+    semantical: true
+  };
+
+  oneof mode {
+    option (validate.required) = true;
+
+    // Parameters related to a relay which is serving end devices.
+    ServingRelayParameters serving = 25;
+    // Parameters related to an end device served by a relay.
+    ServedRelayParameters served = 26;
+  }
+}
+
 // MACParameters represent the parameters of the device's MAC layer (active or desired).
 // This is used internally by the Network Server.
 message MACParameters {
@@ -162,10 +264,10 @@ message MACParameters {
   repeated Channel channels = 19 [(validate.rules).repeated.min_items = 1];
 
   // Whether uplink dwell time is set (400ms).
-  // If this field is not set, then the value is either unknown or irrelevant(Network Server cannot modify it).
+  // If unset, then the value is either unknown or irrelevant(Network Server cannot modify it).
   BoolValue uplink_dwell_time = 20;
   // Whether downlink dwell time is set (400ms).
-  // If this field is not set, then the value is either unknown or irrelevant(Network Server cannot modify it).
+  // If unset, then the value is either unknown or irrelevant(Network Server cannot modify it).
   BoolValue downlink_dwell_time = 21;
 
   // ADR: number of messages to wait before setting ADRAckReq.
@@ -174,6 +276,9 @@ message MACParameters {
   ADRAckDelayExponentValue adr_ack_delay_exponent = 23;
   // Data rate index of the class B ping slot.
   DataRateIndexValue ping_slot_data_rate_index_value = 24;
+
+  // Relay parameters.
+  RelayParameters relay = 25;
 }
 
 // Template for creating end devices.
@@ -443,6 +548,14 @@ message MACSettings {
   // This option can be used in order to disable any downlink interaction with the end device. It will affect all types
   // of downlink messages: data and MAC downlinks, and join accepts.
   BoolValue schedule_downlinks = 35;
+
+  // The relay parameters the end device is using.
+  // If unset, the default value from Network Server configuration or regional parameters specification will be used.
+  RelayParameters relay = 36;
+
+  // The relay parameters 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;
 }
 
 // MACState represents the state of MAC layer of the device.
@@ -574,7 +687,11 @@ message MACState {
         reserved 1 to 10;
       }
       PacketBrokerMetadata packet_broker = 18;
-      reserved 2 to 8, 10, 12, 13, 16, 17, 19, 20, 99;
+      message RelayMetadata {
+        reserved 1 to 3;
+      }
+      RelayMetadata relay = 23;
+      reserved 2 to 8, 10, 12, 13, 16, 17, 19, 20, 21, 22, 99;
     }
     repeated RxMetadata rx_metadata = 5;
     google.protobuf.Timestamp received_at = 6;
@@ -665,6 +782,11 @@ message MACState {
   // The Network Server may choose to store only certain types of MAC
   // command identifiers in the underlying implementation.
   repeated MACCommandIdentifier recent_mac_command_identifiers = 23;
+
+  // Pending relay downlink contents.
+  // The pending downlink will be scheduled to the relay in either Rx1 or Rx2.
+  // The pending downlink will be cleared after the scheduling attempt.
+  RelayForwardDownlinkReq pending_relay_downlink = 24;
 }
 
 // Power state of the device.