Contents
- Project Description
- 1. Introduction
- 2. Main Functions
- 3. Hardware Requirements
- 4. Software Environment
- 5. File Structure
- 6. Description of Key Documents
- 7. Core Idea of Software Design
- 8. Instructions for Use
- 9. Sample Program
- 10. Notes
- 11. Version Record
- 12. Contact the Developer
- 13. Licensing Agreement
- Appendix I: Project Source Code Download
- Appendix II: Hardware Module Reference Materials
- Version Record
Project Description
1. Introduction
1.1 Project Background
Traditional sound playback devices mostly feature fixed tones or preset music, and lack the capability of real-time interaction with the environment. This project is based on the GraftPort-RP2040 development board, and integrates the color recognition module based on TCS34725, the power amplifier speaker module based on LM386 chip and the touch key module based on TTP223 to implement an interactive music system with the workflow of " RGB color recognition - tone conversion - real-time playback", which addresses the problem of single interaction mode of traditional audio devices. Meanwhile, it incorporates the asynchronous task processing and anti-shake mechanism of MicroPython to ensure the real-time response of the system.
1.2 Overview of Main Functions of the Project
This project is developed based on MicroPython. Its core function is to collect color data in real time via the color recognition module based on TCS34725, convert the data into tones of corresponding frequencies, and play the tone sequence through the power amplifier speaker module based on the LM386 chip; it supports the touch key module based on TTP223 to control the start and stop of collection, with built-in asynchronous playback to avoid blocking the main loop, and a complete exception handling mechanism to ensure stable system operation.
1.3 Applicable Scenarios or Application Area
- Music education: Generate corresponding tones through color recognition for music enlightenment education;
- Art Installation: An interactive device that transforms visual art into an auditory experience;
- Teaching Demo: For
MicroPythonasynchronous programming,I2Ccommunication,PWMaudio output and other knowledge points in practical teaching; - Entertainment and Interaction: Develop color-recognition music games or creative musical instruments.
2. Main Functions
- Real-time RGB color acquisition: via the color recognition module based on TCS34725 to collect
RGBcolor data, supporting raw data reading; - Color-to-tone conversion: map the maximum value of the
RGBcomponents to tones of different frequencies (red →500Hz, green →1000Hz, blue →1500Hz, others →2000Hz); - Touch key interaction: When the touch key is pressed, color data is continuously collected, and the tone sequence is played after the key is released;
- Playback Interruption Control: Press the button during playback to immediately stop the current playback and start a new acquisition;
- Debounce Mechanism: Software debounce is adopted for key detection to ensure operation accuracy;
- Exception Fault Tolerance Mechanism: All critical operations incorporate exception handling, and the acquisition status will be automatically reset when sensor reading fails.
3. Hardware Requirements
3.1 Hardware Required
The project is based on the GraftPort-RP2040 development board as the main controller:

Other required modules include:

- Color recognition module based on TCS34725:(
I2Ccommunication, address range0x29-0x3E); - Power Amplifier Speaker Module Based on LM386 Chip:(
PWMOutput, Connect toDIOPin); - Touch key module:(digital input, connected to
DIOpin); - Onboard LED: Used for status indication (Pin 25);
- Onboard button: Used for task start/stop control (Pin 18, pull-up input).
3.2 Hardware Connection
Color recognition module based on TCS34725: Connected via PH2.0 connecting cable to I2C0 interface;

Power Amplifier Speaker Module Based on LM386 Chip: connected to PH2.0 connector cable DIO1 interface;
Touch key module: connected via PH2.0 cable to the DIO0 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 casing (M3 screw holes are pre-reserved on both the main control board and the casing):


Next, secure the periphery of the housing with M3 plastic pillars, then fasten 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 you can charge it 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); - Supporting Tools:
Python 3.12+(optional, for running local helper scripts such as firmware flashing scripts);mpy-cross v1.23.0(used to. pyfiles compile into. 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
color_recognition_audio
├─ .flake8
├─ LICENSE
├─ README.md
├─ tools
│ ├─ dependency_analyzer.py
│ ├─ mpy_compiler.py
│ ├─ mpy_uploader.py
│ └─ README.md
├─ firmware
│ ├─ board.py
│ ├─ boot.py
│ ├─ conf.py
│ ├─ main.py
│ ├─ tasks
│ │ ├─ maintenance.py
│ │ ├─ sensor_task.py
│ │ └─ __init__.py
│ ├─ libs
│ │ ├─ __init__.py
│ │ └─ scheduler
│ └─ drivers
│ ├─ __init__.py
│ ├─ tcs34725_color_driver
│ ├─ passive_buzzer_driver
│ └─ button_driver
├─ examples
└─ docs
6. Description of Key Documents
main.py: Project entry point, with core logic including:- Power on and delay for 3 seconds (wait for hardware to stabilize), initialize the onboard
LED,I2Cbus, color recognition module based on TCS34725, LM386 speaker, and touch key (including interrupt registration); - Hardware initialization:
I2C0bus scan to identifyTCS34725address, initialize the color recognition module based on TCS34725, speaker, and touch button; - 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 critical error handling).
- Power on and delay for 3 seconds (wait for hardware to stabilize), initialize the onboard
tasks/sensor_task.py: Core business task. Key logic of theSensorRGBSoundTaskclass:__init__: Initializes the hardware instance and state variables (_pressed,_reading,_sequence,_is_playing, etc.);tick: Executed every 200ms, the process is "touch status detection → RGB Data Acquisition → color frequency conversion → asynchronous tone playback";_color_to_freq:RGBcolor-to-frequency mapping algorithm (red →500Hz, green →1000Hz, blue →1500Hz, others →2000Hz);_stop_playback: Stop the current playback and reset the playback status flag;_play_async: Asynchronously plays a tone sequence to avoid blocking the main loop
tasks/maintenance.py: System maintenance module, key functions:task_idle_callback: Triggered when the scheduler is idle; if it detects that the 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, prints the full traceback (preferentially usessys.print_exception), then delays forERROR_REPEAT_DELAY_S(1 second by default) to prevent screen flooding;- Supports reading configurations from
conf.py, and uses default values when no configuration is provided to ensure compatibility.
drivers/xxx_driver: hardware driver modules, all adopting the "instantiation + method call" pattern, only expose hardware-related control interfaces while shielding underlying details:tcs34725_color_driver:The TCS34725class communicates viaI2C, and thereadmethod reads the rawRGBcolor data.lm386_speaker_driver:The LMSpeakerclass controls tone output viaPWMand provides methods includingplay_sequence,stop, etc.button_driver:TouchKeyclass detects the touch status, theget_statemethod returns the button status, with built-in debounce processing.
board.py: a board-level pin mapping module that defines theBOARDSdictionary (including the fixed pins ofGraftPort-RP2040and the mapping ofI2C/DIOinterfaces), and provides interfaces such asget_fixed_pin,get_i2c_pins, andget_dio_pinsto achieve "decoupling of board-level configuration and business logic"; to extend support for other development boards later, you only need to add sub-items toBOARDS.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 Idea of Software Design

- System Hierarchy Concept: Adopts a "four-tier architecture" to achieve decoupling and reuse
- Hardware Driver Layer (
drivers/): It is only responsible for the low-level control of hardware and contains no business logic. For example, the color recognition module driver based on TCS34725 only cares about "how to obtainRGBdata" and does not care about "when to play the tone";the LM386speaker driver only cares about "how to play the tone sequence" and does not care about "the source of the tone frequency"; the touch key driver only cares about "how to detect the touch state" and does not care about "the business logic after the touch". - Task Logic Layer (
tasks/): Implements business logic based on the interfaces provided by the driver layer. For example,SensorRGBSoundTaskonly callsTCS34725.read ()to obtain color data without concerning itself with the sensor'sI2Caddress; it only callsLMSpeaker.play_sequence ()to play tones without concerning itself with thePWMpin configuration; it only callsTouchKey.get_state ()to detect key states without concerning itself with the hardware implementation of touch detection. - Scheduling Control Layer (
libs/scheduler.py): It provides general 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 through a soft timer to ensure reasonable allocation of system resources. - Entry Layer (
main.py): It is responsible for "assembling" all layers, following the sequence of initializing hardware → creating tasks → starting scheduling. Acting as the "glue" of the system, it contains no core business logic; it also handles hardware exceptions and user interactions to ensure the stable startup and operation of the system.
- 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, for example
maintenance.pyonly handles system maintenance (GC, exceptions) and does not involve color collection;sensor_task.pyonly handlesRGBData Acquisition and tone playback logic, and does not care about hardware initialization; each driver module only encapsulates the control methods of the corresponding hardware. - Low coupling: Modules interact through "interfaces" instead of directly manipulating internal variables, for example
SensorRGBSoundTaskobtains data viaTCS34725.read ()without directly operatingI2Cregisters; plays tones viaLMSpeaker.play_sequence ()without directly controllingPWMhardware; detects status viaTouchKey.get_state ()without directly readingGPIOlevels. - Scalability: When adding new hardware (such as a light sensor), you only need to add the corresponding driver under
drivers/, create a new task undertasks/, and no modification to existing code is required; when expanding the development board, you only need to add pin mappings inboard.py, which will not affect the business logic; when adding a new playback mode, you only need to modify the tone mapping logic ofSensorRGBSoundTask, without involving any changes at the hardware layer.
- High Cohesion: each module is only responsible for the Single Responsibility Principle, for example
- Core Mechanism: Ensuring System Stability and User Experience
- Task scheduling mechanism: Implemented based on a soft timer (
Timer (-1)), with a scheduling cycle of 50ms and a core task cycle of 200ms. It judges whether a task is due for execution via "counter accumulation" to avoid timer nesting conflicts; it supports dynamic task suspension and resumption to respond to user operations. - Asynchronous Playback Mechanism: Adopts a "thread separation" strategy, where the playback of the tone sequence is executed in an independent thread, which not only avoids blocking the main loop (ensuring real-time response to touch keys) but also guarantees the integrity of tone playback; the synchronization between the playback thread and the main thread is coordinated via status flags.
- Interactive feedback mechanism
: The touch keys feature "instant response": RGB Data Acquisition starts immediately when the key is pressed, and tone playback launches right after the key is released; the on-board key interrupt callback takes "instant effect": all audio output stops immediately upon pause, eliminating unresponsive user operations; when sensor initialization fails, an "explicit error alert"(LEDblinking + terminal message) is triggered to facilitate troubleshooting of hardware connection issues. - Fault-tolerant mechanism: All key operations (such as hardware control, data reading) are wrapped with
try-exceptto prevent the failure of a single module from causing the entire system to crash. For example, a failure in reading the color sensor will not affect the operation of task scheduling; an audio playback exception will not affect the detection of touch buttons; the automatic memory reclamation mechanism prevents memory leaks during long-term operation; the debounce mechanism ensures the accuracy of touch detection.
- 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 the 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, 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
- Color acquisition: Place objects of different colors in front of the sensor, and observe the
RGBvalues and recognition results output by the terminal;
- Tone playback: The corresponding tone sequence shall be played after the touch key is released;
- Interrupt Control: When the touch button is pressed during playback, the playback shall stop immediately;
- Task Control: The onboard buttons can toggle the running/paused status of tasks.
The terminal output is as follows:

8.5 Debugging and Problem Localization
- If the function malfunctions, ensure that
ENABLE_DEBUG= Trueto view the debug information; - If the sensor initialization fails, check the
I2Cconnection and address; - If there is no sound output, check the connection of the speaker module and the
PWMconfiguration.
9. Sample Program
There are no other reference sample codes for this project, you can directly firmware make modifications in the folder.
10. Notes
- Sensor-related Notes:
TCS34725Requires appropriate lighting conditions; avoid direct exposure to strong light; - Audio-related notes:
The LM386module should not be set to an excessively high volume to avoid distortion; - Thread safety: Pay attention to the synchronization of state variables during asynchronous playback;
- Power Requirements: Ensure stable power supply to avoid voltage drops during audio playback.
11. Version Record
- v1.0.0 (2025-10-10): Basic functions implemented
- Supports
RGBreal-time color capture and tone conversion - Implement touch key control and asynchronous playback
- Complete exception handling and state management
- Supports
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:
- Share — to copy, distribute the work in any medium or in any form
- Derivative Works — modify, transform, or create based on this 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. 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 belongs to FreakStudio.
Appendix I: Project Source Code Download
https://github.com/FreakStudioCN/GraftPort_MicroPython_Labs/tree/main/color_recognition_audio
Appendix II: Hardware Module Reference Materials
Color Recognition Module Based on TCS34725
Power Amplifier Speaker Module Based on LM386 Chip
GraftPort - Raspberry Pi Pico Expansion Board (Open Edition Template Files)
Version Record
Document Version | Date of Modification | Modifier | Modified 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. |