Sign inRegisterCheck connection

Weather Display ClientRaw Family Files

Reference for four Weather Display ClientRaw files: time grain, field groups, versioned maps, and encoding principles. Credit WD; not a full field dump.

Back to Personal weather station notebooks

Weather Display (WD) emits a family of four space-delimited text files so websites can show current weather, short history, and monthly daily slots without exposing the full logger database. This page is a field-reference pillar: what each file is for, how time grain differs, how field maps must be versioned, and how representative groups (temperature, wind, rain, extra sensors) are encoded. It is not a reprint of a two-thousand-line recovered field list. For parse mechanics, use the ClientRaw reading tutorial. For a diagnostic viewer article, see /wd-parser.php.

Credit: ClientRaw is a Weather Display format originated by Brian Hamilton. The authoritative map for a running copy is the clientrawdescription.txt (and related description files) shipped with that WD build. Official site: weather-display.com.

Historical context

The historical TNET Weather notebooks maintained a large specification page aligned with WD 10.37-era builds (the recovered page was dated 5 July 2009 and cited version 10.37L build 20). That page listed on the order of 160 fields in clientraw.txt, about 730 in clientrawextra.txt, about 430 in clientrawdaily.txt, and about 422 in clientrawhour.txt. Those counts are historical evidence that the maps are long, optional-sensor-heavy, and version-sensitive. They are not a license to republish every label, and they will not match a newer WD build. Use them to understand structure, then version against the file you actually have.

The four files, by job and time grain

| File | Primary job | Time grain | Why it exists | |---|---|---|---| | clientraw.txt | Live snapshot plus a little context | Seconds to minutes; “now,” today extrema, a few hourly slots | Small enough to overwrite often for a dashboard | | clientrawextra.txt | Extended history and extra/record fields | Hourly series, additional sensors, longer memory | Keeps the live file from growing without bound | | clientrawdaily.txt | Month-to-date daily statistics | One slot per calendar day for several variables | Monthly table without parsing NOAA-style HTML | | clientrawhour.txt | Sub-hour strip chart | One slot per minute for the last 60 minutes | High-frequency traces (wind, and similar) without a database |

All four share encoding: spaces as delimiters, underscores in labels, typed slots, optional sensors that still occupy indexes, and often a trailing WD version token. They do not share field indexes. Position 4 in clientraw.txt is not position 4 in clientrawextra.txt.

Think in grains:

  • Now. Temperature, humidity, pressure, wind, rain totals, packet clock — clientraw.txt.
  • Recent hours. Parallel hourly arrays (wind, temperature, rain, direction) — mostly clientrawextra.txt, with a shorter echo inside the live file on some builds.
  • This month by day. Daily high/low temperature and related daily series — clientrawdaily.txt.
  • This hour by minute. Sixty-value rings — clientrawhour.txt (historical notes: WD updated this on a minute cadence / at a defined minute of the hour depending on setup; confirm in your build).

If you need a monthly climatological table with degree days in HTML form, that is a different WD product; see NOAA-format daily reports.

Encoding principles (the part that stays true)

1. Position is the API. There are no field names in the packet. The map is external. Change WD version, change the map.

2. Space is the delimiter. Labels that would contain spaces are emitted with underscores (Mesa_Arizona not Mesa Arizona). Decode underscores only on label-typed fields.

3. Native units are SI-leaning, not U.S. display units. Typical WD ClientRaw native types:

  • Temperature: Celsius
  • Rain: millimetres
  • Wind speed: knots
  • Pressure: hectopascals (hPa)
  • Direction: meteorological degrees 0–360
  • Humidity: percent
  • Some height fields: feet (cloud-base estimates are a notable exception to SI)

Convert at the display edge. Conversion factors and compass binning are a separate metrology problem. Apparent temperature, humidex, heat index, and wind chill in the packet are derived indexes, not extra thermometers.

4. Optional sensors keep their slots. Extra temperature 1–8, extra humidity, soil, leaf, UV, solar, lightning: unused sensors are still present, often as zero or a placeholder. Collapsing them would shift every later index. Do not “helpfully” drop unused columns.

5. Enumerations are vendor icons, not WMO weather codes. Forecast-icon integers in ClientRaw are WD’s own table (clear, rain, thunder, and so on). They are not METAR present-weather codes and not NWS warning types. Map them through WD’s icon list for that build.

6. Time is fragmented and locale-dependent. Hour, minute, second, day, month, year may be separate fields whose formatting depends on WD settings. Assemble a timestamp, then test freshness (tutorial).

7. A trailing version token versions the map. Later packets end with a WD marker (the 10.37-era documentation used a !!…!! style tag). Store that token with every parse. A map without a version is a guess.

8. Header first, weather second. A leading label identifies the packet. If it is missing, you may be parsing an error page.

Representative field groups

The following groups appear across the family. Examples use the kind of quantity, not a copied 160-row dump.

Temperature and moisture

Live file: outdoor temperature, indoor temperature, humidity, dew point, wet bulb, and today’s maximum/minimum temperature. Extra file: hourly temperature arrays. Daily file: daily high and low temperature for day-of-month 1–31 (and often additional months’ worth of slots depending on build). These are observed or logger-calculated moisture variables. Heat index, wind chill, humidex, and “apparent temperature” travel with this group in the live file on many builds; treat them as indexes with validity limits, not as extra sensors.

Wind

Live file: average speed, gust, direction, 10-minute average, maximum gust, and sometimes a short hourly wind-speed echo for sparkline charts. Extra file: longer hourly wind-speed (and often direction) arrays. Hour file: a 60-minute ring of speed (and, on many builds, related wind quantities). Native speed is knots. Direction is degrees, not a compass string; labels are a display encoding.

Rain and pressure

Live file: daily, monthly, and yearly rain, rain rate, yesterday rain, barometer, barometer trend, max/min barometer. Extra and daily files extend rain into hourly or daily slots. WD may also expose 9 a.m. versus midnight rain resets as separate totals. Those two totals are not interchangeable; they encode different hydrological days.

Pressure is hPa. Inches of mercury is a conversion.

Extra sensors and energy

Optional extra temperature and humidity channels, soil temperature and moisture, leaf wetness, solar radiation, UV, indoor extrema. Hardware-specific blocks (for example Davis VP or WMR-series battery and extra channels) exist because WD supports many loggers. If you do not have the hardware, still parse the slots; do not display them as live.

Lightning and other event counters

Counts, time of last strike, vendor-specific distance/bearing fields. These are logger/processor outputs. They are not NWS warnings.

Identity and geography

Station-name label, latitude, longitude, packet date. Latitude/longitude sign conventions in old maps were easy to invert; verify with a known location before you plot.

How field maps must be versioned

A usable map is a tuple:

map_id = (filename, wd_version_token, field_count, native_units, generated_date)

Rules:

  1. Key by filename. Four maps, not one.
  2. Key by version token and by field_count. If either disagrees, refuse to decode or decode only a documented prefix you have tested.
  3. Record the date you built the map. WD adds fields at the end more often than in the middle, but “more often” is not a contract.
  4. Keep a fixture packet (a saved file from a known day) and a checksum of expected typed values. When you upgrade WD, rerun the fixture.
  5. Never interpolate missing indexes. If extra temperature 5 is unused, it is still index N.
  6. Publish the map version on the dashboard footer. “Parsed as WD 10.37L / 160 fields” is a quality statement. “Temperature: 72” without a map version is not.

The 2009 TNET counts (about 160 / 730 / 430 / 422) are one snapshot. A modern WD install may be longer. Treat any HTML table that claims to be “the” ClientRaw spec as stale until it matches clientrawdescription.txt on disk.

Process: using the family together

  1. Identify the four paths on the web host (names can be customized; default names are the ones in the table above).
  2. Parse each file with its own map (tutorial).
  3. Prefer clientraw.txt for “now.” Prefer clientrawhour.txt for the last hour’s shape. Prefer clientrawdaily.txt for a month grid. Use clientrawextra.txt for hourly history and extra sensors.
  4. If the same quantity appears in two files, define a precedence (usually: live file for current value, extra/hour for series). Do not average them.
  5. Convert units once, at display.
  6. Flag stale clocks independently per file. It is possible for the live file to update while the hour file is stuck.

Output

A station ingest pipeline should expose:

  • Four typed objects, each with map_id and age
  • A current-conditions view from the live file
  • Series views explicitly labeled by grain (minute, hour, day)
  • A human-readable disclaimer that values are from Weather Display at this station, not from NWS

Troubleshooting

Hourly charts look like daily charts. You plotted clientrawdaily.txt on an hour axis.

Wind direction is a temperature. Wrong file map.

Field count is 161 instead of 160. New build. Do not assume the extra token is “just” a version tag without checking; count and trailing token.

Extra sensors show 0°C. Distinguish missing hardware from freezing soil. Metadata (sensor present?) lives in WD configuration, not always in the packet.

Underscores in the station name. Encoding rule, not a fault.

You need a full printed dictionary. Open WD’s description file for your build. This article will not grow into a mirror of that file.

Modern relevance

Versioned, delimited observation files are a general data-source problem: freshness, native units, and schema drift. TNET’s public discussion of source quality and provenance is data sources and methodology. That page does not list ClientRaw indexes, and this page does not describe TNET’s forecast assembly.

Related: how to parse ClientRaw, WD NOAA-style HTML, notebooks hub.

Sources

  • Weather Display (Brian Hamilton). Software, manuals, and description files: weather-display.com. Community documentation hubs such as Weather-Watch discuss clientrawdescription.txt as the on-disk specification; the installation copy matches the running build.
  • Historical TNET notebook at this URL (Wayback recovery): WD 10.37L build 20 field counts dated 5 July 2009 — used here only as evidence of family structure and of the need to version maps.
  • Parse tutorial: /nb-0004.php. Diagnostic viewer article: /wd-parser.php.