Contents
- Project Description
- 1. Introduction
- 2. Main Functions
- 3. Hardware Requirements
- 4. Software Environment
- 5. File Structure
- 6. Description of Key Documents
- 7. Core Ideas of Software Design
- 8. Instructions for Use
- 9. Sample Program
- 10. Notes
- 11. Version Record
- 12. Contact the Developer
- 13. Licensing Agreement
- Appendix 1: Project Source Code Download
- Appendix II: Reference Materials for hardware Modules
- Version Record
Project Description
1. Introduction
1.1 Project Background
Traditional signal acquisition devices mostly feature fixed displays or single functions, lacking real-time waveform display and visualization capabilities. This project is based on the GraftPort-RP2040 development board, and combines an analog-to-digital conversion module based on the ADS1115 chip with a 0.96-inch SSD1306-OLED module to implement an integrated system of "signal acquisition - waveform display - real-time visualization", which integrates the lightweight task scheduling and exception handling mechanism of MicroPython to ensure the stable operation of the system.
1.2 Overview of the Main Functions of the Project
This project is developed based on MicroPython, whose core function is to collect analog signals in real time via the ADS1115 analog-to-digital converter module, convert them into digital waveforms, and display the waveform diagrams in real time on the OLED display screen; it supports on-board key interrupt to switch task start and stop, has built-in automatic garbage collection (GC) to avoid memory leaks, and is equipped with exception capture and rate-limited printing for convenient problem locating.
1.3 Applicable Scenarios or Application Area
- Signal Analysis: Real-time monitoring of analog signal waveforms for circuit debugging and signal analysis;
- Teaching Demonstration: Applied to
MicroPythontask scheduling,ADCData Acquisition,I2Ccommunication, waveform display and other knowledge points for practical teaching; - Portable measurement: As a portable signal acquisition device, it is used for on-site testing and fault diagnosis;
- Data Recording: Integrated into the Data Acquisition system to provide real-time waveform display functionality.
2. Main Functions
- Real-time Signal Acquisition: The
ADS1115module is used to collect analog signals every 50ms to maintain a high sampling rate; - OLED real-time waveform display: via the 0.96-inch SSD1306-OLED module to display signal waveforms in real time, with support for scrolling display;
- Key Interrupt Interaction: The onboard key triggers a falling-edge interrupt to toggle the core task between "run" and "pause", and "
PAUSED" is displayed when paused; - Automatic memory management: detects memory usage when idle, and automatically triggers
GCif the memory is below the threshold, preventingMicroPythonfrom crashing due to memory leaks; - Exception Fault Tolerance Mechanism: When an exception is thrown during task execution, the stack trace will be fully printed with rate limiting enabled to prevent log spamming;
- Flexible board-level adaptation: based on
board.pyto realize pin mapping decoupling, supporting subsequent expansion to otherRP2040development boards.
3. Hardware Requirements
3.1 Hardware Required
The project is based on the GraftPort-RP2040 development board as the main controller:

The other required modules include:

- GraftSense - Based on ADS1115 Analog-to-Digital Converter Module:(
I2CCommunication, Address0x49); - GraftSense 0.96-inch SSD1306 OLED Module:(
I2Ccommunication, address0x3Cor0x3D); - GraftSense-SY7656 Lithium Battery Charge-Discharge Module:(compatible with polymer lithium batteries, outputs 5V voltage, equipped with a
Type-Ccharging port); - Onboard buttons: By default, the fixed pins of the development board (Pin 18, pull-up input) are used, and no additional wiring is required;
- Onboard LED: By default, it uses the fixed pin (Pin 25) of the development board, and no additional wiring is required.
3.2 Hardware Connection
Based on the ADS1115 analog-to-digital converter module: connected via PH2.0 connection cable to the I2C0 interface;
0.96-inch SSD1306-OLED module: connected via PH2.0 connecting cable to I2C1 interface;
Lithium Battery Charge and Discharge Module: BAT interface connects to the lithium battery, and the OUT interface supplies power to the main control board via a PH2.0-2P connection cable.



3.3 Structural Assembly
First, use M3 plastic pillars to fix each module and the main control board to the bottom plate of the housing (M3 screw holes are pre-drilled on both the main control board and the housing):


Next, secure the periphery of the housing with M3 plastic pillars, then screw in M3 screws at the corresponding positions to complete the assembly:

3.4 Notes
When the main control board is not connected to an external watchdog module, the RUN DIP switch 2 must be turned on:

The lithium battery charge-discharge module supports power level display, and can be charged via the Type-C interface below:

4. Software Environment
- Core firmware:
MicroPython v1.23.0(need to adapt toGraftPort-RP2040, supportmachine.Pin/I2C/Timermodule, soft timer scheduling); - Development IDE:
PyCharm(for code writing, uploading and debugging, supportsMicroPython REPLinteraction, and requires the installation of theMicroPythonplugin); - Accessory Tools:
Python 3.12+(optional, for running local helper scripts such as firmware flashing scripts);mpy-cross v1.23.0(used to. pyfiles compile to. mpyto reduce the memory usage of the development board, optional);mpremote v0.11.0+(replacesThonnyfor file upload, supports command-line operations, optional);
- Dependency Modules: No additional third-party libraries are required, and all drivers (including
passive_buzzer_driver.pyand others) are custom-implemented and provided along with the project files.
5. File Structure
signal_waveform_acquisition
├─ LICENSE
├─ tools
│ ├─ dependency_analyzer.py
│ ├─ mpy_compiler.py
│ ├─ mpy_uploader.py
│ └─ README.md
├─ firmware
│ ├─ board.py
│ ├─ boot.py
│ ├─ conf.py
│ ├─ main.py
│ ├─ tasks
│ │ ├─ ads_task.py
│ │ ├─ maintenance.py
│ │ └─ __init__.py
│ ├─ libs
│ │ ├─ __init__.py
│ │ └─ scheduler
│ └─ drivers
│ ├─ __init__.py
│ ├─ pcf8574_driver
│ └─ ads1115_driver
├─ examples
├─ docs
└─ build
└─ build_here6. Description of Key Documents
main.py: the project entry point, whose core logic includes:- Power on and delay for 3 seconds (wait for hardware to stabilize), initialize the onboard
LED,OLED,SI5351,PCF8574key module and keys (including interrupt registration); - Hardware initialization:
I2Cbus scan to automatically identify device addresses,OLEDmenu system initialization; - Create
sensor_taskinstance (pass in hardware driver and configuration parameters), and encapsulate it as a scheduler task (with a period of 200ms); - Initialize
Scheduler(software timer with a scheduling period of 50ms), add tasks and start scheduling, then enter an infinite loop; - Define
button_handlerinterrupt callback (for toggling task start/stop),fatal_hangblocking function (for fatal error handling).
- Power on and delay for 3 seconds (wait for hardware to stabilize), initialize the onboard
tasks/ads_task.py: core business tasks,ADSTaskclass key logic:__init__: Initialize the hardware instance and the waveform buffer;tick: Executed once every 50ms, the process is "readADS1115data → update waveform buffer →OLEDupdate display";immediate_off: Immediately clear the screen and display "PAUSED" when paused;_map_raw_to_y: Maps the raw ADC value to the Y coordinate on the screen.
tasks/maintenance.py: System maintenance module, key functions:task_idle_callbackTriggered when the scheduler is idle; if the detected memory usage is lower thanGC_THRESHOLD_BYTES(100000 bytes by default), it will executegc.collect ();task_err_callback: Triggered when an exception is thrown by a task, it prints the full traceback (preferentially viasys.print_exception), then delays forERROR_REPEAT_DELAY_S(1 second by default) to prevent screen flooding;- Supports reading configuration from
conf.py, uses default values when no configuration is available to ensure compatibility.
drivers/xxx_driver: hardware driver modules, all adopting the "instantiation + method call" pattern:ads1115_driver:The ADS1115class communicates viaI2Cand provides methods includingset_conv,read_rev,raw_to_v, etc.ssd1306_driver:The SSD1306_I2Cclass controlsI2C-basedOLEDdisplay and provides methods includingfill,text,line,showand more;
board.py: A board-level pin mapping module that defines theBOARDSdictionary (including the fixed pins ofGraftPort-RP2040and the mapping ofI2C/DIO/ADCinterfaces), provides interfaces such asget_fixed_pinandget_i2c_pins, and realizes the decoupling of board-level configuration from service logic.conf.py: User configuration file. The parameters that need to be manually defined by the user include:I2C_INIT_MAX_ATTEMPTS(number of retries for sensor initialization),I2C_INIT_RETRY_DELAY_S(retry interval in seconds),ENABLE_DEBUG(debug print switch),AUTO_START(whether the task starts automatically). If not defined, the system will use the default values.
7. Core Ideas of Software Design

- System Hierarchy Concept: Adopt a "four-tier architecture" to achieve decoupling and reuse
- Hardware Driver Layer (
drivers/): Only responsible for the low-level control of hardware, and contains no business logic. For example, theADS1115driver only focuses on "how to obtain theADCvalue" and does not care about "how to display waveforms". - Task Logic Layer (
tasks/): Implements business logic based on the interfaces provided by the driver layer. For example,ADSTaskonly calls the driver'sread_revmethod to obtain data without concerning itself withI2Ccommunication details; it only calls theOLED'slineandtextmethods to display content without caring about theI2Caddress. - Dispatch Control Layer (
libs/scheduler.py): Provides generic task management capabilities, supports task addition/pause/resume, idle/exception callbacks, and is independent of specific services; it uniformly manages the execution timing of all tasks via a soft timer. - Entry Layer (
main.py): responsible for "assembling" all layers, initializing hardware → creating tasks → starting scheduling; it acts as the "glue" of the system and contains no core business logic.
- Hardware Driver Layer (
- Principles for Module Division: High cohesion, low coupling, facilitating easy maintenance and expansion
- High Cohesion: each module is only responsible for the Single Responsibility Principle, e. g.
maintenance.pyonly handles system maintenance (GC, exceptions) and does not involve waveform display;ads_task.pyonly handles signal acquisition and waveform display logic, and does not care about hardware initialization. - Low coupling: Modules interact through "interfaces" instead of directly manipulating internal variables, for example,
ADSTaskobtains data viaADS1115.read_revwithout directly operatingI2Cregisters; it draws waveforms viaSSD1306_I2C.line ()without directly controlling I2C communication. - Scalability: when adding new hardware, simply add the corresponding driver under
drivers/and create a new task undertasks/without modifying existing code; when expanding the development board, just add the pin mapping inboard.pywithout affecting the business logic.
- High Cohesion: each module is only responsible for the Single Responsibility Principle, e. g.
- Core Mechanism: Ensuring System Stability and User Experience
- Task Scheduling Mechanism: Implemented based on a soft timer (
Timer (-1)), with a scheduling cycle of 20ms and a core task cycle of 50ms. It judges whether a task is due for execution via "counter accumulation" to avoid timer nesting conflicts. - Waveform Display Mechanism: Adopts a "circular buffer" strategy to realize scrolling waveform display, which not only reduces memory usage but also ensures waveform continuity; supports simultaneous display of raw values and voltage values.
- Interactive Feedback Mechanism: Key interrupt callbacks take "immediate effect": when paused, Data Acquisition and display update stop immediately, and the
PAUSEDstatus is displayed; when hardware initialization fails, an "explicit error" is reported (LEDblinking + terminal message). - Fault-tolerant mechanism: All critical operations are wrapped with
try-exceptblocks to prevent a single module failure from crashing the entire system; the automatic memory reclamation mechanism guards against memory leaks during long-term operation.
- Task Scheduling Mechanism: Implemented based on a soft timer (
- Task Execution Process: The task execution process is as follows

8. Instructions for Use
8.1 Hardware Connection
Connect the main control board, each sensor module and the battery according to the connection method specified in the "hardware requirements";
8.2 Run the Project (Using PyCharm + MicroPython Plugin)
Open PyCharm and install the corresponding MicroPython plugin.

In the plugin, select Target Device (Target Device) as RP2040, and enable Auto-detect device path (Auto-detect device path).

Set Project/firmware as the project root directory.

Modify runtime configuration:

- Check Allow multiple instances (
Allow multiple instances) - Select Store as Project File (
Store as project file) - Click OK to save the configuration.
Click the IDE green triangle button in the upper right corner to run, and you can start uploading the firmware and executing the project.

8.3 Modification of Running Configuration
You can configure conf.py to modify or add parameters as needed, for example:
# conf.py example configuration
I2C_INIT_MAX_ATTEMPTS = 3 # Maximum number of sensor initialization retries
I2C_INIT_RETRY_DELAY_S = 0.5 # Interval between retries (seconds)
ENABLE_DEBUG = True # Whether to enable debug printing
AUTO_START = True # Whether to run tasks automatically at startup8.4 Functional Testing
Turn on the VBAT battery power switch located at the bottom of the main control board, and you will see the power indicator lights on both the main control board and the module light up:
- Signal acquisition: connect the signal source to the input channel of
ADS1115, and observe whether theOLEDdisplay changes accordingly; - Waveform display: Verify whether the waveform scrolls smoothly for display and whether the numerical values are displayed correctly;
- Button Toggle: Press the on-board button to pause the task (display "
PAUSED"), and press it again to resume.
When conf.py is configured unchanged and the hardware connection is normal, the program can run properly.
The terminal output is as follows:

8.5 Debugging and Troubleshooting
- If a functional abnormality occurs, ensure that
ENABLE_DEBUG = True, then check the debug information in the terminal to determine whether the data is normal; - If sensor initialization fails, check the hardware connections, power supply,
I2Caddress configuration; - If
OLEDdoes not display, check whether theI2Caddress is correct (0x3cor0x3d) and whether theI2Cbus is normal; - If the waveform display is abnormal, check the
ADS1115configuration and input signal range.
9. Sample Program
There are no other reference sample codes for this project, you can directly make modifications in the firmware folder.
10. Notes
- Sensor-related:
ADS1115The module requires an appropriate signal input range to avoid exceeding its operating voltage;- Signal input shall be protected from noise interference, and a filter circuit shall be added if necessary.
- Hardware Connection Related:
ADS1115module'sI2Caddress must be set to0x49;- The 0.96-inch SSD1306-OLED module has an
I2Caddress that may be0x3Cor0x3D, which will be automatically detected by the system.
- Software Version Related:
MicroPython v1.23.0 or later version must be used;- Debug printing consumes a certain amount of memory, so it is recommended to disable it in formal use scenarios.
- Function Usage Related:
- The task cycle (50ms) is not recommended to be set too small, otherwise it may increase the system load;
- Automatic
GCThe threshold is recommended to be adjusted according to the actual memory usage.
11. Version Record
12. Contact the Developer
If you have any questions or need assistance, please contact the developer via the following channels:
📧 Email: 10696531183@qq.com
💻 GitHub: https://github.com/FreakStudioCN
13. Licensing Agreement
In this project, except for machine and other MicroPython official modules (MIT License), all driver and extension codes written by the author are released under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) Licensing Agreement.
You are free to:
- Share — copy, distribute the work in any medium or in any form
- Derivative Works — to modify, transform, or create based on the Work
Only the following conditions shall be complied with:
- Attribution — You must give appropriate credit, provide a link to the Licensing Agreement, and indicate if changes were made to the original work. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
- Non-commercial Use — You may not use this work for commercial purposes.
- Proper Citation Method — You may clearly indicate the source in code comments, documentation, demo videos or project descriptions.
Copyright © FreakStudio. All rights reserved.
Appendix 1: Project Source Code Download
https://github.com/FreakStudioCN/GraftPort_MicroPython_Labs/tree/main/signal_waveform_acquisition
Appendix II: Reference Materials for hardware Modules
GraftSense - Based on ADS1115 Analog-to-Digital Converter Module
GraftSense 0.96-inch SSD1306 OLED Module
GraftSense-SY7656 Lithium Battery Charge-Discharge Module
GraftPort - Raspberry Pi Pico Expansion Board (Open Edition Template Files)
Version Record
Document Version | Date of Revision | Modifier | Revised Content |
V1.0.0 | 2025-11-03 | Hou Junhan | Draft the initial version of the document. |
V1.1.0 | 2026-01-04 | Li Zisheng | Final version. |