Skip to main content

NDBC buoys smart home integration, free and open source

NDBC buoys integration for Gladys Assistant

Unofficial. NOAA buoys and coastal stations: waves, wind, water and air temperature.

View on GitHubAll integrations

Unofficial integration: the observations of the buoys and coastal stations of the National Data Buoy Center (NDBC, NOAA) in Gladys: waves, wind, water and air temperature, pressure. The NDBC covers the US coasts, the Great Lakes, the Gulf of Mexico, Hawaii, Alaska and the Pacific, and relays a few Canadian buoys (Environment and Climate Change Canada).

The data comes from the public realtime files of the NDBC (no account, no key): US government data in the public domain (source: NOAA National Data Buoy Center), except the stations of partners that the NDBC relays, which keep their owner's terms (for example the buoys of Environment and Climate Change Canada, under the Open Government Licence – Canada; the owner is on the NDBC page of each station). This integration is not an official source, and not for navigation: check the NDBC and the official marine forecasts before going out on the water. It has never been tested on a real Gladys installation by its author; it was tested against the live NDBC files.

What you get​

One device per station, named "NDBC buoy 46026" (rename it as you like in Gladys). Every device has the same 14 features; a variable the station does not measure never gets a value (a coastal C-MAN station has no waves, many buoys have no visibility nor tide):

FeatureColumnUnit
Wind direction (degrees, where the wind comes from)WDIR0 to 360 (no unit in Gladys)
Wind speed, wind gustWSPD, GSTm/s
Significant wave heightWVHTm
Dominant wave period, average wave periodDPD, APDs
Wave direction (degrees, where the waves come from)MWD0 to 360 (no unit in Gladys)
Sea level pressure, pressure tendency over 3 hPRES, PTDYhPa
Air temperatureATMP°C
Water temperature, dew pointWTMP, DEWP°C (type "probe": kept out of the room average)
VisibilityVISkm (from nautical miles, 1 nmi = 1.852 km)
Water level (tide)TIDEm (from feet, 1 ft = 0.3048 m)

What is published, and when:

  • each feature gets the newest value of its column among the lines read (a buoy often reports the wind every 10 minutes and the waves every 30 or 60 minutes: each one has its own time);
  • a value is published only if its observation is less than 2 hours old, the age being taken against the time of the NDBC server (its Date header, plus its Age when the answer is a copy kept by the CDN), never against the clock of your Gladys;
  • each observation is published once: the time of the last one published for each feature is kept in /data, so neither the next read, nor a restart, publishes it again; an older observation is never published after a newer one;
  • MM in a file means missing: nothing is published, never 0. A value outside the plausible range of its variable (or a "9" fill value: 99, 999, 9999), or a wave period of 0 s, is not a measure either;
  • a device created after a read gets right away the values of that read still under 2 hours old;
  • in the history of Gladys, a value is dated when it is published, not when it was observed (up to about an hour later for an hourly station): the time of the observation is in the status.

Configuration​

  • Station ids: up to 10 ids of 4 or 5 letters or digits (as 46026, 44025, PSBM1, or KATP for an oil platform of the Gulf of Mexico), separated by commas. Find them on the NDBC map (https://www.ndbc.noaa.gov/). An entry that is not an id is left out and named in the status; past 10, the first 10 are read.
  • Language of the names: English or French, for the names proposed in Discovery.
  • Read interval: from 10 to 180 minutes, 30 by default.

After saving, open Discovery to create the devices.

Pace and courtesy toward the NDBC​

  • one request at a time, 3 s at least between two, with a User-Agent naming the integration;
  • only the head of each file is asked for (Range, 16 KiB, about 15 hours of 10-minute lines): never the whole file (up to 1 MB). A server that would ignore the range is cut there too;
  • If-None-Match: a file read in this run of the integration, unchanged since, answers 304 (nothing downloaded);
  • a round of reads starts every interval: a reconnection to Gladys, a saved but unchanged configuration, Discovery or the test button never read sooner, nor a restart while /data works (the time of the last attempt is kept there; when /data cannot be read or written, a restart waits 10 minutes, see Limits). The stations added to the list are read alone right away, at most once a minute (the others keep their turn), and a failed read may be retried sooner (below);
  • a 429 (too many requests) pauses every read 5 minutes, doubled when it comes again, at most 6 hours, Retry-After honoured within that bound; the pause is kept in /data and holds after a restart;
  • a 5xx or another unexpected answer on the file of one station backs that station off alone: read again 2 minutes later, then 4, 8... up to 6 hours (Retry-After honoured), while the other stations are read at their pace. When every station read in a round answers so, every read also pauses 2 minutes (doubled, in /data);
  • a station whose read failed for a passing cause (network, timeout, pause) is read again before the next round: at the end of the pause, else 2 minutes later, doubled at each new failure, as long as that comes before the next round;
  • a round interrupted by a saved configuration or a reconnection keeps the answer of the request that went (shown at once in the status, it counts as the read of that station); the stations it had not read yet are read right after, not at the next interval;
  • a station without realtime file (404) is tried again 1 hour later, then 2, 4... up to 24 hours, on its own timer (the other stations are read as usual).

Status​

The configuration screen shows, for each station: how many values are under 2 hours old and the time of its newest observation (UTC); or "silent" when its newest value is older than 2 hours; or "every value missing (MM)"; or why the read failed (with the HTTP status) and what the last good read said, followed by "nothing published since". When a value turns 2 hours old the status is updated at once, even between two reads. Gladys shows the integration as connected only when the last read of at least one station gave a value under 2 hours old. The "Show the last read" button gives the same text and never reads.

Limits​

  • The NDBC files are near real time, not real time: a buoy observation usually reaches the file 10 to 60 minutes after it was made, sometimes more. A station that sends nothing for 2 hours gets nothing published.
  • Some buoys are seasonal (Great Lakes buoys are taken out in winter): their file stops, the station turns "silent", then the file may disappear (404).
  • The station lines of the status are shortened when 10 stations would not fit in it (the global lines, next read and /data warnings, always stay).
  • A copy kept by a cache and served without an Age header would look newer than it is: it cannot be detected (the NDBC CDN always sends Age; seen up to about 10 minutes).
  • The age of an observation needs the time of the NDBC server: an answer without a readable Date, or one more than a day away from the clock of your Gladys, publishes nothing ("the server time cannot be read").
  • A column whose unit on the second header line is not the expected one (for example knots instead of m/s) is never used, and the status says so.
  • If /data cannot be read (or does not answer within 2 s), it is left untouched and the integration runs from memory: the first read waits 10 minutes after the start, and a restart may publish the newest observations once more.
  • At most 250 values are published per minute: in the rare case of more (10 stations and a burst of device creations), the rest is published at the next read if still under 2 hours old.
  • Only the standard meteorological file (.txt) is read: no spectral wave data, no currents, no DART (tsunami) data, no ocean or water quality data.

Configuration settings​

These are the settings NDBC buoys asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
NOAA buoys (NDBC)sectionNoObservations of the buoys and coastal stations of the National Data Buoy Center (NOAA): US coasts, Great Lakes, Gulf of Mexico, Pacific, and a few Canadian buoys. Read from the public realtime files, no account, no key; US government data in the public domain, except the partner stations relayed by the NDBC, which keep their owner's terms (Environment and Climate Change Canada buoys: Open Government Licence – Canada). One device per station; a value is published only when the observation is less than 2 hours old. Not an official source, not for navigation.
Station idsstringYesUp to 10 NDBC station ids (4 or 5 letters or digits, as on the NDBC map: 46026, KATP), separated by commas.
Language of the namesselectNoLanguage of the device and feature names proposed in Discovery.
Read interval (minutes)numberNoFrom 10 to 180 minutes. Most buoys report every 10 to 60 minutes; the stations are read one after the other, 3 s apart.

How to install NDBC buoys in Gladys​

  1. In Gladys, open Integrations: NDBC buoys appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/lm1lc3n7/gladys-ndbc:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-ndbc.

NDBC buoys requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

NDBC buoys is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on