Add Network layer BatteryPercentage to ApplicationUplink

CHANGELOG.md

@@ -12,6 +12,7 @@ For details about compatibility between different releases, see the **Commitment
 ### Added
 
 - Add recvTime field to the decodeUplink input in payload formatters
+- Add the latest battery percentage of the end device in the `ApplicationUplink` message.
 
 ### Changed
 

api/ttn/lorawan/v3/api.md

@@ -615,6 +615,7 @@
   - [Message `DownlinkQueueRequest`](#ttn.lorawan.v3.DownlinkQueueRequest)
   - [Message `GatewayTxAcknowledgment`](#ttn.lorawan.v3.GatewayTxAcknowledgment)
   - [Message `GatewayUplinkMessage`](#ttn.lorawan.v3.GatewayUplinkMessage)
+  - [Message `LastBatteryPercentage`](#ttn.lorawan.v3.LastBatteryPercentage)
   - [Message `MessagePayloadFormatters`](#ttn.lorawan.v3.MessagePayloadFormatters)
   - [Message `TxAcknowledgment`](#ttn.lorawan.v3.TxAcknowledgment)
   - [Message `UplinkMessage`](#ttn.lorawan.v3.UplinkMessage)
@@ -8795,6 +8796,7 @@ Application uplink message.
 | `locations` | [`ApplicationUplink.LocationsEntry`](#ttn.lorawan.v3.ApplicationUplink.LocationsEntry) | repeated | End device location metadata, set by the Application Server while handling the message. |
 | `version_ids` | [`EndDeviceVersionIdentifiers`](#ttn.lorawan.v3.EndDeviceVersionIdentifiers) |  | End device version identifiers, set by the Application Server while handling the message. |
 | `network_ids` | [`NetworkIdentifiers`](#ttn.lorawan.v3.NetworkIdentifiers) |  | Network identifiers, set by the Network Server that handles the message. |
+| `last_battery_percentage` | [`LastBatteryPercentage`](#ttn.lorawan.v3.LastBatteryPercentage) |  | Last battery percentage of the end device. Received via the DevStatus MAC command at last_dev_status_received_at or earlier. Set by the Network Server while handling the message. |
 
 #### Field Rules
 
@@ -8940,6 +8942,20 @@ ncrc: [scheduled.advanced]
 | ----- | ----------- |
 | `message` | <p>`message.required`: `true`</p> |
 
+### <a name="ttn.lorawan.v3.LastBatteryPercentage">Message `LastBatteryPercentage`</a>
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| `f_cnt` | [`uint32`](#uint32) |  | Frame counter value of last uplink containing DevStatusAns. |
+| `value` | [`google.protobuf.FloatValue`](#google.protobuf.FloatValue) |  | The battery percentage of the end device. The value is defined in the [0, 100] interval. |
+| `received_at` | [`google.protobuf.Timestamp`](#google.protobuf.Timestamp) |  | Time when last DevStatus MAC command was received. |
+
+#### Field Rules
+
+| Field | Validations |
+| ----- | ----------- |
+| `value` | <p>`float.lte`: `100`</p><p>`float.gte`: `0`</p> |
+
 ### <a name="ttn.lorawan.v3.MessagePayloadFormatters">Message `MessagePayloadFormatters`</a>
 
 | Field | Type | Label | Description |

api/ttn/lorawan/v3/api.swagger.json

@@ -21068,6 +21068,10 @@
         "network_ids": {
           "$ref": "#/definitions/v3NetworkIdentifiers",
           "description": "Network identifiers, set by the Network Server that handles the message."
+        },
+        "last_battery_percentage": {
+          "$ref": "#/definitions/v3LastBatteryPercentage",
+          "description": "Last battery percentage of the end device.\nReceived via the DevStatus MAC command at last_dev_status_received_at or earlier.\nSet by the Network Server while handling the message."
         }
       }
     },
@@ -25802,6 +25806,26 @@
         }
       }
     },
+    "v3LastBatteryPercentage": {
+      "type": "object",
+      "properties": {
+        "f_cnt": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Frame counter value of last uplink containing DevStatusAns."
+        },
+        "value": {
+          "type": "number",
+          "format": "float",
+          "description": "The battery percentage of the end device.\nThe value is defined in the [0, 100] interval."
+        },
+        "received_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Time when last DevStatus MAC command was received."
+        }
+      }
+    },
     "v3ListBandsResponse": {
       "type": "object",
       "properties": {

api/ttn/lorawan/v3/messages.proto

@@ -186,6 +186,19 @@ message GatewayUplinkMessage {
   string band_id = 2;
 }
 
+message LastBatteryPercentage {
+  // Frame counter value of last uplink containing DevStatusAns.
+  uint32 f_cnt = 1;
+  // The battery percentage of the end device.
+  // The value is defined in the [0, 100] interval.
+  google.protobuf.FloatValue value = 2 [(validate.rules).float = {
+    gte: 0,
+    lte: 100
+  }];
+  // Time when last DevStatus MAC command was received.
+  google.protobuf.Timestamp received_at = 3;
+}
+
 message ApplicationUplink {
   option (thethings.flags.message) = {
     select: true,
@@ -259,7 +272,12 @@ message ApplicationUplink {
   // Network identifiers, set by the Network Server that handles the message.
   NetworkIdentifiers network_ids = 16;
 
-  // next: 20
+  // Last battery percentage of the end device.
+  // Received via the DevStatus MAC command at last_dev_status_received_at or earlier.
+  // Set by the Network Server while handling the message.
+  LastBatteryPercentage last_battery_percentage = 20;
+
+  // next: 21
 }
 
 message ApplicationUplinkNormalized {

pkg/networkserver/grpc_gsns.go

@@ -43,6 +43,7 @@ import (
 	"google.golang.org/protobuf/types/known/durationpb"
 	"google.golang.org/protobuf/types/known/emptypb"
 	"google.golang.org/protobuf/types/known/timestamppb"
+	"google.golang.org/protobuf/types/known/wrapperspb"
 )
 
 const (
@@ -904,6 +905,18 @@ const (
 	initialDeduplicationRound = iota
 )
 
+func lastBatteryPercentage(dev *ttnpb.EndDevice) *ttnpb.LastBatteryPercentage {
+	if dev.MacState == nil || dev.BatteryPercentage == nil || dev.LastDevStatusReceivedAt == nil {
+		return nil
+	}
+
+	return &ttnpb.LastBatteryPercentage{
+		FCnt:       dev.MacState.LastDevStatusFCntUp,
+		Value:      wrapperspb.Float(dev.BatteryPercentage.Value * 100),
+		ReceivedAt: dev.LastDevStatusReceivedAt,
+	}
+}
+
 func (ns *NetworkServer) handleDataUplink(ctx context.Context, up *ttnpb.UplinkMessage) (err error) {
 	defer trace.StartRegion(ctx, "handle data uplink").End()
 
@@ -1149,17 +1162,18 @@ func (ns *NetworkServer) handleDataUplink(ctx context.Context, up *ttnpb.UplinkM
 			CorrelationIds: up.CorrelationIds,
 			Up: &ttnpb.ApplicationUp_UplinkMessage{
 				UplinkMessage: &ttnpb.ApplicationUplink{
-					Confirmed:       up.Payload.MHdr.MType == ttnpb.MType_CONFIRMED_UP,
-					FCnt:            pld.FullFCnt,
-					FPort:           pld.FPort,
-					FrmPayload:      frmPayload,
-					RxMetadata:      up.RxMetadata,
-					SessionKeyId:    stored.Session.Keys.SessionKeyId,
-					Settings:        up.Settings,
-					ReceivedAt:      up.ReceivedAt,
-					ConsumedAirtime: up.ConsumedAirtime,
-					PacketErrorRate: mac.LossRate(stored.MacState, matched.phy),
-					NetworkIds:      ns.networkIdentifiers(ctx),
+					Confirmed:             up.Payload.MHdr.MType == ttnpb.MType_CONFIRMED_UP,
+					FCnt:                  pld.FullFCnt,
+					FPort:                 pld.FPort,
+					FrmPayload:            frmPayload,
+					RxMetadata:            up.RxMetadata,
+					SessionKeyId:          stored.Session.Keys.SessionKeyId,
+					Settings:              up.Settings,
+					ReceivedAt:            up.ReceivedAt,
+					ConsumedAirtime:       up.ConsumedAirtime,
+					PacketErrorRate:       mac.LossRate(stored.MacState, matched.phy),
+					NetworkIds:            ns.networkIdentifiers(ctx),
+					LastBatteryPercentage: lastBatteryPercentage(stored),
 				},
 			},
 		})