Measurement & Formatting

How the Meshtastic Android/KMP app formats numbers, units, and locale-sensitive values.

Overview

All measurement data transmitted by Meshtastic radios 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`	Low-level fixed-point number formatting with locale-independent dot separator

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:

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 windSpeed(metersPerSecond: Float, isImperial: Boolean, decimalPlaces: Int = 1): String
    fun rainfall(millimeters: Float, isImperial: Boolean, decimalPlaces: Int = 1): String
}

Usage

// 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)  // "3.7 m/s"
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 provides locale-independent decimal formatting using pure arithmetic (no String.format or DecimalFormat):

object NumberFormatter {
    fun format(value: Double, decimalPlaces: Int): String
    fun format(value: Float, decimalPlaces: Int): String
}

Why locale-independent? Meshtastic is a mesh networking app where consistency matters — sensor readings shared between nodes should look the same everywhere. NumberFormatter always uses . as the decimal separator.

Unit Conversion

Three measurements convert away from metric for display, each gated by a boolean flag sourced from the user's device locale or preferences:

Measurement	Flag	Conversion
`temperature`	`isFahrenheit`	`°F = °C × 1.8 + 32`
`windSpeed`	`isImperial`	m/s × 2.23694 → mph
`rainfall`	`isImperial`	mm ÷ 25.4 → in

Everything else (voltage, current, pressure, SNR, RSSI, humidity, percent) displays in its native metric units. The user-facing Units & Locale page explains what end users see.

Adding a New Measurement Type

To add a new measurement formatter:

Add a function to MetricFormatter in core/common/src/commonMain/kotlin/org/meshtastic/core/common/util/MetricFormatter.kt:

fun radiation(microSieverts: Float, decimalPlaces: Int = 2): String =
    "${NumberFormatter.format(microSieverts, decimalPlaces)} μSv/h"

Add tests in core/common/src/commonTest/:

@Test
fun radiationFormatting() {
    assertEquals("0.15 μSv/h", MetricFormatter.radiation(0.15f))
    assertEquals("1.23 μSv/h", MetricFormatter.radiation(1.234f))
}

Use in UI — call from any commonMain composable or ViewModel:

Text(text = MetricFormatter.radiation(node.radiationLevel))

Run verification:
```
./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
Locale-independent decimal separator (`.`)	Mesh data shared between nodes must be consistent
Pure arithmetic formatting (no `DecimalFormat`)	Works identically on JVM, Native, and JS targets
Only temperature, wind speed, and rainfall convert	The remaining metric units are universally understood in their native form
`object` singleton pattern	Stateless utility — no instance management needed

User-facing docs: Units & 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

Overview​

MetricFormatter API​

Usage​

NumberFormatter​

Unit Conversion​

Adding a New Measurement Type​

DateFormatter​

Design Decisions​

Related​