RoamCurrent

See where the watts went—before the good sun does.

RoamCurrent is a local-first macOS menu-bar dashboard for solar and battery monitoring. It brings Bluetti Apex 300 power flow, an optional LiTime house battery, recent cloud cover, and a condition-adjusted solar estimate into one compact view.

When solar input falls, RoamCurrent helps answer the useful question: is the sun disappearing, did a panel find some shade, did the load change, or did the telemetry connection simply go stale? That is a lot more actionable than a lonely watt number in a vendor app.

Compact Light Mode dashboard	Compact Dark Mode dashboard

The screenshots use deterministic demo telemetry. No personal location, device identifier, or live power history is included.

Why RoamCurrent

• Catch actionable solar loss. A four-hour graph puts PV input, load, and cloud cover on one clock, making a shade-shaped dip much easier to spot while there is still daylight left to move a panel.
• See the whole energy picture. Current input, output, state of charge, and estimated runtime for the Bluetti and LiTime systems live in one glanceable menu-bar panel.
• Know whether the numbers deserve trust. Source badges, sample age, and explicit connecting, cached, stale, and unavailable states keep an old reading from masquerading as live telemetry.
• Keep the telemetry yours. History is stored locally in SQLite. There is no RoamCurrent account, hosted backend, or telemetry upload service.

What It Does Today

• Reads Apex 300 telemetry through a persistent Bluetooth session and/or an optional local Home Assistant connection.
• Shows aggregate solar, separate PV channels when Bluetooth supplies them, grid input, AC/DC output, and battery state of charge.
• Monitors a LiTime battery independently, so one missing device does not block the rest of the dashboard.
• Adds local cloud cover, UV, sun position, sunrise/sunset, and a modeled best-case solar input for the configured array.
• Retains seven days of local AP300, LiTime, and cloud history.
• Runs as a compact menu-bar panel or a detachable, resizable window in Light and Dark Mode.
• Provides a terse health check for source freshness and recovery guidance.

RoamCurrent does not yet send sustained-drop notifications. The current app makes a drop visible and diagnosable; conservative, local shade alerts are the next product direction under investigation.

Quick Start

RoamCurrent currently builds from source and requires macOS 14 or later with a Swift 6 toolchain.

cp .env.example .env
# Configure at least one telemetry source in .env.
scripts/run_app.sh
scripts/health_check.py

macOS may request Bluetooth and Location Services access on the first launch. The weather card is optional and never blocks power monitoring.

See Setup for the complete first-run workflow and Configuration for telemetry, battery, weather, and solar-array options.

Hardware Reality

The direct Bluetooth paths have been exercised with an Apex 300 and a LiTime battery, but consumer-energy hardware is delightfully weird. Device firmware, advertising behavior, and register layouts can vary. RoamCurrent reports what it can verify and shows N/A or a recovery state when it cannot.

Bluetooth peripherals commonly allow only one active client. If a device is awake but missing, close its vendor phone app and let RoamCurrent reconnect.

Documentation

• Setup — prerequisites, first launch, lifecycle commands, and validation
• Configuration — .env keys and source-specific guidance
• Current version — detailed runtime and UI behavior
• Optional local Home Assistant — container and integration setup
• Roadmap — current product boundary and next bets

Development

Render sanitized previews:

scripts/render_menu_preview.sh
scripts/render_menu_preview.sh output/current/menu-preview-dark.png \
  --render-preview-appearance dark

Run the complete Python and Swift verification gate:

scripts/verify.sh

Generated apps, logs, databases, captures, real configuration, and telemetry remain ignored. Keep secrets, device identifiers, network details, and personal location data out of commits.

Support

☕ Found this project useful? You can buy me a coffee to support more small, practical, independent tools.