tempest — Hyper-local weather from your Tempest station
Drive a WeatherFlow Tempest station from the terminal. Two transports, both
first-class: the documented REST API (swd.weatherflow.com/swd/rest,
personal-use token) for conditions, forecast, and history — officially the
primary data source — and the hub's unauthenticated UDP broadcast on port
50222 for real-time, lowest-latency readings on your LAN. The bundled CLI
decodes the positional observation arrays and every UDP message family, keeps
--json output metric-native, and converts units only for human display.
Setup
- Create a personal access token: sign in to the Tempest web app
(tempestwx.com), then Settings → Data Authorizations → Create Token.
(This is the documented non-graphical auth method; OAuth exists for web
apps but is not what a CLI uses.)
- Export it:
export TEMPEST_TOKEN="<YOUR_TOKEN>"
The token travels to the API as a query parameter (?token=...) per the
official docs — the CLI handles this. If the env var is not set, the CLI
falls back to reading TEMPEST_TOKEN= from ~/.tempest.env (handy for agent
subprocesses that skip shell profiles). --help and --dry-run never need a
token. UDP listening never needs one either — the hub broadcast is
unauthenticated and LAN-only.
Essential Commands
stations — discover your stations and devices
tempest stations # names, station ids, device types, serials
tempest stations --json | jq '.stations[] | {station_id, name,
devices: [.devices[] | {device_id, device_type, serial_number}]}'
Every station response nests a devices array: device_type is ST (the
Tempest all-in-one), AR/AIR, SK/SKY, or HB (the hub — it has no
observations; always filter it out before querying observations). Run this
first when you don't know your ids.
current — latest conditions
tempest current # human-readable, converted
tempest current --json # metric-native, jq-ready
tempest current --station-id 12799 --device-id 60526 # pin exact hardware
With one station it auto-selects and picks the best sensor (ST, then
SKY/SK, then AIR/AR, skipping HB). Output .observation carries the
decoded positional array as named fields with _unit companions.
forecast — current conditions + daily + hourly
tempest forecast # current + 5-day daily + next 12 hours
tempest forecast --days 7 --json
tempest forecast --station-id 12799 --days 3
The better_forecast response nests daily/hourly under a forecast wrapper
key, and it is unit-selectable (units_temp=c|f and friends, default metric)
— the CLI reads the response's units before converting anything.
obs — historical observations
tempest obs --device-id 60526 --days 1 # last UTC day (day_offset)
tempest obs --device-id 60526 --days 7
tempest obs --device-id 60526 --json
--days N maps to the API's day_offset (whole UTC days). The underlying
endpoint also accepts time_start/time_end epoch ranges (one-minute
resolution guaranteed up to 5 days) — use raw calls for those; see
references/rest-api-and-auth.md.
UDP broadcasts from your hub (port 50222, listen-only)
tempest udp listen # live stream until Ctrl-C
tempest udp listen --timeout 30 # auto-stop after 30s
tempest udp listen --timeout 60 --json # one JSON object per datagram
tempest udp listen --show-all # include hub_status/device_status
Requires being on the same LAN as the hub (routed connectivity is not enough
— broadcasts don't cross routers). No token involved. The listener decodes
every message family, dispatching on type before touching array positions:
| Family |
Payload shape |
Decoded fields |
obs_st / obs_air / obs_sky |
list of report rows under obs |
named observation fields |
rapid_wind |
ONE 3-element array under ob |
wind_speed_mps, wind_direction |
evt_precip |
ONE array under evt |
timestamp (rain started) |
evt_strike |
ONE array under evt |
distance_km, energy |
hub_status, device_status |
named fields, no array |
uptime, rssi, seq, voltage, sensor_status |
Multi-step pipeline recipes
Discover, then observe
# Stage 1 -> stage 2: stations --json emits integer ids that current consumes
tempest stations --json | jq -r '.stations[].devices[]
| select(.device_type == "ST") | .device_id' | head -1
tempest current --device-id <DEVICE_ID> --json
Rain watch: yesterday's total, then live rain events
tempest obs --device-id 60526 --days 1 --json \
| jq '{samples: (.observations | length),
day_rain_mm: .observations[-1].local_day_rain_accumulation}'
tempest udp listen --timeout 600 --json | jq 'select(.type == "evt_precip")'
obs --json ends with decoded observations carrying
local_day_rain_accumulation (mm, number); evt_precip datagrams decode to
{type, serial_number, timestamp} — both stages emit typed fields the next
stage can consume.
Unit-aware forecast slice
tempest forecast --days 7 --json \
| jq '{units_temp: .forecast.units.units_temp,
highs_f: [.forecast.forecast.daily[] | .air_temp_high * 9 / 5 + 32],
rain_hours: [.forecast.forecast.hourly[]
| select(.precip_probability > 30) | .local_hour]}'
The jq math here is safe only because it checks units_temp first — see
gotcha 2.
JSON output and jq processing
--json output is metric-native — the raw wire units (m/s wind, mm rain,
°C temperature, MB pressure) with _unit companion fields naming each.
Convert at the consumption edge:
tempest current --json | jq '{temp_c: .observation.air_temperature,
temp_f: (.observation.air_temperature * 9 / 5 + 32),
wind_mph: (.observation.wind_avg * 2.237),
rain_in: (.observation.rain_accumulation / 25.4)}'
Global flags work in any position: tempest --json current --device-id 60526
and tempest current --device-id 60526 --json are identical. --quiet
silences the progress logs (data on stdout, logs on stderr).
--dry-run prints a plan object and exits 0 without touching the network.
Known Gotchas
- Observations are positional arrays, not objects. Raw
obs rows have
no field names; meaning comes from the index (obs_st: 0 epoch, 2 wind avg
m/s, 4 wind direction, 6 pressure MB, 7 temperature °C, 12 rain mm, 16
battery V, 17 report interval). Reading index 6 as temperature gives you a
plausible-looking wrong number — decode with the CLI or the layout tables
in references/observation-layouts-and-units.md.
/better_forecast is unit-selectable, not Celsius-locked. It defaults
to metric but honors units_temp=f, units_wind=mph, units_pressure=inhg,
units_precip=in. It reports what it used in response.units. Converting
an already-Fahrenheit response doubles it (25.4 °C → 77.7 °F → 172 "°F").
Always read units before converting; the CLI does this for you.
- UDP message families differ structurally — dispatch on
type first.
obs families nest rows under obs; rapid_wind carries one array under
ob; evt_precip/evt_strike carry one array under evt;
hub_status/device_status carry named fields with no payload array.
Iterating rapid_wind's ob element-wise is the classic TypeError; the
bundled decode_message() shows the correct dispatch.
- UDP obs_st rows stop at index 17; REST rows run to 21. The four
Nearcast/analysis fields (18–21) exist only in REST responses. Decoders
must tolerate both lengths — the CLI emits
None for missing tails.
- Pressure is MB (millibars), numerically hPa — not kPa. It is also
station pressure (raw sensor). The Tempest app's "relative pressure"
adds an elevation adjustment; don't compare raw station pressure against
the app and conclude the sensor drifted.
- Forecast timestamps are epoch integers, never ISO strings.
day_start_local, sunrise, sunset, hourly time are epoch seconds;
hourly objects carry local_hour (0–23) and local_day (day of month).
There is no local_time or time_string field — code expecting one
silently falls back to its default branch.
- The forecast nests under a
forecast wrapper key. data["daily"] is
always empty; read data["forecast"]["daily"] and
data["forecast"]["hourly"] (the CLI's --json preserves the full
response, wrapper and all).
- Hubs (
HB) have no observations. They only relay. Auto-selection
skips them; if you call the API directly, filter device_type == "HB"
out before hitting /observations/device/{id} (documented 404 otherwise).
- UDP is LAN-only and unauthenticated. Broadcasts don't cross routers
and can't be token-gated — anyone on the network can read your station.
WeatherFlow officially positions REST/WebSocket as primary and UDP as the
off-grid/backup interface.
obs_sky UDP day-rain is always null. Local-day rain accumulation
(index 11) is null in UDP SKY broadcasts; REST supplies the real value.
Don't build day-rain totals from UDP SKY rows.
When to use
- The user owns or manages a WeatherFlow Tempest / Air / Sky station and asks
about its readings, forecast, or history.
- Parsing or integrating with the hub's local UDP broadcast (port 50222).
- Rain/wind/lightning monitoring scripts, dashboards, or home-automation
hooks fed from the station.
When not to use
- Generic city forecasts or users without a station — every endpoint
requires the user's own Tempest station and a personal-use token; use a
public weather service instead.
- Shakespeare's play The Tempest, or any literary/meteorological-theory
question — this is a station-data CLI, not an encyclopedia.
- Other vendors' hardware (Netatmo, Ecowitt, Davis, Ambient) — different
APIs entirely; no endpoint here will accept their devices.
- Commercial/network-wide data products — those need WeatherFlow's
TempestONE agreements, not a personal token (see the remote developer
policy).
Reference Files
| File |
Read when |
| references/rest-api-and-auth.md |
Working with REST endpoints directly: token auth, StationSet shapes, observation parameters, forecast units, error signatures |
| references/udp-broadcast-protocol.md |
Parsing raw UDP datagrams: port 50222 transport, every message family's layout, the type-dispatch rule |
| references/observation-layouts-and-units.md |
Decoding positional observation arrays by index (obs_st/obs_air/obs_sky, UDP vs REST lengths) and unit conversion tables |
| references/cli-worked-recipes.md |
Copy-paste multi-step CLI recipes with jq stages, dry-run plans, and expected error paths |
Available Scripts
- scripts/tempest — the CLI:
stations, current, obs,
forecast, udp listen; global --json, --dry-run, --quiet,
--verbose accepted in any position; offline dry-run plans for every
command.
- scripts/test_tempest.py — offline suite: canned
UDP datagram bytes fed to the decoder (no sockets), mocked REST transport,
both pytest and unittest runners.
Prerequisites
- Python 3.8+ with
requests (the only dependency).
TEMPEST_TOKEN for REST commands (free, personal use; created in the
Tempest web app). UDP listening needs no token, only line-of-sight to the
hub's LAN.
1---2name: tempest3description: >-4 Query hyper-local weather from a WeatherFlow Tempest station over its REST5 API and the hub's local UDP broadcast: current conditions, forecast,6 historical observations, and real-time decoded datagrams (obs_st,7 rapid_wind, evt_precip, evt_strike, hub_status). Use when the user asks8 about weather, temperature, rain, wind, humidity, or forecast data from9 their own Tempest/WeatherFlow station, or wants to parse the hub's UDP port10 50222 broadcast. Do not use this skill for generic or city forecasts11 without a Tempest station (public weather services serve those), for12 Shakespeare's play The Tempest or other literature questions, or for13 weather hardware from other vendors - the REST endpoints require a14 personal-use token and the UDP broadcast only exists on a Tempest hub's15 LAN.16license: MIT17compatibility: >-18 Requires TEMPEST_TOKEN env var for REST (create it in the Tempest web app19 under Settings -> Data Authorizations), Python 3.8+, and `requests`. UDP20 listening needs a Tempest hub on the LAN and no token. `--help` and21 `--dry-run` work without credentials.22metadata:23 source: https://skillmd.com/skills/magnus919/tempest24 tags: weather, tempest, weatherflow, forecast, station, udp, hyper-local25 sources: https://apidocs.tempestwx.com/reference/quick-start, https://weatherflow.github.io/Tempest/api/udp/v171/26---2728# tempest — Hyper-local weather from your Tempest station2930Drive a WeatherFlow Tempest station from the terminal. Two transports, both31first-class: the documented REST API (`swd.weatherflow.com/swd/rest`,32personal-use token) for conditions, forecast, and history — officially the33primary data source — and the hub's unauthenticated UDP broadcast on port3450222 for real-time, lowest-latency readings on your LAN. The bundled CLI35decodes the positional observation arrays and every UDP message family, keeps36`--json` output metric-native, and converts units only for human display.3738## Setup39401. Create a personal access token: sign in to the Tempest web app41 (tempestwx.com), then **Settings → Data Authorizations → Create Token**.42 (This is the documented non-graphical auth method; OAuth exists for web43 apps but is not what a CLI uses.)442. Export it:4546```bash47export TEMPEST_TOKEN="<YOUR_TOKEN>"48```4950The token travels to the API as a **query parameter** (`?token=...`) per the51official docs — the CLI handles this. If the env var is not set, the CLI52falls back to reading `TEMPEST_TOKEN=` from `~/.tempest.env` (handy for agent53subprocesses that skip shell profiles). `--help` and `--dry-run` never need a54token. UDP listening never needs one either — the hub broadcast is55unauthenticated and LAN-only.5657## Essential Commands5859### stations — discover your stations and devices6061```bash62tempest stations # names, station ids, device types, serials63tempest stations --json | jq '.stations[] | {station_id, name,64 devices: [.devices[] | {device_id, device_type, serial_number}]}'65```6667Every station response nests a `devices` array: `device_type` is `ST` (the68Tempest all-in-one), `AR`/`AIR`, `SK`/`SKY`, or `HB` (the hub — it has **no**69observations; always filter it out before querying observations). Run this70first when you don't know your ids.7172### current — latest conditions7374```bash75tempest current # human-readable, converted76tempest current --json # metric-native, jq-ready77tempest current --station-id 12799 --device-id 60526 # pin exact hardware78```7980With one station it auto-selects and picks the best sensor (`ST`, then81`SKY`/`SK`, then `AIR`/`AR`, skipping `HB`). Output `.observation` carries the82decoded positional array as named fields with `_unit` companions.8384### forecast — current conditions + daily + hourly8586```bash87tempest forecast # current + 5-day daily + next 12 hours88tempest forecast --days 7 --json89tempest forecast --station-id 12799 --days 390```9192The `better_forecast` response nests daily/hourly under a `forecast` wrapper93key, and it is unit-selectable (`units_temp=c|f` and friends, default metric)94— the CLI reads the response's `units` before converting anything.9596### obs — historical observations9798```bash99tempest obs --device-id 60526 --days 1 # last UTC day (day_offset)100tempest obs --device-id 60526 --days 7101tempest obs --device-id 60526 --json102```103104`--days N` maps to the API's `day_offset` (whole UTC days). The underlying105endpoint also accepts `time_start`/`time_end` epoch ranges (one-minute106resolution guaranteed up to 5 days) — use raw calls for those; see107references/rest-api-and-auth.md.108109## UDP broadcasts from your hub (port 50222, listen-only)110111```bash112tempest udp listen # live stream until Ctrl-C113tempest udp listen --timeout 30 # auto-stop after 30s114tempest udp listen --timeout 60 --json # one JSON object per datagram115tempest udp listen --show-all # include hub_status/device_status116```117118Requires being on the same LAN as the hub (routed connectivity is not enough119— broadcasts don't cross routers). No token involved. The listener decodes120every message family, dispatching on `type` before touching array positions:121122| Family | Payload shape | Decoded fields |123|---|---|---|124| `obs_st` / `obs_air` / `obs_sky` | list of report rows under `obs` | named observation fields |125| `rapid_wind` | ONE 3-element array under `ob` | wind_speed_mps, wind_direction |126| `evt_precip` | ONE array under `evt` | timestamp (rain started) |127| `evt_strike` | ONE array under `evt` | distance_km, energy |128| `hub_status`, `device_status` | named fields, no array | uptime, rssi, seq, voltage, sensor_status |129130## Multi-step pipeline recipes131132### Discover, then observe133134```bash135# Stage 1 -> stage 2: stations --json emits integer ids that current consumes136tempest stations --json | jq -r '.stations[].devices[]137 | select(.device_type == "ST") | .device_id' | head -1138tempest current --device-id <DEVICE_ID> --json139```140141### Rain watch: yesterday's total, then live rain events142143```bash144tempest obs --device-id 60526 --days 1 --json \145 | jq '{samples: (.observations | length),146 day_rain_mm: .observations[-1].local_day_rain_accumulation}'147tempest udp listen --timeout 600 --json | jq 'select(.type == "evt_precip")'148```149150`obs --json` ends with decoded observations carrying151`local_day_rain_accumulation` (mm, number); `evt_precip` datagrams decode to152`{type, serial_number, timestamp}` — both stages emit typed fields the next153stage can consume.154155### Unit-aware forecast slice156157```bash158tempest forecast --days 7 --json \159 | jq '{units_temp: .forecast.units.units_temp,160 highs_f: [.forecast.forecast.daily[] | .air_temp_high * 9 / 5 + 32],161 rain_hours: [.forecast.forecast.hourly[]162 | select(.precip_probability > 30) | .local_hour]}'163```164165The jq math here is safe **only because** it checks `units_temp` first — see166gotcha 2.167168## JSON output and jq processing169170`--json` output is **metric-native** — the raw wire units (m/s wind, mm rain,171°C temperature, MB pressure) with `_unit` companion fields naming each.172Convert at the consumption edge:173174```bash175tempest current --json | jq '{temp_c: .observation.air_temperature,176 temp_f: (.observation.air_temperature * 9 / 5 + 32),177 wind_mph: (.observation.wind_avg * 2.237),178 rain_in: (.observation.rain_accumulation / 25.4)}'179```180181Global flags work in any position: `tempest --json current --device-id 60526`182and `tempest current --device-id 60526 --json` are identical. `--quiet`183silences the progress logs (data on stdout, logs on stderr).184`--dry-run` prints a plan object and exits 0 without touching the network.185186## Known Gotchas1871881. **Observations are positional arrays, not objects.** Raw `obs` rows have189 no field names; meaning comes from the index (obs_st: 0 epoch, 2 wind avg190 m/s, 4 wind direction, 6 pressure MB, 7 temperature °C, 12 rain mm, 16191 battery V, 17 report interval). Reading index 6 as temperature gives you a192 plausible-looking wrong number — decode with the CLI or the layout tables193 in references/observation-layouts-and-units.md.1942. **`/better_forecast` is unit-selectable, not Celsius-locked.** It defaults195 to metric but honors `units_temp=f`, `units_wind=mph`, `units_pressure=inhg`,196 `units_precip=in`. It reports what it used in `response.units`. Converting197 an already-Fahrenheit response doubles it (25.4 °C → 77.7 °F → 172 "°F").198 Always read `units` before converting; the CLI does this for you.1993. **UDP message families differ structurally — dispatch on `type` first.**200 obs families nest rows under `obs`; `rapid_wind` carries one array under201 `ob`; `evt_precip`/`evt_strike` carry one array under `evt`;202 `hub_status`/`device_status` carry named fields with no payload array.203 Iterating `rapid_wind`'s `ob` element-wise is the classic TypeError; the204 bundled `decode_message()` shows the correct dispatch.2054. **UDP obs_st rows stop at index 17; REST rows run to 21.** The four206 Nearcast/analysis fields (18–21) exist only in REST responses. Decoders207 must tolerate both lengths — the CLI emits `None` for missing tails.2085. **Pressure is MB (millibars), numerically hPa — not kPa.** It is also209 *station* pressure (raw sensor). The Tempest app's "relative pressure"210 adds an elevation adjustment; don't compare raw station pressure against211 the app and conclude the sensor drifted.2126. **Forecast timestamps are epoch integers, never ISO strings.**213 `day_start_local`, `sunrise`, `sunset`, hourly `time` are epoch seconds;214 hourly objects carry `local_hour` (0–23) and `local_day` (day of month).215 There is **no** `local_time` or `time_string` field — code expecting one216 silently falls back to its default branch.2177. **The forecast nests under a `forecast` wrapper key.** `data["daily"]` is218 always empty; read `data["forecast"]["daily"]` and219 `data["forecast"]["hourly"]` (the CLI's `--json` preserves the full220 response, wrapper and all).2218. **Hubs (`HB`) have no observations.** They only relay. Auto-selection222 skips them; if you call the API directly, filter `device_type == "HB"`223 out before hitting `/observations/device/{id}` (documented 404 otherwise).2249. **UDP is LAN-only and unauthenticated.** Broadcasts don't cross routers225 and can't be token-gated — anyone on the network can read your station.226 WeatherFlow officially positions REST/WebSocket as primary and UDP as the227 off-grid/backup interface.22810. **`obs_sky` UDP day-rain is always null.** Local-day rain accumulation229 (index 11) is `null` in UDP SKY broadcasts; REST supplies the real value.230 Don't build day-rain totals from UDP SKY rows.231232## When to use233234- The user owns or manages a WeatherFlow Tempest / Air / Sky station and asks235 about its readings, forecast, or history.236- Parsing or integrating with the hub's local UDP broadcast (port 50222).237- Rain/wind/lightning monitoring scripts, dashboards, or home-automation238 hooks fed from the station.239240## When not to use241242- **Generic city forecasts or users without a station** — every endpoint243 requires the user's own Tempest station and a personal-use token; use a244 public weather service instead.245- **Shakespeare's play *The Tempest*, or any literary/meteorological-theory246 question** — this is a station-data CLI, not an encyclopedia.247- **Other vendors' hardware** (Netatmo, Ecowitt, Davis, Ambient) — different248 APIs entirely; no endpoint here will accept their devices.249- **Commercial/network-wide data products** — those need WeatherFlow's250 TempestONE agreements, not a personal token (see the remote developer251 policy).252253## Reference Files254255| File | Read when |256|---|---|257| [references/rest-api-and-auth.md](references/rest-api-and-auth.md) | Working with REST endpoints directly: token auth, StationSet shapes, observation parameters, forecast units, error signatures |258| [references/udp-broadcast-protocol.md](references/udp-broadcast-protocol.md) | Parsing raw UDP datagrams: port 50222 transport, every message family's layout, the type-dispatch rule |259| [references/observation-layouts-and-units.md](references/observation-layouts-and-units.md) | Decoding positional observation arrays by index (obs_st/obs_air/obs_sky, UDP vs REST lengths) and unit conversion tables |260| [references/cli-worked-recipes.md](references/cli-worked-recipes.md) | Copy-paste multi-step CLI recipes with jq stages, dry-run plans, and expected error paths |261262## Available Scripts263264- [scripts/tempest](scripts/tempest) — the CLI: `stations`, `current`, `obs`,265 `forecast`, `udp listen`; global `--json`, `--dry-run`, `--quiet`,266 `--verbose` accepted in any position; offline dry-run plans for every267 command.268- [scripts/test_tempest.py](scripts/test_tempest.py) — offline suite: canned269 UDP datagram bytes fed to the decoder (no sockets), mocked REST transport,270 both pytest and unittest runners.271272## Prerequisites273274- Python 3.8+ with `requests` (the only dependency).275- `TEMPEST_TOKEN` for REST commands (free, personal use; created in the276 Tempest web app). UDP listening needs no token, only line-of-sight to the277 hub's LAN.