Add Network layer BatteryPercentage to ApplicationUplink

[KrishnaIyer]

Summary

Add Network layer BatteryPercentage to ApplicationUplink.

Current Situation

Battery (value/percentage/capacity etc) is usually a part of the application payload for many devices. The format here is left to the device implementation.

However, LoRaWAN supports the DevStatus commands to allow the Network Server to query BatteryPercentage from end devices and the format of this value is standardized.

Why do we need this? Who uses it, and when?

Some customers choose not to send this data in the application payload but use the LoRaWAN network layer value.

In TTS we already store this in the end device.

We just have to append this to the ApplicationUplink similar to what we do with the Packet Error Rate.

The downside is that this adds an extra field which bloats the uplink message.

@johanstokking: Do you see any side effects of doing this?

Proposed Implementation

• Define a new field LatestBatteryPercentage to ApplicationUplink.
  • We should add a clear message of where this value comes from and when this value is 0 or static (ex: if DevStatusReq was never sent or sent a very long time ago)
• Get this value from the end device store when an uplink is matched and add it to ApplicationUplink.

Contributing

• I can help by doing more research.
• I can help by implementing the feature after the proposal above is approved.
• I can help by testing the feature before it's released.

Validation

• The feature is tested in a staging environment.
• The feature is documented in The Things Stack Documentation

Code of Conduct

• I agree to follow TTN's Community Code of Conduct.

[johanstokking]

The downside is that this adds an extra field which bloats the uplink message.

@johanstokking: Do you see any side effects of doing this?

I think this is worth an extra field.

Proposed Implementation

* Define a new field `LatestBatteryPercentage` to `ApplicationUplink`.
  
  * We should add a clear message of where this value comes from and when this value is 0 or static (ex: if `DevStatusReq` was never sent or sent a very long time ago)

* Get this value from the end device store when an uplink is matched and add it to `ApplicationUplink`.

I don't think this field should be sticky, that is, always included. I think it should only be there when there's a new value. To query the latest battery percentage, we already have NS API.

[KrishnaIyer]

I don't think this field should be sticky, that is, always included. I think it should only be there when there's a new value.

Hmm how do we track this though? We'd need to store the state that there's a new value and set/unset that or something.

Also if the first uplink that contains an updated value is missed by the data sink (integration), then they'd miss the update.

I get the idea but it feels like this adds a complication.

[johanstokking]

I don't think this field should be sticky, that is, always included. I think it should only be there when there's a new value.

Hmm how do we track this though? We'd need to store the state that there's a new value and set/unset that or something.

NS receives the value in DevStatusAns and then sets it on the ApplicationUplink, right?

Also if the first uplink that contains an updated value is missed by the data sink (integration), then they'd miss the update.

True. OK.

Then, how about we add it, as last_battery_percentage but then as message that includes the value as well as the FCntUp of when it was reported.

[KrishnaIyer]

Then, how about we add it, as last_battery_percentage but then as message that includes the value as well as the FCntUp of when it was reported.

Ok so we send the value every message but indicate the last update using FCntUp so that clients can choose to use or ignore the value?

[johanstokking]

Then, how about we add it, as last_battery_percentage but then as message that includes the value as well as the FCntUp of when it was reported.

Ok so we send the value every message but indicate the last update using FCntUp so that clients can choose to use or ignore the value?

Yes, something like this:

{
   ...
   "received_at": "2024-12-12T12:36:21Z",
   "uplink_message": {
      "f_cnt": 42,
      ...
      "last_battery_percentage": {
         "f_cnt": 24,
         "value": 93,
         "received_at": "2024-12-12T12:14:01Z"
      }
   }

[KrishnaIyer]

ACK sounds good 👍