mirror of
https://github.com/meshtastic/Meshtastic-Android.git
synced 2026-09-21 11:15:18 -04:00
184 lines
8.8 KiB
HTML
184 lines
8.8 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en" dir="ltr">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>Measurement & Formatting</title>
|
||
<link rel="stylesheet" href="../styles/docs.css">
|
||
</head>
|
||
<body data-page="measurement" data-locale="en">
|
||
<pre class="markdown-content"># Measurement & Formatting
|
||
|
||
How the Meshtastic Android/KMP app formats numbers, units, and locale-sensitive values.
|
||
|
||
## Overview
|
||
|
||
All measurement data transmitted by Meshtastic nodes uses **metric units** (meters, °C, hPa, m/s, etc.). The app converts and formats these values for display using two core utilities:
|
||
|
||
Utility | Location | Purpose |
|
||
---|---|---|
|
||
`MetricFormatter` | `core/common/.../util/MetricFormatter.kt` | Converts and formats physical measurements (temperature, pressure, speed, etc.) |
|
||
`NumberFormatter` | `core/common/.../util/NumberFormatter.kt` | Decimal formatting: `format` follows the OS locale, `formatInvariant` keeps a fixed dot separator |
|
||
`MeasureFormatting` | `core/common/.../util/MeasureFormatting.kt` | Pairs a fixed English unit symbol with a locale-formatted number, for the units that convert |
|
||
|
||
Both live in `org.meshtastic.core.common.util` and are available to all KMP targets (Android, Desktop, iOS).
|
||
|
||
## MetricFormatter API
|
||
|
||
`MetricFormatter` is a Kotlin `object` with pure functions for each measurement type:
|
||
|
||
```kotlin
|
||
object MetricFormatter {
|
||
fun temperature(celsius: Float, isFahrenheit: Boolean): String
|
||
fun voltage(volts: Float, decimalPlaces: Int = 2): String
|
||
fun current(milliAmps: Float, decimalPlaces: Int = 1): String
|
||
fun percent(value: Float, decimalPlaces: Int = 1): String
|
||
fun humidity(value: Float): String
|
||
fun pressure(hPa: Float, decimalPlaces: Int = 1): String
|
||
fun snr(value: Float?, decimalPlaces: Int = 1): String
|
||
fun rssi(value: Int?): String
|
||
fun degreeSymbol(isFahrenheit: Boolean): String
|
||
fun percent(value: Int): String
|
||
fun windSpeed(metersPerSecond: Float, isImperial: Boolean, decimalPlaces: Int = 1): String
|
||
fun rainfall(millimeters: Float, isImperial: Boolean, decimalPlaces: Int = 1): String
|
||
fun weight(kilograms: Float, isImperial: Boolean, decimalPlaces: Int = 2): String
|
||
}
|
||
|
||
`snr` and `rssi` take a nullable reading and render the `—` placeholder when it is absent.
|
||
```
|
||
|
||
### Usage
|
||
|
||
```kotlin
|
||
// Temperature — Fahrenheit conversion is handled automatically
|
||
MetricFormatter.temperature(22.5f, isFahrenheit = true) // "72.5°F"
|
||
MetricFormatter.temperature(22.5f, isFahrenheit = false) // "22.5°C"
|
||
|
||
// Signal metrics
|
||
MetricFormatter.snr(-5.2f) // "-5.2 dB"
|
||
MetricFormatter.rssi(-97) // "-97 dBm"
|
||
|
||
// Environment
|
||
MetricFormatter.pressure(1013.25f) // "1013.3 hPa"
|
||
MetricFormatter.humidity(65.0f) // "65%"
|
||
MetricFormatter.windSpeed(3.7f, isImperial = false) // "13.3 km/h"
|
||
MetricFormatter.windSpeed(3.7f, isImperial = true) // "8.3 mph"
|
||
MetricFormatter.rainfall(12.3f, isImperial = false) // "12.3 mm"
|
||
MetricFormatter.rainfall(12.3f, isImperial = true) // "0.5 in"
|
||
|
||
// Power
|
||
MetricFormatter.voltage(3.95f) // "3.95 V"
|
||
MetricFormatter.current(125.0f) // "125.0 mA"
|
||
```
|
||
|
||
## NumberFormatter
|
||
|
||
`NumberFormatter` has two halves, and picking the wrong one is the mistake to avoid:
|
||
|
||
```kotlin
|
||
object NumberFormatter {
|
||
fun format(value: Double, decimalPlaces: Int): String // follows the OS locale
|
||
fun format(value: Float, decimalPlaces: Int): String // follows the OS locale
|
||
fun formatInvariant(value: Double, decimalPlaces: Int): String // fixed dot separator
|
||
}
|
||
```
|
||
|
||
**Use 0 for anything a person reads.** It delegates to the platform's own number formatter
|
||
through an `expect`/`actual` (`java.text.NumberFormat` on JVM and Android), so a number reads the
|
||
way that user writes numbers. `NaN` and infinity render as `—`.
|
||
|
||
**Use 0 for anything a machine parses** — a CoT payload another client reads, or a
|
||
value written out and read back. Localizing those turns `1.5` into `1,5` and breaks the reader.
|
||
It rounds half away from zero to match the locale path, which matters because firmware reports SNR
|
||
in quarter-dB steps and ties are routine.
|
||
|
||
## Unit conversion
|
||
|
||
Four measurements convert away from metric for display, each gated by a boolean flag sourced from the device locale or preferences:
|
||
|
||
Measurement | Flag | Source | Conversion |
|
||
---|---|---|---|
|
||
`temperature` | `isFahrenheit` | `getSystemTemperatureUnit()` | `°F = °C × 1.8 + 32` |
|
||
`windSpeed` | `isImperial` | `getSystemMeasurementSystem()` | m/s × 3.6 → km/h, or × 2.23694 → mph |
|
||
`rainfall` | `isImperial` | `getSystemMeasurementSystem()` | mm ÷ 25.4 → in |
|
||
`weight` | `isImperial` | `getSystemMeasurementSystem()` | kg × 2.20462 → lb |
|
||
|
||
The two source functions (in `core/common/.../util/MeasurementSystem.kt`) are deliberately separate: some locales mix systems (the UK uses miles for distance but Celsius for temperature), so temperature must never be derived from the distance unit. On Android, `getSystemTemperatureUnit()` delegates to `androidx.core.text.util.LocalePreferences`, which resolves CLDR locale data and honors the Android 14+ Regional preferences temperature override.
|
||
|
||
The in-app **Units** choice (`UnitsOverride`, stored in `UiPrefs`) is folded in by `LocaleUnitsProvider`, which is the only place display code takes units from. A Konsist rule (`MeasurementSystemSourceTest`) keeps direct reads of the OS resolution out of the rest of the codebase, because a direct read follows the locale but ignores the setting. A forced system carries its temperature with it (metric → °C, imperial → °F), overriding even an explicit OS regional temperature preference.
|
||
|
||
`getSystemMeasurementSystem()` resolves the locale in this order (temperature is separate: as described above, `getSystemTemperatureUnit()` reads the regional temperature preference via `LocalePreferences`, shares only the region backfill, and falls back to Celsius):
|
||
|
||
1. The `ms` Unicode extension (the Android 16+ Measurement system preference) wins outright.
|
||
2. A locale with no region — the in-app language picker offers bare tags like `en` — takes its region from the system configuration rather than letting ICU guess one from the language.
|
||
3. Anything still unclassified falls back to metric, never imperial.
|
||
|
||
The Android and Desktop implementations share the region table and the override reader in `commonMain`, so the two clients can't disagree about the same locale.
|
||
|
||
Everything else (voltage, current, pressure, SNR, RSSI, humidity, percent) displays in its native metric units. The user-facing [Units & Locale](../user/units-and-locale) page explains what end users see.
|
||
|
||
## Adding a new measurement type
|
||
|
||
To add a new measurement formatter:
|
||
|
||
1. **Add a function to 0 ** in `core/common/src/commonMain/kotlin/org/meshtastic/core/common/util/MetricFormatter.kt`:
|
||
|
||
```kotlin
|
||
fun radiation(microSieverts: Float, decimalPlaces: Int = 2): String =
|
||
"${NumberFormatter.format(microSieverts, decimalPlaces)} μSv/h"
|
||
```
|
||
|
||
2. **Add tests** in `core/common/src/commonTest/`:
|
||
|
||
```kotlin
|
||
@Test
|
||
fun radiationFormatting() {
|
||
assertEquals("0.15 μSv/h", MetricFormatter.radiation(0.15f))
|
||
assertEquals("1.23 μSv/h", MetricFormatter.radiation(1.234f))
|
||
}
|
||
```
|
||
|
||
3. **Use in UI** — call from any `commonMain` composable or ViewModel:
|
||
|
||
```kotlin
|
||
Text(text = MetricFormatter.radiation(node.radiationLevel))
|
||
```
|
||
|
||
4. **Run verification**:
|
||
```bash
|
||
./gradlew :core:common:allTests
|
||
```
|
||
|
||
## DateFormatter
|
||
|
||
Date and time formatting uses the `DateFormatter` `expect object` with platform-specific `actual` implementations:
|
||
|
||
Function | Output Example |
|
||
---|---|
|
||
`formatRelativeTime()` | "5 min ago" |
|
||
`formatDateTime()` | "May 13, 2026 2:30 PM" |
|
||
`formatShortDate()` | "May 13" |
|
||
`formatTime()` | "2:30 PM" |
|
||
`formatTimeWithSeconds()` | "2:30:45 PM" |
|
||
`formatDate()` | "2026-05-13" |
|
||
`formatDateTimeShort()` | "5/13/26 2:30 PM" |
|
||
|
||
Unlike `MetricFormatter`, `DateFormatter` is declared with `expect`/`actual` (an `expect object` in `commonMain`, an `actual object` per platform) because date formatting inherently depends on platform locale APIs.
|
||
|
||
## Design decisions
|
||
|
||
Decision | Rationale |
|
||
---|---|
|
||
Display formatting follows the OS locale | A number shown to a user should read the way that user writes numbers |
|
||
`formatInvariant` keeps a fixed `.` for machine-read values | Interop payloads and re-parsed values break if localized |
|
||
Only temperature, wind speed, rainfall and weight convert | The remaining metric units are universally understood in their native form |
|
||
`object` singleton pattern | Stateless utility — no instance management needed |
|
||
|
||
## Related
|
||
|
||
- **User-facing docs**: [Units & Locale](../user/units-and-locale) explains what end users see
|
||
- **Source code**: `core/common/src/commonMain/kotlin/org/meshtastic/core/common/util/MetricFormatter.kt`
|
||
- **Tests**: `core/common/src/commonTest/kotlin/org/meshtastic/core/common/util/MetricFormatterTest.kt`
|
||
</pre>
|
||
</body>
|
||
</html> |