Skip to content

Commit

Permalink
Merge pull request #7449 from TheThingsNetwork/feature/7427-battery-p…
Browse files Browse the repository at this point in the history
…ercentage

Add Network layer BatteryPercentage to ApplicationUplink
  • Loading branch information
halimi authored Jan 22, 2025
2 parents 18f015f + d63d032 commit 46220fd
Show file tree
Hide file tree
Showing 14 changed files with 1,053 additions and 554 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
16 changes: 16 additions & 0 deletions api/ttn/lorawan/v3/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 |
Expand Down
24 changes: 24 additions & 0 deletions api/ttn/lorawan/v3/api.swagger.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
}
}
},
Expand Down Expand Up @@ -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": {
Expand Down
20 changes: 19 additions & 1 deletion api/ttn/lorawan/v3/messages.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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 {
Expand Down
36 changes: 25 additions & 11 deletions pkg/networkserver/grpc_gsns.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand Down Expand Up @@ -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()

Expand Down Expand Up @@ -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),
},
},
})
Expand Down
8 changes: 8 additions & 0 deletions pkg/ttnpb/applicationserver.pb.paths.fm.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 46220fd

Please sign in to comment.