Merge pull request #6962 from TheThingsNetwork/feature/adr-fine-grained

Fine grained ADR NbTrans controls
TheThingsNetwork · Mar 6, 2024 · f372251 · f372251
2 parents ab6d907 + 9524f26
commit f372251
Show file tree

Hide file tree

Showing 20 changed files with 5,473 additions and 1,462 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,8 @@ For details about compatibility between different releases, see the **Commitment
 
 ### Added
 
+- Fine grained NbTrans overrides for the dynamic ADR mode. See the `--mac-settings.adr.mode.dynamic.overrides.data-rate-[index].min-nb-trans` and `--mac-settings.adr.mode.dynamic.overrides.data-rate-[index].max-nb-trans` family of parameters.
+
 ### Changed
 
 ### Deprecated

diff --git a/api/ttn/lorawan/v3/api.md b/api/ttn/lorawan/v3/api.md
@@ -239,6 +239,8 @@
   - [Message `ADRSettings.DynamicMode.ChannelSteeringSettings`](#ttn.lorawan.v3.ADRSettings.DynamicMode.ChannelSteeringSettings)
   - [Message `ADRSettings.DynamicMode.ChannelSteeringSettings.DisabledMode`](#ttn.lorawan.v3.ADRSettings.DynamicMode.ChannelSteeringSettings.DisabledMode)
   - [Message `ADRSettings.DynamicMode.ChannelSteeringSettings.LoRaNarrowMode`](#ttn.lorawan.v3.ADRSettings.DynamicMode.ChannelSteeringSettings.LoRaNarrowMode)
+  - [Message `ADRSettings.DynamicMode.Overrides`](#ttn.lorawan.v3.ADRSettings.DynamicMode.Overrides)
+  - [Message `ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride)
   - [Message `ADRSettings.StaticMode`](#ttn.lorawan.v3.ADRSettings.StaticMode)
   - [Message `BatchDeleteEndDevicesRequest`](#ttn.lorawan.v3.BatchDeleteEndDevicesRequest)
   - [Message `BatchGetEndDevicesRequest`](#ttn.lorawan.v3.BatchGetEndDevicesRequest)
@@ -3715,6 +3717,7 @@ Configuration options for dynamic ADR.
 | `min_nb_trans` | [`google.protobuf.UInt32Value`](#google.protobuf.UInt32Value) |  | Minimum number of retransmissions. If unset, the default value from Network Server configuration will be used. |
 | `max_nb_trans` | [`google.protobuf.UInt32Value`](#google.protobuf.UInt32Value) |  | Maximum number of retransmissions. If unset, the default value from Network Server configuration will be used. |
 | `channel_steering` | [`ADRSettings.DynamicMode.ChannelSteeringSettings`](#ttn.lorawan.v3.ADRSettings.DynamicMode.ChannelSteeringSettings) |  |  |
+| `overrides` | [`ADRSettings.DynamicMode.Overrides`](#ttn.lorawan.v3.ADRSettings.DynamicMode.Overrides) |  |  |
 
 #### Field Rules
 
@@ -3745,6 +3748,45 @@ Configuration options for LoRa narrow channels steering.
 The narrow mode attempts to steer the end device towards
 using the LoRa modulated, 125kHz bandwidth channels.
 
+### <a name="ttn.lorawan.v3.ADRSettings.DynamicMode.Overrides">Message `ADRSettings.DynamicMode.Overrides`</a>
+
+EXPERIMENTAL: Configuration overrides.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `data_rate_0` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_1` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_2` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_3` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_4` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_5` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_6` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_7` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_8` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_9` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_10` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_11` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_12` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_13` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_14` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+| `data_rate_15` | [`ADRSettings.DynamicMode.PerDataRateIndexOverride`](#ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride) |  |  |
+
+### <a name="ttn.lorawan.v3.ADRSettings.DynamicMode.PerDataRateIndexOverride">Message `ADRSettings.DynamicMode.PerDataRateIndexOverride`</a>
+
+EXPERIMENTAL: Data rate index override settings.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `min_nb_trans` | [`google.protobuf.UInt32Value`](#google.protobuf.UInt32Value) |  | Minimum number of retransmissions. If unset, the default value from Network Server configuration will be used. |
+| `max_nb_trans` | [`google.protobuf.UInt32Value`](#google.protobuf.UInt32Value) |  | Maximum number of retransmissions. If unset, the default value from Network Server configuration will be used. |
+
+#### Field Rules
+
+| Field | Validations |
+| ----- | ----------- |
+| `min_nb_trans` | <p>`uint32.lte`: `3`</p><p>`uint32.gte`: `1`</p> |
+| `max_nb_trans` | <p>`uint32.lte`: `3`</p><p>`uint32.gte`: `1`</p> |
+
 ### <a name="ttn.lorawan.v3.ADRSettings.StaticMode">Message `ADRSettings.StaticMode`</a>
 
 Configuration options for static ADR.

diff --git a/api/ttn/lorawan/v3/api.swagger.json b/api/ttn/lorawan/v3/api.swagger.json
@@ -14218,6 +14218,9 @@
         },
         "channel_steering": {
           "$ref": "#/definitions/DynamicModeChannelSteeringSettings"
+        },
+        "overrides": {
+          "$ref": "#/definitions/DynamicModeOverrides"
         }
       },
       "description": "Configuration options for dynamic ADR."
@@ -15002,6 +15005,76 @@
       "type": "object",
       "description": "Configuration options for cases in which ADR is not supposed to steer the end device\nto another set of channels."
     },
+    "DynamicModeOverrides": {
+      "type": "object",
+      "properties": {
+        "data_rate_0": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_1": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_2": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_3": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_4": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_5": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_6": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_7": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_8": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_9": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_10": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_11": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_12": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_13": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_14": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        },
+        "data_rate_15": {
+          "$ref": "#/definitions/DynamicModePerDataRateIndexOverride"
+        }
+      },
+      "description": "EXPERIMENTAL: Configuration overrides."
+    },
+    "DynamicModePerDataRateIndexOverride": {
+      "type": "object",
+      "properties": {
+        "min_nb_trans": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Minimum number of retransmissions.\nIf unset, the default value from Network Server configuration will be used."
+        },
+        "max_nb_trans": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Maximum number of retransmissions.\nIf unset, the default value from Network Server configuration will be used."
+        }
+      },
+      "description": "EXPERIMENTAL: Data rate index override settings."
+    },
     "EndDeviceClaimingServerAuthorizeApplicationBody": {
       "type": "object",
       "properties": {

diff --git a/api/ttn/lorawan/v3/end_device.proto b/api/ttn/lorawan/v3/end_device.proto
@@ -493,6 +493,56 @@ message ADRSettings {
     }
 
     ChannelSteeringSettings channel_steering = 8;
+
+    // EXPERIMENTAL: Data rate index override settings.
+    message PerDataRateIndexOverride {
+      option (thethings.flags.message) = {
+        select: true,
+        set: true
+      };
+      reserved 1;
+      reserved "min_tx_power_index";
+      reserved 2;
+      reserved "max_tx_power_index";
+      // Minimum number of retransmissions.
+      // If unset, the default value from Network Server configuration will be used.
+      google.protobuf.UInt32Value min_nb_trans = 3 [(validate.rules).uint32 = {
+        gte: 1,
+        lte: 3
+      }];
+      // Maximum number of retransmissions.
+      // If unset, the default value from Network Server configuration will be used.
+      google.protobuf.UInt32Value max_nb_trans = 4 [(validate.rules).uint32 = {
+        gte: 1,
+        lte: 3
+      }];
+    }
+
+    // EXPERIMENTAL: Configuration overrides.
+    message Overrides {
+      option (thethings.flags.message) = {
+        select: true,
+        set: true
+      };
+      PerDataRateIndexOverride data_rate_0 = 1;
+      PerDataRateIndexOverride data_rate_1 = 2;
+      PerDataRateIndexOverride data_rate_2 = 3;
+      PerDataRateIndexOverride data_rate_3 = 4;
+      PerDataRateIndexOverride data_rate_4 = 5;
+      PerDataRateIndexOverride data_rate_5 = 6;
+      PerDataRateIndexOverride data_rate_6 = 7;
+      PerDataRateIndexOverride data_rate_7 = 8;
+      PerDataRateIndexOverride data_rate_8 = 9;
+      PerDataRateIndexOverride data_rate_9 = 10;
+      PerDataRateIndexOverride data_rate_10 = 11;
+      PerDataRateIndexOverride data_rate_11 = 12;
+      PerDataRateIndexOverride data_rate_12 = 13;
+      PerDataRateIndexOverride data_rate_13 = 14;
+      PerDataRateIndexOverride data_rate_14 = 15;
+      PerDataRateIndexOverride data_rate_15 = 16;
+    }
+
+    Overrides overrides = 9;
   }
 
   // Configuration options for cases in which ADR is to be disabled