Night Heron User Guide

1. Getting Started

Welcome to the Night Heron Alert System! This guide will walk you through setting up sensors and configuring alerts to monitor environmental data effectively.

Night Heron is designed to track sensor data in real-time from sources like USGS , Monitor My Watershed and Purple Air and notify you via email or text message when measurements fall outside your defined safe zones.

2. Adding Sensors

Before you can create alerts, you need to add the sensor sites you want to monitor. Sensor readings reach Night Heron in one of two ways:

  • Push — your device sends readings to us over the Strawberry Creek API.
  • Pull — Night Heron fetches readings from a provider on a timer (e.g. Monitor My Watershed or USGS Water Services).

Either way, you start by registering the sensor on the Sensors page. The Data Source you pick on the form decides which of the two paths applies and which fields you'll need to fill in.

2.1 The Sensor Form

Go to the "Sensors" page and click "Add New Sensor". The form shows and hides fields based on the Data Source you choose:

FieldDescription
Site Code (always required) A short name for the site, e.g. North Fork 0. This becomes the name of the sensor's data table (lowercased, with anything that isn't a letter/number turned into _ — so North Fork 0 → north_fork_0). Letters, numbers, spaces, hyphens and underscores only, 64 characters max. You can't rename it later without recreating the table, so choose carefully.
Data Source Where the data comes from. This guide covers Strawberry Creek API (push), Monitor My Watershed and USGS Water Services (pull).
Data URL Only shown for URL-based pull sources such as USGS — the endpoint Night Heron polls.
Update Frequency (minutes) How often the sensor reports new data. Required for every source except the Strawberry Creek API (where the device controls timing). For pull sources it sets how often Night Heron polls.
Timezone The sensor's local timezone, used to align timestamps.
Downtime threshold (minutes) (Downtime alerts section) Optional. Raise a downtime alarm if no new data arrives from this sensor for this many minutes. Leave blank to auto-derive from the update frequency (3× the frequency, minimum 30 min).
Downtime alert emails Who to email when this sensor goes silent. Click Manage recipients to add addresses one at a time (validated) or paste a comma-separated list — the same picker used by static and moving alerts.
Downtime alert phone numbers Who to text (SMS) when this sensor goes silent, via the same Manage recipients picker. Include the country code (e.g. 15105551234) or the carrier will reject the number.

The Downtime alerts fields group together on the sensor form. A downtime alarm fires once when a sensor first goes silent past its threshold (not repeatedly), and clears when data resumes. If you leave the email/SMS lists blank, the alarm falls back to the system-wide downtime recipient list.

Saving the form creates the sensor and its (initially empty) data table. From then on the Sensors list shows an ingest-health badge for each site — No data yet → Healthy once readings start arriving, or Stale if they stop.

Sensor Details List
Figure 1 – Sensors list
Sensor Details Form
Figure 2 – Add Sensor form

2.2 Straight to the API (device push)

Use this when your device sends its own readings — for example an EnviroDIY Mayfly. The device posts each reading directly to Night Heron over the Strawberry Creek API, so there's nothing for the server to poll.

  1. Register the sensor with Data Source = Strawberry Creek API. Update Frequency isn't required here — the device controls its own timing.
  2. Program the device and start uploading. Flashing the Mayfly, the Arduino sketch, generating an API key, and confirming data transmission are all covered step-by-step in the Install a New Sensor guide. (The raw request format also lives on the API Docs page.)
Add Sensor form with Data Source set to Strawberry Creek API
Figure 3 – Registering an API (device-push) sensor

2.3 Monitor My Watershed (server pull)

Use this for Hydros21 / EnviroDIY sites that already publish to Monitor My Watershed. Night Heron pulls the data on a timer; the device never talks to us directly.

  1. On Monitor My Watershed, find the site's sampling-feature code (the code MMW assigns to the site).
  2. Register the sensor with Data Source = Monitor My Watershed and set the Site Code to exactly that MMW sampling-feature code — for MMW the Site Code does double duty: it names the local data table and is the key sent to MMW, so it must match. Set the Update Frequency and Timezone to match the site.
  3. Save. Ingestion picks the new site up within seconds and fetches each available variable (conductivity, depth, temperature, battery, precipitation, humidity…), adding table columns automatically as data arrives.
Monitor My Watershed site listing
Figure 4 – Finding the sampling-feature code on Monitor My Watershed

2.4 USGS Water Services (server pull)

USGS sensors pull from the official USGS Water Data API. All you need is the site's USGS site number — find it on the gauge's page at waterdata.usgs.gov (e.g. 11447650 for "Sacramento R A Freeport CA"; entering it as USGS-11447650 also works).

  1. Set Data Source to USGS Water Services.
  2. Enter the USGS site number in the field that appears — no URL needed.
  3. Set the upload frequency to the gauge's reporting interval (most USGS gauges report every 15 minutes).

Each ingest cycle fetches the last 24 hours of gage height (stage, ft), discharge (flow_rate, ft³/s), and water temperature (temperature, °C) where the site provides them; already-stored readings are deduplicated automatically.

Add Sensor form with Data Source set to USGS Water Services
Figure 5 – Registering a USGS sensor (current form)

2.5 The Views Page

Once a sensor is ingesting, the Views page controls how it surfaces in the rest of the app. Variables are discovered automatically from the sensor's data table — assign each one a friendly label and unit, choose which are plotted on the analytics page, and toggle whether the sensor appears on the analytics page and the public map (the map also needs a latitude and longitude).

Views page: per-sensor analytics/map toggles and per-variable labels, units and plot checkboxes
Figure 6 – The Views page

3. Creating Alerts

Alerts define the conditions under which you will be notified. Night Heron supports two main types of alerts: Static Alerts and Moving-Average Alerts.

Example alerts
Figure 7 – Example Alerts Overview

3.1 Static Alerts

Static alerts trigger when a sensor reading crosses a fixed threshold (an absolute high or low value).

Example: Notify if water temperature exceeds 20°C or drops below 2°C.

Field Description Example
Title Name of the rule for identification Example 1 Temperature
Zipcode Location used for fetching local weather data 94704
Site code Unique identifier from Monitor My Watershed North Fork #0
Sensor type The type of measurement (e.g., temperature, depth) Temperature (Celsius)
Upperbound Value above which an alert is triggered 20.0
Lowerbound Value below which an alert is triggered 2.0
Min consecutive breaches How many readings in a row must cross the bound before the alert fires. Default 1 (fire on the first breach); raise it to ignore one-off spikes. A data gap breaks the streak — readings on either side of an outage don't count as consecutive. 3
Post rain pause Minimum hours after last rainfall before reactivating alerts 0
Pre rain pause Minimum hours before expected rainfall to suppress alerts 0
Rain behavior What to do during the rain window: skip alerts during rain, or use alternate thresholds during rain (keep alerting, but against the rain bounds below). Use alternate thresholds during rain
Rain upper / lower bound Alternate high/low values applied during the rain window. Used only when Rain behavior is set to "use alternate thresholds". 30.0 / 0.5
Minutes between consecutive alerts Cooldown period before firing another alert 15
Email list Comma-separated list of emails to notify example@gmail.com
Text list Comma-separated phone numbers for SMS alerts [1-111-1111]
Static alert list view
Figure 8 – Static alert view
Static alert form
Figure 9 – Static alert form

The rain-related fields live behind the Rain & weather settings button at the top of the alert form. Rain is looked up by zip code; pick whether the rule should skip alerts during the pre/post-rain window, or use alternate thresholds while it rains. The same dialog appears on moving-average alerts.

Rain and weather settings with Skip alerts during rain selected Rain and weather settings with Use alternate thresholds during rain selected
Figure 10 – Rain & weather settings: skip alerts during rain (left) or switch to alternate thresholds (right)

3.2 Moving-Average Alerts

Moving-average alerts are more dynamic. They track a simple moving average (SMA) or exponential moving average (EMA) of sensor readings over a defined period. An alert triggers when the current reading deviates from that moving average by more than the band you set — measured either as a percentage of the average or in standard deviations of the recent data (your choice, via Band type).

This is useful for detecting sudden changes relative to recent trends, rather than absolute values.

Example: Notify if turbidity increases by more than 50% above the 24-hour moving average.

Field Description Example
Title Name of the rule for identification test
Zip code ZIP code for weather/rain-check lookups (optional) 94704
Site code Sensor site to monitor North Fork #0
Stat choice Which averaging method to use for the alert (SMA or EMA) Simple Moving Average
Average time (hrs) Rolling window in hours used to compute average 24
Sensor type The type of sensor being monitored Temperature (Celsius)
Band type How the alert band is measured off the moving average: as a % deviation from the average, or in standard deviations of the readings in the window. This decides what the upper/lower numbers below mean. % deviation from average
Upperbound How far above the moving average triggers an alert — read as a percent or in standard deviations, depending on Band type. 5
Lowerbound How far below the moving average triggers an alert — same units as Upperbound. 5
Min consecutive breaches How many readings in a row must fall outside the band before the alert fires. Default 1; raise it to ride out brief blips. Gap-aware — a data outage breaks the streak. 3
Post rain pause Minimum hours after rain before alerts can fire again 0
Pre rain pause Minimum hours before forecasted rain to allow alerts 0
Rain behavior During the rain window: skip alerts, or use alternate thresholds (keep alerting against the rain percentages below). Use alternate thresholds during rain
Rain upper / lower % Alternate band percentages applied during the rain window. Used only when Rain behavior is set to "use alternate thresholds". 50 / 50
Time between alerts Cooldown time before the same alert can fire again (minutes) 180
Email list Comma-separated list of emails for notification example@gmail.com
Text list Comma-separated phone numbers to send SMS alerts 1-111-1111
Moving alert list view
Figure 11 – Moving-average alert view
Moving alert form
Figure 12 – Moving-average alert form

4. Notifications

When an alert condition is met, Night Heron will send notifications to the configured email addresses and/or phone numbers (via SMS).

Each alert configuration allows you to specify:

  • Email List: Comma-separated email addresses.
  • Text List: Comma-separated phone numbers (1-111-1111).
  • Cooldown Period: Minimum time between consecutive alerts for the same rule to prevent notification fatigue.

5. Reviewing Alert Events

The "Alert Events" page provides a historical log of all alert processing attempts and their outcomes. This is crucial for understanding if your alerts are triggering as expected, if notifications are being sent successfully, and for diagnosing any issues.

5.1 Accessing the Page

You can navigate to this page using the "Logs" link in the main navigation bar.

5.2 Understanding the Alert Events Table

The table on this page displays the following information for each event:

  • Time: The date and time when the alert condition was checked or the event was processed.
  • Site: The sensor site code relevant to the event.
  • Sensor: The specific sensor being monitored (if applicable).
  • Type: The type of alert or data point (e.g., 'Static', 'Moving Average', or the sensor variable type).
  • Value: The sensor reading or value that was evaluated (if applicable).
  • Rain Pause: Indicates if a "rain pause" was active at the time of the event, which might suppress alerts (True/False).
  • Email: The status of the email notification attempt (e.g., success or failure).
  • SMS: The status of the SMS notification attempt (e.g., success or failure).
  • Notes: Provides additional details, especially error messages if an alert failed to process or a notification failed to send (e.g., "Data load failure: ...", "Email send error: ..."). This column is very important for troubleshooting.

5.3 Filtering Events

Above the table, you'll find a filter form that allows you to narrow down the list of events:

Alert Events Filter Form
Figure 13 – Alert Events Filter Form
  • Status Dropdown: Allows you to view:
    • All events.
    • Success events — where the notification was delivered.
    • Failure events — where there was an error processing the alert, a data load issue, or a notification attempt failed.
  • Sensor: Narrow the list to a single sensor site. The dropdown is populated with the sensors that actually appear in your events.
  • Type: Narrow the list to one event type — e.g. a specific sensor variable, or an ingestion-failure event. The dropdown is populated with the types present in your events.
  • Start Date: Select a date to see events that occurred on or after this date.
  • End Date: Select a date to see events that occurred on or before this date. The filter includes the entire end date.

After selecting your filter criteria, click the Apply Filters button to update the list.

Using these links will allow you to browse through all the historical alert events that match your current filter settings.

6. Troubleshooting

If you are not receiving alerts:

  • Verify the sensor data is updating correctly at the source.
  • Check your alert configurations for correct thresholds and sensor selection.
  • Ensure email addresses and phone numbers are correctly entered.
  • Check your spam/junk folder for email notifications.
  • Review the "Alert Events" page (Section 5) for any error messages related to data fetching or notification sending.