Posting sensor data to Bayou

How a small ESP32 firmware — or a five-line Python script — pushes a measurement to a Bayou feed, and what Bayou will do with each field.

1. The end-to-end pipeline

In the reference kit that this repo ships (examples/v3-ultrasonic), a physical distance reading takes four hops to reach a browser chart:

This page is about the last hop: the plain HTTP POST from the Heltec receiver to Bayou. It's simple enough that anything that can make an HTTPS request — a shell script, a Python script, a webhook, another microcontroller — can play the role of "sensor" for a Bayou feed. The Python script in section 5 is a working example of exactly that.

2. What the microcontroller does

When the receiver gets a LoRa DM from the sender, it parses the distance and battery voltage out of the payload, then builds a small JSON object and POSTs it to Bayou. The relevant firmware is in examples/v3-ultrasonic/companion_sensor_receiver/main.cpp, function postToBayou. The request looks like this:

POST https://bayou.pvos.org/data/<feed_public_key>
Content-Type: application/json

{
  "private_key":     "<feed_private_key>",
  "node_id":         2,
  "distance_meters": 1.723,
  "battery_volts":   3.874,
  "aux_1":           0,
  "aux_2":           1,
  "log":             "path=5a.91 route=DIRECT",
  "source":          "Sensor"
}

Two things about that body worth pausing on:

• The URL only carries the public key. The private key travels in the JSON body, not the URL — that's how Bayou distinguishes "anyone who knows the feed" from "someone allowed to write to it". More on this in section 3.
• Some fields are recognized, some aren't. Bayou has a fixed set of column names it knows about (section 4). Every recognized field goes into its own database column; every unrecognized field is silently ignored. In the example above, distance_meters, battery_volts, node_id, aux_1, aux_2, and log are stored; source is dropped on the floor because Bayou has no column for it. The receiver sends it anyway because it costs nothing and reads nicely in a packet capture.

On a successful post Bayou answers 200 Measurement recorded. On a private-key mismatch it answers 400 Private key mismatch. A network error or unreachable server produces an HTTP client error, which the receiver logs and retries after 15 seconds.

3. Bayou feeds: what the keys are for

A Bayou "feed" is just two 12-character IDs (nanoid, alphabet 23456789abcdefghijkmnpqrstuvwxyz — ambiguous characters removed) plus a Postgres row backing it. There are no accounts, no logins, and no email addresses; the two keys are the only access control.

To create a feed, either open the Bayou home page in a browser and click through the create-feed form, or from a script:

curl -X POST https://bayou.pvos.org/manage/

Either way, Bayou returns an HTML page showing the new feed's public key, private key, feed URL, and a QR code. Save the private key immediately — it's shown once and there is no recovery flow if you lose it.

4. The allowed measurement fields

A POST to /data/<public_key> may include any subset of the fields below (plus the required private_key). Unknown fields are ignored; omitted fields are stored as SQL NULL. Numeric fields are numeric-typed in Postgres, so pass numbers not strings. Timestamps are assigned by Bayou when the row is inserted — clients cannot supply their own timestamp, which also means offline data cannot be backfilled.

If none of the recognized fields fits, use aux_1–aux_3 or log. Adding a genuinely new column is possible but touches three files in the Bayou codebase (the SQL schema, the INSERT statement, and restructureJSON in controllers/dataControllers.js).

5. A Python script that mimics the sensor

The script example_temp_poster.py next to this page does exactly what the receiver does — build a small JSON object with the private key plus a measurement field, and POST it to Bayou every few seconds. The only difference is that instead of pulling a real distance from a LoRa DM, it generates a random temperature.

The heart of the script:

URL = f"https://bayou.pvos.org/data/{PUBLIC_KEY}"

while True:
    payload = {
        "private_key":   PRIVATE_KEY,
        "node_id":       1,
        "temperature_c": round(random.uniform(15.0, 25.0), 2),
    }
    r = requests.post(URL, json=payload, timeout=10)
    print(payload["temperature_c"], "->", r.status_code, r.text.strip())
    time.sleep(10)

You can swap temperature_c for any recognized field in section 4, or include several at once — everything Bayou recognizes in one POST lands on the same measurement row.

6. End-to-end walkthrough

1. Create a feed. Open https://bayou.pvos.org/ and click to create a feed. Copy the public key and (especially) the private key from the page it hands back.
2. Point the poster at your feed. Open example_temp_poster.py in a text editor and paste the two keys into PUBLIC_KEY and PRIVATE_KEY.
3. Run the poster.

   pip install requests   # first time only
   python3 example_temp_poster.py

   You should see one line per POST: temperature_c=21.4 -> 200 Measurement recorded.
4. Watch the chart. Open, in a browser:

   https://bayou.pvos.org/data/<YOUR_PUBLIC_KEY>/?plot_param=temperature_c

   The chart refreshes every few seconds. Each POST from the script should add another point.
5. Explore the read side. Try the JSON, CSV, and latest endpoints:

   curl "https://bayou.pvos.org/data/<PUBKEY>/latest/"
   curl "https://bayou.pvos.org/data/<PUBKEY>/json/?limit=20"
   curl -O "https://bayou.pvos.org/data/<PUBKEY>/csv/"

   The JSON response always includes every recognized field, with null for fields you never posted — that's how the feed page can plot any parameter without knowing in advance which ones you actually populate.
6. Swap in the real hardware (optional). Flash the ultrasonic kit from this repo, point the receiver at your feed with set bayou_public_key <your pubkey> / set bayou_private_key <your privkey>, and pair it with the Rook sender. From Bayou's point of view the microcontroller and the Python script are indistinguishable: same URL, same JSON body shape, different measurement field.

7. Gotchas & things Bayou does not do

• No client-supplied timestamps. Every measurement is stamped with the server's NOW() when the row is inserted. There is no way to backfill offline data — a queue-and-flush strategy will end up with all queued readings sharing the flush time.
• No time-range queries. Read endpoints paginate by limit (newest N rows), not by time. The CSV endpoint always returns every row for the feed. Filtering by time has to happen on the client.
• Unknown fields are silently dropped. A typo like tempeature_c won't error — it just posts a row with every real field NULL. If a value seems missing, print the payload you sent and confirm the field name matches the table in section 4.
• Type validation is loose. Server-side numeric validation is disabled; a non-numeric value passed for a numeric column will either coerce oddly or trigger a Postgres error surfaced as a 400.
• The clear-feed endpoint is destructive on GET. Never put the private key in a URL, and don't publish a URL of the form /manage/clear/<pub>/<priv> anywhere a crawler might follow it.