Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Network layer BatteryPercentage to ApplicationUplink #7449

Open
wants to merge 3 commits into
base: v3.33
Choose a base branch
from
Open

Add Network layer BatteryPercentage to ApplicationUplink #7449

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9d6e011
api: Add `LastBatteryPercentage` to the `ApplicationUplink`
halimi Dec 18, 2024
3ddac1b
ns: Add `LastBatteryPercentage` to the `ApplicationUplink` message
halimi Dec 18, 2024
f0668ce
dev: Update CHANGELOG
halimi Dec 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ For details about compatibility between different releases, see the **Commitment

### Added

- Add the latest battery percentage of the end device in the `ApplicationUplink` message.

### Changed

### Deprecated
Expand Down
16 changes: 16 additions & 0 deletions api/ttn/lorawan/v3/api.md
View file
Open in desktop
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`: `1`</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
View file
Open in desktop
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
View file
Open in desktop
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: 1
}];
Comment on lines +192 to +197
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment doesn't really match the validation rules. I think the comment needs to be changed to [0..1] interval. That would not be a percentage anymore, which is [0..100].

I hope it is [0, 100] like the comment says, otherwise turn it into a [0, 100] so that it matches the name (percentage), which is what API consumers would find most natural I think.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've copied this from the end_device.proto and calls it "percentage" but indeed then the validation should be [0, 100]
https://github.com/TheThingsNetwork/lorawan-stack/blob/v3.33/api/ttn/lorawan/v3/end_device.proto#L1142-L1148

  // Latest-known battery percentage of the device.
  // Received via the DevStatus MAC command at last_dev_status_received_at or earlier.
  // Stored in Network Server.
  google.protobuf.FloatValue battery_percentage = 35 [(validate.rules).float = {
    gte: 0,
    lte: 1
  }];

But I'll check it again and change it (or convert it) in my implementation to be a percentage value [0, 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
35 changes: 24 additions & 11 deletions pkg/networkserver/grpc_gsns.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -896,6 +896,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: dev.BatteryPercentage,
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 @@ -1141,17 +1153,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
View file
Open in desktop

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

Loading
Loading