api: Add recent downlink format

TheThingsNetwork · Jul 14, 2022 · 9d339b2 · 9d339b2
1 parent 430713f
commit 9d339b2
Show file tree

Hide file tree

Showing 11 changed files with 804 additions and 400 deletions.
diff --git a/api/api.md b/api/api.md
@@ -223,6 +223,7 @@
   - [Message `MACState`](#ttn.lorawan.v3.MACState)
   - [Message `MACState.DataRateRange`](#ttn.lorawan.v3.MACState.DataRateRange)
   - [Message `MACState.DataRateRanges`](#ttn.lorawan.v3.MACState.DataRateRanges)
+  - [Message `MACState.DownlinkMessage`](#ttn.lorawan.v3.MACState.DownlinkMessage)
   - [Message `MACState.JoinAccept`](#ttn.lorawan.v3.MACState.JoinAccept)
   - [Message `MACState.JoinRequest`](#ttn.lorawan.v3.MACState.JoinRequest)
   - [Message `MACState.RejectedDataRateRangesEntry`](#ttn.lorawan.v3.MACState.RejectedDataRateRangesEntry)
@@ -3622,7 +3623,7 @@ This is used internally by the Network Server.
 | `pending_join_request` | [`MACState.JoinRequest`](#ttn.lorawan.v3.MACState.JoinRequest) |  | Pending join request. Set each time a join-accept is scheduled and removed each time an uplink is received from the device. |
 | `rx_windows_available` | [`bool`](#bool) |  | Whether or not Rx windows are expected to be open. Set to true every time an uplink is received. Set to false every time a successful downlink scheduling attempt is made. |
 | `recent_uplinks` | [`MACState.UplinkMessage`](#ttn.lorawan.v3.MACState.UplinkMessage) | repeated | Recent data uplink messages sorted by time. The number of messages stored may depend on configuration. |
-| `recent_downlinks` | [`DownlinkMessage`](#ttn.lorawan.v3.DownlinkMessage) | repeated | Recent data downlink messages sorted by time. The number of messages stored may depend on configuration. |
+| `recent_downlinks` | [`MACState.DownlinkMessage`](#ttn.lorawan.v3.MACState.DownlinkMessage) | repeated | Recent data downlink messages sorted by time. The number of messages stored may depend on configuration. |
 | `last_network_initiated_downlink_at` | [`google.protobuf.Timestamp`](#google.protobuf.Timestamp) |  | Time when the last network-initiated downlink message was scheduled. |
 | `rejected_adr_data_rate_indexes` | [`DataRateIndex`](#ttn.lorawan.v3.DataRateIndex) | repeated | ADR Data rate index values rejected by the device. Reset each time `current_parameters.channels` change. Elements are sorted in ascending order. |
 | `rejected_adr_tx_power_indexes` | [`uint32`](#uint32) | repeated | ADR TX output power index values rejected by the device. Elements are sorted in ascending order. |
@@ -3669,6 +3670,22 @@ This is used internally by the Network Server.
 | ----- | ----------- |
 | `ranges` | <p>`repeated.min_items`: `1`</p> |
 
+### <a name="ttn.lorawan.v3.MACState.DownlinkMessage">Message `MACState.DownlinkMessage`</a>
+
+A minimal DownlinkMessage definition which is binary compatible with the top level DownlinkMessage message.
+Used for type safe recent downlink storage.
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `payload` | [`Message`](#ttn.lorawan.v3.Message) |  |  |
+| `correlation_ids` | [`string`](#string) | repeated |  |
+
+#### Field Rules
+
+| Field | Validations |
+| ----- | ----------- |
+| `correlation_ids` | <p>`repeated.items.string.max_len`: `100`</p> |
+
 ### <a name="ttn.lorawan.v3.MACState.JoinAccept">Message `MACState.JoinAccept`</a>
 
 | Field | Type | Label | Description |

diff --git a/api/api.swagger.json b/api/api.swagger.json
@@ -12668,6 +12668,38 @@
         }
       }
     },
+    "lorawanv3DownlinkMessage": {
+      "type": "object",
+      "properties": {
+        "raw_payload": {
+          "type": "string",
+          "format": "byte"
+        },
+        "payload": {
+          "$ref": "#/definitions/lorawanv3Message"
+        },
+        "end_device_ids": {
+          "$ref": "#/definitions/v3EndDeviceIdentifiers"
+        },
+        "request": {
+          "$ref": "#/definitions/v3TxRequest"
+        },
+        "scheduled": {
+          "$ref": "#/definitions/lorawanv3TxSettings"
+        },
+        "correlation_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "session_key_id": {
+          "type": "string",
+          "format": "byte"
+        }
+      },
+      "title": "Downlink message from the network to the end device"
+    },
     "lorawanv3GatewayIdentifiers": {
       "type": "object",
       "properties": {
@@ -15080,38 +15112,6 @@
         }
       }
     },
-    "v3DownlinkMessage": {
-      "type": "object",
-      "properties": {
-        "raw_payload": {
-          "type": "string",
-          "format": "byte"
-        },
-        "payload": {
-          "$ref": "#/definitions/lorawanv3Message"
-        },
-        "end_device_ids": {
-          "$ref": "#/definitions/v3EndDeviceIdentifiers"
-        },
-        "request": {
-          "$ref": "#/definitions/v3TxRequest"
-        },
-        "scheduled": {
-          "$ref": "#/definitions/lorawanv3TxSettings"
-        },
-        "correlation_ids": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "session_key_id": {
-          "type": "string",
-          "format": "byte"
-        }
-      },
-      "title": "Downlink message from the network to the end device"
-    },
     "v3DownlinkPath": {
       "type": "object",
       "properties": {
@@ -16192,7 +16192,7 @@
       "type": "object",
       "properties": {
         "downlink_message": {
-          "$ref": "#/definitions/v3DownlinkMessage",
+          "$ref": "#/definitions/lorawanv3DownlinkMessage",
           "description": "DownlinkMessage for the gateway."
         }
       },
@@ -17246,7 +17246,7 @@
         "recent_downlinks": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/v3DownlinkMessage"
+            "$ref": "#/definitions/v3MACStateDownlinkMessage"
           },
           "description": "Recent data downlink messages sorted by time.\nThe number of messages stored may depend on configuration."
         },
@@ -17298,6 +17298,21 @@
       },
       "description": "MACState represents the state of MAC layer of the device.\nMACState is reset on each join for OTAA or ResetInd for ABP devices.\nThis is used internally by the Network Server."
     },
+    "v3MACStateDownlinkMessage": {
+      "type": "object",
+      "properties": {
+        "payload": {
+          "$ref": "#/definitions/lorawanv3Message"
+        },
+        "correlation_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "A minimal DownlinkMessage definition which is binary compatible with the top level DownlinkMessage message.\nUsed for type safe recent downlink storage."
+    },
     "v3MACStateJoinRequest": {
       "type": "object",
       "properties": {
@@ -18879,7 +18894,7 @@
           "$ref": "#/definitions/TxAcknowledgmentResult"
         },
         "downlink_message": {
-          "$ref": "#/definitions/v3DownlinkMessage",
+          "$ref": "#/definitions/lorawanv3DownlinkMessage",
           "description": "The acknowledged downlink message. Set by the Gateway Server."
         }
       }

diff --git a/api/end_device.proto b/api/end_device.proto
@@ -491,6 +491,18 @@ message MACState {
     reserved 10; // consumed_airtime
   }
 
+  // A minimal DownlinkMessage definition which is binary compatible with the top level DownlinkMessage message.
+  // Used for type safe recent downlink storage.
+  message DownlinkMessage {
+    reserved 1; // raw_payload
+    Message payload = 2;
+    reserved 3; // end_device_ids
+    reserved 4; // request
+    reserved 5; // scheduled
+    repeated string correlation_ids = 6 [(validate.rules).repeated.items.string.max_len = 100];
+    reserved 7; // session_key_id
+  }
+
   // Recent data uplink messages sorted by time.
   // The number of messages stored may depend on configuration.
   repeated UplinkMessage recent_uplinks = 14;