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 | |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
