myWindsock

Why have we gone to an extraordinary effort modelling the wind for cycling?

myWindsock models on-road wind speed — estimating the wind a cyclist actually experiences.

So now you can...

Optimise power to the weather & terrain
Discover where time was lost or gained due to wind and hills
Train your aerodynamics on every ride

Extension developer guide

Start with an idea, then go as deep into the code as you want.

You do not need to be a programmer

Use Vibe Code to describe what you want in ordinary language. The editor lets you understand, adjust and test the result. Experienced developers can work directly in both files.

1. An extension has two files

extension.lua

Optional calculation and simulation logic. It reads model values, can publish results, and can change supported model inputs.

meta.json

The name, description, applicable modelling modes, user-adjustable parameters and declarative UI components.

A UI-only extension needs no calculation. Its Lua file can contain one comment while the UI binds directly to an existing stream.

2. A small working example

This publishes a Yes/No climbing status using an adjustable threshold.

extension.lua

export("guideClimbing", "status", "", "Climbing")

local threshold = tonumber(extensionParameters.climbThreshold) or 0.03
local validSlope = type(slope) == "number"
    and slope == slope
    and slope > -math.huge
    and slope < math.huge

guideClimbing = validSlope and slope >= threshold

meta.json

{
  "schemaVersion": 3,
  "name": "Climbing status",
  "description": "Shows when the route is climbing.",
  "modes": {
    "analysis": true,
    "prediction": true
  },
  "parameters": [{
    "key": "climbThreshold",
    "label": "Climb threshold",
    "description": "Decimal gradient; 0.03 means 3%.",
    "type": "number",
    "defaultValue": 0.03,
    "min": 0, "max": 0.3, "step": 0.005,
    "unit": "", "unitGroup": "",
    "refreshRequired": true,
    "options": []
  }],
  "ui": { "components": [] }
}

modes.analysis and modes.prediction state where the extension is relevant. Set either flag to false to keep its Lua and UI out of that mode. Missing or non-boolean flags default to true, so older extensions remain available in both modes.

Important: slope is decimal rise/run. 0.05 means 5%; 5 means 500%.

3. Add presentation without JavaScript

ui.components describes presentation using route streams, parameters or genuine Lua exports.

pointA marker or map label.

rangeA route section, overlay, route style or timeline swimlane.

mapLineA styled map line using coordinates from a stream.

chartOverlayA suggested series, reference line or value band.

widgetA suggested metric, status, progress display or table.

alertA notice or recommendation triggered by route data.

Use an existing stream directly when it already contains the value.
For markers, content.label is visible on the map and timeline; content.description appears in details.
Map lines accept a coordinate-pair stream through source.geometry, or separate numeric source.latitude and source.longitude bindings.
Chart and Data Panel items are suggestions which the user chooses to apply. They do not silently replace formatting.
Bindings use canonical stored values. A unit label never changes a number's scale.

Common streams and user units

Exact keys include distanceM, utcTimeSeconds, altitudeM, speedMs, powerWatts, slope, temperatureC, windSpeedMs, wPrimeBal and yaw. Map-line geometry may also bind to the decorator-runtime stream latlng_offset, which follows the displayed offset route and falls back to the original route when no offset is active. Do not invent stream names.

Templates can use selected units, for example {{occurrence.value|unit:distance}}. Groups are distance, altitude, speed, windSpeed and temperature.

Map-line decorator example

This metadata fragment describes presentation only. It follows the decorator-runtime latlng_offset coordinate stream and colours each segment from a numeric braking-severity stream; it does not define or request an extension which calculates braking severity.

{
  "id": "brakingLine",
  "type": "mapLine",
  "variant": "polyline",
  "source": {
    "mode": "binding",
    "geometry": { "source": "stream", "key": "latlng_offset" }
  },
  "appearance": {
    "color": "#22c55e",
    "colorBy": { "source": "stream", "key": "brakingSeverity" },
    "colorScale": [
      { "value": 0, "color": "#22c55e" },
      { "value": 0.5, "color": "#f59e0b" },
      { "value": 1, "color": "#7f1d1d" }
    ],
    "opacity": 0.9,
    "weight": 5,
    "lineStyle": "solid"
  },
  "placements": [{ "surface": "map", "mode": "line" }],
  "limits": { "maxPoints": 10000 }
}

source.geometry values may be [latitude, longitude] pairs or objects with lat and lng. Invalid points create a gap instead of joining unrelated positions. appearance.color is the fallback and fixed colour. When colorBy and colorScale are supplied, scale colours are linearly interpolated and applied per segment. Values outside the scale use its nearest end colour. Styling also supports opacity from 0 to 1, weight from 1 to 24, and lineStyle values solid, dashed or dotted.

4. Understand when Lua runs

The combined extension code runs before each route point is solved, often thousands of times per pass.

Current route inputs

distanceM, altitudeM, slope and distanceChange describe the point about to be solved.

Previous solved state

elapsedS, stepS, speedMs, airSpeedMs, temperatureC, humidity, precipitationProbability and precipitationIntensity come from the previous state. Current-point speed is not yet available.

An extension may calculate its own theoretical or estimated current-point value from the available inputs. Keep the calculation lightweight and bounded, explain important assumptions, and do not present the estimate as the main solver's actual current-point result.

routeContext provides bounded, static terrain and major-corner summaries calculated before modelling. Use routeIdx, currentTerrainSegmentNumber, nextCornerNumber and distanceToNextCornerM for efficient per-point access. Route indexes are zero-based, context arrays are one-based Lua arrays, and each endIdxExclusive is the first point outside its range. A corner remains next at its apex and advances on the following point; a corner number of 0 and distance of -1 mean none remains.

Each analysis or prediction starts clean. Globals persist between points during that pass; top-level local values are recreated every call. Prefix persistent globals because active extensions share the container.

5. Read, change and export values

Read supplied values

Examples include slope, power, cda, massKg, airDensity, criticalPower and wPrimeBal.

Change supported inputs

The model reads back power, cda, massKg, drivetrainEfficiency, crr, brakingForceN, wPrime, wPrimeTauMin, wPrimeTauRange and wPrimeTauSensitivity. Leave values unchanged outside the intended condition.

Export a new result

Declare it first with export(name, base, unit, displayLabel), then assign a finite number or boolean every call. The base is a UI group or category, never the source word stream.

6. Parameters and units

Parameters can be number, boolean or select.
Read them through extensionParameters.yourKey with a fallback matching the metadata default.
Use refreshRequired: true when a change reruns Lua or the model; use false only for presentation-only settings.
User-unit conversion expects canonical metres, metres per second or Celsius. Custom units use an empty unitGroup and remain labels only.

7. Keep hot-loop code safe and fast

Keep normal work constant-time.
Avoid growing arrays and route-length loops.
Guard missing values, division and invalid maths.
Give necessary loops a small fixed bound.

Never use a top-level return; it skips later extensions.
No external files, I/O or operating-system access.
Reuse supplied results, but use lightweight custom physics when the extension genuinely needs a theoretical value.
Check syntax before closing.

Before you finish

Check every parameter and export has a purpose.
Test active and inactive paths, zero values and the first route point.
Confirm units and timing describe the value honestly.
Close fullscreen to save the revision and refresh the model.

Welcome back

Optimum conditions coming up

Why have we gone to an extraordinary effort modelling the wind for cycling?

Connects to