protocentral-easyecg 0.2.0__tar.gz

protocentral_easyecg-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/

protocentral_easyecg-0.2.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this driver are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-11-07
+
+First public release. A port of the
+[Protocentral easyECG Arduino library](https://github.com/Protocentral/protocentral_easyecg_arduino)
+1.0.0 for MicroPython and Raspberry Pi.
+
+### Added
+- The Arduino API in snake_case, with the same defaults and validation rules: paced
+  sampling with missed-sample counting, 50/60 Hz notch, 40 Hz low-pass, optional
+  high-pass, heart rate from a simplified Pan-Tompkins detector, saturation, mains
+  pickup and a provisional lead-off heuristic, readings in µV at the electrodes.
+- Low-level ADC passthroughs: `set_range()`, `set_data_rate()`, `set_mode()`,
+  `set_mux()` and `read_single_shot()`.
+- Python-only extras: `set_gain()` / `get_gain()` and `.adc`.
+- An example for every Arduino example: `easyecg_simpletest.py` and
+  `easyecg_raspberrypi.py` (`01`), `easyecg_plotter.py` (`02`), `easyecg_heartrate.py`
+  (`03`), `easyecg_openview.py` (`04`, the same packets for OpenView's easyECG Breakout
+  profile) and `easyecg_diagnostics.py` (`05`).
+- Mocked-bus tests and an `mpy-cross` compile in CI, on every push and before every
+  PyPI publish.
+
+### Differences from the Arduino library
+- The default ADC rate is 250 SPS rather than 1000, because interpreted Python can't
+  hold 1 kSPS through the filters. Output rates (125 / 250 Hz) are the same.
+- `begin()` returns `False` on a missing board instead of writing to it.
+
+Validated with the mocked-bus tests. Bench results on MicroPython and Raspberry Pi
+hosts will be added to the README as they're measured.

protocentral_easyecg-0.2.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashwin Whitchurch, Protocentral Electronics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

protocentral_easyecg-0.2.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: protocentral-easyecg
+Version: 0.2.0
+Summary: MicroPython + Raspberry Pi driver for the Protocentral easyECG single-lead ECG breakout (TLA2024-based)
+Project-URL: Homepage, https://protocentral.com
+Project-URL: Source, https://github.com/Protocentral/protocentral-micropython-easyecg
+Author-email: Protocentral Electronics <info@protocentral.com>
+License: MIT
+License-File: LICENSE.md
+Keywords: easyecg,ecg,i2c,micropython,protocentral,qwiic,raspberry-pi,tla2024
+Requires-Python: >=3.9
+Requires-Dist: protocentral-tla20xx>=1.0
+Description-Content-Type: text/markdown
+
+# Protocentral easyECG MicroPython Library
+
+[![Tests](https://github.com/Protocentral/protocentral-micropython-easyecg/actions/workflows/test.yml/badge.svg)](https://github.com/Protocentral/protocentral-micropython-easyecg/actions/workflows/test.yml)
+[![Publish to PyPI](https://github.com/Protocentral/protocentral-micropython-easyecg/actions/workflows/publish.yml/badge.svg)](https://github.com/Protocentral/protocentral-micropython-easyecg/actions/workflows/publish.yml)
+
+MicroPython library for the **Protocentral easyECG Breakout**: single-lead (Lead I) ECG over I²C / Qwiic. It handles the sampling, filtering and heart-rate detection. The same driver also runs on a Raspberry Pi.
+
+## Don't have one? [Buy it here](https://protocentral.com/product/easyecg-single-lead-ecg-breakout-qwiic/)
+
+![Protocentral easyECG](https://raw.githubusercontent.com/Protocentral/protocentral-micropython-easyecg/main/assets/easyecg.jpg)
+
+**Wiring, electrode placement and troubleshooting are in the [easyECG Getting Started guide](https://protocentral.com/product/easyecg-single-lead-ecg-breakout-qwiic/docs/getting-started/).**
+
+## Links
+
+| | |
+|---|---|
+| Product page | https://protocentral.com/product/easyecg-single-lead-ecg-breakout-qwiic/ |
+| Getting Started guide | https://protocentral.com/product/easyecg-single-lead-ecg-breakout-qwiic/docs/getting-started/ |
+| Arduino library | https://github.com/Protocentral/protocentral_easyecg_arduino |
+| Hardware design files | https://github.com/Protocentral/protocentral_easyecg_hardware |
+
+## Features
+
+- Paced sampling with missed-sample counting: 250 SPS in, 125 or 250 Hz out
+- 50/60 Hz notch and 40 Hz low-pass in software; no high-pass by default, to keep the ST segment
+- Heart rate from a simplified Pan-Tompkins R-peak detector
+- Saturation, mains-pickup and a provisional lead-off flag
+- Readings in µV at the electrodes
+- A port of the [Arduino library](https://github.com/Protocentral/protocentral_easyecg_arduino) 1.0.0: the same API in snake_case, and a Python version of every Arduino example
+
+> **Not a medical device. For research and education only.** The breakout has no patient isolation: when electrodes are on a person, power the host from a battery or connect through an [easyISO isolated Qwiic adapter](https://protocentral.com/product/easyiso-isolated-qwiic-adapter/). On a mains-powered host you get a flat line, and `is_saturated()` reports it.
+
+## Installation
+
+**MicroPython** (Raspberry Pi Pico, ESP32, …):
+
+```bash
+mpremote mip install github:Protocentral/protocentral-micropython-easyecg
+```
+
+This also installs the [TLA20xx driver](https://github.com/Protocentral/protocentral-micropython-tla20xx). With Thonny, copy `protocentral_easyecg.py` and `protocentral_tla20xx.py` to the board instead.
+
+**Raspberry Pi**, with I²C enabled (`sudo raspi-config nonint do_i2c 0`):
+
+```bash
+python3 -m venv ~/easyecg && source ~/easyecg/bin/activate
+pip install protocentral-easyecg
+```
+
+## Quick Start
+
+```python
+from machine import Pin, I2C
+from protocentral_easyecg import EasyECG
+
+i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)   # Pico: GP5, GP4. Change for your board
+ecg = EasyECG(i2c)                                  # default address 0x49
+if not ecg.begin():
+    raise OSError("easyECG not found")
+
+while True:
+    if ecg.update():                                # True at the output rate, 125 Hz
+        print(ecg.ecg_microvolts(), ecg.heart_rate())
+```
+
+On a Raspberry Pi, replace the I²C lines with `from protocentral_tla20xx_linux import I2C` and `EasyECG(I2C(bus=1))`.
+
+Call `update()` as often as you can; it samples only when the clock is due, and never blocks. If `missed_samples()` grows, your loop is too slow.
+
+## API Reference
+
+| Method | Description |
+|---|---|
+| `EasyECG(i2c, address=0x49)` / `begin()` | Construct / configure the ADC. `begin()` returns `False` if the board doesn't answer |
+| `update()` | Non-blocking. `True` when a new output sample is ready |
+| `ecg_microvolts()` / `ecg_filtered()` | Filtered output, in µV at the electrodes / in counts |
+| `ecg_unfiltered_microvolts()` / `ecg_unfiltered()` | Plain ADC average |
+| `heart_rate()` / `beat_detected()` / `last_rr_millis()` | bpm, 0 until established / true once per beat / last R-R interval |
+| `is_saturated()` / `is_lead_off()` / `mains_microvolts()` | Signal-quality flags; lead-off is a provisional heuristic |
+| `set_sampling(adc, out)` / `missed_samples()` | Sample clock (default 250, 125) / samples the loop couldn't take on time |
+| `set_notch(hz)` / `set_low_pass(hz)` / `set_high_pass(hz)` | Filters: 50 Hz, 40 Hz, off by default. 0 disables |
+| `calibrate_baseline(ms)` / `set_baseline(n)` | Measure and subtract the resting offset |
+
+The full API, including the low-level ADC passthroughs, is documented in [protocentral_easyecg.py](https://github.com/Protocentral/protocentral-micropython-easyecg/blob/main/protocentral_easyecg.py).
+
+## Examples
+
+| # | Example | Description |
+|---|---|---|
+| 01 | `easyecg_simpletest.py` / `easyecg_raspberrypi.py` | Filtered ECG in counts and µV (MicroPython / Raspberry Pi) |
+| 02 | `easyecg_plotter.py` | Filtered and unfiltered traces for Thonny's plotter |
+| 03 | `easyecg_heartrate.py` | Heart rate on every beat, with saturation and lead-off messages |
+| 04 | `easyecg_openview.py` | Stream to [OpenView](https://github.com/Protocentral/protocentral_openview) 3.4+ (**easyECG Breakout**). Save it to the board as `main.py`, then close Thonny or `mpremote` before connecting OpenView |
+| 05 | `easyecg_diagnostics.py` | I²C, ADC, noise, mains and sample-rate checks. **Run this first if something is wrong** |
+
+The examples default to QT Py ESP32-C3 pins: change the `I2C(...)` line for your board.
+
+## License
+
+- **Software:** MIT, see [LICENSE.md](https://github.com/Protocentral/protocentral-micropython-easyecg/blob/main/LICENSE.md)
+- **Hardware:** CERN-OHL-P v2, in the [hardware repo](https://github.com/Protocentral/protocentral_easyecg_hardware)
+
+Copyright (c) 2026 Protocentral Electronics.
+
+## Support
+
+Open an issue on [GitHub](https://github.com/Protocentral/protocentral-micropython-easyecg/issues) or email support@protocentral.com.

protocentral_easyecg-0.2.0/README.md

@@ -0,0 +1,108 @@
+# Protocentral easyECG MicroPython Library
+
+[![Tests](https://github.com/Protocentral/protocentral-micropython-easyecg/actions/workflows/test.yml/badge.svg)](https://github.com/Protocentral/protocentral-micropython-easyecg/actions/workflows/test.yml)
+[![Publish to PyPI](https://github.com/Protocentral/protocentral-micropython-easyecg/actions/workflows/publish.yml/badge.svg)](https://github.com/Protocentral/protocentral-micropython-easyecg/actions/workflows/publish.yml)
+
+MicroPython library for the **Protocentral easyECG Breakout**: single-lead (Lead I) ECG over I²C / Qwiic. It handles the sampling, filtering and heart-rate detection. The same driver also runs on a Raspberry Pi.
+
+## Don't have one? [Buy it here](https://protocentral.com/product/easyecg-single-lead-ecg-breakout-qwiic/)
+
+![Protocentral easyECG](https://raw.githubusercontent.com/Protocentral/protocentral-micropython-easyecg/main/assets/easyecg.jpg)
+
+**Wiring, electrode placement and troubleshooting are in the [easyECG Getting Started guide](https://protocentral.com/product/easyecg-single-lead-ecg-breakout-qwiic/docs/getting-started/).**
+
+## Links
+
+| | |
+|---|---|
+| Product page | https://protocentral.com/product/easyecg-single-lead-ecg-breakout-qwiic/ |
+| Getting Started guide | https://protocentral.com/product/easyecg-single-lead-ecg-breakout-qwiic/docs/getting-started/ |
+| Arduino library | https://github.com/Protocentral/protocentral_easyecg_arduino |
+| Hardware design files | https://github.com/Protocentral/protocentral_easyecg_hardware |
+
+## Features
+
+- Paced sampling with missed-sample counting: 250 SPS in, 125 or 250 Hz out
+- 50/60 Hz notch and 40 Hz low-pass in software; no high-pass by default, to keep the ST segment
+- Heart rate from a simplified Pan-Tompkins R-peak detector
+- Saturation, mains-pickup and a provisional lead-off flag
+- Readings in µV at the electrodes
+- A port of the [Arduino library](https://github.com/Protocentral/protocentral_easyecg_arduino) 1.0.0: the same API in snake_case, and a Python version of every Arduino example
+
+> **Not a medical device. For research and education only.** The breakout has no patient isolation: when electrodes are on a person, power the host from a battery or connect through an [easyISO isolated Qwiic adapter](https://protocentral.com/product/easyiso-isolated-qwiic-adapter/). On a mains-powered host you get a flat line, and `is_saturated()` reports it.
+
+## Installation
+
+**MicroPython** (Raspberry Pi Pico, ESP32, …):
+
+```bash
+mpremote mip install github:Protocentral/protocentral-micropython-easyecg
+```
+
+This also installs the [TLA20xx driver](https://github.com/Protocentral/protocentral-micropython-tla20xx). With Thonny, copy `protocentral_easyecg.py` and `protocentral_tla20xx.py` to the board instead.
+
+**Raspberry Pi**, with I²C enabled (`sudo raspi-config nonint do_i2c 0`):
+
+```bash
+python3 -m venv ~/easyecg && source ~/easyecg/bin/activate
+pip install protocentral-easyecg
+```
+
+## Quick Start
+
+```python
+from machine import Pin, I2C
+from protocentral_easyecg import EasyECG
+
+i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)   # Pico: GP5, GP4. Change for your board
+ecg = EasyECG(i2c)                                  # default address 0x49
+if not ecg.begin():
+    raise OSError("easyECG not found")
+
+while True:
+    if ecg.update():                                # True at the output rate, 125 Hz
+        print(ecg.ecg_microvolts(), ecg.heart_rate())
+```
+
+On a Raspberry Pi, replace the I²C lines with `from protocentral_tla20xx_linux import I2C` and `EasyECG(I2C(bus=1))`.
+
+Call `update()` as often as you can; it samples only when the clock is due, and never blocks. If `missed_samples()` grows, your loop is too slow.
+
+## API Reference
+
+| Method | Description |
+|---|---|
+| `EasyECG(i2c, address=0x49)` / `begin()` | Construct / configure the ADC. `begin()` returns `False` if the board doesn't answer |
+| `update()` | Non-blocking. `True` when a new output sample is ready |
+| `ecg_microvolts()` / `ecg_filtered()` | Filtered output, in µV at the electrodes / in counts |
+| `ecg_unfiltered_microvolts()` / `ecg_unfiltered()` | Plain ADC average |
+| `heart_rate()` / `beat_detected()` / `last_rr_millis()` | bpm, 0 until established / true once per beat / last R-R interval |
+| `is_saturated()` / `is_lead_off()` / `mains_microvolts()` | Signal-quality flags; lead-off is a provisional heuristic |
+| `set_sampling(adc, out)` / `missed_samples()` | Sample clock (default 250, 125) / samples the loop couldn't take on time |
+| `set_notch(hz)` / `set_low_pass(hz)` / `set_high_pass(hz)` | Filters: 50 Hz, 40 Hz, off by default. 0 disables |
+| `calibrate_baseline(ms)` / `set_baseline(n)` | Measure and subtract the resting offset |
+
+The full API, including the low-level ADC passthroughs, is documented in [protocentral_easyecg.py](https://github.com/Protocentral/protocentral-micropython-easyecg/blob/main/protocentral_easyecg.py).
+
+## Examples
+
+| # | Example | Description |
+|---|---|---|
+| 01 | `easyecg_simpletest.py` / `easyecg_raspberrypi.py` | Filtered ECG in counts and µV (MicroPython / Raspberry Pi) |
+| 02 | `easyecg_plotter.py` | Filtered and unfiltered traces for Thonny's plotter |
+| 03 | `easyecg_heartrate.py` | Heart rate on every beat, with saturation and lead-off messages |
+| 04 | `easyecg_openview.py` | Stream to [OpenView](https://github.com/Protocentral/protocentral_openview) 3.4+ (**easyECG Breakout**). Save it to the board as `main.py`, then close Thonny or `mpremote` before connecting OpenView |
+| 05 | `easyecg_diagnostics.py` | I²C, ADC, noise, mains and sample-rate checks. **Run this first if something is wrong** |
+
+The examples default to QT Py ESP32-C3 pins: change the `I2C(...)` line for your board.
+
+## License
+
+- **Software:** MIT, see [LICENSE.md](https://github.com/Protocentral/protocentral-micropython-easyecg/blob/main/LICENSE.md)
+- **Hardware:** CERN-OHL-P v2, in the [hardware repo](https://github.com/Protocentral/protocentral_easyecg_hardware)
+
+Copyright (c) 2026 Protocentral Electronics.
+
+## Support
+
+Open an issue on [GitHub](https://github.com/Protocentral/protocentral-micropython-easyecg/issues) or email support@protocentral.com.

protocentral_easyecg-0.2.0/examples/easyecg_diagnostics.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Ashwin Whitchurch, Protocentral Electronics
+#
+# easyecg_diagnostics.py - Arduino counterpart: 05.Diagnostics
+#
+# Run this when the trace looks wrong and you want numbers instead of guesses. Runs on
+# MicroPython and on a Raspberry Pi.
+#
+#   1. Is the ADC on the bus, and at which address?
+#   2. Did the configuration take? (CONFIG read back, expect 0x04C3)
+#   3. Is the conversion register changing at all?
+#   4. Every 2 s: noise and mains figures for the live signal.
+#
+# Step 4 prints, per 2 s window, in uV at the electrodes:
+#
+#   filt_rms   RMS of the filtered output
+#   raw_rms    RMS of the unfiltered output
+#   mains      mains pickup the notch is removing
+#   pp         peak-to-peak of the filtered output (about the R-wave height with a heart)
+#   hr         heart rate, bpm
+#   rate       output samples per second actually delivered (should read 250; Python only)
+#   sat, lead  amplifier saturated, lead-off heuristic
+#   missed     samples the loop couldn't take on time (should stay 0)
+#
+# Two runs separate board noise from body noise:
+#
+#   a) Short LA, RA and RL together at the jack (or clip all three leads to one
+#      electrode). filt_rms is now the board's own noise floor - expect a few uV.
+#   b) Electrodes on, sitting still. If filt_rms is far above (a) and mains is small, the
+#      extra noise is muscle or electrode contact. Filtering won't remove it.
+#
+# For research and education only - not a medical device. With electrodes on a person,
+# power the host from a battery or connect through an easyISO isolated Qwiic adapter.
+
+try:
+    from machine import Pin, I2C
+    # Defaults for the Adafruit QT Py ESP32-C3 (SCL=6, SDA=5). Change for your board.
+    i2c = I2C(0, scl=Pin(6), sda=Pin(5), freq=400000)
+except ImportError:                     # Raspberry Pi
+    from protocentral_tla20xx_linux import I2C
+    i2c = I2C(bus=1)
+
+import math
+
+from protocentral_easyecg import (
+    EasyECG, EASYECG_I2C_ADDR_DEFAULT, EASYECG_I2C_ADDR_ALT, EASYECG_SATURATION_COUNTS,
+    EASYECG_DEFAULT_ADC_RATE, ticks_us, ticks_diff, sleep_ms,
+)
+
+MAINS_HZ = 50.0                         # 50 or 60
+EXPECTED_CONFIG = 0x04C3
+
+
+def yes_no(flag):
+    return "Y" if flag else "-"
+
+
+print()
+print("=== Protocentral easyECG diagnostics ===")
+
+print("--- 1. I2C scan")
+found = None
+for addr in i2c.scan():
+    label = ""
+    if addr in (EASYECG_I2C_ADDR_DEFAULT, EASYECG_I2C_ADDR_ALT):
+        label = "  <- easyECG"
+        if found is None:
+            found = addr
+    print("   device at 0x{:02X}{}".format(addr, label))
+if found is None:
+    raise OSError("easyECG not found at 0x49/0x48 - check wiring and power")
+
+ecg = EasyECG(i2c, found)
+ecg.begin()
+ecg.set_sampling(EASYECG_DEFAULT_ADC_RATE, 250)     # 250 Hz out, as in the Arduino sketch
+ecg.set_notch(MAINS_HZ)
+
+# Bit 15 reads 0 while a conversion is in progress, so it is masked off.
+print("--- 2. CONFIG read-back")
+conf = ecg.read_config()
+print("   read 0x{:04X}, expected 0x{:04X} (+/-2.048 V, continuous, 3300 SPS)  {}".format(
+    conf, EXPECTED_CONFIG, "OK" if (conf & 0x7FFF) == EXPECTED_CONFIG else "MISMATCH"))
+
+print("--- 3. Conversion register activity")
+lo = 32767
+hi = -32768
+total = 0
+for _ in range(500):
+    v = ecg.read_raw_uncorrected()
+    lo = min(lo, v)
+    hi = max(hi, v)
+    total += v
+    sleep_ms(1)
+print("   500 samples: min {}  max {}  mean {}".format(lo, hi, int(total / 500)))
+if lo == hi:
+    print("   STUCK: the ADC returns a constant. Check power and the CONFIG word.")
+elif hi >= EASYECG_SATURATION_COUNTS or lo <= -EASYECG_SATURATION_COUNTS:
+    print("   Near a rail: electrode off, or mains-powered host without isolation.")
+else:
+    print("   OK - converting.")
+
+ecg.calibrate_baseline(1000)
+print("   baseline {} counts".format(ecg.get_baseline()))
+
+print("--- 4. Live figures, uV at the electrodes, every 2 s")
+print("   ADC {} SPS, output {} Hz".format(ecg.adc_rate_hz(), ecg.output_rate_hz()))
+print("   filt_rms  raw_rms    mains       pp      hr    rate  sat lead missed")
+
+window = 2 * ecg.output_rate_hz()
+skip = 1                                # let the filters settle first
+sum_f = sum_f2 = sum_r = sum_r2 = 0.0
+min_f = 1e9
+max_f = -1e9
+n = 0
+t0 = ticks_us()
+
+while True:
+    if not ecg.update():
+        continue
+
+    f = ecg.ecg_microvolts()
+    r = ecg.ecg_unfiltered_microvolts()
+    sum_f += f
+    sum_f2 += f * f
+    sum_r += r
+    sum_r2 += r * r
+    min_f = min(min_f, f)
+    max_f = max(max_f, f)
+    n += 1
+    if n < window:
+        continue
+
+    t1 = ticks_us()
+    if skip:
+        skip -= 1
+    else:
+        rms_f = math.sqrt(max(0.0, sum_f2 / n - (sum_f / n) ** 2))
+        rms_r = math.sqrt(max(0.0, sum_r2 / n - (sum_r / n) ** 2))
+        rate = n * 1000000.0 / ticks_diff(t1, t0)
+        print("   {:8.1f} {:8.1f} {:8.1f} {:8.1f} {:7.1f} {:7.1f}   {}    {}   {}".format(
+            rms_f, rms_r, ecg.mains_microvolts(), max_f - min_f, ecg.heart_rate(), rate,
+            yes_no(ecg.is_saturated()), yes_no(ecg.is_lead_off()), ecg.missed_samples()))
+
+    sum_f = sum_f2 = sum_r = sum_r2 = 0.0
+    min_f = 1e9
+    max_f = -1e9
+    n = 0
+    t0 = ticks_us()

protocentral_easyecg-0.2.0/examples/easyecg_heartrate.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Ashwin Whitchurch, Protocentral Electronics
+#
+# easyecg_heartrate.py - Arduino counterpart: 03.HeartRate
+#
+# Prints the heart rate on every detected beat, blinks an LED if the board has one, and
+# says so plainly when the signal can't be trusted. Runs on MicroPython and on a Raspberry
+# Pi (no LED there).
+#
+# The detector is a simplified Pan-Tompkins: it needs about 2 s to learn the signal level,
+# then averages the last 8 R-R intervals. Expect a number after 3-5 beats.
+#
+# Status messages, once a second:
+#   SATURATED - the amplifier is pinned at a rail. Usually a mains-powered host (switch
+#               to battery, or use an easyISO), or an electrode that has come off.
+#   LEAD OFF? - mains pickup is far above normal, which is what a loose or missing
+#               electrode looks like. Provisional heuristic - see the README.
+#
+# For research and education only - not a medical device. With electrodes on a person,
+# power the host from a battery or connect through an easyISO isolated Qwiic adapter.
+
+try:
+    from machine import Pin, I2C
+    # Defaults for the Adafruit QT Py ESP32-C3 (SCL=6, SDA=5). Change for your board.
+    i2c = I2C(0, scl=Pin(6), sda=Pin(5), freq=400000)
+    try:
+        led = Pin("LED", Pin.OUT)       # Pico / Pico W; boards without a named LED skip it
+    except Exception:                   # noqa: BLE001 - ports raise different errors
+        led = None
+except ImportError:                     # Raspberry Pi
+    from protocentral_tla20xx_linux import I2C
+    i2c = I2C(bus=1)
+    led = None
+
+from protocentral_easyecg import EasyECG, ticks_us, ticks_diff
+
+MAINS_HZ = 50.0                         # 50 or 60
+
+ecg = EasyECG(i2c)                      # ships at 0x49
+if not ecg.begin():
+    raise OSError("easyECG not found - check wiring and I2C address (0x49)")
+
+ecg.set_notch(MAINS_HZ)
+ecg.calibrate_baseline(1000)
+print("Sit still - learning the signal for 2 s...")
+
+led_on_at = None
+last_status = ticks_us()
+
+while True:
+    now = ticks_us()
+
+    if led_on_at is not None and ticks_diff(now, led_on_at) >= 60000:
+        led.value(0)
+        led_on_at = None
+
+    if not ecg.update():
+        continue
+
+    if ecg.beat_detected():
+        if led is not None:
+            led.value(1)
+            led_on_at = now
+        hr = ecg.heart_rate()
+        print("Beat  RR {} ms  HR {}".format(
+            ecg.last_rr_millis(), "{:.0f} bpm".format(hr) if hr > 0.0 else "--"))
+
+    # Signal-quality status once a second.
+    if ticks_diff(now, last_status) >= 1000000:
+        last_status = now
+        if ecg.is_saturated():
+            print("SATURATED - battery host or isolated adapter? electrode off?")
+        elif ecg.is_lead_off():
+            print("LEAD OFF? mains pickup {:.0f} uV RMS".format(ecg.mains_microvolts()))

protocentral_easyecg-0.2.0/examples/easyecg_openview.py

@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Ashwin Whitchurch, Protocentral Electronics
+#
+# easyecg_openview.py - Arduino counterpart: 04.OpenView
+#
+# Streams the ECG into the Protocentral OpenView desktop app over USB serial. MicroPython
+# only (it needs sys.stdout.buffer).
+#
+#   In OpenView 3.4 or later:  Connect -> USB -> select "easyECG Breakout"
+#
+# On earlier versions the "ADS1292R Breakout" profile also reads this stream, with the
+# labels wrong: its ECG is the filtered trace, its Respiration the unfiltered trace, its
+# HR the heart rate and its RR the signal status.
+#
+# Same packets as the Arduino sketch, 125 per second, written as raw bytes to the USB
+# serial port (the baud rate setting doesn't matter over USB CDC):
+#
+#   0x0A 0xFA 0x08 0x00 0x02 | 8-byte payload | 0x00 0x0B
+#   payload, int16 little-endian:
+#     ECG (filtered)   <- notch + 40 Hz low-pass, counts
+#     ECG (unfiltered) <- plain average of the ADC samples (0 if SECOND_CHANNEL_UNFILTERED
+#                         is False). Hidden by default in OpenView.
+#     Heart rate       <- bpm, rounded
+#     Signal           <- 0 = OK, 1 = lead-off / mains pickup, 2 = amplifier saturated
+#
+# The driver samples at 250 SPS (Arduino: 1000) and decimates to 125 Hz, so OpenView sees
+# the same rate and scale. No digital high-pass by default: the board's 0.5 Hz analog
+# corner is already there, and a second pole distorts the ST segment.
+#
+# HOW TO RUN: save this file to the board as main.py and reset it, then close Thonny or
+# mpremote so OpenView can open the port. The REPL shares that port, so `mpremote run`
+# can't be used here: it would read the packets itself. Don't print() anything else -
+# OpenView expects binary packets only. To stop it, connect Thonny and press Ctrl-C.
+#
+# Needs a port whose sys.stdout has a .buffer (ESP32, RP2040/RP2350 and most others).
+#
+# Download OpenView: https://github.com/Protocentral/protocentral_openview
+#
+# On a mains-powered host the driven-right-leg amplifier saturates and there is no trace.
+# For research and education only - not a medical device. With electrodes on a person,
+# power the host from a battery or connect through an easyISO isolated Qwiic adapter.
+
+import struct
+import sys
+
+from machine import Pin, I2C
+from protocentral_easyecg import EasyECG, EASYECG_DEFAULT_ADC_RATE, sleep_ms
+
+# ---- user settings ------------------------------------------------------------------
+MAINS_HZ = 50.0                         # 50 or 60
+LOW_PASS_HZ = 40.0                      # 0 disables the digital low-pass
+HIGH_PASS_HZ = 0.0                      # 0 = off (keeps ST shape); 0.5 for wander
+SECOND_CHANNEL_UNFILTERED = True
+
+# Defaults for the Adafruit QT Py ESP32-C3 (SCL=6, SDA=5). Change for your board.
+i2c = I2C(0, scl=Pin(6), sda=Pin(5), freq=400000)
+
+# ---- Protocentral OpenView packet format -------------------------------------------
+CES_CMDIF_PKT_START_1 = 0x0A
+CES_CMDIF_PKT_START_2 = 0xFA
+CES_CMDIF_TYPE_DATA = 0x02
+CES_CMDIF_PKT_STOP = 0x0B
+DATA_LEN = 0x08
+
+# One preallocated packet: header (5) + payload (8) + footer (2). Only the payload changes.
+packet = bytearray(5 + DATA_LEN + 2)
+packet[0] = CES_CMDIF_PKT_START_1
+packet[1] = CES_CMDIF_PKT_START_2
+packet[2] = DATA_LEN
+packet[3] = 0
+packet[4] = CES_CMDIF_TYPE_DATA
+packet[13] = 0
+packet[14] = CES_CMDIF_PKT_STOP
+
+out = getattr(sys.stdout, "buffer", sys.stdout)
+
+
+def send_data_packet(ecg_ch, second_ch, hr, status):
+    struct.pack_into("<hhhh", packet, 5, ecg_ch, second_ch, hr, status)
+    out.write(packet)
+
+
+ecg = EasyECG(i2c)                      # ships at 0x49
+if not ecg.begin():
+    # No text output - the host is expecting binary packets.
+    while True:
+        sleep_ms(500)
+
+ecg.set_sampling(EASYECG_DEFAULT_ADC_RATE, 125)
+ecg.set_notch(MAINS_HZ)
+ecg.set_low_pass(LOW_PASS_HZ)
+ecg.set_high_pass(HIGH_PASS_HZ)
+
+# Zero the amplifier offset over one second. Sit still.
+ecg.calibrate_baseline(1000)
+
+while True:
+    if not ecg.update():
+        continue
+
+    status = 0
+    if ecg.is_saturated():
+        status = 2
+    elif ecg.is_lead_off():
+        status = 1
+
+    second = ecg.ecg_unfiltered() if SECOND_CHANNEL_UNFILTERED else 0
+    send_data_packet(ecg.ecg_filtered(), second, int(ecg.heart_rate() + 0.5), status)

protocentral_easyecg-0.2.0/examples/easyecg_plotter.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Ashwin Whitchurch, Protocentral Electronics
+#
+# easyecg_plotter.py - Arduino counterpart: 02.SerialPlotter
+#
+# The ECG for a plotter, such as Thonny's View -> Plotter. Runs on MicroPython and on a
+# Raspberry Pi.
+#
+# Two traces, in uV at the electrodes:
+#   Filtered   - 50 Hz notch + 40 Hz low-pass: what you normally want
+#   Unfiltered - the plain ADC average, offset below so the two don't overlap
+#
+# Output is 250 Hz, as in the Arduino sketch, so the QRS keeps its shape. If
+# missed_samples() grows on a slow board, change OUTPUT_HZ to 125.
+#
+# For research and education only - not a medical device. With electrodes on a person,
+# power the host from a battery or connect through an easyISO isolated Qwiic adapter.
+
+try:
+    from machine import Pin, I2C
+    # Defaults for the Adafruit QT Py ESP32-C3 (SCL=6, SDA=5). Change for your board.
+    i2c = I2C(0, scl=Pin(6), sda=Pin(5), freq=400000)
+except ImportError:                     # Raspberry Pi
+    from protocentral_tla20xx_linux import I2C
+    i2c = I2C(bus=1)
+
+from protocentral_easyecg import EasyECG, EASYECG_DEFAULT_ADC_RATE
+
+MAINS_HZ = 50.0                         # 50 or 60
+OUTPUT_HZ = 250
+UNFILTERED_OFFSET = 1500.0              # uV, vertical spacing between the traces
+
+ecg = EasyECG(i2c)                      # ships at 0x49
+if not ecg.begin():
+    raise OSError("easyECG not found - check wiring and I2C address (0x49)")
+
+ecg.set_sampling(EASYECG_DEFAULT_ADC_RATE, OUTPUT_HZ)
+ecg.set_notch(MAINS_HZ)
+ecg.calibrate_baseline(1000)            # one second, sitting still
+
+while True:
+    if ecg.update():
+        print("Filtered:{:.0f},Unfiltered:{:.0f}".format(
+            ecg.ecg_microvolts(), ecg.ecg_unfiltered_microvolts() - UNFILTERED_OFFSET))