Labs / MicroPython module projects

Smart Music Control Light (Based on GraftPort-RP2040 Development Board)(Open Version)

Author: Li Zisheng · Source: FreakStudio open documentation · License: CC BY 4.0

Contents
GraftPort-RP2040
GraftPort-RP2040

Project Description

1. Introduction

1.1 Project Background

Traditional LED lamps mostly feature fixed brightness adjustment, and buzzers usually produce a single sound effect, lacking interactivity with the environment. Based on the GraftPort-RP2040 development board, this project integrates the RCWL9623 high-precision ranging sensor to realize "distance-sound and light" linkage control, addressing the insufficient interactivity of traditional audio-visual devices. Meanwhile, it incorporates the lightweight task scheduling and exception handling mechanism of MicroPython to ensure the stable operation of the system.

1.2 Overview of Main Functions of the Project

This project is developed based on MicroPython. Its core function is to detect the distance of the target in real time through the RCWL9623 ranging sensor, and dynamically control the brightness of PiranhaLED (the closer the distance, the higher the brightness) and the frequency of the passive buzzer (the closer the distance, the higher the frequency) after data filtering; it supports on-board key interrupt to switch task start and stop, has built-in automatic garbage collection (GC) to avoid memory leakage, is equipped with exception capture and rate-limited printing for convenient problem locating, and the sensor initialization retry mechanism improves hardware compatibility.

1.3 Applicable Scenarios or Application Area

2. Main Functions

3. Hardware Requirements

3.1 Hardware Required

The project is based on the GraftPort-RP2040 development board as the main controller:

GraftPort-RP2040 I2C 2020

Other required modules include:

SY7656 RCWL9623

3.2 Hardware Connection

RCWL9623 Transmit-Receive Integrated Ultrasonic Sensor Module: Connect via PH2.0-4P cable to the I2C0 interface;

GraftPort-RP2040 PH2.0-4P I2C0 0 1 PH2.0-2P

Piranha LED light module: connect to digital interface 0 via PH2.0-4P connection cable;

v1.0 0 PH2.0-4P UART0 I2C0

Passive Buzzer Module: Connect to Digital Port 1 via PH2.0-4P connection cable;

GraftPort-RP2040 PH2.0-4P RCWL9623

Lithium Battery Charge and Discharge Module: BAT interface is connected to the lithium battery, and the OUT interface supplies power to the main control board via a PH2.0-2P connection cable.

PH2.0 2P 3.3
GraftPort-RP2040 3.1
3.3

3.3 Hardware Connection

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):

GraftPort-RP2040 M3 3.3
M3

Next, secure the housing around its perimeter using M3 plastic pillars, then fasten M3 screws into the corresponding positions to complete the assembly:

M3 3.3

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:

2

The lithium battery charge-discharge module supports power level display, and you can charge it via the following Type-C interface:

2024-06 3000mAh 3.7V

4. Software Environment

5. File Structure

Project root directory/
├── libs/                       # Common utility library folder, holds reusable core modules
│   └── scheduler/              # Task scheduler library, implements multi-task management based on soft timers (supports adding/pausing/resuming tasks, idle/exception callbacks)
├── drivers/                    # Hardware driver folder, encapsulates control interfaces for different peripherals (high cohesion, exposes only necessary methods)
│   ├── passive_buzzer_driver/    # Passive buzzer driver package, provides the `play_tone(freq, duration)` method
│   ├── piranha_led_driver/       # PiranhaLED driver package, provides the `set_brightness(percent)` method
│   └── rcwl9623_driver/          # RCWL9623 driver package, provides the `read_distance()` method
├── tasks/                      # Task logic folder, holds business-related task implementations (decoupled from hardware drivers)
│   ├── sensor_task.py          # Core task module, defines the `SensorBuzzerLedTask` class, implements the complete "ranging → filtering → sound and light control" logic
│   └── maintenance.py          # Maintenance task module, provides `task_idle_callback` (automatic GC) and `task_err_callback` (exception handling)
├── main.py                     # Project entry file, responsible for hardware initialization, task creation, scheduler startup, and exception blocking handling
├── board.py                    # Board support file, defines the pin mapping of the GraftPort-RP2040 (fixed pins, I2C/DIO/ADC interfaces)
├── conf.py                     # Configuration file, holds customizable parameters (such as sensor initialization retry count, GC threshold, etc.)
├── README.md                   # Project documentation, includes feature introduction, usage steps, notes, etc.
├── build/                      # Build artifacts / scripts / firmware packaging specifications (placeholder)
├── tools/                      # Development / testing / packaging helper scripts
└── docs/                       # Documentation: design notes, API specifications, development board pin mapping and related images
    ├── graftport_pinout_table.md   # GraftPort-RP2040 pin mapping table
    ├── xxx.jpg                 # Several photos related to development board \m module \ wiring
└── examples                    # A folder of some running examples; this project has none.

If you want to add other sensor modules to the main control board, it is recommended that you refer to the docs folder, and check the graftport_pinout_table.md file for the pin mapping.

6. Description of Key Documents

7. Core Idea of Software Design

GraftPort-RP2040 drivers/rcwl9623_driver.py
GraftPort-RP2040

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.

1.45.20241 1.45.20241.1

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

Smart Music Control Light (Based on GraftPort-RP2040 Development Board)(Open Version)

Set Project/firmware as the project root directory.

Smart Music Control Light (Based on GraftPort-RP2040 Development Board)(Open Version)

Modify the runtime configuration:

Smart Music Control Light (Based on GraftPort-RP2040 Development Board)(Open Version)

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.1

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 startup

8.4 Functional Testing

Turn on the VBAT battery power switch located below the main control board, and you will see the power indicators on the main control board and the module light up:

GraftPort-RP2040

When conf.py remains unchanged in configuration and there is no issue with the hardware connection, the program can run normally (the buzzer's tone changes as the distance between the hand and the device varies):

GraftPort-RP2040 8.4

The terminal output is as follows:

25.57 99 987 B5

8.5 Debugging and Problem Localization

9. Sample Program

There are no other reference sample codes for this project, you can directly firmware make modifications in the folder.

10. Notes

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 (under the 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:

Only the following conditions shall be complied with:

Copyright belongs to FreakStudio.

Appendix I: Project Source Code Download

https://github.com/FreakStudioCN/GraftPort_MicroPython_Labs/tree/main/proximity_music_light

proximity_music_light.rar 22.4 MB

Appendix II: Hardware Module Reference Materials

GraftSense-RCWL9623

GraftSense - Piranha LED Module;

GraftSense - Passive Buzzer Module

GraftSense-SY7656 Lithium Battery Charge-Discharge Module

GraftPort - Raspberry Pi Pico Expansion Board (Internal Edition Template Files)

Version Record

Document Version

Date of Modification

Modifier

Modified Content

V1.0.0

2025-09-11

Li Zisheng

Draft the initial version of the document.

V1.1.0

2026-01-04

Li Zisheng

Final version.