Skip to content

README.md

Latest commit

 

History

History
114 lines (86 loc) · 4.33 KB

README.md

File metadata and controls

114 lines (86 loc) · 4.33 KB
Raw

Water quality analysis bench

Linux only. The I2C runlet requires /dev/i2c-* bus access and is intended for quick tests and examples, not production use.

A QC lab runs periodic water quality checks. Three Atlas Scientific EZO sensors (pH, dissolved oxygen, conductivity) sit on an I2C bus connected to a Raspberry Pi. Tinkwell reads raw sensor values directly over I2C, evaluates water quality signals, and alerts on out-of-spec conditions.

Hardware

  • Raspberry Pi 4 (or any Linux SBC with I2C)
  • Atlas Scientific EZO-pH — pH probe circuit (I2C address 0x63)
  • Atlas Scientific EZO-DO — dissolved oxygen circuit (I2C address 0x61)
  • Atlas Scientific EZO-EC — conductivity circuit (I2C address 0x64)
  • Carrier board (e.g. Whitebox Labs Tentacle T3) to host the EZO circuits

Network diagram

┌──────────────────────────┐
│    Raspberry Pi 4        │
│                          │
│  Tinkwell.Runlet.I2c     │
│    bus 1 ──┬── 0x63 pH   │─── Atlas EZO-pH + probe
│            ├── 0x61 DO   │─── Atlas EZO-DO + probe
│            └── 0x64 EC   │─── Atlas EZO-EC + probe
│                          │
│  Measures → Signals      │
│          → Actions       │
└──────────────────────────┘

Files

File Description
ensemble.tw Complete Tinkwell configuration
README.md This file

How it works

  1. The I2C runlet opens three devices on bus 1 at addresses 0x63, 0x61, and 0x64.
  2. Every 2 seconds, it writes the register address byte (0x00) and reads 4 bytes (IEEE 754 float, big-endian) from each sensor.
  3. Decoded values are pushed to Tinkwell measures: ph, dissolved-oxygen, conductivity.
  4. Signals evaluate water quality:
    • ph-out-of-range fires when pH < 6.5 or > 8.5
    • low-dissolved-oxygen fires when DO < 4 mg/L
    • high-conductivity fires when EC > 1500 µS/cm
  5. Actions log alerts and send HTTP POST webhooks to a LIMS.

Quick start

1. Enable I2C on the Raspberry Pi

sudo raspi-config
# Interface Options → I2C → Enable
sudo usermod -aG i2c $USER
# Log out and back in

2. Verify sensors are detected

i2cdetect -y 1
# Should show devices at 0x61, 0x63, 0x64

3. Start Tinkwell

tw start samples/use-cases/water-quality/ensemble.tw

If running from a build output directory (not an installed copy), use ./Tinkwell.Coordinator samples/use-cases/water-quality/ensemble.tw instead.

4. Monitor (separate terminals)

# Terminal 2 — live sensor readings
tw measures watch

# Terminal 3 — water quality alerts
tw signals watch --beep

# Terminal 4 — audit trail
tw events list --last 20

Signal thresholds

Signal Fires Clears Severity
ph-out-of-range pH < 6.5 or > 8.5 pH 6.5–8.5 Critical
low-dissolved-oxygen DO < 4 mg/L DO >= 4.5 mg/L Critical
high-conductivity EC > 1500 µS/cm EC <= 1400 µS/cm Warning

Important notes

  • Sensor calibration: Atlas EZO sensors require calibration before use. Follow the Atlas Scientific calibration procedures for each sensor. This is outside the scope of Tinkwell.
  • Register protocol: This example assumes sensors are in I2C polling mode and return a 4-byte float at register 0x00. The actual EZO I2C protocol involves sending a read command (0x52) and waiting for the response. For real deployment, a custom runlet implementing the full EZO protocol would be more appropriate.
  • Not for production: The I2C runlet performs simple register reads. Production water quality monitoring should use a dedicated runlet with proper command sequencing, calibration support, and error recovery.

Customization

  • Additional sensors: add more device blocks with the sensor's I2C address and register layout.
  • Different bus: change bus = 1 to the appropriate bus number.
  • Temperature compensation: Atlas EZO sensors support temperature compensation — this would require write support (not available in the basic I2C runlet).
  • MQTT forwarding: add an MQTT runlet and publish readings to a broker for integration with other systems.