emgteach: an open-source teaching platform for surface electromyography

Abstract

emgteach is an open-source Python package that provides a unified PySide6 desktop application for real-time acquisition, offline analysis and maximum voluntary contraction (MVC) normalisation of surface electromyography (sEMG) signals. It is designed for hands-on biopotential acquisition in undergraduate physiology teaching laboratories, and is meant to be set up by instructors with different levels of technical background and used directly by students during a practical session. The application is hardware-agnostic through a common AcquisitionDevice interface and ships with two interchangeable low-cost backends: BITalino (revolution) over Bluetooth, and an Arduino RedBoard Plus + MyoWare 2.0 over USB serial (open firmware included). A single setting switches between them. Main features: Three-tab GUI (Acquisition, Analysis, MVC normalisation) wrapping a reusable, Qt-free analytic core. Bilingual interface (English / Spanish) with automatic start-up language detection and an in-app language switch. Two-channel acquisition (e.g. agonist/antagonist) with a stacked two-channel live view. Automatic contraction-onset detection (baseline + k·SD threshold) stored as EDF+ annotations. Muscle-load analysis (Jonsson APDF): static (P10), median (P50) and peak (P90) %MVC levels, both offline and as a live monitor with warning/danger zones. One-click PDF session and MVC/muscle-load reports. Reliable EDF+ output using a buffered-write pattern that avoids a silent file-corruption artefact during continuous streaming. Assisted selection of significant fragments, with an editable fragment editor (detection parameters and envelope-filter cut-offs) applied to the analysis. CSV export of results and a live signal-quality check during recording. Classroom mode: a read-only live dashboard served over the local network so students follow the session on their phone/tablet browser (no install), with a per-session access code so the follower link only works while the broadcast is running. Kinematics via the BITalino accelerometer (v2.0.0): a movement-versus-EMG analysis panel, a guided force-velocity acquisition wizard (an MVC maximum followed by cued quick lifts, each auto-marked with its load), and a force-velocity study that turns one recording into the load-velocity, Hill force-velocity, power and recruitment curves. Since v3.0.0 the accelerometer's input is a stated convention (muscle on A1, accelerometer on A2) rather than a selectable channel. Configuration by practical (v3.0.0): three practicals — one muscle, agonist/antagonist and muscle kinematics — fix the channel count, the accelerometer and what each tab offers, replacing the settings that were previously chosen one at a time. The session as a single file with its phases marked inside it (v3.0.0): warm-up, calibration repetitions, preparation and recording, so the maximum voluntary contraction every percentage is measured against travels with the signal, and a derived (tuned) recording carries the decisions taken on screen. Teaching layer (v3.0.0): a guided tour over the interface, contextual help on every box, one analysis row per contraction with its electromechanical delay, and an agonist/antagonist co-activation index (Falconer-Winter) computed per marked phase in %MVC. Handling at the laboratory bench (v3.1.0): the fragment editor as a three-step procedure that counts the marked contractions against the protocol and lets each be kept, dropped, split or dragged, with the detection sensitivity set per practical and recorded in the report and the CSV; a single running instance with a start-up splash; pictures of the electrode placement and the calibration in the guided tour; and a printable sheet for each station of the agonist/antagonist practical. Patch 3.1.1: the co-activation of a named window is read on the uncut recording, with each muscle's resting level taken from the whole recording phase, so choosing fragments no longer measures the antagonist against a rest taken from a signal with no rest in it. Patch 3.1.2: the calibration asks for a brief, explosive maximal jerk of each muscle's own movement (wrist flexion with the fist clenched for the forearm flexor, wrist extension with the hand open for the extensor) instead of a sustained push against something fixed, and releases carry the source only. Version 3.2.0: the MVC reference is the highest point the envelope reaches across the calibration repetitions kept (it was the highest 0.2 s running mean), and everything judged against it is measured the same way; the co-activation floor is 4.5 % of that reference; each fatigue segment's MDF is computed over the analysis band. A recording reanalysed with 3.2.0 gives % MVC figures different from those of 3.1.2. Version 3.3.0: the task maximum is read on the whole recording phase, from the start of the recording to the end of the file, whatever fragments are chosen (a maximum of the phase, not of the selection); panel 3 draws each spectrum scaled to unit area, with the MDF and the total power in the legend. Version 3.4.0: the Analysis tab's panels are numbered 1 to 12 from one table, the same in every practical, and every title says how to read its panel and names the muscle when it shows one; the two muscles' raw traces share panel 1 with an axis each; panel 8 is a path through time. Nothing computed changes. Version 3.5.0: a BITalino simulated by the application itself (the address «simulada»), which speaks the board's protocol byte for byte, so the acquisition, the calibration, the recording and the classroom broadcast can be prepared and taught where the board is not at hand; a connection diagnostic for the station, built without Qt or scipy; the event log of every recording saved beside it and a recovery for a recording whose process died before it could be closed; and the session report and the CSV export repaired, the report's table of contractions having lost four of its seven columns off the page. Version 3.6.0: the simulated board obeys the calibration — the wizard tells the device when it is asking for a maximal effort and the synthetic subject gives it, so a session rehearsed without hardware reads in % MVC as a real one does (about a half for the alternating gestures, 40 % for the grip, which co-activates) instead of above 100 % of its own maximum. Nothing computed changes. Version 3.7.0, the version the article describes: the guided session goes on into the task — four panels, each with a row of boxes that maps its phase, the free manoeuvres counted as the muscle clears a tenth of its own maximum for 0.30 s, and the grip as one hold of about eight seconds squeezing a ball — and the force-velocity study has the same map; the fragment editor proposes each row from where its contraction leaves rest to where it returns, and in the kinematics practical one row per lift the wizard marked, each load going to the lift its cue announced; the pair practical names its pair; one reference electrode, on the olecranon, and both pairs placed 5 cm from the epicondyle of their own side; the recording says it is connecting until the board answers and gives up with a warning after 20 s without holding the window. emgteach runs on Windows, macOS and Linux with Python 3.10–3.12, is covered by a suite of 1376 automated tests, and is released under the GPL-3.0-or-later license. Source code, documentation and issue tracker: https://github.com/aagisto-maker/emgteach Started in 2025 as the author's own Python programs over open-source libraries and the boards' interfaces; brought together into a single application and developed since with the assistance of an AI coding tool (Claude Code, Anthropic) under the author's specification, review and hardware validation. See the README section "How this software was developed". The anatomical base of the electrode-placement figure and of the guided tour's pictures is an AI-generated image of two forearms, made without text or electrodes; the muscles, electrodes and labels are drawn over it by the figure script.