protocentral-easyemg 0.2.0__tar.gz

protocentral_easyemg-0.2.0/.gitignore

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

protocentral_easyemg-0.2.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# 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 easyEMG Arduino library](https://github.com/Protocentral/protocentral_easyemg_arduino)
+1.1.0 for MicroPython and Raspberry Pi.
+
+### Added
+- The Arduino API in snake_case: raw sEMG in µV at the electrodes, sliding-window RMS
+  envelope, baseline zeroing, activation threshold and %MVC.
+- `set_mains_notch()`, a notch on every mains harmonic up to 0.45× the sample rate
+  (6 Hz wide at the fundamental, 2 Hz on the harmonics), the single `set_notch()`, and
+  a 2nd-order digital high-pass. All off by default.
+- Paced sampling: `update()` on a fixed clock (500 SPS by default), with
+  `missed_samples()` and `reset_clock()`.
+- `MvcRecorder`, the MVC recording step from the Arduino `06.OpenView` sketch.
+- Low-level ADC passthroughs: `set_range()`, `set_data_rate()`, `set_mode()`,
+  `set_mux()` and `read_single_shot()`.
+- Python-only extras: `set_gain()`, `microvolts_per_count()`, `last_envelope_raw()`
+  and `.adc`.
+- An example for every Arduino example: `easyemg_simpletest.py` and
+  `easyemg_raspberrypi.py` (`01`), `easyemg_plotter.py` (`02`),
+  `easyemg_calibration.py` (`03`), `easyemg_envelope.py` (`04`),
+  `easyemg_activation_led.py` (`05`), `easyemg_openview.py` (`06`, the same packets for
+  OpenView's easyEMG Breakout profile) and `easyemg_diagnostics.py` (`07`).
+- Mocked-bus tests, including each example run end to end, and an `mpy-cross` compile
+  in CI, on every push and before every PyPI publish.
+
+### Differences from the Arduino library
+- The driver paces sampling itself, at 500 SPS by default, where the Arduino sketches
+  pace at 1000 SPS. `easyemg_openview.py` therefore sends one sample per packet rather
+  than averaging two, and its harmonic notch covers 50–200 Hz.
+
+Validated with the mocked-bus tests. On an ESP32-S3 (MicroPython 1.29) the driver holds
+500 SPS through the full filter chain with no missed samples. Further bench results
+will be added to the README as they're measured.

protocentral_easyemg-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_easyemg-0.2.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: protocentral-easyemg
+Version: 0.2.0
+Summary: MicroPython + Raspberry Pi driver for the Protocentral easyEMG surface EMG breakout (TLA2024-based)
+Project-URL: Homepage, https://protocentral.com
+Project-URL: Source, https://github.com/Protocentral/protocentral-micropython-easyemg
+Author-email: Protocentral Electronics <info@protocentral.com>
+License: MIT
+License-File: LICENSE.md
+Keywords: easyemg,emg,i2c,micropython,protocentral,qwiic,raspberry-pi,semg,tla2024
+Requires-Python: >=3.9
+Requires-Dist: protocentral-tla20xx>=1.0
+Description-Content-Type: text/markdown
+
+# Protocentral easyEMG MicroPython Library
+
+[![Tests](https://github.com/Protocentral/protocentral-micropython-easyemg/actions/workflows/test.yml/badge.svg)](https://github.com/Protocentral/protocentral-micropython-easyemg/actions/workflows/test.yml)
+[![Publish to PyPI](https://github.com/Protocentral/protocentral-micropython-easyemg/actions/workflows/publish.yml/badge.svg)](https://github.com/Protocentral/protocentral-micropython-easyemg/actions/workflows/publish.yml)
+
+MicroPython library for the **Protocentral easyEMG Breakout**: single-channel surface EMG (sEMG) over I²C / Qwiic. It gives you the raw band-limited waveform and computes the RMS envelope in software. The same driver also runs on a Raspberry Pi.
+
+## Don't have one? [Buy it here](https://protocentral.com/product/easyemg-surface-emg-breakout-qwiic/)
+
+![Protocentral easyEMG](https://raw.githubusercontent.com/Protocentral/protocentral-micropython-easyemg/main/assets/easyemg.jpg)
+
+**Wiring, electrode placement and troubleshooting are in the [easyEMG Getting Started guide](https://protocentral.com/product/easyemg-surface-emg-breakout-qwiic/docs/getting-started/).**
+
+## Links
+
+| | |
+|---|---|
+| Product page | https://protocentral.com/product/easyemg-surface-emg-breakout-qwiic/ |
+| Getting Started guide | https://protocentral.com/product/easyemg-surface-emg-breakout-qwiic/docs/getting-started/ |
+| Arduino library | https://github.com/Protocentral/protocentral_easyemg_arduino |
+| Hardware design files | https://github.com/Protocentral/protocentral_easyemg_hardware |
+
+## Features
+
+- Raw sEMG in µV at the electrodes, on a paced 500 SPS clock with missed-sample counting
+- Sliding-window RMS envelope, activation threshold and %MVC
+- `MvcRecorder`, the same MVC recording step as the Arduino OpenView sketch
+- Optional mains notch (fundamental or every harmonic) and digital high-pass
+- A port of the [Arduino library](https://github.com/Protocentral/protocentral_easyemg_arduino) 1.1.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 no EMG at all.
+
+## Installation
+
+**MicroPython** (Raspberry Pi Pico, ESP32, …):
+
+```bash
+mpremote mip install github:Protocentral/protocentral-micropython-easyemg
+```
+
+This also installs the [TLA20xx driver](https://github.com/Protocentral/protocentral-micropython-tla20xx). With Thonny, copy `protocentral_easyemg.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 ~/easyemg && source ~/easyemg/bin/activate
+pip install protocentral-easyemg
+```
+
+## Quick Start
+
+```python
+from machine import Pin, I2C
+from protocentral_easyemg import EasyEMG
+
+i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)   # Pico: GP5, GP4. Change for your board
+emg = EasyEMG(i2c)                                  # default address 0x48
+if not emg.begin():
+    raise OSError("easyEMG not found")
+emg.calibrate_baseline()                            # muscle relaxed, electrodes on
+
+n = 0
+while True:
+    if emg.update():                                # True once per sample, 500 SPS
+        n += 1
+        if n % 50 == 0:                             # print 10 times a second
+            print(emg.last_envelope(), emg.missed_samples())
+```
+
+On a Raspberry Pi, replace the I²C lines with `from protocentral_tla20xx_linux import I2C` and `EasyEMG(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, print less or lower the rate with `set_sample_rate()`. Filters need that same rate: `set_mains_notch(50, emg.sample_rate_hz())`.
+
+## API Reference
+
+| Method | Description |
+|---|---|
+| `EasyEMG(i2c, address=0x48)` / `begin()` | Construct / configure the ADC. `begin()` returns `False` if the board doesn't answer |
+| `update()` | Non-blocking. Takes one sample when the clock is due; `True` if it did |
+| `last_microvolts()` / `last_envelope()` | The latest sample and RMS envelope, in µV at the electrodes |
+| `set_sample_rate(hz)` / `missed_samples()` | Paced clock, default 500 SPS / samples it couldn't take on time |
+| `set_envelope_window(n)` | 1–128 samples, default 64 (128 ms at 500 SPS) |
+| `set_mains_notch(hz, fs)` / `set_notch(hz, fs)` / `set_high_pass(hz, fs)` | Optional filters, off by default |
+| `calibrate_baseline(n)` / `set_baseline(n)` | Measure and subtract the resting offset |
+| `set_activation_threshold(uv)` / `is_active()` | Compare the envelope with a threshold |
+| `set_mvc(uv)` / `read_percent_mvc()` / `MvcRecorder` | %MVC normalisation and the MVC recording step |
+
+The full API, including the unpaced reads and low-level ADC passthroughs, is documented in [protocentral_easyemg.py](https://github.com/Protocentral/protocentral-micropython-easyemg/blob/main/protocentral_easyemg.py).
+
+## Examples
+
+| # | Example | Description |
+|---|---|---|
+| 01 | `easyemg_simpletest.py` / `easyemg_raspberrypi.py` | Raw µV and envelope (MicroPython / Raspberry Pi) |
+| 02 | `easyemg_plotter.py` | sEMG and envelope for Thonny's plotter |
+| 03 | `easyemg_calibration.py` | Baseline zeroing and your resting noise floor |
+| 04 | `easyemg_envelope.py` | RMS envelope, MVC recording and %MVC |
+| 05 | `easyemg_activation_led.py` | Flex to light an LED, with an automatic threshold and hysteresis |
+| 06 | `easyemg_openview.py` | Stream to [OpenView](https://github.com/Protocentral/protocentral_openview) 3.4+ (**easyEMG Breakout**), with the MVC step. Save it to the board as `main.py`, then close Thonny or `mpremote` before connecting OpenView |
+| 07 | `easyemg_diagnostics.py` | I²C, ADC, sample-rate, noise and mains-hum 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-easyemg/blob/main/LICENSE.md)
+- **Hardware:** CERN-OHL-P v2, in the [hardware repo](https://github.com/Protocentral/protocentral_easyemg_hardware)
+
+Copyright (c) 2026 Protocentral Electronics.
+
+## Support
+
+Open an issue on [GitHub](https://github.com/Protocentral/protocentral-micropython-easyemg/issues) or email support@protocentral.com.

protocentral_easyemg-0.2.0/README.md

@@ -0,0 +1,113 @@
+# Protocentral easyEMG MicroPython Library
+
+[![Tests](https://github.com/Protocentral/protocentral-micropython-easyemg/actions/workflows/test.yml/badge.svg)](https://github.com/Protocentral/protocentral-micropython-easyemg/actions/workflows/test.yml)
+[![Publish to PyPI](https://github.com/Protocentral/protocentral-micropython-easyemg/actions/workflows/publish.yml/badge.svg)](https://github.com/Protocentral/protocentral-micropython-easyemg/actions/workflows/publish.yml)
+
+MicroPython library for the **Protocentral easyEMG Breakout**: single-channel surface EMG (sEMG) over I²C / Qwiic. It gives you the raw band-limited waveform and computes the RMS envelope in software. The same driver also runs on a Raspberry Pi.
+
+## Don't have one? [Buy it here](https://protocentral.com/product/easyemg-surface-emg-breakout-qwiic/)
+
+![Protocentral easyEMG](https://raw.githubusercontent.com/Protocentral/protocentral-micropython-easyemg/main/assets/easyemg.jpg)
+
+**Wiring, electrode placement and troubleshooting are in the [easyEMG Getting Started guide](https://protocentral.com/product/easyemg-surface-emg-breakout-qwiic/docs/getting-started/).**
+
+## Links
+
+| | |
+|---|---|
+| Product page | https://protocentral.com/product/easyemg-surface-emg-breakout-qwiic/ |
+| Getting Started guide | https://protocentral.com/product/easyemg-surface-emg-breakout-qwiic/docs/getting-started/ |
+| Arduino library | https://github.com/Protocentral/protocentral_easyemg_arduino |
+| Hardware design files | https://github.com/Protocentral/protocentral_easyemg_hardware |
+
+## Features
+
+- Raw sEMG in µV at the electrodes, on a paced 500 SPS clock with missed-sample counting
+- Sliding-window RMS envelope, activation threshold and %MVC
+- `MvcRecorder`, the same MVC recording step as the Arduino OpenView sketch
+- Optional mains notch (fundamental or every harmonic) and digital high-pass
+- A port of the [Arduino library](https://github.com/Protocentral/protocentral_easyemg_arduino) 1.1.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 no EMG at all.
+
+## Installation
+
+**MicroPython** (Raspberry Pi Pico, ESP32, …):
+
+```bash
+mpremote mip install github:Protocentral/protocentral-micropython-easyemg
+```
+
+This also installs the [TLA20xx driver](https://github.com/Protocentral/protocentral-micropython-tla20xx). With Thonny, copy `protocentral_easyemg.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 ~/easyemg && source ~/easyemg/bin/activate
+pip install protocentral-easyemg
+```
+
+## Quick Start
+
+```python
+from machine import Pin, I2C
+from protocentral_easyemg import EasyEMG
+
+i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)   # Pico: GP5, GP4. Change for your board
+emg = EasyEMG(i2c)                                  # default address 0x48
+if not emg.begin():
+    raise OSError("easyEMG not found")
+emg.calibrate_baseline()                            # muscle relaxed, electrodes on
+
+n = 0
+while True:
+    if emg.update():                                # True once per sample, 500 SPS
+        n += 1
+        if n % 50 == 0:                             # print 10 times a second
+            print(emg.last_envelope(), emg.missed_samples())
+```
+
+On a Raspberry Pi, replace the I²C lines with `from protocentral_tla20xx_linux import I2C` and `EasyEMG(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, print less or lower the rate with `set_sample_rate()`. Filters need that same rate: `set_mains_notch(50, emg.sample_rate_hz())`.
+
+## API Reference
+
+| Method | Description |
+|---|---|
+| `EasyEMG(i2c, address=0x48)` / `begin()` | Construct / configure the ADC. `begin()` returns `False` if the board doesn't answer |
+| `update()` | Non-blocking. Takes one sample when the clock is due; `True` if it did |
+| `last_microvolts()` / `last_envelope()` | The latest sample and RMS envelope, in µV at the electrodes |
+| `set_sample_rate(hz)` / `missed_samples()` | Paced clock, default 500 SPS / samples it couldn't take on time |
+| `set_envelope_window(n)` | 1–128 samples, default 64 (128 ms at 500 SPS) |
+| `set_mains_notch(hz, fs)` / `set_notch(hz, fs)` / `set_high_pass(hz, fs)` | Optional filters, off by default |
+| `calibrate_baseline(n)` / `set_baseline(n)` | Measure and subtract the resting offset |
+| `set_activation_threshold(uv)` / `is_active()` | Compare the envelope with a threshold |
+| `set_mvc(uv)` / `read_percent_mvc()` / `MvcRecorder` | %MVC normalisation and the MVC recording step |
+
+The full API, including the unpaced reads and low-level ADC passthroughs, is documented in [protocentral_easyemg.py](https://github.com/Protocentral/protocentral-micropython-easyemg/blob/main/protocentral_easyemg.py).
+
+## Examples
+
+| # | Example | Description |
+|---|---|---|
+| 01 | `easyemg_simpletest.py` / `easyemg_raspberrypi.py` | Raw µV and envelope (MicroPython / Raspberry Pi) |
+| 02 | `easyemg_plotter.py` | sEMG and envelope for Thonny's plotter |
+| 03 | `easyemg_calibration.py` | Baseline zeroing and your resting noise floor |
+| 04 | `easyemg_envelope.py` | RMS envelope, MVC recording and %MVC |
+| 05 | `easyemg_activation_led.py` | Flex to light an LED, with an automatic threshold and hysteresis |
+| 06 | `easyemg_openview.py` | Stream to [OpenView](https://github.com/Protocentral/protocentral_openview) 3.4+ (**easyEMG Breakout**), with the MVC step. Save it to the board as `main.py`, then close Thonny or `mpremote` before connecting OpenView |
+| 07 | `easyemg_diagnostics.py` | I²C, ADC, sample-rate, noise and mains-hum 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-easyemg/blob/main/LICENSE.md)
+- **Hardware:** CERN-OHL-P v2, in the [hardware repo](https://github.com/Protocentral/protocentral_easyemg_hardware)
+
+Copyright (c) 2026 Protocentral Electronics.
+
+## Support
+
+Open an issue on [GitHub](https://github.com/Protocentral/protocentral-micropython-easyemg/issues) or email support@protocentral.com.

protocentral_easyemg-0.2.0/examples/easyemg_activation_led.py

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Ashwin Whitchurch, Protocentral Electronics
+#
+# easyemg_activation_led.py - Arduino counterpart: 05.MuscleActivation_LED
+#
+# Flex the muscle, the LED lights. Runs on MicroPython and on a Raspberry Pi.
+#
+# The classic muscle-sensor demo, and the starting point for prosthetics and gesture
+# control. The threshold is set from YOUR resting noise floor rather than hard-coded,
+# because the right number depends on electrode placement, skin prep and the person: the
+# script measures the resting envelope, then triggers at a multiple of it.
+#
+# Hysteresis matters. A single threshold makes the LED chatter whenever the envelope sits
+# near it, so this uses separate ON and OFF levels: a Schmitt trigger, in software.
+#
+# FLEX / relax is printed either way, so it works with no LED. Set LED_PIN for yours.
+#
+# 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)
+    Pin = None
+
+from protocentral_easyemg import EasyEMG, sleep_ms
+
+# MicroPython: "LED" on a Pico / Pico W, 2 on many ESP32 dev boards. The QT Py ESP32-C3
+# has only an RGB NeoPixel, so wire an LED (with a resistor) to a free pin.
+# Raspberry Pi: a BCM pin number, driven through gpiozero.
+LED_PIN = None
+
+TRIGGER_MULTIPLE = 4.0                  # ON at 4x the resting noise floor ...
+RELEASE_MULTIPLE = 2.5                  # ... OFF below 2.5x
+ENVELOPE_WINDOW = 32                    # samples: 64 ms at 500 SPS, quicker to react
+REST_SECONDS = 2
+
+
+def make_led(pin):
+    """A function that sets the LED on (1) or off (0), or None with no LED."""
+    if pin is None:
+        return None
+    if Pin is not None:
+        p = Pin(pin, Pin.OUT)
+        return p.value
+    from gpiozero import LED            # Raspberry Pi
+    led = LED(pin)
+    return lambda v: led.on() if v else led.off()
+
+
+set_led = make_led(LED_PIN)
+if set_led:
+    set_led(0)
+
+emg = EasyEMG(i2c)                      # ships at 0x48
+if not emg.begin():
+    raise OSError("easyEMG not found - check wiring and I2C address (0x48)")
+
+print("Relax the muscle. Measuring your resting noise floor...")
+sleep_ms(1000)
+emg.calibrate_baseline()
+emg.set_envelope_window(ENVELOPE_WINDOW)
+
+# Average the resting envelope over a couple of seconds rather than trusting one reading.
+total = 0.0
+n = 0
+target = REST_SECONDS * emg.sample_rate_hz()
+while n < target:
+    if emg.update():
+        total += emg.last_envelope()
+        n += 1
+resting = total / n
+
+# A dead-quiet (or stuck) ADC gives a resting level of 0, and a 0 threshold would light the
+# LED permanently. Hold the floor at one ADC count.
+floor = emg.microvolts_per_count()
+if resting < floor:
+    print("Resting level is under one ADC count. If every reading stays at 0, run")
+    print("easyemg_diagnostics.py: step 4 tells a quiet board from a stuck ADC.")
+    resting = floor
+
+on_threshold = resting * TRIGGER_MULTIPLE
+off_threshold = resting * RELEASE_MULTIPLE
+emg.set_activation_threshold(on_threshold)
+
+print("Resting level : {:.2f} uV RMS".format(resting))
+print("Trigger at    : {:.2f} uV RMS".format(on_threshold))
+print("Release at    : {:.2f} uV RMS".format(off_threshold))
+print()
+print("Flex the muscle.")
+
+muscle_on = False
+while True:
+    if not emg.update():
+        continue
+    envelope = emg.last_envelope()
+
+    # Schmitt trigger: different levels for turning on and off.
+    if not muscle_on and envelope >= on_threshold:
+        muscle_on = True
+        if set_led:
+            set_led(1)
+        print("FLEX  {:.1f} uV".format(envelope))
+    elif muscle_on and envelope < off_threshold:
+        muscle_on = False
+        if set_led:
+            set_led(0)
+        print("relax")
+
+    # emg.is_active() is the simple single-threshold version, if you don't want
+    # hysteresis:
+    #   if emg.is_active(): ...

protocentral_easyemg-0.2.0/examples/easyemg_calibration.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Ashwin Whitchurch, Protocentral Electronics
+#
+# easyemg_calibration.py - Arduino counterpart: 03.Calibration
+#
+# Zeroes the resting offset and measures your noise floor. Runs on MicroPython and on a
+# Raspberry Pi.
+#
+# Do this every session, per subject. The board reads differentially against its own
+# buffered mid-rail, so the resting count is already near zero, but amplifier offset leaves
+# a few counts behind. calibrate_baseline() averages the resting signal and subtracts it.
+#
+# The front-end gain (x51.7) is set by the onboard resistors, so there is nothing to
+# calibrate there. The script prints it for reference.
+#
+# With the muscle relaxed, the resting envelope should sit close to the board's resolution
+# (a few uV). If it is much higher, suspect mains pickup, long electrode leads or poor skin
+# prep, and run easyemg_diagnostics.py.
+#
+# 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_easyemg import EasyEMG, sleep_ms
+
+BASELINE_SAMPLES = 512
+ENVELOPE_WINDOW = 64                    # samples: 128 ms at 500 SPS
+NOISE_SECONDS = 2
+
+emg = EasyEMG(i2c)                      # ships at 0x48
+if not emg.begin():
+    raise OSError("easyEMG not found - check wiring and I2C address (0x48)")
+
+print("=== easyEMG calibration ===")
+print("Front-end gain        : x{:.2f}".format(emg.get_gain()))
+print("ADC full scale        : +/-{:.3f} V".format(emg.full_scale_volts()))
+print("Resolution at the skin: {:.2f} uV per count".format(emg.microvolts_per_count()))
+print()
+
+print("Relax the muscle completely. Measuring baseline in 3 seconds...")
+sleep_ms(3000)
+emg.calibrate_baseline(BASELINE_SAMPLES)
+print("Baseline offset: {} counts".format(emg.get_baseline()))
+print()
+
+# Paced on the driver's clock, so the envelope covers a known time span.
+print("Measuring resting noise floor ({} s)...".format(NOISE_SECONDS))
+emg.set_envelope_window(ENVELOPE_WINDOW)
+n = 0
+target = NOISE_SECONDS * emg.sample_rate_hz()
+while n < target:
+    if emg.update():
+        n += 1
+print("Resting envelope: {:.2f} uV RMS".format(emg.last_envelope()))
+if emg.missed_samples():
+    print("({} samples missed - the host couldn't hold {} SPS)".format(
+        emg.missed_samples(), emg.sample_rate_hz()))
+print()
+
+print("Copy this line into your own script, after emg.begin():")
+print("  emg.set_baseline({})".format(emg.get_baseline()))