Ambient Weather Network

Pulls the latest observations from Ambient Weather personal weather stations (WS-2000, WS-5000, WS-2902, PoolWatch, AirQuality, and related product families) through the Ambient Weather Network cloud REST API. One device row in GEM holds the account credentials; each station in the account maps to one GEM zone keyed by MAC address.

Ambient Weather is one of the two dominant DIY-friendly weather-station brands in North America (alongside Davis / WeatherFlow), so this driver is aimed at residential deployments that already have an Ambient console reporting to the cloud and want the readings to drive GEM automations — irrigation skips on rain, HVAC lockouts on hot/humid days, macro branches on wind gusts.

Prerequisites

• An account on ambientweather.net with at least one station uploading. If your console reports "connected" in the Ambient app, you are good.
• An Application Key issued by Ambient Weather. Request one at ambientweather.docs.apiary.io. The application key identifies the integration (this GEM install) and is separate from any individual user's credentials.
• A per-user API Key minted from the account holder's AmbientWeather.net dashboard under Account → API Keys.
• Outbound HTTPS from the GEM controller to api.ambientweather.net.

Setup steps

1. Get an application key. If you don't already have one, register at ambientweather.docs.apiary.io. This is a one-time step per integrator/install.
2. Get an API key. Sign into ambientweather.net, open Account → API Keys, click Create API Key, and copy the string. Treat it like a password — it grants read access to every station on the account.
3. Create the GEM device. In the GEM admin console under Devices, add a new device with driver Ambient Weather Network and fill in:
   • Application Key
   • API Key
   • Leave Status Poll Interval at 60000 (60 s) unless you have a specific reason to poll more often. The Ambient Weather rate limit is 1 request/second, so polling faster than the station's own upload cadence wastes API budget without gaining freshness.
4. Confirm connectivity. Save. On connect the driver hits GET /v1/devices and reads back the station roster. On success the device shows connected and station_count populates.
5. Enumerate stations. From the device page or Script Console, run get_devices. The response is an array; note each macAddress and its info.name.
6. Create a GEM zone per station. For each station you care about, add a zone under the appropriate subsystem (typically "Weather" or "Sensor") and set zone.address to the station's MAC address as reported by AWN (e.g. 00:12:AB:34:CD:EF). MAC addresses are matched case-insensitively and tolerate - vs : separators.

Once zones exist, the poll loop writes attributes like temperature_f, humidity, wind_speed_mph, rain_hourly_in, uv_index, solar_radiation, and a last_updated epoch timestamp onto the zone each time it runs.

Attribute reference

Device attributes

Attribute	Required	Default	Purpose
application_key	✓	—	Ambient Weather application key. Stored encrypted.
api_key	✓	—	Per-user API key. Stored encrypted.
status_interval		60000	Milliseconds between polls of /v1/devices. Minimum 30 000.

Zone attributes (written by the driver)

Fields marked (indoor) require an indoor sensor (WS-2000 console, WH31B remote, etc.). Not every field appears on every station; the driver skips fields the API omits.

Attribute	Source	Notes
temperature / temperature_f	tempf	Outdoor temp, °F. temperature is the canonical alias.
humidity	humidity	Outdoor RH %.
dew_point_f	dewPoint	°F.
feels_like_f	feelsLike	°F.
wind_speed_mph / wind_gust_mph / wind_direction	windspeedmph / windgustmph / winddir	Direction is degrees (0-359).
pressure_in / pressure_absolute_in	baromrelin / baromabsin	Inches Hg.
solar_radiation	solarradiation	W/m².
uv_index	uv	0-11+.
rain_hourly_in / rain_daily_in / rain_weekly_in / rain_monthly_in / rain_yearly_in / rain_event_in	*rainin	Inches.
temperature_indoor_f / humidity_indoor	tempinf / humidityin	Indoor console readings.
battery / battery_indoor / battery_co2	battout / battin / batt_co2	0/1 for most sensors; a 0 indicates low battery.
pm25 / pm25_24h / co2	pm25 / pm25_24h / co2	Air-quality readings on AQM stations.
lightning_strikes_today / lightning_distance_mi	lightning_day / lightning_distance	Lightning-detector stations only.
station_name / station_location	info.name / info.location	Ambient Weather account metadata.
last_updated	dateutc	Epoch ms of the observation. Use to detect stale data.

Zone address format

zone.address = the station MAC address as reported by AWN. Colon or dash separators are accepted, case-insensitive:

• 00:12:AB:34:CD:EF ✓
• 00-12-AB-34-CD-EF ✓
• 00:12:ab:34:cd:ef ✓

Commands

Command	Args	What it does
get_devices	—	Return the full /v1/devices array (every station + its lastData).
get_zone_data	address	Return the single station entry matching that MAC.
poll_now	—	Force a poll immediately and fan-out to zone attributes.
raw_command	path	GET any /v1/* endpoint. Auth keys are appended automatically.

What we don't yet support

• Historical / query API. /v1/devices/{macAddress}?endDate=... returns time-series data. The driver only reads the "current" snapshot; historical export lives in the raw_command escape hatch.
• Real-time WebSocket API. Ambient Weather offers a socket.io real-time stream that pushes updates as stations upload. We poll REST for now — simpler to maintain and stays under the rate limit without ceremony.
• Multi-account fan-out. One device row = one account. Households with two AWN accounts (e.g. main house + vacation home under different logins) need one device row per account.

Troubleshooting

• 401 Unauthorized. Either the application key or the api key is wrong. The AWN API does not distinguish which — check both against the values shown on the ambientweather.net dashboard.
• 403 Forbidden. The application key has been revoked (rare) or is not yet approved. Re-check the apiary.io approval status.
• get_devices returns []. The account has no stations attached, OR the station is a legacy WS-1200 that reports directly to Weather Underground and never uploads to AWN. Confirm the station appears in the ambientweather.net dashboard before troubleshooting further.
• Values look stale. Compare zone.last_updated against Date.now(). If the delta is > 10 minutes the station itself is offline, not the driver. Check the console's Wi-Fi signal and battery.
• Rate-limit warnings. The AWN limit is 1 req/sec per (application_key, api_key) pair. If multiple GEM instances share the same api_key, back the status_interval off to 120000 or higher on each.
• Wind direction is a small integer, not a compass name. AWN reports degrees (0-359). Translate to N/NE/E/SE/… in a macro if you need the string form.

References

• Ambient Weather API docs: https://ambientweather.docs.apiary.io/
• Ambient Weather account portal: https://ambientweather.net/