tempest

tempest — Tempest ステーションから得られる地域密着型の天気情報

ターミナルから WeatherFlow Tempest ステーションを操作します。どちらの通信方式も主要な機能として利用できます。条件、予報、履歴には、公式に主要なデータソースとされている、ドキュメント化された REST API（swd.weatherflow.com/swd/rest、個人利用向けトークン）を使用できます。また、LAN 上でリアルタイムの最小遅延の観測値を取得するには、ハブからの認証不要な UDP ブロードキャスト（ポート 50222）を利用できます。付属の CLI は、位置ベースの観測値配列とすべての UDP メッセージ種別をデコードし、--json 出力ではメートル法の単位を維持し、人向けの表示に限って単位を変換します。

セットアップ

1. 個人用アクセストークンを作成します。Tempest Web アプリ （tempestwx.com）にサインインして、Settings → Data Authorizations → Create Token を選択します。 （これはドキュメントに記載されている、グラフィカルインターフェースを使わない認証方法です。Web アプリ向けの OAuth もありますが、CLI では使用しません。）
2. トークンをエクスポートします。

export TEMPEST_TOKEN="<YOUR_TOKEN>"

公式ドキュメントに従い、トークンは クエリパラメーター（?token=...）として API に送信されます。これは CLI が処理します。環境変数が設定されていない場合、CLI は ~/.tempest.env から TEMPEST_TOKEN= を読み取ります（シェルのプロファイルを読み込まないエージェントのサブプロセスに便利です）。--help と --dry-run ではトークンは不要です。UDP のリッスンにも不要です。ハブのブロードキャストは認証不要で、LAN 内でのみ利用できます。

基本的なコマンド

stations — ステーションとデバイスを検出する

tempest stations                       # names, station ids, device types, serials
tempest stations --json | jq '.stations[] | {station_id, name,
  devices: [.devices[] | {device_id, device_type, serial_number}]}'

各ステーションのレスポンスには、devices 配列が含まれています。device_type は ST（Tempest オールインワン）、AR／AIR、SK／SKY、または HB（ハブ。観測値は ありません。観測値を取得する前に、必ず対象から除外してください）です。ID がわからない場合は、まずこのコマンドを実行します。

current — 最新の気象条件

tempest current                                       # human-readable, converted
tempest current --json                                # metric-native, jq-ready
tempest current --station-id 12799 --device-id 60526  # pin exact hardware

ステーションが 1 台の場合は、自動的に選択して最適なセンサーを取得します（ST、次に SKY／SK、次に AIR／AR の順で、HB は除外します）。出力の .observation には、デコードされた位置ベースの配列が名前付きフィールドとして格納され、各フィールドに対応する _unit も含まれます。

forecast — 現在の気象条件、日別・時間別の予報

tempest forecast                       # current + 5-day daily + next 12 hours
tempest forecast --days 7 --json
tempest forecast --station-id 12799 --days 3

better_forecast のレスポンスでは、日別・時間別のデータは forecast ラッパーキーの下に格納され、単位を選択できます（units_temp=c|f など。デフォルトはメートル法です）。CLI は何かを変換する前に、レスポンスの units を確認します。

obs — 過去の観測値

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 は API の day_offset（UTC の整数日数）に対応します。基盤となるエンドポイントでは、エポック時刻の範囲を指定する time_start／time_end も利用できます（最大 5 日間、1 分間隔の精度が保証されます）。その場合は生の呼び出しを使用してください。詳細は references/rest-api-and-auth.md を参照してください。

ハブからの UDP ブロードキャスト（ポート 50222、受信専用）

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

ハブと同じ LAN 上にいる必要があります（ルーティングされた接続だけでは不十分です。ブロードキャストはルーターを越えません）。トークンは不要です。リスナーはすべてのメッセージ種別をデコードし、配列の位置にアクセスする前に type に基づいて処理を振り分けます。

種別	ペイロードの形式	デコードされるフィールド
obs_st / obs_air / obs_sky	obs 内のレポート行のリスト	名前付きの観測フィールド
rapid_wind	ob 内の 3 要素の配列 1 つ	wind_speed_mps、wind_direction
evt_precip	evt 内の配列 1 つ	timestamp（降雨開始時刻）
evt_strike	evt 内の配列 1 つ	distance_km、energy
hub_status、device_status	名前付きフィールド。配列なし	uptime、rssi、seq、voltage、sensor_status

複数ステップのパイプライン例

検出してから観測する

# 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

降雨の監視：昨日の合計値を確認してから、リアルタイムの降雨イベントを監視する

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 は、デコードされた観測値を含めて出力を終えます。観測値には local_day_rain_accumulation（mm、数値）が含まれます。evt_precip データグラムは {type, serial_number, timestamp} にデコードされます。どちらの段階も、次の段階で利用できる型付きフィールドを出力します。

単位を考慮した予報の一部取得

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]}'

ここでの jq の計算が安全なのは、units_temp を最初に確認している 場合に限ります。落とし穴 2 を参照してください。

JSON 出力と jq による処理

--json 出力はメトリック単位をネイティブに使用します。生の通信単位（風速は m/s、雨量は mm、気温は °C、気圧は MB）を使い、それぞれの単位を示す _unit フィールドが付属します。使用する際に変換してください。

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)}'

グローバルフラグはどの位置でも使用できます。tempest --json current --device-id 60526 と tempest current --device-id 60526 --json は同じ動作です。--quiet は進行状況ログを抑制します（データは stdout、ログは stderr に出力されます）。 --dry-run はプランオブジェクトを出力し、ネットワークに接続せずに終了コード 0 で終了します。

既知の注意点

1. 観測値はオブジェクトではなく、位置で識別する配列です。 生の obs 行にはフィールド名がなく、各インデックスで意味が決まります（obs_st：0 はエポック、2 は平均風速 m/s、4 は風向、6 は気圧 MB、7 は気温 °C、12 は雨量 mm、16 はバッテリー電圧 V、17 はレポート間隔）。インデックス 6 を気温として読むと、もっともらしく見える誤った数値になります。CLI、または references/observation-layouts-and-units.md のレイアウト表を使ってデコードしてください。
2. /better_forecast は単位を選択でき、摂氏に固定されているわけではありません。 デフォルトはメトリックですが、units_temp=f、units_wind=mph、units_pressure=inhg、units_precip=in が指定されていれば、それらに従います。使用した単位は response.units で報告されます。すでに華氏のレスポンスを変換すると、二重に変換されます（25.4 °C → 77.7 °F → 172 "°F"）。変換する前に必ず units を確認してください。CLI はこの処理を行います。
3. UDP のメッセージファミリーは構造が異なるため、まず type で振り分けてください。 obs ファミリーは行を obs の下にネストします。rapid_wind は ob の下に配列を 1 つ持ち、evt_precip／evt_strike は evt の下に配列を 1 つ持ちます。hub_status／device_status は名前付きフィールドを持ち、ペイロード配列はありません。rapid_wind の ob 要素を個別に反復処理すると TypeError が発生します。正しい振り分け方法は同梱の decode_message() を参照してください。
4. UDP の obs_st 行はインデックス 17 で終わりますが、REST の行はインデックス 21 まであります。 Nearcast／analysis の 4 つのフィールド（18～21）は REST レスポンスにのみ存在します。デコーダーはどちらの長さにも対応する必要があります。CLI は不足する末尾の値に None を出力します。
5. 気圧の単位は MB（ミリバール）で、数値上は hPa と同じです。kPa ではありません。 また、これは観測所の気圧（センサーの生値）です。Tempest アプリの「相対気圧」には標高補正が加わります。アプリの値と生の観測所気圧を比較して、センサーがドリフトしたと判断しないでください。
6. 予報のタイムスタンプは常にエポック秒の整数で、ISO 文字列ではありません。 day_start_local、sunrise、sunset、時間別の time はエポック秒です。時間別オブジェクトには local_hour（0～23）と local_day（月内の日付）が含まれます。local_time や time_string フィールドはありません。これらのフィールドを想定するコードは、気付かないままデフォルトの分岐に進みます。
7. 予報は forecast ラッパーキーの下にネストされています。 data["daily"] は常に空です。data["forecast"]["daily"] と data["forecast"]["hourly"] を読み取ってください（CLI の --json はラッパーを含むレスポンス全体を保持します）。
8. ハブ（HB）には観測値がありません。 ハブは中継のみを行います。自動選択ではハブを除外します。API を直接呼び出す場合は、/observations/device/{id} を呼び出す前に device_type == "HB" を除外してください（そうしないと 404 になることが説明されています）。
9. UDP は LAN 内のみで利用でき、認証もありません。 ブロードキャストはルーターを越えず、トークンでアクセス制限もできないため、ネットワーク上の誰もがステーションを読み取れます。WeatherFlow は REST／WebSocket を主要インターフェース、UDP をオフグリッド用またはバックアップ用のインターフェースとして公式に位置付けています。
10. obs_sky の UDP における当日雨量は常に null です。 現地日の雨量累積値（インデックス 11）は UDP SKY ブロードキャストでは null ですが、REST では実際の値が取得できます。UDP SKY の行から当日雨量の合計を算出しないでください。

使用する場面

• WeatherFlow Tempest／Air／Sky ステーションを所有または管理するユーザーから、観測値、予報、履歴について質問された場合。
• ハブのローカル UDP ブロードキャスト（ポート 50222）を解析または統合する場合。
• ステーションのデータを使う、雨量・風・落雷の監視スクリプト、ダッシュボード、ホームオートメーション用フックの場合。

使用しない場合

• 一般的な都市の天気予報や、ステーションを持っていないユーザー — すべてのエンドポイントで、ユーザー自身の Tempest ステーションと個人利用トークンが必要です。代わりに一般公開の気象サービスを使用してください。
• シェイクスピアの戯曲『テンペスト』、または文学・気象理論に関する質問 — これはステーションデータ用の CLI であり、百科事典ではありません。
• 他社製のハードウェア（Netatmo、Ecowitt、Davis、Ambient） — API がまったく異なるため、ここにあるエンドポイントではこれらのデバイスを受け付けません。
• 商用またはネットワーク全体向けのデータ製品 — これらには個人用トークンではなく、WeatherFlow の TempestONE 契約が必要です（リモート開発者ポリシーを参照）。

リファレンスファイル

ファイル	読むタイミング
references/rest-api-and-auth.md	REST エンドポイントを直接操作する場合：トークン認証、StationSet の形式、観測パラメーター、予報の単位、エラーのパターン
references/udp-broadcast-protocol.md	生の UDP データグラムを解析する場合：ポート 50222 のトランスポート、各メッセージファミリーの構造、型の振り分けルール
references/observation-layouts-and-units.md	インデックスによる位置ベースの観測配列（obs_st／obs_air／obs_sky、UDP と REST の長さ）と単位変換表をデコードする場合
references/cli-worked-recipes.md	jq の処理段階、ドライラン計画、想定されるエラー経路を含む、コピーして使える複数手順の CLI レシピが必要な場合

利用可能なスクリプト

• scripts/tempest — CLI：stations、current、obs、 forecast、udp listen。グローバルオプション --json、--dry-run、--quiet、 --verbose は任意の位置で指定できます。すべてのコマンドでオフラインのドライラン計画を利用できます。
• scripts/test_tempest.py — オフラインテストスイート：デコーダーに渡す UDP データグラムのバイト列（ソケット不要）、モック化された REST トランスポート。pytest と unittest の両方で実行できます。

前提条件

• requests（唯一の依存関係）を含む Python 3.8 以降。
• REST コマンドには TEMPEST_TOKEN が必要です（無料の個人利用向け。Tempest ウェブアプリで作成します）。UDP のリスニングにはトークンは不要で、ハブの LAN を見通せることのみ必要です。