From f72ae851681da289e9370db8e779f769da13ecac Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 24 Mar 2022 21:47:46 +1100 Subject: [PATCH 01/56] RFC 0018 - BATTERY_STATUS v2 --- text/001x-battery_improvements.md | 110 ++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 text/001x-battery_improvements.md diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md new file mode 100644 index 0000000..0505f97 --- /dev/null +++ b/text/001x-battery_improvements.md @@ -0,0 +1,110 @@ + * Start date: 2022-03-26 + * Contributors: Hamish Willee , ... + * Related issues: + - [16-cell support #1747](https://github.com/mavlink/mavlink/pull/1747) + - [common: added voltage and current multipliers to BATTERY_STATUS #233](https://github.com/ArduPilot/mavlink/pull/233) + + +# Summary + +This RFC proposes: +- a new `BATTERY_STATUS_V2` message that has a single cumulative voltage value rather than individual cell voltage arrays. +- a new (optional) `BATTERY_VOLTAGES` message that can be scaled to as many cells as needed, and which reports them as faults. +- mechanisms to ease supporting both message types until we can eventually deprecate `BATTERY_STATUS` + + +# Motivation + +The motivation is to: +- reduce the memory required for battery reporting ([anecdotal evidence](https://github.com/ArduPilot/mavlink/pull/233#issuecomment-976197179) indicates cases with 15% of bandwidth on a default RF channel). +- Provide a cleaner message and design for both implementers and consumers. + +The [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) has two arrays that can be used to report individual cell voltages (up to 14), or a single cumulative voltage, and which cannot be truncated. +The vast majority of consumers are only interested in the total battery voltage, and either sum the battery cells or get the cumulative voltage. +By separating the cell voltage reporting into a separate message the new battery status can be much smaller, and the cell voltages need only be sent if the consumer is actually interested. + +# Detailed Design + +There are three parts to the design: +1. A more efficient status message +2. A scalable battery voltage message. +3. Mechanisms that allow the new messages to seamlessly coexist with the old one along with eventual deprecation of the older message. + +## BATTERY_STATUS_V2 + +The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) but: +- removes the cell voltage arrays: `voltages` and `voltages_ext` +- adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. + + +```xml + + Battery information. Updates GCS with flight controller battery status. Smart batteries also use this message, but may additionally send SMART_BATTERY_INFO. + Battery ID + Function of the battery + Type (chemistry) of the battery + Temperature of the battery. INT16_MAX for unknown temperature. + Battery voltage (total). + Battery current (through all cells/loads). Positive if discharging, negative if charging. UINT16_MAX: field not provided. + Consumed charge, -1: Current consumption estimate not provided. + Consumed energy, -1: Energy consumption estimate not provided. + Remaining battery energy. Values: [0-100], -1: Remaining battery energy is not provided. + Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. + State for extent of discharge, provided by autopilot for warning or external reactions + Battery mode. Default (0) is that battery mode reporting is not supported or battery is in normal-use mode. + Fault/health indications. These should be set when charge_state is MAV_BATTERY_CHARGE_STATE_FAILED or MAV_BATTERY_CHARGE_STATE_UNHEALTHY (if not, fault reporting is not supported). + +``` + + +Questions: +- It is desirable to move static fields like the `type` (battery chemistry) and `battery_function` out of the new message because they only need to be read once, and afterwards are dead weight. + For this to be OK, the information either has to be non-essential (i.e might never be provided) or guaranteed to be sent in another message (this info is present in [SMART_BATTERY_INFO](https://mavlink.io/en/messages/common.html#SMART_BATTERY_INFO)). + - Is it non-essential? + - If it is essential, do we leave it in the message or mandate sending of `SMART_BATTERY_INFO`? +- Do we need all the other fields? +- Are there any other fields missing? + + +## Battery Voltages + +The proposed battery message is below. + +This assumes that the reason you might need the individual battery voltages is in order to identify that a particular cell has a significantly different voltage, and is hence in fault. +It simply sends information about which cells are in fault, providing battery manufacturers a way of reporting more detailed debugging information. + +```xml + + Battery information. Updates GCS with flight controller battery status. Smart batteries also use this message, but may additionally send SMART_BATTERY_INFO. + Battery ID + Cell index (0 by default). This is iterated for every 64 cells, allowing very large cell fault information. + Fault/health indications. . + +``` + +## Migration/Discovery + +`BATTERY_STATUS` consumes significant bandwidth: sending `BATTERY_STATUS_V2` at the same time would just increase the problem. + +[ +What are options here? +- Add support for either format in QGC/Mission Planner etc. +- Flight stack send `BATTERY_STATUS` but ground station can request BATTERY_STATUS_V2 and turn off BATTERY_STATUS_V2 using SET_INTERVAL? +- In a few releases we allow ground stations to set BATTERY_STATUS_V2 by default. +] + + + +# Alternatives + +TBD + +# Unresolved Questions + +TBD + +# References + * ? + + + From 4a719f2cac47ba1cf47262af5cc676d371ed5309 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 12:58:17 +1100 Subject: [PATCH 02/56] Update text/001x-battery_improvements.md Co-authored-by: Jacob Dahl <37091262+dakejahl@users.noreply.github.com> --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 0505f97..15ee497 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -48,7 +48,7 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ Battery current (through all cells/loads). Positive if discharging, negative if charging. UINT16_MAX: field not provided. Consumed charge, -1: Current consumption estimate not provided. Consumed energy, -1: Energy consumption estimate not provided. - Remaining battery energy. Values: [0-100], -1: Remaining battery energy is not provided. + Remaining battery energy. Values: [0-100], -1: Remaining battery energy is not provided. Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. State for extent of discharge, provided by autopilot for warning or external reactions Battery mode. Default (0) is that battery mode reporting is not supported or battery is in normal-use mode. From 496d464df6067b7db0bbed95ac0b5e83967ef120 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 13:03:36 +1100 Subject: [PATCH 03/56] Remove energy_consumed - not required (developer feedback) --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 15ee497..a5247dc 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -35,6 +35,7 @@ There are three parts to the design: The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) but: - removes the cell voltage arrays: `voltages` and `voltages_ext` - adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. +- removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. ```xml @@ -47,7 +48,6 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ Battery voltage (total). Battery current (through all cells/loads). Positive if discharging, negative if charging. UINT16_MAX: field not provided. Consumed charge, -1: Current consumption estimate not provided. - Consumed energy, -1: Energy consumption estimate not provided. Remaining battery energy. Values: [0-100], -1: Remaining battery energy is not provided. Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. State for extent of discharge, provided by autopilot for warning or external reactions From 657d762495615ffdea5c196ff4dadaf00668e038 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 13:13:16 +1100 Subject: [PATCH 04/56] Remove type and function from v2 battery status --- text/001x-battery_improvements.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index a5247dc..6bf7189 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -36,14 +36,16 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - removes the cell voltage arrays: `voltages` and `voltages_ext` - adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. - removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. - +- removes `battery_function` and `type` (chemistry) as these are present in `SMART_BATTERY_INFO` and invariant. A GCS that needs this information should request it from that message on startup. NOTE THIS MEANS that the chemistry and function of a particular battery ID must be invariant! + ```xml + Function of the battery + Type (chemistry) of the battery + ``` ```xml Battery information. Updates GCS with flight controller battery status. Smart batteries also use this message, but may additionally send SMART_BATTERY_INFO. Battery ID - Function of the battery - Type (chemistry) of the battery Temperature of the battery. INT16_MAX for unknown temperature. Battery voltage (total). Battery current (through all cells/loads). Positive if discharging, negative if charging. UINT16_MAX: field not provided. From 5c684c63c6d10756e73bdc6b9857cce060938053 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 13:25:17 +1100 Subject: [PATCH 05/56] Remove question on removing the battery type/function (answered) --- text/001x-battery_improvements.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 6bf7189..3fdc66e 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -36,7 +36,7 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - removes the cell voltage arrays: `voltages` and `voltages_ext` - adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. - removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. -- removes `battery_function` and `type` (chemistry) as these are present in `SMART_BATTERY_INFO` and invariant. A GCS that needs this information should request it from that message on startup. NOTE THIS MEANS that the chemistry and function of a particular battery ID must be invariant! +- removes `battery_function` and `type` (chemistry) as these are present in `SMART_BATTERY_INFO` and invariant. A GCS that needs this information should request it from that message on startup. NOTE THIS MEANS that either the chemistry and function of a particular battery ID must be invariant OR the message must be streamed. Otherwise there is no way to detect a battery change. ```xml Function of the battery Type (chemistry) of the battery @@ -60,10 +60,7 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ Questions: -- It is desirable to move static fields like the `type` (battery chemistry) and `battery_function` out of the new message because they only need to be read once, and afterwards are dead weight. - For this to be OK, the information either has to be non-essential (i.e might never be provided) or guaranteed to be sent in another message (this info is present in [SMART_BATTERY_INFO](https://mavlink.io/en/messages/common.html#SMART_BATTERY_INFO)). - - Is it non-essential? - - If it is essential, do we leave it in the message or mandate sending of `SMART_BATTERY_INFO`? + - Do we need all the other fields? - Are there any other fields missing? @@ -84,6 +81,16 @@ It simply sends information about which cells are in fault, providing battery ma ``` +## SMART_BATTERY_INFO + +No changes are required to [SMART_BATTERY_INFO](https://mavlink.io/en/messages/common.html#SMART_BATTERY_INFO). + +Note however that it must be streamed at a low rate in order to allow detection of battery change. + +Questions: +- What low rate is OK for streaming? is there another alternative? + + ## Migration/Discovery `BATTERY_STATUS` consumes significant bandwidth: sending `BATTERY_STATUS_V2` at the same time would just increase the problem. @@ -96,7 +103,6 @@ What are options here? ] - # Alternatives TBD From 8247fbc868720782de5a7beaeda23163189be39f Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 13:25:53 +1100 Subject: [PATCH 06/56] Update text/001x-battery_improvements.md Co-authored-by: Jacob Dahl <37091262+dakejahl@users.noreply.github.com> --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 3fdc66e..1765ccc 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -98,7 +98,7 @@ Questions: [ What are options here? - Add support for either format in QGC/Mission Planner etc. -- Flight stack send `BATTERY_STATUS` but ground station can request BATTERY_STATUS_V2 and turn off BATTERY_STATUS_V2 using SET_INTERVAL? +- Flight stack send `BATTERY_STATUS` but ground station can request BATTERY_STATUS_V2 and turn off BATTERY_STATUS using SET_INTERVAL? - In a few releases we allow ground stations to set BATTERY_STATUS_V2 by default. ] From cdfcac19579a6f76ae4c51b3a95cf2d3270e4385 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 15:26:54 +1100 Subject: [PATCH 07/56] Propose updated Battery cell voltage message --- text/001x-battery_improvements.md | 71 +++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 22 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 1765ccc..e488798 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -32,19 +32,11 @@ There are three parts to the design: ## BATTERY_STATUS_V2 -The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) but: -- removes the cell voltage arrays: `voltages` and `voltages_ext` -- adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. -- removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. -- removes `battery_function` and `type` (chemistry) as these are present in `SMART_BATTERY_INFO` and invariant. A GCS that needs this information should request it from that message on startup. NOTE THIS MEANS that either the chemistry and function of a particular battery ID must be invariant OR the message must be streamed. Otherwise there is no way to detect a battery change. - ```xml - Function of the battery - Type (chemistry) of the battery - ``` +The proposed message is: ```xml - Battery information. Updates GCS with flight controller battery status. Smart batteries also use this message, but may additionally send SMART_BATTERY_INFO. + Battery dynamic information. This should be streamed (nominally at 1Hz). Static battery information is sent in SMART_BATTERY_INFO. Battery ID Temperature of the battery. INT16_MAX for unknown temperature. Battery voltage (total). @@ -58,34 +50,70 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ ``` +The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) but: +- removes the cell voltage arrays: `voltages` and `voltages_ext` +- adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. +- removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. +- removes `battery_function` and `type` (chemistry) as these are present in `SMART_BATTERY_INFO` and invariant. + ```xml + Function of the battery + Type (chemistry) of the battery + ``` + - A GCS that needs invariant information should read `SMART_BATTERY_INFO` on startup + - A vehicle that allows battery swapping must stream `SMART_BATTERY_INFO` (at low rate) to ensure that battery changes are notifie (and ideally also emit it on battery change). -Questions: +#### Questions - Do we need all the other fields? - Are there any other fields missing? -## Battery Voltages +## Battery Cell Voltages + +The proposed battery message is: + +```xml + + Battery cell voltages. + This message is provided primarily for cell fault debugging. + For batteries with more than 10 cells the message should be sent multiple times, iterating the index value. + It should not be streamed at very low rate (less than once a minute) or streamed only on request. + Battery ID + Cell index (0 by default). This can be iterated for batteries with more than 10 cells. + Battery voltage of 10 cells at current index. Cells above the valid cell count for this battery should be set to 0. + +``` + +Cell voltages can be used to verify that poorly performing batteries have failing cells, and to providing early warning of longer term battery degradation. +It is useful to have long term trace information in logs, but not necessary for this to be at particularly high rate. +Therefore the message provides all information about the battery voltages, but is expected to be sent at low rate, or on request. + +As designed, the message will not be zero-byte truncated (field re-ordering means that the array is last). +The message might be modified to make: +- `voltages` an extension field. For a 4S battery this would save 12 bytes per message but lose checking. If we do this we might as well mandate "no extension". +- `id` and `index` into `uint16_t`. For a 4S battery this would save 10 bytes per message,and retain mavlink checking on field. It would cost 2 additional bytes on every new message. + -The proposed battery message is below. +#### Alternatives -This assumes that the reason you might need the individual battery voltages is in order to identify that a particular cell has a significantly different voltage, and is hence in fault. -It simply sends information about which cells are in fault, providing battery manufacturers a way of reporting more detailed debugging information. +An alternative is just to send fault information. +This assumes that the smart battery is capable of providing the long term trend analysis that can be obtained from logs using the above message. ```xml - - Battery information. Updates GCS with flight controller battery status. Smart batteries also use this message, but may additionally send SMART_BATTERY_INFO. + + Battery cell fault information. Battery ID Cell index (0 by default). This is iterated for every 64 cells, allowing very large cell fault information. - Fault/health indications. . + Fault/health indications. ``` ## SMART_BATTERY_INFO -No changes are required to [SMART_BATTERY_INFO](https://mavlink.io/en/messages/common.html#SMART_BATTERY_INFO). +No changes are required to [SMART_BATTERY_INFO](https://mavlink.io/en/messages/common.html#SMART_BATTERY_INFO) fields -Note however that it must be streamed at a low rate in order to allow detection of battery change. +Note however that it must be streamed at a low rate in order to allow detection of battery change, and should also be sent when the battery changes. +We should specify the rate. Questions: - What low rate is OK for streaming? is there another alternative? @@ -112,7 +140,6 @@ TBD TBD # References - * ? - +* ? From 28b23db88379954d470a6f49e4ac35ab098fa54c Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 15:30:38 +1100 Subject: [PATCH 08/56] Add charge state --- text/001x-battery_improvements.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index e488798..d9a9ec7 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -3,6 +3,7 @@ * Related issues: - [16-cell support #1747](https://github.com/mavlink/mavlink/pull/1747) - [common: added voltage and current multipliers to BATTERY_STATUS #233](https://github.com/ArduPilot/mavlink/pull/233) + - [Add MAV_BATTERY_CHARGE_STATE_CHARGING #1068](https://github.com/mavlink/mavlink/pull/1068) # Summary @@ -110,6 +111,9 @@ This assumes that the smart battery is capable of providing the long term trend ## SMART_BATTERY_INFO +TBD: + + No changes are required to [SMART_BATTERY_INFO](https://mavlink.io/en/messages/common.html#SMART_BATTERY_INFO) fields Note however that it must be streamed at a low rate in order to allow detection of battery change, and should also be sent when the battery changes. From f110cfabc8bcf7ef7e26959f67001da625da9d9b Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 18:36:00 +1100 Subject: [PATCH 09/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index d9a9ec7..2a66eea 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -81,7 +81,7 @@ The proposed battery message is: It should not be streamed at very low rate (less than once a minute) or streamed only on request. Battery ID Cell index (0 by default). This can be iterated for batteries with more than 10 cells. - Battery voltage of 10 cells at current index. Cells above the valid cell count for this battery should be set to 0. + Battery voltage of 10 cells at current index. Cells above the valid cell count for this battery should be set to 0. ``` From 3e56f60a297dc872926c9977d30b226894af3765 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 18:36:30 +1100 Subject: [PATCH 10/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 2a66eea..db80306 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -81,7 +81,7 @@ The proposed battery message is: It should not be streamed at very low rate (less than once a minute) or streamed only on request. Battery ID Cell index (0 by default). This can be iterated for batteries with more than 10 cells. - Battery voltage of 10 cells at current index. Cells above the valid cell count for this battery should be set to 0. + Battery voltage of 12 cells at current index. Cells above the valid cell count for this battery should be set to 0. ``` From f15e54212a45aae59d671f223930070534ce3ba3 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 30 Mar 2022 18:37:43 +1100 Subject: [PATCH 11/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index db80306..8e92852 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -80,7 +80,7 @@ The proposed battery message is: For batteries with more than 10 cells the message should be sent multiple times, iterating the index value. It should not be streamed at very low rate (less than once a minute) or streamed only on request. Battery ID - Cell index (0 by default). This can be iterated for batteries with more than 10 cells. + Cell index (0 by default). This can be iterated for batteries with more than 12 cells. Battery voltage of 12 cells at current index. Cells above the valid cell count for this battery should be set to 0. ``` From 05be55ef559454ae022b4b876e9740f6957594fb Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 31 Mar 2022 09:51:18 +1100 Subject: [PATCH 12/56] Add note about duplication --- text/001x-battery_improvements.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 8e92852..99b88aa 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -67,6 +67,7 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - Do we need all the other fields? - Are there any other fields missing? +- `current_consumed`, `percent_remaining`, `time_remaining` all tell much the same the same story, and can be estimated from each other. Do we need all of these, and if so which ones? ## Battery Cell Voltages From cc943932ff7d452b7475bca9fc6d245a9015c4b4 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 31 Mar 2022 10:05:23 +1100 Subject: [PATCH 13/56] Add question about charge states into questions --- text/001x-battery_improvements.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 99b88aa..3e587b5 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -11,7 +11,6 @@ This RFC proposes: - a new `BATTERY_STATUS_V2` message that has a single cumulative voltage value rather than individual cell voltage arrays. - a new (optional) `BATTERY_VOLTAGES` message that can be scaled to as many cells as needed, and which reports them as faults. -- mechanisms to ease supporting both message types until we can eventually deprecate `BATTERY_STATUS` # Motivation @@ -112,28 +111,22 @@ This assumes that the smart battery is capable of providing the long term trend ## SMART_BATTERY_INFO -TBD: +[SMART_BATTERY_INFO](https://mavlink.io/en/messages/common.html#SMART_BATTERY_INFO) is already deployed and it is not clear if it can be modified. It may be possible to extend. - -No changes are required to [SMART_BATTERY_INFO](https://mavlink.io/en/messages/common.html#SMART_BATTERY_INFO) fields - -Note however that it must be streamed at a low rate in order to allow detection of battery change, and should also be sent when the battery changes. -We should specify the rate. +Add note that it must be streamed at a low rate in order to allow detection of battery change, and should also be sent when the battery changes. Questions: -- What low rate is OK for streaming? is there another alternative? +- What low rate is OK for streaming? is there another alternative for tracking battery change +- Perhaps charge_state, mode, and fault_bitmask could be combined into a single uint32_t status? (Feedback comment: the concept of a "charge state" doesn't make a lot of sense. It's either charging, discharging, or idle. If it's not charging/discharging due to some error, that would be indicated using one of the other fault flags. Having separate enums to convey some "charge state" is effectively redundant, since it's just telling you to look at the fault flags to understand why the "charge state" is abnormal. The same argument might be applied to mode. +- ## Migration/Discovery `BATTERY_STATUS` consumes significant bandwidth: sending `BATTERY_STATUS_V2` at the same time would just increase the problem. -[ -What are options here? -- Add support for either format in QGC/Mission Planner etc. -- Flight stack send `BATTERY_STATUS` but ground station can request BATTERY_STATUS_V2 and turn off BATTERY_STATUS using SET_INTERVAL? -- In a few releases we allow ground stations to set BATTERY_STATUS_V2 by default. -] +The proposal here is that GCS should support both messages for the forseeable future. +Flight stacks should manage their own migration after relevant ground stations have been updated. # Alternatives From 9033cc906000bc3db0b71db7242e22e77d642e57 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 31 Mar 2022 10:08:52 +1100 Subject: [PATCH 14/56] Update 001x-battery_improvements.md --- text/001x-battery_improvements.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 3e587b5..c12a37d 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -117,8 +117,7 @@ Add note that it must be streamed at a low rate in order to allow detection of b Questions: - What low rate is OK for streaming? is there another alternative for tracking battery change -- Perhaps charge_state, mode, and fault_bitmask could be combined into a single uint32_t status? (Feedback comment: the concept of a "charge state" doesn't make a lot of sense. It's either charging, discharging, or idle. If it's not charging/discharging due to some error, that would be indicated using one of the other fault flags. Having separate enums to convey some "charge state" is effectively redundant, since it's just telling you to look at the fault flags to understand why the "charge state" is abnormal. The same argument might be applied to mode. -- + ## Migration/Discovery From 42cfe84bd599617ecf6b668aa29496dda8495aa2 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 31 Mar 2022 10:10:15 +1100 Subject: [PATCH 15/56] Update 001x-battery_improvements.md --- text/001x-battery_improvements.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index c12a37d..18dbd11 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -66,7 +66,8 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - Do we need all the other fields? - Are there any other fields missing? -- `current_consumed`, `percent_remaining`, `time_remaining` all tell much the same the same story, and can be estimated from each other. Do we need all of these, and if so which ones? +- `current_consumed`, `percent_remaining`, `time_remaining` all tell much the same story, and can be estimated from each other. Do we need all of these, and if so which ones? +- Perhaps charge_state, mode, and fault_bitmask could be combined into a single uint32_t status? (Feedback comment: the concept of a "charge state" doesn't make a lot of sense. It's either charging, discharging, or idle. If it's not charging/discharging due to some error, that would be indicated using one of the other fault flags. Having separate enums to convey some "charge state" is effectively redundant, since it's just telling you to look at the fault flags to understand why the "charge state" is abnormal. The same argument might be applied to mode. ## Battery Cell Voltages From dc630569eee844a04d646b36df245daf352870b8 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 31 Mar 2022 11:17:28 +1100 Subject: [PATCH 16/56] Propose removal of mode and charging state into fault --- text/001x-battery_improvements.md | 43 ++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 18dbd11..658f151 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -44,12 +44,26 @@ The proposed message is: Consumed charge, -1: Current consumption estimate not provided. Remaining battery energy. Values: [0-100], -1: Remaining battery energy is not provided. Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. - State for extent of discharge, provided by autopilot for warning or external reactions - Battery mode. Default (0) is that battery mode reporting is not supported or battery is in normal-use mode. - Fault/health indications. These should be set when charge_state is MAV_BATTERY_CHARGE_STATE_FAILED or MAV_BATTERY_CHARGE_STATE_UNHEALTHY (if not, fault reporting is not supported). + Fault/health/ready-to-use indications. ``` +With `MAV_BATTERY_FAULT` having the following **additions** (from `MAV_BATTERY_CHARGE_STATE` and `MAV_BATTERY_MODE`): +```xml + + Battery supply status flags (bitmask) indicating battery health and readiness for flight. + ... + + Battery is charging. Not ready to use. + + + Battery is auto discharging (towards storage level). Not ready to use. + + + Battery in hot-swap mode (current limited to prevent spikes that might damage sensitive electrical circuits). Not ready to use. + +``` + The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) but: - removes the cell voltage arrays: `voltages` and `voltages_ext` - adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. @@ -61,14 +75,35 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ ``` - A GCS that needs invariant information should read `SMART_BATTERY_INFO` on startup - A vehicle that allows battery swapping must stream `SMART_BATTERY_INFO` (at low rate) to ensure that battery changes are notifie (and ideally also emit it on battery change). +- Removes [`charge_state`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_CHARGE_STATE) [`mode`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_MODE) + ```xml + State for extent of discharge, provided by autopilot for warning or external reactions + Battery mode. Default (0) is that battery mode reporting is not supported or battery is in normal-use mode. + ``` + - The state is almost all inferred from the battery remaining. Traditionally the GCS sets appropriate levels for warning - the battery has a less accurate view on appropriate warning levels for a particular system, making this redundant. The exception is charging status. + - The mode is reasonable enough, but can be expressed as a fault "there is a concern with using this battery". + + #### Questions - Do we need all the other fields? - Are there any other fields missing? - `current_consumed`, `percent_remaining`, `time_remaining` all tell much the same story, and can be estimated from each other. Do we need all of these, and if so which ones? -- Perhaps charge_state, mode, and fault_bitmask could be combined into a single uint32_t status? (Feedback comment: the concept of a "charge state" doesn't make a lot of sense. It's either charging, discharging, or idle. If it's not charging/discharging due to some error, that would be indicated using one of the other fault flags. Having separate enums to convey some "charge state" is effectively redundant, since it's just telling you to look at the fault flags to understand why the "charge state" is abnormal. The same argument might be applied to mode. +- Should we have `MAV_BATTERY_FAULT` for critical level "just before deep discharge"? The battery can know this, and it might prevent over discharge. + ```xml + + Battery is at critically low level. Undamaged, but not ready to use. + + ``` + - Should we have `MAV_BATTERY_FAULT` summarising "not ready to use"? Simplifies things for GCS/user as unhealthy vs you can't use this at all. + ```xml + + Battery is not ready/safe to use. Check other bitmasks for reasons. + + ``` +- ## Battery Cell Voltages From 1a2fb834c0f68b047fc464378d2cbdcdf3103ab5 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Apr 2022 11:54:34 +1000 Subject: [PATCH 17/56] percent_remaining is a uint8 --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 658f151..f9ec5c0 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -42,7 +42,7 @@ The proposed message is: Battery voltage (total). Battery current (through all cells/loads). Positive if discharging, negative if charging. UINT16_MAX: field not provided. Consumed charge, -1: Current consumption estimate not provided. - Remaining battery energy. Values: [0-100], -1: Remaining battery energy is not provided. + Remaining battery energy. Values: [0-100], UINT32_MAX: Remaining battery energy is not provided. Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. Fault/health/ready-to-use indications. From 8372532bcb5d2ca57639b6fea2626d1978339890 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Apr 2022 12:06:48 +1000 Subject: [PATCH 18/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index f9ec5c0..80a8334 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -59,7 +59,7 @@ With `MAV_BATTERY_FAULT` having the following **additions** (from `MAV_BATTERY_C Battery is auto discharging (towards storage level). Not ready to use. - + Battery in hot-swap mode (current limited to prevent spikes that might damage sensitive electrical circuits). Not ready to use. ``` From 57d9d9b7f2200b5de31e157a50f46fa9332045d9 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Apr 2022 12:39:41 +1000 Subject: [PATCH 19/56] Remove time_remaining --- text/001x-battery_improvements.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 80a8334..7fe0e3a 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -43,7 +43,6 @@ The proposed message is: Battery current (through all cells/loads). Positive if discharging, negative if charging. UINT16_MAX: field not provided. Consumed charge, -1: Current consumption estimate not provided. Remaining battery energy. Values: [0-100], UINT32_MAX: Remaining battery energy is not provided. - Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. Fault/health/ready-to-use indications. ``` @@ -68,6 +67,12 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - removes the cell voltage arrays: `voltages` and `voltages_ext` - adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. - removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. +- removes `time_remaining`. + ```xml + Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. + ``` + - This is an estimated "convenience" value which can be calculated as well or better by a GCS, in particular on multi-battery systems (from original charge, `current_consumed` and looking at the rate of `current` over some time period). + - Better to be lightweight. - removes `battery_function` and `type` (chemistry) as these are present in `SMART_BATTERY_INFO` and invariant. ```xml Function of the battery @@ -89,7 +94,6 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - Do we need all the other fields? - Are there any other fields missing? -- `current_consumed`, `percent_remaining`, `time_remaining` all tell much the same story, and can be estimated from each other. Do we need all of these, and if so which ones? - Should we have `MAV_BATTERY_FAULT` for critical level "just before deep discharge"? The battery can know this, and it might prevent over discharge. ```xml From bfa89c45c5004bc696c44e49452ac1ef1400558b Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Apr 2022 12:43:30 +1000 Subject: [PATCH 20/56] Add doc that percent_remaining is proposed as uint8 --- text/001x-battery_improvements.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 7fe0e3a..8f97e6d 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -72,7 +72,9 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. ``` - This is an estimated "convenience" value which can be calculated as well or better by a GCS, in particular on multi-battery systems (from original charge, `current_consumed` and looking at the rate of `current` over some time period). - - Better to be lightweight. + - Better to be lightweight. +- `percent_remaining` changed from int8 to uint8 (and max value set to invalid value). + This is consistent with other MAVLink percentage fields. - removes `battery_function` and `type` (chemistry) as these are present in `SMART_BATTERY_INFO` and invariant. ```xml Function of the battery @@ -107,7 +109,6 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ ``` -- ## Battery Cell Voltages From 660d9c37dcb2dbb47aaa0a2d1c556df7c3b6274d Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 7 Apr 2022 12:24:42 +1000 Subject: [PATCH 21/56] Update 001x-battery_improvements.md --- text/001x-battery_improvements.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 8f97e6d..955ce9a 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -108,6 +108,7 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ Battery is not ready/safe to use. Check other bitmasks for reasons. ``` +- Is the size of the `current` field large enough. It has maximum value of 327.67A. We could make it a float or a uint_16 and change units to mA. ## Battery Cell Voltages From 2e634576376874f5fac2d0a8dfd80cb1c5daa4dc Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 7 Apr 2022 13:22:20 +1000 Subject: [PATCH 22/56] change `current` from a `int16_t` (cA) to a `int32_t` --- text/001x-battery_improvements.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 955ce9a..32a939e 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -38,11 +38,11 @@ The proposed message is: Battery dynamic information. This should be streamed (nominally at 1Hz). Static battery information is sent in SMART_BATTERY_INFO. Battery ID - Temperature of the battery. INT16_MAX for unknown temperature. - Battery voltage (total). - Battery current (through all cells/loads). Positive if discharging, negative if charging. UINT16_MAX: field not provided. - Consumed charge, -1: Current consumption estimate not provided. - Remaining battery energy. Values: [0-100], UINT32_MAX: Remaining battery energy is not provided. + Temperature of the battery. INT16_MAX field not provided. + Battery voltage (total). UINT32_MAX: field not provided. + Battery current (through all cells/loads). UINT32_MAX: field not provided. + Consumed charge (estimate). -1: field not provided. + Remaining battery energy. Values: [0-100], UINT32_MAX: field not provided. Fault/health/ready-to-use indications. ``` @@ -67,6 +67,7 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - removes the cell voltage arrays: `voltages` and `voltages_ext` - adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. - removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. +- change `current` from a `int16_t` (cA) to a `int32_t` (mA). Maximum size was previously 327.67A, which is not large enough to be future proof. - removes `time_remaining`. ```xml Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. From 199a2c6cf03bdd3037f0811d7b406a195732b177 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 7 Apr 2022 15:26:02 +1000 Subject: [PATCH 23/56] Update 001x-battery_improvements.md --- text/001x-battery_improvements.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 32a939e..6064163 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -42,6 +42,7 @@ The proposed message is: Battery voltage (total). UINT32_MAX: field not provided. Battery current (through all cells/loads). UINT32_MAX: field not provided. Consumed charge (estimate). -1: field not provided. + Remaining charge (estimate). -1: field not provided. Remaining battery energy. Values: [0-100], UINT32_MAX: field not provided. Fault/health/ready-to-use indications. @@ -67,6 +68,9 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - removes the cell voltage arrays: `voltages` and `voltages_ext` - adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. - removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. +- adds `current_remaining`(mAh) estimate. + - This allows a GCS to more accurately determine available current and remaining time than inferring from the `current_consumed` and `percent_remaining`. + - Note that this also gives the current reliably on plug-in. All the other information provided by messages (other than `percent_remaining`) assumes that the battery was full when it was plugged in. - change `current` from a `int16_t` (cA) to a `int32_t` (mA). Maximum size was previously 327.67A, which is not large enough to be future proof. - removes `time_remaining`. ```xml @@ -109,7 +113,6 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ Battery is not ready/safe to use. Check other bitmasks for reasons. ``` -- Is the size of the `current` field large enough. It has maximum value of 327.67A. We could make it a float or a uint_16 and change units to mA. ## Battery Cell Voltages From 1295684603e1c1fe0c3a31a0830fb23c6c15d1e7 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 7 Apr 2022 15:38:31 +1000 Subject: [PATCH 24/56] Make current_consumed a uint32 --- text/001x-battery_improvements.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 6064163..5ea150c 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -41,8 +41,8 @@ The proposed message is: Temperature of the battery. INT16_MAX field not provided. Battery voltage (total). UINT32_MAX: field not provided. Battery current (through all cells/loads). UINT32_MAX: field not provided. - Consumed charge (estimate). -1: field not provided. - Remaining charge (estimate). -1: field not provided. + Consumed charge (estimate). UINT32_MAX: field not provided. + Remaining charge (estimate). UINT32_MAX: field not provided. Remaining battery energy. Values: [0-100], UINT32_MAX: field not provided. Fault/health/ready-to-use indications. @@ -67,11 +67,12 @@ With `MAV_BATTERY_FAULT` having the following **additions** (from `MAV_BATTERY_C The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) but: - removes the cell voltage arrays: `voltages` and `voltages_ext` - adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. +- `current_consumed` has changed from an `int32_t` to a `uint32_t`. This allows future proofs from 32767 mAh limit to 4294967295 mAh - removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. - adds `current_remaining`(mAh) estimate. - This allows a GCS to more accurately determine available current and remaining time than inferring from the `current_consumed` and `percent_remaining`. - Note that this also gives the current reliably on plug-in. All the other information provided by messages (other than `percent_remaining`) assumes that the battery was full when it was plugged in. -- change `current` from a `int16_t` (cA) to a `int32_t` (mA). Maximum size was previously 327.67A, which is not large enough to be future proof. +- change `current` from a `int16_t` (cA) to a `uint32_t` (mA). Maximum size was previously 327.67A, which is not large enough to be future proof. The value is absolute - if you're charging the value can be assumed to be in a reversed direction. - removes `time_remaining`. ```xml Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. From 5e530eb34b8da7567a871eb77920589303368d66 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 7 Apr 2022 16:29:11 +1000 Subject: [PATCH 25/56] Clarify temp is "whole battery" not internal electronics --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 5ea150c..b1530ba 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -38,7 +38,7 @@ The proposed message is: Battery dynamic information. This should be streamed (nominally at 1Hz). Static battery information is sent in SMART_BATTERY_INFO. Battery ID - Temperature of the battery. INT16_MAX field not provided. + Temperature of the whole battery pack (not internal electronics). INT16_MAX field not provided. Battery voltage (total). UINT32_MAX: field not provided. Battery current (through all cells/loads). UINT32_MAX: field not provided. Consumed charge (estimate). UINT32_MAX: field not provided. From c8915b890b5e65d229d31e5f24a541f65578fced Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 14 Apr 2022 14:01:03 +1000 Subject: [PATCH 26/56] Add dronecan alignment as a key driver and link to the WIP discussion --- text/001x-battery_improvements.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index b1530ba..77c6c54 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -4,6 +4,7 @@ - [16-cell support #1747](https://github.com/mavlink/mavlink/pull/1747) - [common: added voltage and current multipliers to BATTERY_STATUS #233](https://github.com/ArduPilot/mavlink/pull/233) - [Add MAV_BATTERY_CHARGE_STATE_CHARGING #1068](https://github.com/mavlink/mavlink/pull/1068) + - dronecan / DSDL : [WIP smart battery messages](https://github.com/dronecan/DSDL/pull/7) # Summary @@ -18,6 +19,7 @@ This RFC proposes: The motivation is to: - reduce the memory required for battery reporting ([anecdotal evidence](https://github.com/ArduPilot/mavlink/pull/233#issuecomment-976197179) indicates cases with 15% of bandwidth on a default RF channel). - Provide a cleaner message and design for both implementers and consumers. +- Align with DroneCan battery messages to ease transport and data conversion across different transports. The [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) has two arrays that can be used to report individual cell voltages (up to 14), or a single cumulative voltage, and which cannot be truncated. The vast majority of consumers are only interested in the total battery voltage, and either sum the battery cells or get the cumulative voltage. From 9acf2675370afd7178e532254fbc404bd77cceae Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 14 Apr 2022 15:01:43 +1000 Subject: [PATCH 27/56] Update on handling power monitors --- text/001x-battery_improvements.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 77c6c54..fa55030 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -38,13 +38,21 @@ The proposed message is: ```xml - Battery dynamic information. This should be streamed (nominally at 1Hz). Static battery information is sent in SMART_BATTERY_INFO. + Battery dynamic information. + This should be streamed (nominally at 1Hz). + Static/invariant battery information is sent in SMART_BATTERY_INFO. + + The full-battery charge is current_remaining + current_consumed, iff both values are supplied. + The `current_remaining` field should only be sent if it is guaranteed to be near-accurate. + Power monitors typically should not send the `current_remaining` field as it can only be accurate if the battery is fully charged when the drone is turned on. + (A GCS can use `current_remaining` being invalid as a trigger to notify the user to fully charge the battery before flight). + Battery ID Temperature of the whole battery pack (not internal electronics). INT16_MAX field not provided. Battery voltage (total). UINT32_MAX: field not provided. Battery current (through all cells/loads). UINT32_MAX: field not provided. - Consumed charge (estimate). UINT32_MAX: field not provided. - Remaining charge (estimate). UINT32_MAX: field not provided. + Consumed charge (from full). UINT32_MAX: field not provided. Note: Power modules report the current consumed since they were last turned on (the expectation is that batteries are fully charged before turning on the vehicle). + Remaining charge (until empty). UINT32_MAX: field not provided. Note: Power monitors should not set this value. Remaining battery energy. Values: [0-100], UINT32_MAX: field not provided. Fault/health/ready-to-use indications. @@ -73,7 +81,11 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. - adds `current_remaining`(mAh) estimate. - This allows a GCS to more accurately determine available current and remaining time than inferring from the `current_consumed` and `percent_remaining`. - - Note that this also gives the current reliably on plug-in. All the other information provided by messages (other than `percent_remaining`) assumes that the battery was full when it was plugged in. + - Note that this also gives the current reliably on plug-in. + All the other information provided by messages (other than `percent_remaining`) assumes that the battery was full when it was plugged in. + - Includes a note that should not be set by power modules. + Power modules can only provide this reliably if the battery is fully charged when they are turned on. + A GCS can still infer the battery remaining from the consumed current, but by setting this as empty, we tell the GCS that it can't be "sure" of the value, and should prompt the user to use full batteries. - change `current` from a `int16_t` (cA) to a `uint32_t` (mA). Maximum size was previously 327.67A, which is not large enough to be future proof. The value is absolute - if you're charging the value can be assumed to be in a reversed direction. - removes `time_remaining`. ```xml From 45c83617f6cf2106a745f1f5ab01ec880cc54ad2 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 14 Apr 2022 16:54:02 +1000 Subject: [PATCH 28/56] Battery now has status flags --- text/001x-battery_improvements.md | 117 +++++++++++++++++++++++------- 1 file changed, 91 insertions(+), 26 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index fa55030..3647321 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -43,9 +43,9 @@ The proposed message is: Static/invariant battery information is sent in SMART_BATTERY_INFO. The full-battery charge is current_remaining + current_consumed, iff both values are supplied. - The `current_remaining` field should only be sent if it is guaranteed to be near-accurate. - Power monitors typically should not send the `current_remaining` field as it can only be accurate if the battery is fully charged when the drone is turned on. - (A GCS can use `current_remaining` being invalid as a trigger to notify the user to fully charge the battery before flight). + The `current_remaining` field should only be sent if it is guaranteed to be near-accurate. + Power monitors typically should not send the `current_remaining` field as it can only be accurate if the battery is fully charged when the drone is turned on. + (A GCS can use `current_remaining` being invalid as a trigger to notify the user to fully charge the battery before flight). Battery ID Temperature of the whole battery pack (not internal electronics). INT16_MAX field not provided. @@ -54,24 +54,93 @@ The proposed message is: Consumed charge (from full). UINT32_MAX: field not provided. Note: Power modules report the current consumed since they were last turned on (the expectation is that batteries are fully charged before turning on the vehicle). Remaining charge (until empty). UINT32_MAX: field not provided. Note: Power monitors should not set this value. Remaining battery energy. Values: [0-100], UINT32_MAX: field not provided. - Fault/health/ready-to-use indications. + Fault, health, and readiness status indications. ``` -With `MAV_BATTERY_FAULT` having the following **additions** (from `MAV_BATTERY_CHARGE_STATE` and `MAV_BATTERY_MODE`): +`MAV_BATTERY_STATUS_FLAGS` is a new enum that includes faults, charge state, and battery mode: + ```xml - - Battery supply status flags (bitmask) indicating battery health and readiness for flight. - ... - - Battery is charging. Not ready to use. + + Battery status flags for fault, health and state indication. + + + The battery is ready to use (fly). + Only set if the battery is safe and ready to fly with (not charging, no critical faults, such as those that would set MAV_BATTERY_STATUS_FLAGS_REQUIRES_SERVICE or MAV_BATTERY_STATUS_FLAGS_BAD_BATTERY, etc.). + + + + + Battery is charging. + Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). + + + + + Battery is auto discharging (towards storage level). + Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). + + + + + Battery requires service (not safe to fly). + This is set at vendor discretion. + It is likely to be set for most faults, and may also be set according to a maintenance schedule (such as age, or number of recharge cycles, etc.). + + + + + Battery is faulty and cannot be repaired (not safe to fly). + This is set at vendor discretion. + The battery should be disposed of safely. + + + + + Automatic battery protection monitoring is enabled. + When enabled, the system will monitor for certain kinds of faults, such as cells being over-voltage. + If a fault is triggered then and protections are enabled then a safety fault (MAV_BATTERY_STATUS_FLAGS_FAULT_PROTECTION_SYSTEM) will be set and power from the battery will be stopped. + Note that the associated fault (such as MAV_BATTERY_STATUS_FLAGS_FAULT_OVER_VOLT) should always be set whether or not the protection system is engaged. + + + + + The battery fault protection system had detected a fault and cut all power from the battery. + This will only trigger if MAV_BATTERY_STATUS_FLAGS_PROTECTIONS_ENABLED is set. + Other faults like MAV_BATTERY_STATUS_FLAGS_FAULT_OVER_VOLT may also be set, indicating the cause of the protection fault. + + + + One or more cells are above their maximum voltage rating. + + + + One or more cells are below their minimum voltage rating. + A battery that had deep-discharged might be irrepairably damaged, and set both MAV_BATTERY_STATUS_FLAGS_FAULT_UNDER_VOLT and MAV_BATTERY_STATUS_FLAGS_BAD_BATTERY. + - - Battery is auto discharging (towards storage level). Not ready to use. + + Over-temperature fault. - - Battery in hot-swap mode (current limited to prevent spikes that might damage sensitive electrical circuits). Not ready to use. + + Under-temperature fault. + + Over-current fault. + + + One or more cells have failed. The battery (or may not) may still be safe to fly. + + + Voltage not compatible power rail voltage (batteries on same power rail should have similar voltage). + + + Battery firmware is not compatible with current autopilot firmware. + + + Battery is not compatible due to cell configuration (e.g. 5s1p when vehicle requires 6s). + + ``` The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) but: @@ -102,14 +171,15 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ ``` - A GCS that needs invariant information should read `SMART_BATTERY_INFO` on startup - A vehicle that allows battery swapping must stream `SMART_BATTERY_INFO` (at low rate) to ensure that battery changes are notifie (and ideally also emit it on battery change). -- Removes [`charge_state`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_CHARGE_STATE) [`mode`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_MODE) +- New `battery_status` (`MAV_BATTERY_STATUS_FLAGS`) replaces [`fault_bitmask`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_FAULT), [`charge_state`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_CHARGE_STATE) and [`mode`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_MODE) ```xml State for extent of discharge, provided by autopilot for warning or external reactions Battery mode. Default (0) is that battery mode reporting is not supported or battery is in normal-use mode. + Fault/health/ready-to-use indications. ``` - The state is almost all inferred from the battery remaining. Traditionally the GCS sets appropriate levels for warning - the battery has a less accurate view on appropriate warning levels for a particular system, making this redundant. The exception is charging status. - - The mode is reasonable enough, but can be expressed as a fault "there is a concern with using this battery". - + - The mode and fault are reasonable, but make more sense as general status indication. + - The status loses some faults which make no sense (e.g. `MAV_BATTERY_FAULT_SPIKES`) or which can now be inferred (like deep discharge). #### Questions @@ -122,13 +192,8 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ Battery is at critically low level. Undamaged, but not ready to use. ``` - - Should we have `MAV_BATTERY_FAULT` summarising "not ready to use"? Simplifies things for GCS/user as unhealthy vs you can't use this at all. - ```xml - - Battery is not ready/safe to use. Check other bitmasks for reasons. - - ``` - +- `MAV_BATTERY_STATUS_FLAGS` + - Should this include `MAV_BATTERY_STATUS_FLAGS_IN_USE` (connected, drawing significant power to fly). Not clear when you would need this or how you would use it. Or precisely what would count as "in use". ## Battery Cell Voltages @@ -138,8 +203,8 @@ The proposed battery message is: Battery cell voltages. This message is provided primarily for cell fault debugging. - For batteries with more than 10 cells the message should be sent multiple times, iterating the index value. - It should not be streamed at very low rate (less than once a minute) or streamed only on request. + For batteries with more than 10 cells the message should be sent multiple times, iterating the index value. + It should not be streamed at very low rate (less than once a minute) or streamed only on request. Battery ID Cell index (0 by default). This can be iterated for batteries with more than 12 cells. Battery voltage of 12 cells at current index. Cells above the valid cell count for this battery should be set to 0. From 7f464ed0a887b4f37fa3724425543c6bf54d2955 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 14 Apr 2022 17:08:37 +1000 Subject: [PATCH 29/56] Missed a couple of faults. Added now --- text/001x-battery_improvements.md | 46 +++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 3647321..25bd8d4 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -75,27 +75,39 @@ The proposed message is: Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). - + + + Battery is cell balancing (during charging). + Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). + + + + + Battery cells are not balanced. + Not ready to use. + + + Battery is auto discharging (towards storage level). Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). - + Battery requires service (not safe to fly). This is set at vendor discretion. It is likely to be set for most faults, and may also be set according to a maintenance schedule (such as age, or number of recharge cycles, etc.). - + Battery is faulty and cannot be repaired (not safe to fly). This is set at vendor discretion. The battery should be disposed of safely. - + Automatic battery protection monitoring is enabled. When enabled, the system will monitor for certain kinds of faults, such as cells being over-voltage. @@ -103,41 +115,47 @@ The proposed message is: Note that the associated fault (such as MAV_BATTERY_STATUS_FLAGS_FAULT_OVER_VOLT) should always be set whether or not the protection system is engaged. - + The battery fault protection system had detected a fault and cut all power from the battery. This will only trigger if MAV_BATTERY_STATUS_FLAGS_PROTECTIONS_ENABLED is set. Other faults like MAV_BATTERY_STATUS_FLAGS_FAULT_OVER_VOLT may also be set, indicating the cause of the protection fault. - + One or more cells are above their maximum voltage rating. - + One or more cells are below their minimum voltage rating. A battery that had deep-discharged might be irrepairably damaged, and set both MAV_BATTERY_STATUS_FLAGS_FAULT_UNDER_VOLT and MAV_BATTERY_STATUS_FLAGS_BAD_BATTERY. - + Over-temperature fault. - + Under-temperature fault. - + Over-current fault. - + One or more cells have failed. The battery (or may not) may still be safe to fly. + + + + Short circuit event detected. + The battery (or may not) may still be safe to use (check other flags). + - + Voltage not compatible power rail voltage (batteries on same power rail should have similar voltage). - + Battery firmware is not compatible with current autopilot firmware. - + Battery is not compatible due to cell configuration (e.g. 5s1p when vehicle requires 6s). From 41a7fb80589e0bc77d7786a4d48a3314dc4c4ff1 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 20 Apr 2022 10:10:04 +1000 Subject: [PATCH 30/56] Clarify current consumed is from vehicle being powered on --- text/001x-battery_improvements.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 25bd8d4..c05ab88 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -42,16 +42,16 @@ The proposed message is: This should be streamed (nominally at 1Hz). Static/invariant battery information is sent in SMART_BATTERY_INFO. - The full-battery charge is current_remaining + current_consumed, iff both values are supplied. + The full-battery charge can be inferred from current_remaining and percent_remaining if both values are supplied. The `current_remaining` field should only be sent if it is guaranteed to be near-accurate. - Power monitors typically should not send the `current_remaining` field as it can only be accurate if the battery is fully charged when the drone is turned on. + Power monitors do not normally send the `current_remaining` field as it can only be accurate if the battery is fully charged when the drone is turned on. (A GCS can use `current_remaining` being invalid as a trigger to notify the user to fully charge the battery before flight). Battery ID Temperature of the whole battery pack (not internal electronics). INT16_MAX field not provided. Battery voltage (total). UINT32_MAX: field not provided. Battery current (through all cells/loads). UINT32_MAX: field not provided. - Consumed charge (from full). UINT32_MAX: field not provided. Note: Power modules report the current consumed since they were last turned on (the expectation is that batteries are fully charged before turning on the vehicle). + Consumed charge (since vehicle powered on). UINT32_MAX: field not provided. Note: For power modules the expectation is that batteries are fully charged before turning on the vehicle. Remaining charge (until empty). UINT32_MAX: field not provided. Note: Power monitors should not set this value. Remaining battery energy. Values: [0-100], UINT32_MAX: field not provided. Fault, health, and readiness status indications. From 506de4620118f4b4274109fc5847cdbedf647a05 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 20 Apr 2022 10:10:28 +1000 Subject: [PATCH 31/56] Update text/001x-battery_improvements.md Co-authored-by: Jacob Dahl <37091262+dakejahl@users.noreply.github.com> --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index c05ab88..47b69d1 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -54,7 +54,7 @@ The proposed message is: Consumed charge (since vehicle powered on). UINT32_MAX: field not provided. Note: For power modules the expectation is that batteries are fully charged before turning on the vehicle. Remaining charge (until empty). UINT32_MAX: field not provided. Note: Power monitors should not set this value. Remaining battery energy. Values: [0-100], UINT32_MAX: field not provided. - Fault, health, and readiness status indications. + Fault, health, and readiness status indications. ``` From af11eafdaff1b2ae776964520545a73ad432f482 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 20 Apr 2022 10:14:35 +1000 Subject: [PATCH 32/56] Update text/001x-battery_improvements.md Co-authored-by: Jacob Dahl <37091262+dakejahl@users.noreply.github.com> --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 47b69d1..5e5c377 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -75,7 +75,7 @@ The proposed message is: Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). - + Battery is cell balancing (during charging). Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). From 9d17b5551b28368b10e6c946c3b4956db18bb090 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 20 Apr 2022 10:18:32 +1000 Subject: [PATCH 33/56] Remove cell fail fault - not needed according to jacob --- text/001x-battery_improvements.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 5e5c377..fdecaa1 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -140,22 +140,19 @@ The proposed message is: Over-current fault. - - One or more cells have failed. The battery (or may not) may still be safe to fly. - - + Short circuit event detected. The battery (or may not) may still be safe to use (check other flags). - + Voltage not compatible power rail voltage (batteries on same power rail should have similar voltage). - + Battery firmware is not compatible with current autopilot firmware. - + Battery is not compatible due to cell configuration (e.g. 5s1p when vehicle requires 6s). From abe7dce3ce0a5433255faeb3923d1016400defff Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 20 Apr 2022 10:19:18 +1000 Subject: [PATCH 34/56] Update text/001x-battery_improvements.md Co-authored-by: Jacob Dahl <37091262+dakejahl@users.noreply.github.com> --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index fdecaa1..9e957c9 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -143,7 +143,7 @@ The proposed message is: Short circuit event detected. - The battery (or may not) may still be safe to use (check other flags). + The battery may or may not be safe to use (check other flags). From 469e5c3e49cf8a91511d2dc7879339caf401194d Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 20 Apr 2022 10:19:31 +1000 Subject: [PATCH 35/56] Update text/001x-battery_improvements.md Co-authored-by: Jacob Dahl <37091262+dakejahl@users.noreply.github.com> --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 9e957c9..8856b86 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -147,7 +147,7 @@ The proposed message is: - Voltage not compatible power rail voltage (batteries on same power rail should have similar voltage). + Voltage not compatible with power rail voltage (batteries on same power rail should have similar voltage). Battery firmware is not compatible with current autopilot firmware. From ff245bb1d5b8760be6b60a91c0e8e0df235b3e99 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 1 Jun 2022 14:01:04 +1000 Subject: [PATCH 36/56] add ids for messages close to smart battery info --- text/001x-battery_improvements.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 8856b86..66b992b 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -37,7 +37,7 @@ There are three parts to the design: The proposed message is: ```xml - + Battery dynamic information. This should be streamed (nominally at 1Hz). Static/invariant battery information is sent in SMART_BATTERY_INFO. @@ -215,11 +215,11 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ The proposed battery message is: ```xml - + Battery cell voltages. This message is provided primarily for cell fault debugging. For batteries with more than 10 cells the message should be sent multiple times, iterating the index value. - It should not be streamed at very low rate (less than once a minute) or streamed only on request. + It should be streamed at very low rate (less than once a minute) or streamed only on request. Battery ID Cell index (0 by default). This can be iterated for batteries with more than 12 cells. Battery voltage of 12 cells at current index. Cells above the valid cell count for this battery should be set to 0. From e4e9b577109bc05015505eae6e607173e3da0b82 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 2 Jun 2022 11:06:58 +1000 Subject: [PATCH 37/56] Add flag to indicate whether values are assumed to be re;ative full battery Set for a smart battery to indicate the values are reliable. Unset for a power module to indicate the values are based one assumption of initial full battery on power on. --- text/001x-battery_improvements.md | 43 ++++++++++++++++++------------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 66b992b..036f213 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -41,20 +41,17 @@ The proposed message is: Battery dynamic information. This should be streamed (nominally at 1Hz). Static/invariant battery information is sent in SMART_BATTERY_INFO. - - The full-battery charge can be inferred from current_remaining and percent_remaining if both values are supplied. - The `current_remaining` field should only be sent if it is guaranteed to be near-accurate. - Power monitors do not normally send the `current_remaining` field as it can only be accurate if the battery is fully charged when the drone is turned on. - (A GCS can use `current_remaining` being invalid as a trigger to notify the user to fully charge the battery before flight). + Note that smart batteries should set the MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL bit to indicate that supplied capacity values are relative to a battery that is known to be full. + Power monitors would not set this bit, indicating that capacity_consumed is relative to drone power-on, and that other values are estimated based on the assumption that the battery was full on power-on. Battery ID Temperature of the whole battery pack (not internal electronics). INT16_MAX field not provided. Battery voltage (total). UINT32_MAX: field not provided. Battery current (through all cells/loads). UINT32_MAX: field not provided. - Consumed charge (since vehicle powered on). UINT32_MAX: field not provided. Note: For power modules the expectation is that batteries are fully charged before turning on the vehicle. - Remaining charge (until empty). UINT32_MAX: field not provided. Note: Power monitors should not set this value. + Consumed charge. UINT32_MAX: field not provided. This is either the consumption since power-on or since the battery was full, depending on the value of MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL. + Remaining charge (until empty). UINT32_MAX: field not provided. Note: If MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL is unset, this value is based on the assumption the battery was full when the system was powered. Remaining battery energy. Values: [0-100], UINT32_MAX: field not provided. - Fault, health, and readiness status indications. + Fault, health, readiness, and other status indications. ``` @@ -155,27 +152,37 @@ The proposed message is: Battery is not compatible due to cell configuration (e.g. 5s1p when vehicle requires 6s). + + + Battery capacity values are relative to a known-full battery. + If set: the supplied capacity_consumed and capacity_remaining are relative to battery full. + If unset: capacity_consumed is relative to drone power-on, and capacity_remaining estimated from capacity_consumed and the assumption that the battery was full at power on. + This bit should be set by smart batteries and unset for power modules. + If unset a GCS is recommended to advise that users fully charge the battery on power on. + + ``` The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) but: - removes the cell voltage arrays: `voltages` and `voltages_ext` - adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. -- `current_consumed` has changed from an `int32_t` to a `uint32_t`. This allows future proofs from 32767 mAh limit to 4294967295 mAh -- removes `energy_consumed`. This essentially duplicates `current_consumed` for most purposes, and `current_consumed`/mAh is nearly ubiquitous. -- adds `current_remaining`(mAh) estimate. - - This allows a GCS to more accurately determine available current and remaining time than inferring from the `current_consumed` and `percent_remaining`. - - Note that this also gives the current reliably on plug-in. - All the other information provided by messages (other than `percent_remaining`) assumes that the battery was full when it was plugged in. - - Includes a note that should not be set by power modules. - Power modules can only provide this reliably if the battery is fully charged when they are turned on. - A GCS can still infer the battery remaining from the consumed current, but by setting this as empty, we tell the GCS that it can't be "sure" of the value, and should prompt the user to use full batteries. +- `current_consumed` has changed to capacity_consumed, and from an `int32_t` to a `uint32_t`. + This future proofs from 32767 mAh limit to 4294967295 mAh +- removes `energy_consumed`, which essentially duplicates `capacity_consumed` for most purposes, and `capacity_consumed` in mAh is nearly ubiquitous. +- adds `capacity_remaining`(mAh). + - This allows a GCS to more accurately determine available current and remaining time than inferring from the `capacity_consumed` and `percent_remaining`. + - This will be reliable for smart batteries. + - A flag has been added to indicate whether this is calculated from an assumed or known-full battery. + A GCS can use this to prompt that batteries be fully charged for power modules. +- Note that with capacity consumed and remaining, you have the full capacity and you could calculate the percentage remaining. + However percentage remaining is supplied anyway, as the other values are optional, and this is actually the one value that most users really want. - change `current` from a `int16_t` (cA) to a `uint32_t` (mA). Maximum size was previously 327.67A, which is not large enough to be future proof. The value is absolute - if you're charging the value can be assumed to be in a reversed direction. - removes `time_remaining`. ```xml Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. ``` - - This is an estimated "convenience" value which can be calculated as well or better by a GCS, in particular on multi-battery systems (from original charge, `current_consumed` and looking at the rate of `current` over some time period). + - This is an estimated "convenience" value which can be calculated as well or better by a GCS, in particular on multi-battery systems (from original charge, `capacity_consumed` and looking at the rate of `current` over some time period). - Better to be lightweight. - `percent_remaining` changed from int8 to uint8 (and max value set to invalid value). This is consistent with other MAVLink percentage fields. From 8b9625f7ca48a3d440a147db25f47bcffd1ccb0d Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 2 Jun 2022 12:15:10 +1000 Subject: [PATCH 38/56] Reserve final value of status flag for later extension --- text/001x-battery_improvements.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 036f213..52b3c06 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -161,6 +161,9 @@ The proposed message is: If unset a GCS is recommended to advise that users fully charge the battery on power on. + + Reserved (not used). If set, this will indicate that an additional status field exists for higher status values. + ``` From acc9e731cfe00686466ead9cdea3974987d71a41 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 2 Jun 2022 16:23:34 +1000 Subject: [PATCH 39/56] Update text/001x-battery_improvements.md Co-authored-by: Josh Henderson --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 52b3c06..f60bfb9 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -228,7 +228,7 @@ The proposed battery message is: Battery cell voltages. This message is provided primarily for cell fault debugging. - For batteries with more than 10 cells the message should be sent multiple times, iterating the index value. + For batteries with more than 12 cells the message should be sent multiple times, iterating the index value. It should be streamed at very low rate (less than once a minute) or streamed only on request. Battery ID Cell index (0 by default). This can be iterated for batteries with more than 12 cells. From d563499205adab6ab9d751f869385adc7faa88d2 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 2 Jun 2022 16:25:39 +1000 Subject: [PATCH 40/56] Update text/001x-battery_improvements.md Co-authored-by: Josh Henderson --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index f60bfb9..6213430 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -50,7 +50,7 @@ The proposed message is: Battery current (through all cells/loads). UINT32_MAX: field not provided. Consumed charge. UINT32_MAX: field not provided. This is either the consumption since power-on or since the battery was full, depending on the value of MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL. Remaining charge (until empty). UINT32_MAX: field not provided. Note: If MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL is unset, this value is based on the assumption the battery was full when the system was powered. - Remaining battery energy. Values: [0-100], UINT32_MAX: field not provided. + Remaining battery energy. Values: [0-100], UINT8_MAX: field not provided. Fault, health, readiness, and other status indications. ``` From 0f678c7f59b71c1d8b5424ddf63db1c03bc4fcbe Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 2 Jun 2022 16:36:40 +1000 Subject: [PATCH 41/56] Update text/001x-battery_improvements.md Co-authored-by: Josh Henderson --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 6213430..5e153ae 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -63,7 +63,7 @@ The proposed message is: The battery is ready to use (fly). - Only set if the battery is safe and ready to fly with (not charging, no critical faults, such as those that would set MAV_BATTERY_STATUS_FLAGS_REQUIRES_SERVICE or MAV_BATTERY_STATUS_FLAGS_BAD_BATTERY, etc.). + Set if the battery has no known issues that would make it unsafe to fly with. This includes critical faults, such as those that would set MAV_BATTERY_STATUS_FLAGS_REQUIRES_SERVICE or MAV_BATTERY_STATUS_FLAGS_BAD_BATTERY). From 8801ef49c3a8529de563d98c33c930261ac999ab Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 2 Jun 2022 16:39:13 +1000 Subject: [PATCH 42/56] Battery might be OK to use during charging --- text/001x-battery_improvements.md | 1 - 1 file changed, 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 5e153ae..a966cea 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -69,7 +69,6 @@ The proposed message is: Battery is charging. - Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). From e5aeab50f8c9e489ef3904fb13fd3d9ba4f56199 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 2 Jun 2022 16:54:20 +1000 Subject: [PATCH 43/56] Update text/001x-battery_improvements.md Co-authored-by: Josh Henderson --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index a966cea..1806594 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -179,7 +179,7 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ A GCS can use this to prompt that batteries be fully charged for power modules. - Note that with capacity consumed and remaining, you have the full capacity and you could calculate the percentage remaining. However percentage remaining is supplied anyway, as the other values are optional, and this is actually the one value that most users really want. -- change `current` from a `int16_t` (cA) to a `uint32_t` (mA). Maximum size was previously 327.67A, which is not large enough to be future proof. The value is absolute - if you're charging the value can be assumed to be in a reversed direction. +- change `current` from a `int16_t` (cA) to a `int32_t` (mA). Maximum size was previously 327.67A, which is not large enough to be future proof. New value gives up to 2,147,483A. The value is positive when discharging, and negative when charging. - removes `time_remaining`. ```xml Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. From f84e83bf6b86e424eb88481cef8ccdc6a717deb7 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 2 Jun 2022 16:54:55 +1000 Subject: [PATCH 44/56] current to int32 --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 1806594..9275fb5 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -47,7 +47,7 @@ The proposed message is: Battery ID Temperature of the whole battery pack (not internal electronics). INT16_MAX field not provided. Battery voltage (total). UINT32_MAX: field not provided. - Battery current (through all cells/loads). UINT32_MAX: field not provided. + Battery current (through all cells/loads). Positive value when discharging and negative if charging. INT32_MAX: field not provided. Consumed charge. UINT32_MAX: field not provided. This is either the consumption since power-on or since the battery was full, depending on the value of MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL. Remaining charge (until empty). UINT32_MAX: field not provided. Note: If MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL is unset, this value is based on the assumption the battery was full when the system was powered. Remaining battery energy. Values: [0-100], UINT8_MAX: field not provided. From 5d19e49067324de80e64265864ec72d7fc958d0b Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 3 Jun 2022 08:49:57 +1000 Subject: [PATCH 45/56] Add the smart battery standard DS-013 Co-authored-by: Claudio Micheli --- text/001x-battery_improvements.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 9275fb5..1dd6780 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -5,6 +5,7 @@ - [common: added voltage and current multipliers to BATTERY_STATUS #233](https://github.com/ArduPilot/mavlink/pull/233) - [Add MAV_BATTERY_CHARGE_STATE_CHARGING #1068](https://github.com/mavlink/mavlink/pull/1068) - dronecan / DSDL : [WIP smart battery messages](https://github.com/dronecan/DSDL/pull/7) +- [DS-013 Pixhawk Smart Battery Standard](https://docs.google.com/document/d/1xYBhhgjND_RS2W3Hq0Seyc-R661ge3zonk9DTIyHclc/edit) v0.4.0 # Summary From 75bdacc58fd8099fe46bc7f25f8414d194318817 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 3 Jun 2022 08:50:20 +1000 Subject: [PATCH 46/56] Typo --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 1dd6780..01b0101 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -5,7 +5,7 @@ - [common: added voltage and current multipliers to BATTERY_STATUS #233](https://github.com/ArduPilot/mavlink/pull/233) - [Add MAV_BATTERY_CHARGE_STATE_CHARGING #1068](https://github.com/mavlink/mavlink/pull/1068) - dronecan / DSDL : [WIP smart battery messages](https://github.com/dronecan/DSDL/pull/7) -- [DS-013 Pixhawk Smart Battery Standard](https://docs.google.com/document/d/1xYBhhgjND_RS2W3Hq0Seyc-R661ge3zonk9DTIyHclc/edit) v0.4.0 + - [DS-013 Pixhawk Smart Battery Standard](https://docs.google.com/document/d/1xYBhhgjND_RS2W3Hq0Seyc-R661ge3zonk9DTIyHclc/edit) v0.4.0 # Summary From 5fb3ff8bc1887cdcc75bef2139ec2e2cb976dec5 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 3 Jun 2022 17:57:44 +1000 Subject: [PATCH 47/56] MAV_BATTERY_STATUS_FLAGS_READY_TO_USE to MAV_BATTERY_STATUS_FLAGS_NOT_READY_TO_USE --- text/001x-battery_improvements.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 01b0101..0cef2c9 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -61,10 +61,11 @@ The proposed message is: ```xml Battery status flags for fault, health and state indication. - + - The battery is ready to use (fly). - Set if the battery has no known issues that would make it unsafe to fly with. This includes critical faults, such as those that would set MAV_BATTERY_STATUS_FLAGS_REQUIRES_SERVICE or MAV_BATTERY_STATUS_FLAGS_BAD_BATTERY). + The battery is not ready to use (fly). + Set if the battery has faults that would make it unsafe to fly with. + It aggregates other serious faults, like MAV_BATTERY_STATUS_FLAGS_REQUIRES_SERVICE, MAV_BATTERY_STATUS_FLAGS_BAD_BATTERY and others (at manufacturer/integrator discretion). @@ -75,7 +76,7 @@ The proposed message is: Battery is cell balancing (during charging). - Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). + Not ready to use (MAV_BATTERY_STATUS_FLAGS_NOT_READY_TO_USE may be set). @@ -87,7 +88,7 @@ The proposed message is: Battery is auto discharging (towards storage level). - Not ready to use (MAV_BATTERY_STATUS_FLAGS_READY_TO_USE would not be set). + Not ready to use (MAV_BATTERY_STATUS_FLAGS_NOT_READY_TO_USE would be set). From ab3d25fb0bbb68a65f13499678b1add23d847086 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 3 Jun 2022 18:16:12 +1000 Subject: [PATCH 48/56] improve description not ready to fly --- text/001x-battery_improvements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 0cef2c9..3f3fffe 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -64,8 +64,8 @@ The proposed message is: The battery is not ready to use (fly). - Set if the battery has faults that would make it unsafe to fly with. - It aggregates other serious faults, like MAV_BATTERY_STATUS_FLAGS_REQUIRES_SERVICE, MAV_BATTERY_STATUS_FLAGS_BAD_BATTERY and others (at manufacturer/integrator discretion). + Set if the battery has faults or other conditions that make it unsafe to fly with. + Note: It will be the logical OR of other status bits (chosen by the manufacturer/integrator). From 5fa4be2cc2383fb330029e3cc1b462a1d6e7add4 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 21 Sep 2022 15:56:38 +1000 Subject: [PATCH 49/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 3f3fffe..853aaec 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -107,10 +107,10 @@ The proposed message is: - Automatic battery protection monitoring is enabled. + Automatic battery protection monitoring is enabled. When enabled, the system will monitor for certain kinds of faults, such as cells being over-voltage. If a fault is triggered then and protections are enabled then a safety fault (MAV_BATTERY_STATUS_FLAGS_FAULT_PROTECTION_SYSTEM) will be set and power from the battery will be stopped. - Note that the associated fault (such as MAV_BATTERY_STATUS_FLAGS_FAULT_OVER_VOLT) should always be set whether or not the protection system is engaged. + Note that battery protection monitoring should only be enabled when the vehicle is landed. Once the vehicle is armed, or starts moving, the protections should be disabled to prevent false positives from disabling the output. From 6aa86db59318abc14912c1fed43f3d1e54bc887c Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 21 Sep 2022 16:02:31 +1000 Subject: [PATCH 50/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 853aaec..4a7be70 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -231,9 +231,9 @@ The proposed battery message is: This message is provided primarily for cell fault debugging. For batteries with more than 12 cells the message should be sent multiple times, iterating the index value. It should be streamed at very low rate (less than once a minute) or streamed only on request. - Battery ID - Cell index (0 by default). This can be iterated for batteries with more than 12 cells. - Battery voltage of 12 cells at current index. Cells above the valid cell count for this battery should be set to 0. + Battery ID + Cell index (0 by default). This can be iterated for batteries with more than 12 cells. + Battery voltage of up to 126 cells at current index. Cells above the valid cell count for this battery should be set to 0. ``` From ce998279d83443f4e18ada9d764d345d2674b082 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 21 Sep 2022 16:44:00 +1000 Subject: [PATCH 51/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 4a7be70..273b5c8 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -155,10 +155,9 @@ The proposed message is: - Battery capacity values are relative to a known-full battery. - If set: the supplied capacity_consumed and capacity_remaining are relative to battery full. - If unset: capacity_consumed is relative to drone power-on, and capacity_remaining estimated from capacity_consumed and the assumption that the battery was full at power on. - This bit should be set by smart batteries and unset for power modules. + Battery capacity_consumed and capacity_remaining values are relative to a full battery (they sum to the total capacity of the battery). + This flag would be set for a smart battery that can accurately determine its remaining charge across vehicle reboots and discharge/recharge cycles. + If unset the capacity_consumed indicates the consumption since vehicle power-on, as measured using a power monitor. The capacity_remaining, if provided, indicates the estimated remaining capacity on the assumption that the battery was full on vehicle boot. If unset a GCS is recommended to advise that users fully charge the battery on power on. From 8e2deb7acd8ada475a3cdd44679c11a8b90ab202 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 12 Oct 2022 14:20:44 +1100 Subject: [PATCH 52/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 273b5c8..9aeaac0 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -228,7 +228,7 @@ The proposed battery message is: Battery cell voltages. This message is provided primarily for cell fault debugging. - For batteries with more than 12 cells the message should be sent multiple times, iterating the index value. + For batteries with more than 126 cells the message should be sent multiple times, iterating the index value. It should be streamed at very low rate (less than once a minute) or streamed only on request. Battery ID Cell index (0 by default). This can be iterated for batteries with more than 12 cells. From b5f65c0b466a34f41154b07b2c3d5e8dc77e5d24 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 12 Oct 2022 15:56:01 +1100 Subject: [PATCH 53/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index 9aeaac0..d0e9587 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -47,10 +47,10 @@ The proposed message is: Battery ID Temperature of the whole battery pack (not internal electronics). INT16_MAX field not provided. - Battery voltage (total). UINT32_MAX: field not provided. - Battery current (through all cells/loads). Positive value when discharging and negative if charging. INT32_MAX: field not provided. - Consumed charge. UINT32_MAX: field not provided. This is either the consumption since power-on or since the battery was full, depending on the value of MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL. - Remaining charge (until empty). UINT32_MAX: field not provided. Note: If MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL is unset, this value is based on the assumption the battery was full when the system was powered. + Battery voltage (total). NaN: field not provided. + Battery current (through all cells/loads). Positive value when discharging and negative if charging. NaN: field not provided. + Consumed charge. NaN: field not provided. This is either the consumption since power-on or since the battery was full, depending on the value of MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL. + Remaining charge (until empty). UINT32_MAX: field not provided. Note: If MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL is unset, this value is based on the assumption the battery was full when the system was powered. Remaining battery energy. Values: [0-100], UINT8_MAX: field not provided. Fault, health, readiness, and other status indications. From ea508a78abfb40162db79aebb0b17b172e1504a9 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 12 Oct 2022 15:59:04 +1100 Subject: [PATCH 54/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index d0e9587..ce606af 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -169,18 +169,18 @@ The proposed message is: The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) but: - removes the cell voltage arrays: `voltages` and `voltages_ext` -- adds `voltage`, the total cell voltage. This is a uint32_t to allow batteries with more than 65V. -- `current_consumed` has changed to capacity_consumed, and from an `int32_t` to a `uint32_t`. - This future proofs from 32767 mAh limit to 4294967295 mAh +- adds `voltage`, the total cell voltage. This is a float to allow batteries with more than 65V and also very small voltage changes. +- `current_consumed` has changed to capacity_consumed, and from an `int32_t` to a `float` in A. + This future proofs from 32767 mAh limit and allows very large and very small values. - removes `energy_consumed`, which essentially duplicates `capacity_consumed` for most purposes, and `capacity_consumed` in mAh is nearly ubiquitous. -- adds `capacity_remaining`(mAh). +- adds `capacity_remaining`(Ah) as a `float`. - This allows a GCS to more accurately determine available current and remaining time than inferring from the `capacity_consumed` and `percent_remaining`. - This will be reliable for smart batteries. - A flag has been added to indicate whether this is calculated from an assumed or known-full battery. A GCS can use this to prompt that batteries be fully charged for power modules. - Note that with capacity consumed and remaining, you have the full capacity and you could calculate the percentage remaining. However percentage remaining is supplied anyway, as the other values are optional, and this is actually the one value that most users really want. -- change `current` from a `int16_t` (cA) to a `int32_t` (mA). Maximum size was previously 327.67A, which is not large enough to be future proof. New value gives up to 2,147,483A. The value is positive when discharging, and negative when charging. +- change `current` from a `int16_t` (cA) to a `float` (A). Maximum size was previously 327.67A, which is not large enough to be future proof. New value gives full range and both very small and very high values. - removes `time_remaining`. ```xml Remaining battery time (estimated), UINT32_MAX: Remaining battery time estimate not provided. From c25344b9a150d58805b4f2bfc3654bdb332fa73f Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 13 Oct 2022 14:32:46 +1100 Subject: [PATCH 55/56] Update text/001x-battery_improvements.md --- text/001x-battery_improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index ce606af..bf9162b 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -161,7 +161,7 @@ The proposed message is: If unset a GCS is recommended to advise that users fully charge the battery on power on. - + Reserved (not used). If set, this will indicate that an additional status field exists for higher status values. From 12561b9f0c5155e70de3d388fe0d207f349813ac Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 14 Feb 2024 11:17:30 +1100 Subject: [PATCH 56/56] Update now that SMART_BATTERY_INFO was renamed to BATTERY_INFO --- text/001x-battery_improvements.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/text/001x-battery_improvements.md b/text/001x-battery_improvements.md index bf9162b..4a2651b 100644 --- a/text/001x-battery_improvements.md +++ b/text/001x-battery_improvements.md @@ -6,6 +6,7 @@ - [Add MAV_BATTERY_CHARGE_STATE_CHARGING #1068](https://github.com/mavlink/mavlink/pull/1068) - dronecan / DSDL : [WIP smart battery messages](https://github.com/dronecan/DSDL/pull/7) - [DS-013 Pixhawk Smart Battery Standard](https://docs.google.com/document/d/1xYBhhgjND_RS2W3Hq0Seyc-R661ge3zonk9DTIyHclc/edit) v0.4.0 + - [Common: rename SMART_BATTERY_INFO to BATTERY_INFO and add SOH](https://github.com/mavlink/mavlink/pull/2070) # Summary @@ -41,7 +42,7 @@ The proposed message is: Battery dynamic information. This should be streamed (nominally at 1Hz). - Static/invariant battery information is sent in SMART_BATTERY_INFO. + Static/invariant battery information is sent in BATTERY_INFO. Note that smart batteries should set the MAV_BATTERY_STATUS_FLAGS_CAPACITY_RELATIVE_TO_FULL bit to indicate that supplied capacity values are relative to a battery that is known to be full. Power monitors would not set this bit, indicating that capacity_consumed is relative to drone power-on, and that other values are estimated based on the assumption that the battery was full on power-on. @@ -189,13 +190,13 @@ The message is heavily based on [BATTERY_STATUS](https://mavlink.io/en/messages/ - Better to be lightweight. - `percent_remaining` changed from int8 to uint8 (and max value set to invalid value). This is consistent with other MAVLink percentage fields. -- removes `battery_function` and `type` (chemistry) as these are present in `SMART_BATTERY_INFO` and invariant. +- removes `battery_function` and `type` (chemistry) as these are present in `BATTERY_INFO` and are invariant. ```xml Function of the battery Type (chemistry) of the battery ``` - - A GCS that needs invariant information should read `SMART_BATTERY_INFO` on startup - - A vehicle that allows battery swapping must stream `SMART_BATTERY_INFO` (at low rate) to ensure that battery changes are notifie (and ideally also emit it on battery change). + - A GCS that needs invariant information should read `BATTERY_INFO` on startup + - A vehicle that allows battery swapping must stream `BATTERY_INFO` (at low rate) to ensure that battery changes are notifie (and ideally also emit it on battery change). - New `battery_status` (`MAV_BATTERY_STATUS_FLAGS`) replaces [`fault_bitmask`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_FAULT), [`charge_state`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_CHARGE_STATE) and [`mode`](https://mavlink.io/en/messages/common.html#MAV_BATTERY_MODE) ```xml State for extent of discharge, provided by autopilot for warning or external reactions @@ -260,14 +261,11 @@ This assumes that the smart battery is capable of providing the long term trend ``` -## SMART_BATTERY_INFO +## BATTERY_INFO -[SMART_BATTERY_INFO](https://mavlink.io/en/messages/common.html#SMART_BATTERY_INFO) is already deployed and it is not clear if it can be modified. It may be possible to extend. +[BATTERY_INFO](https://mavlink.io/en/messages/common.html#BATTERY_INFO) is WIP in common. This has been renamed from `SMART_BATTERY_INFO` as there were no known implementations. Add note that it must be streamed at a low rate in order to allow detection of battery change, and should also be sent when the battery changes. - -Questions: -- What low rate is OK for streaming? is there another alternative for tracking battery change