Just Watts
A free, open-source smart-trainer app.
Just Watts connects to any Bluetooth FTMS smart trainer and heart rate strap, runs your workouts in
ERG mode or lets you ride free by grade, watts or resistance level, and keeps your history: NP, TSS,
zones, intervals, trends. It runs on your own computer, with no account and no API keys. The trainer
connection lives in a small local server, so reloading or closing the browser never drops the trainer or the ride.
Try it in the browser, no install: justwatts.com (Chrome or
Edge, Web Bluetooth; rides stay in the browser, no uploads). The local app below adds Garmin and Strava
upload and a trainer connection that survives closing the tab.
Quick start
Needs Python 3.10+ and a computer with Bluetooth LE. Any modern browser works for the page.
git clone https://github.com/yaportmax/justwatts
cd justwatts
pip install -e .
justwatts serve
Open http://127.0.0.1:8765, press Connect trainer,
pick it from the scan list. The server remembers it and reconnects by itself. A trainer accepts one
controller at a time: close Zwift or any other app using it first. start.cmd (Windows) or
./start.sh (macOS, Linux) starts the server and opens the browser.
No trainer? justwatts simulate starts a workout on the server's fake trainer; watch it in the page.
What you get
- Workouts: library, a builder with a text format (
10m 45-75%, 5x(3m 115%, 3m 50%), 10m free),
.zwo import and export, an FTP ramp test.
- Ride modes: structured ERG workouts, free ride by grade (simulation), ERG watts or FTMS
resistance level. When the plan ends you keep riding free until you press End.
- Manual control mid-ride: intensity, segment watts and time, the rest of the plan, trainer
mode, in one or two taps (see Ride controls).
- Ride screen on one page: power, target, distance (and climb on a course), cadence against your
target range, HR with zones, interval timer, the chart with a right-hand HR axis. On a course: the
route map in four styles or a 3D terrain view that follows you (MapLibre GL JS, vendored).
- Open world: Marin, from the Golden Gate Bridge over the Headlands and Mt Tam to West Marin and
Point Reyes Station, with named starts (the bridge, Hawk Hill, Rodeo Beach, Sausalito, Mill Valley, Muir
and Stinson Beach, Pantoll, East Peak, Seven Sisters, Fairfax, Whites Hill, Samuel P. Taylor, Point Reyes
Station) or a tap on the map. Ride real roads with no route: you stay on the road; at a junction you go
straight on or follow the main road unless you pick another way, and no way leads out of the world. A
workout can run on top, and the road ridden can be saved as a course. The ride map shows it as a 3D world
(three.js, vendored): terrain, grass that moves in the wind, roads with their lanes and markings, trees, towns,
the Golden Gate Bridge and the city across the water, a little traffic and wildlife, wind and road sound, a
chase camera (V: first person, T: time of day, G: fog, M: sound, K: kit colour), other riders, and their
draft when you sit on a wheel. Without WebGL2, or if it runs too slowly, the 3D map or the 2D map shows
instead. Roads, terrain and ground data are OpenStreetMap and Mapzen terrain, baked into the app
(
app/roads/marin, app/world) so a ride never waits on a server.
- Riding with others (justwatts.com, signed in): riders on the same course or within about 5 km in
the open world show on the 2D and 3D maps with name and watts, friends highlighted. Friends by name
or share link, a Friends panel with who is riding now and "Ride here", group rides (a course or
open-world start, a time, an optional workout, a lobby and a countdown, everyone starts together),
text chat per friend and per group ride, and ride-ons for friends' finished rides. Plain HTTP
polling to the accounts API (
web/api/_lib/social.js), no extra service. Visibility can be switched
off in Settings. The local app has no accounts, so none of this shows there.
- History: every ride with NP, IF, TSS, best 1/5/20 min, power and HR zones, laps per interval,
FIT and TCX export, a share card (PNG) to download or share; weekly TSS, FTP history and best
efforts.
- Uploads (optional): Garmin Connect and Strava.
- Crash-safe: every second of the ride is fsync'd to disk; a crash, kill or restart resumes the ride.
- The web version (justwatts.com) runs the same app with Bluetooth in the browser tab (Chrome or Edge).
Ride controls
Common actions sit on the ride screen; the rest are in Adjust. Each change shows what changed,
and intensity, watts, segment time, length, trainer mode and settings can be undone for 15 s.
| Control | Where | Key |
|---|
| Pause, resume (Pause during an auto-pause stays paused) | bar | Space |
| Intensity ±1 % (grade, watts or level when not in ERG) | bar −/+ | ↑ ↓ (Shift ±5) |
| Back (restart segment; in its first 10 s, the previous one), Skip | bar | ← → |
| Segment time ±1 min (±30 s in Adjust) | bar | [ ] |
| Segment watts ±5/±10 | Adjust | - = |
| Intensity presets, reset to 100 % | Adjust | |
| Workout length ±5 min | Adjust | |
| Trainer: ERG, or ERG off by grade or level (the plan keeps showing) | Adjust | 1 2 3 |
| Edit the plan from the current segment | Adjust | |
| After the plan: hold the last target or ride flat | Adjust | |
| Cadence on/off and range (off: no readout, target or cues), beeps | Adjust | |
| Map style (Map, Satellite, Topo, Cycling), 3D terrain, map or chart focus (courses with a route) | map | F |
| Open world: the way at the junction ahead (shown about 200 m before it) | tap | ← ↑ → |
| Open world: U-turn (ride back the way you came) | bar, junction prompt | ↓ |
| Open world: go to another spot, the ride goes on | bar (Spots) | P |
| Full screen | bar | Shift F |
| Undo, Save, End (two taps) | bar | Z, S |
| Reconnect trainer or HR | header | |
? shows the keys. Free segments and a flat finish ride by grade, and −/+ moves it. FTP tests keep
their targets.
Supported hardware
| Device | Support |
|---|
Smart trainers with Bluetooth FTMS (service 0x1826) | ERG, grade simulation, resistance level |
| Tested | Zwift Hub (server Bluetooth, survives page reloads) |
HR straps, Bluetooth Heart Rate service 0x180D | Yes; trainer-relayed HR is used if no strap. Straps that hide the HR service until they feel a heartbeat (seen on a Wahoo TRACKR) show "waiting for heartbeat" and connect once you wet the contacts. |
| ANT+ only devices | No |
Most current trainers (Wahoo, Tacx, Elite, Saris, JetBlack) expose FTMS; only the Zwift Hub has been
tested so far. Resistance-level mode follows FTMS 1.0 and is untested on hardware.
Uploads
Garmin (pip install "justwatts[garmin]", then justwatts login-garmin once). On first start with
Garmin linked, Just Watts imports your FTP and weight (only the ones you have not set yourself;
Import from Garmin in Settings redoes it and also brings HR zones). HR zones from Garmin are a
choice under Settings > HR zones; the default is % of max HR. It uses the unofficial
python-garminconnect library, which Garmin can
break at any time. Garmin is only active for the default data dir; JUSTWATTS_GARMIN=off or
serve --no-garmin disables it, and any other JUSTWATTS_DATA has it off unless JUSTWATTS_GARMIN=on.
Strava (no extra needed). Press Connect Strava in Settings and approve on Strava. This uses
Just Watts's Strava app: its client secret is not in this repo, it lives only in a tiny stateless token
service (web/api/strava/token.js) that swaps the sign-in code and refresh
tokens for access tokens. Uploads go straight from your computer to Strava; tokens stay in your data
folder. To skip the token service, open Use your own Strava API app in Settings and enter your own
Client ID and secret (strava.com/settings/api, callback domain localhost), or host the function
yourself and set JUSTWATTS_STRAVA_RELAY and JUSTWATTS_STRAVA_CLIENT_ID. Uploads go through the official API with the FIT file,
the ride name and a text summary (NP, IF, TSS, intervals, "Recorded with Just Watts"). If Garmin
Connect already syncs to Strava for you, uploading to both makes duplicates: pick one.
Share card: the ride summary renders a PNG card to download or share. Strava's API cannot attach
photos, so add it by hand. If you set a public base URL in Settings (your own proxy or host), the
Strava description links the card.
Every FIT file is saved to ~/.justwatts/rides/ before any upload, and History can always export
.fit and .tcx.
Security model
The server binds 127.0.0.1 and rejects any non-localhost Host header (the only exception is
/share/<ride>.png when you set a public base URL). The page proves itself with its own Origin
plus an X-HW: 1 header; the CLI uses a bearer token from a 0600 file. Details in
docs/PROTOCOL.md.
Data and configuration
| Env | Default | |
|---|
JUSTWATTS_PORT | 8765 | server port |
JUSTWATTS_DATA | ~/.justwatts | settings, devices, rides, the ride in progress, logs, token, Strava tokens |
JUSTWATTS_GARMIN_TOKENS | ~/.garminconnect | Garmin session tokens |
JUSTWATTS_TOKEN | from <data>/token | API token for the CLI |
JUSTWATTS_GARMIN | auto | off disables Garmin, on forces it for a non-default data dir |
JUSTWATTS_BLE | on | off disables Bluetooth |
JUSTWATTS_STRAVA_RELAY | justwatts.com | Strava token service for the shared app; off allows only your own API app |
JUSTWATTS_STRAVA_CLIENT_ID | 168528 | Strava client ID used with that token service |
Older OPENSPIN_* and HW_* names still work. An existing ~/.openspin data dir keeps being used,
and older data dirs move to ~/.justwatts on first start.
Development
pip install -e ".[dev]"
pytest
Tests run the browser code under Node (node 18+ on PATH), boot the full page against a real test
server, drive BLE through a fake bleak module, mock Garmin and Strava, force Garmin and Bluetooth
off, and check that a full ride works with none of the optional extras installed.
Security
See SECURITY.md for the threat model and how to report a vulnerability.
License
MIT, see LICENSE. The vendored MapLibre GL JS 5.24.0 (app/vendor/, the 3D map) is BSD-3-Clause,
license next to it.
