Labs / MicroPython module projects

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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

Contents

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

2. Main Functions

3. Hardware Requirements

3.1 Hardware Required

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

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

Other required modules include:

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

3.2 Hardware Connection

Color recognition module based on TCS34725: Connected via PH2.0 connecting cable to I2C0 interface;

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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.

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)
Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)
Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)
Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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:

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

4. Software Environment

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

7. Core Idea of Software Design

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)
Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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.

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

Set Project/firmware as the project root directory.

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

Modify the runtime configuration:

Color Recognition Linked Audible-Visual Feedback Device (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.

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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 startup

8.4 Functional Testing

The terminal output is as follows:

Color Recognition Linked Audible-Visual Feedback Device (Based on GraftPort-RP2040 Development Board)(Open Version)

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/color_recognition_audio

Appendix II: Hardware Module Reference Materials

Color Recognition Module Based on TCS34725

Power Amplifier Speaker Module Based on LM386 Chip

Touch Key Module

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.