Welcome to the world of hardware making. Before you write your very first line of code, let's get to know what's inside your treasure box and what each of these little parts can do.

1. Unboxing: Your Maker's Treasure Box

The moment you open the kit, you might see a bunch of odd-looking little things. Don't panic. Each one has a clear purpose. Just like LEGO bricks, they may not look like much on their own, but together they build a castle.

2. Core Team Members: Know Every Part at a Glance

3. Three Golden Safety Rules

Before you start building, commit these iron rules to memory. They're not constraints. They're shields that protect both you and your components.

Rule One: Power Off Before Plugging or Unplugging

Whenever you're about to plug in or remove a wire, first make sure the dev board is unpowered. Don't touch anything on the breadboard while the USB cable is plugged in, especially the power (red) and ground (black) wires. A short circuit can fry components and even burn your fingers.

Imagine you're unplugging an appliance from a wall socket. You wouldn't start pulling wires while it's still plugged in, would you?

Rule Two: Water Is a Circuit Board's Worst Enemy

Keep your desk dry. The dev board, breadboard, and every electronic component fear water. Keep your drinking cup on the other side of the table, never next to your circuit.

Later in the course you'll use the water pump. When that time comes, be extra careful to direct water flow away from all electronics.

Rule Three: Handle Every Component Gently

• Jumper wires: Grip the plastic housing to pull, never yank the wire body
• Dev board: Hold the board by its edges, don't squeeze the components on top
• Breadboard: Insert wires straight down, never force them in at an angle
• Header pins: The ESP32's two rows of thin gold pins bend easily. Once bent, they're hard to insert into the breadboard. Handle with care.

4. First Power-Up: Bring the Dev Board to Life

Before writing any code, let's run a zero-code experiment. Just to confirm your dev board itself is working.

1. Take out your ESP32-S3 dev board and place it on the desk
2. Connect the dev board to your computer with the USB-C cable
3. Observe: The moment you plug it in, the LED on the board should briefly flash or light up

If you see the light turn on, your board is alive. If there's no response at all, try a different USB port or a different cable. Some USB cables can only charge and cannot transfer data. Those will cause upload problems later too.

This is your very first small victory on this journey. Every lesson from here on follows the same pattern: do one small thing, see one immediate result. The code you write doesn't live inside a screen. It lives in the real world.

5. A Preview of What You'll Build

Stop One: The Fruit Piano (Levels 1–2)

You'll build a piano that lights up and plays music when you touch fruit. A banana becomes Do, an apple becomes Re, an orange becomes Mi. Touch it with your finger and the LED strip glows and the buzzer sings. You'll go from a single key all the way to a full 7-key instrument, from simple triggering to behaving like a real instrument (hold to sustain, release to stop), and finally the OLED screen will show you exactly which note you're playing.

Stop Two: Wireless AIoT Fruit Piano (Level 3)

Your piano evolves. The XiaoZhi AI host will remotely control your piano through wireless signals. The host says "lights on" and your entire LED strip glows white. The host says "play Do" and your piano automatically sounds the note Do. You'll watch an entire chain run: AI speaks a sentence, then your device performs an action.

Stop Three: Smart Practice Piano (Level 4)

Your piano won't just passively follow orders. It will remember your practice sessions: how many times you got it right, how many wrong, how fast you reacted. The screen will show your score and performance in real time. It even has a built-in guided mode for teaching you to play Twinkle Twinkle Little Star.

6. Mindset Prep: What "Normal" Learning Looks Like

Before we officially begin, one thing is worth saying upfront.

Failure Is Normal. It Doesn't Mean You're "Bad at This."

In the world of hardware development, the following scenarios are completely normal:

• Your code fails to upload and the screen fills with red error messages
• You've plugged everything in correctly but nothing lights up or makes a sound
• It worked perfectly last time, and now suddenly it doesn't
• After half an hour of struggle, you discover a loose wire

Every engineer, including the people who designed this very dev board, goes through this every single day. Failing doesn't mean failure. Finding the cause after you fail is what learning is. The problem-solving process itself is proof you're growing.

Each Lesson Only Moves One Small Step Forward

Our course design principle: each lesson introduces only 1–2 new ideas. Everything else is something you already know how to do. You won't suddenly be thrown into the deep end. At the end of every lesson, you'll have something in your hands that works, that you can see, and that you can touch.

7. Pre-Lesson Checklist

Before diving into your first official lesson, "1.1 Meet the ESP32," make sure the following are ready:

• Kit unboxed, all parts checked against the inventory
• ESP32-S3 dev board powers on successfully (the LED lights up)
• Arduino IDE installed on your computer
• A clean, dry workspace cleared on your desk
• Phone or camera ready. Your first build deserves to be recorded.

References

• Arduino IDE: arduino.cc/en/software
• ESP32 Arduino Core: docs.espressif.com/projects/arduino-esp32

The breadboard will be your wiring headquarters for every lesson ahead. It solves one core problem: connecting components and wires securely without any soldering. It sounds simple, but the breadboard hides a clever internal structure. Once you understand it, you'll never get lost wiring things up again.

1. Why Is It Called a "Breadboard"?

The name comes from its ancestor. Back in the 1960s, electronics hobbyists literally used wooden bread-cutting boards, hammering nails into them and soldering components on top. It eventually evolved into today's plastic plug-in board, but the name "breadboard" stuck.

2. The Underground City: An Intuitive Analogy

Think of the breadboard as an underground city.

• The holes on the surface are building entrances at street level
• The metal clips underneath are interconnected underground tunnels
• Any components plugged into the same underground tunnel have their legs connected

The key question: which holes share the same underground tunnel? Once you grasp this, the breadboard has no more secrets.

3. Internal Structure: Lifting the Veil

A standard 830-point breadboard can be divided into three zones.

Zone One: Top and Bottom Power Rails (Horizontal Connections)

Each end of the breadboard has two long rails, usually marked with a red line and a blue line (or + and −).

+---+---+---+---+---+---+---+---+---+---+---+---+---+
| + | X---X---X---X---X---X---X---X---X---X---X  ...  |  Every hole along this horizontal line is connected
| - | X---X---X---X---X---X---X---X---X---X---X  ...  |  Every hole along this horizontal line is connected
+---+---+---+---+---+---+---+---+---+---+---+---+---+
|                                                       |
|                   (Main area)                          |
|                                                       |
+---+---+---+---+---+---+---+---+---+---+---+---+---+
| + | X---X---X---X---X---X---X---X---X---X---X  ...  |
| - | X---X---X---X---X---X---X---X---X---X---X  ...  |
+---+---+---+---+---+---+---+---+---+---+---+---+---+

Rule: Every hole along the same horizontal rail is connected. Plug 5V into any hole on the red rail, and the entire red rail now carries 5V.

Zone Two: The Terminal Strip (Vertical Connection, 5 Holes per Column)

This is the breadboard's core work area.

       a   b   c   d   e          f   g   h   i   j
     +-----------------+     +-----------------+
  1  | o   o   o   o   o |     | o   o   o   o   o | 1
  2  | o   o   o   o   o |     | o   o   o   o   o | 2
  3  | o   o   o   o   o |     | o   o   o   o   o | 3
  4  | o   o   o   o   o |     | o   o   o   o   o | 4
  5  | o   o   o   o   o |     | o   o   o   o   o | 5
     +-----------------+     +-----------------+
       5 holes per column       5 holes per column
       all connected (a-e)      all connected (f-j)

Three rules:

1. In each column, holes a, b, c, d, and e are connected vertically.
2. In each column, holes f, g, h, i, and j are connected vertically.
3. The central groove separates the left half (a-e) from the right half (f-j). 1e and 1f are not connected.

Zone Three: The Central Groove

That groove down the middle isn't random. It's specifically designed for DIP-packaged IC chips to straddle across. The two rows of chip legs plug into the left and right sides of the breadboard, with each leg occupying its own independent column. In our course, the ESP32-S3 dev board itself straddles the central groove.

4. Three Most Common Wiring Patterns

Pattern One: Dev Board to Breadboard Power Rails

This is the first thing you'll do in almost every lesson:

ESP32 5V pin   --> jumper wire -->  Breadboard red rail (+)
ESP32 GND pin  --> jumper wire -->  Breadboard blue rail (-)

Now the entire red rail carries 5V, and the entire blue rail carries GND.

Pattern Two: Connecting a Component to a GPIO Pin

ESP32 GPIO pin       --> jumper wire -->  A column on the breadboard (e.g. 5a)
Component signal pin --> plug into same column (5b) -->  Now they're connected

The golden rule: To connect A and B, plug A's leg and B's leg into any two holes in the same column.

Pattern Three: Powering a Component from the Rails

Breadboard red rail (+)  --> jumper wire -->  Column where component VCC is plugged in
Breadboard blue rail (-) --> jumper wire -->  Column where component GND is plugged in

5. Hands-On Demo: Lighting Up an External LED

We haven't officially started programming yet, but we can already wire up a simple circuit to get a feel for the breadboard's wiring logic.

What You Need

• ESP32-S3 dev board
• Breadboard
• One LED (any color)
• One 220Ω resistor (color bands: red, red, brown)
• Two male-to-male jumper wires

Wiring Steps

1. Place the ESP32-S3 onto the breadboard. The dev board straddles the central groove. Press down gently until the pins are fully seated.
2. Insert the LED. Long leg (positive) → 10a. Short leg (negative) → 12a (different column).
3. Insert one end of the resistor into 12b (same column as the short leg). Insert the other end into the blue rail (GND).
4. Connect with jumper wires: One wire from 10b to the ESP32's 3.3V pin. One wire from the blue rail to the ESP32's GND pin.
5. Plug in the USB cable. The LED should light up.

       a   b   c   d   e          f   g   h   i   j
     +-----------------+     +---------------------+
 10  |[L]--[wire to 3.3V]|     |                     | 10  LED long leg at 10a
     | leg              |     |                     |
 11  |                  |     |                     | 11
 12  |[S]--[resistor]--..---> blue rail (GND)      | 12  LED short leg at 12a
     | leg              |     |                     |
     +-----------------+     +---------------------+

    Resistor bridges from 12b to any hole on the blue rail
    Blue rail connected to ESP32 GND with another wire

6. The Six Most Common Wiring Disasters

7. Debugging Mindset: Divide and Conquer

If you're not sure which part of the circuit is the problem, use this method:

1. Verify the source: Is there voltage on the red rail?
2. Split in half: Break the circuit into two halves. Test whether the left half can work independently.
3. Minimal reproduction: Strip down to only the core component (e.g., one LED + one resistor). Once confirmed, add components back one at a time.

You'll use this method over and over throughout this course. It works for more than just breadboards. Any time a complex system misbehaves, use the "minimize first, then gradually build back up" strategy.

8. Mini Challenges

1. Count it out: How many ESP32-S3 boards could your breadboard physically hold at once?
2. Draw it out: On paper, sketch a breadboard power rail diagram. How does the red rail deliver power to three different components?
3. Think it through: Without a breadboard, how would you connect an LED to an ESP32? (Answer: soldering, or alligator clips. This is exactly why breadboards are valuable.)

9. Bonus: Breadboard Size Variations

1. What This Project Can Do

The Smart Flowerpot automatically detects ambient temperature, air humidity, light level, soil moisture, and water tank level. When the soil gets too dry, it automatically turns on the pump to water the plant. An OLED screen displays current readings, while an RGB LED and buzzer provide status alerts. When paired with a XiaoZhi AI host, you can remotely query status, manually water, set automatic watering strategies, and calibrate the soil sensor.

Four Core Capabilities

2. Hardware You'll Need

2.1 Core Hardware

2.2 Water System Materials

• Small water tank
• Silicone tubing
• Small flowerpot and soil
• Zip ties / tape

3. Software Download & Installation

This project uses VS Code + PlatformIO. The Smart Flowerpot code is split across multiple .cpp and .h files, so PlatformIO is better suited than Arduino IDE for this project.

3.1 Install VS Code

1. Visit code.visualstudio.com
2. Download the version for your operating system
3. Double-click the installer and follow the prompts

3.2 Install the PlatformIO Extension

1. Open VS Code, click the Extensions icon on the left sidebar
2. Search for PlatformIO IDE
3. Click Install
4. After installation, a small ant icon will appear on the left sidebar

3.3 Install USB Serial Drivers

Common serial chips on ESP32-S3 dev boards are CH340 or CP2102. If no serial port appears after plugging in the board, install the appropriate driver.

3.4 Open This Project

1. In VS Code, click File → Open Folder
2. Select the project directory: PIO-esp32-espnow-flowerpot
3. Confirm you can see platformio.ini, include/, src/ in the root
4. PlatformIO will automatically install dependency libraries

4. Hardware Connections (Wiring)

4.1 Pin Assignment Table

I2C devices (DHT20, BH1750, OLED) share the same bus: all SDA → GPIO17, all SCL → GPIO18, all VCC → 3.3V, all GND → GND.

4.2 Wiring Diagram (Text Version)

                    +-----------------------------+
                    |        ESP32-S3 Dev Board     |
                    |                             |
DHT20 / BH1750 / OLED SDA --- GPIO17              |
DHT20 / BH1750 / OLED SCL --- GPIO18              |
HD-38 AO                --- GPIO4                 |
XKC-Y21 OUT             --- GPIO5                 |
Relay IN                --- GPIO6                 |
Passive Buzzer +        --- GPIO7                 |
WS2812B DIN             --- GPIO48                |
                    |                             |
3.3V --- DHT20 / BH1750 / OLED / HD-38 / Water Level|
5V   --- WS2812B / Relay / 5V small pump power     |
GND  --- All module GNDs must share common ground   |
                    +-----------------------------+

4.3 Pre-Power-On Checklist

• Are OLED, DHT20, BH1750 connected to 3.3V?
• Is HD-38 AO connected to GPIO4?
• Is Relay IN connected to GPIO6?
• Is the pump only connected to low-voltage 5V, not 220V?
• Are all GNDs connected together?
• Is the tubing secured so it won't spray onto the dev board?

5. Using the Complete Project Code

The Smart Flowerpot code is already split into multiple modules. Use the complete project in the directory as-is.

Key Files

Key Configuration Reference

Adjusting for Different Relay Modules

If relay behavior is reversed, open include/config.h and flip RELAY_ON_LEVEL and RELAY_OFF_LEVEL. For low-level triggered relays:

#define RELAY_ON_LEVEL  LOW
#define RELAY_OFF_LEVEL HIGH

6. Flashing the Program to the Board

6.1 Compile

1. Connect the ESP32-S3 to your computer via USB data cable
2. Open the PlatformIO icon on the left of VS Code
3. Find the environment esp32-s3-devkitc-1
4. Click Build
5. Wait for SUCCESS in the terminal

6.2 Upload

1. Click PlatformIO's Upload
2. If it gets stuck at Connecting...: hold down the BOOT button, click Upload, release BOOT once the upload starts

6.3 Open the Serial Monitor

1. Click PlatformIO's Monitor
2. Baud rate is 115200
3. Normal output includes: === Smart Flowerpot ESP32-S3 ===, I2C init confirmations, and [OK] System ready

7. Power-On Testing & Usage

RGB LED Status Guide

8. Using with the Host (XiaoZhi)

8.1 Flowerpot Commands the Host Can Send

8.2 ACK Result Codes

9. Troubleshooting Common Issues

Software Issues

Sensor Issues

Pump and Relay Issues

10. Appendix: Code Structure Overview

Main Loop: Eight-Step Pipeline

Step 1: Sensor sampling — DHT20, BH1750, soil moisture, water level
Step 2: OLED refresh — display temperature, humidity, light, soil, water, pump status
Step 3: Host command handling — WATER, INFO_*, FLOWER_*, RE_TRY
Step 4: Auto-watering check — starts only if soil is dry + water available + cooldown elapsed
Step 5: Watering monitor — stops pump on low water, soil becoming wet, or timeout
Step 6: ESP-NOW periodic reporting — reports flower_sensor every 5 seconds
Step 7: ESP-NOW maintenance — broadcast, bind, receive packets
Step 8: Buzzer and RGB state machine — non-blocking updates

Status Priority

Auto-Watering Logic

Auto-watering requires ALL of the following to be true:

1. Auto-watering is enabled
2. Soil moisture percentage is below threshold
3. Water level is normal
4. Pump is not currently running
5. Cooldown period since the last watering has elapsed

Commonly Adjusted Parameters

Open include/config.h to modify: WATERING_DURATION_MS, WATERING_COOLDOWN_MS, TEMP_HIGH_THRESHOLD, TEMP_LOW_THRESHOLD, HUMIDITY_LOW_THRESHOLD, LIGHT_LOW_THRESHOLD, SOIL_DRY_THRESHOLD, SOIL_WET_THRESHOLD.

1. What This Project Can Do

Use fruit as piano keys. Touch them with your fingers and hear piano notes. An LED strip changes color to match each note. Once you have a XiaoZhi host, you can also control the lights and music remotely.

Three Core Capabilities

2. Hardware You'll Need

2.1 Core Hardware

2.2 Optional Auxiliary Materials

• 7 kinds of fruit: apple, orange, banana, strawberry, pineapple, blueberry, grape
• Electrical tape / 3M double-sided tape
• Power bank (to run without a computer)

3. Software Download & Installation

This project uses Arduino IDE. Install it from arduino.cc/en/software.

3.1 Install ESP32 Board Support

1. Open Arduino IDE, go to File → Preferences
2. In "Additional boards manager URLs", paste: https://espressif.github.io/arduino-esp32/package_esp32_index.json
3. Go to Tools → Board → Boards Manager, search for esp32, install esp32 by Espressif Systems

3.2 Install Required Libraries

Via Sketch → Include Library → Manage Libraries, install:

• FastLED — LED strip control
• U8g2 by oliver — OLED display control

Also install the InsightEspNow communication library via Sketch → Include Library → Add .ZIP Library (obtained from course materials).

3.3 Select Board and Port

1. Connect the ESP32-S3 via USB data cable
2. Tools → Board → esp32 → ESP32S3 Dev Module
3. Tools → Port → select the COM port

4. Hardware Connections (Wiring)

4.1 Pin Assignment Table

4.2 Wiring Diagram

                    +---------------------------+
                    |     ESP32-S3 Dev Board      |
                    |                            |
  Fruit 1 (Apple) ---- GPIO1       GPIO12 ---- WS2812B LED Strip DIN
  Fruit 2 (Orange) --- GPIO2       GPIO15 ---- Buzzer Positive
  Fruit 3 (Banana) --- GPIO3       GPIO17 ---- OLED SCL
  Fruit 4 (Strawberry) GPIO4       GPIO18 ---- OLED SDA
  Fruit 5 (Pineapple) - GPIO5       |
  Fruit 6 (Blueberry) - GPIO6       |
  Fruit 7 (Grape) ---- GPIO7        |
                    |                            |
                    |   3.3V ---- OLED VCC       |
                    |   5V   ---- LED Strip VCC  |
                    |   GND  ---- LED Strip GND  |
                    |   GND  ---- Buzzer GND     |
                    |   GND  ---- OLED GND       |
                    +---------------------------+

5. Complete Code

The complete code is approximately 36KB. Create a new project in Arduino IDE (File → New), paste the entire code, and save as FruitPiano. The code handles touch detection, note playback, LED control, guided mode, and ESP-NOW wireless communication with the XiaoZhi host.

Key constants:

6. Flashing the Program to the Board

1. Confirm board settings: ESP32S3 Dev Module, USB CDC On Boot: Enabled, CPU: 240MHz
2. Click the Verify (checkmark) button to compile
3. Click the Upload (arrow) button to flash
4. If stuck at "Connecting...": hold BOOT, click Upload, release BOOT when it starts
5. Open Serial Monitor at 115200 baud. You should see: Fruit Piano helper READY

7. Power-On Testing & Usage

7.1 First Test: Touch the Fruit

1. The OLED shows "Fruit Piano / Starting..." then "[Free Play] + WiFi: --"
2. Touch the first fruit (apple). You should hear the "Do" note, see the first 7 LEDs light up red, and the OLED show "Play: Apple"
3. Release and the sound stops, lights turn off
4. Touch other fruits to hear do re mi fa sol la si, while LEDs change to orange, yellow, green, cyan, blue, purple

7.2 Test Guided Mode

1. Hold the first fruit (apple) for 5 seconds
2. OLED changes to "[Guide] Next: E4 + 1/32"
3. Touch the matching fruit. Correct advances; wrong flashes red for 0.2s and stays on the same note
4. After 32 notes it loops. Hold first fruit again for 5s to exit guided mode.

8. Using with the Host (XiaoZhi)

8.1 Commands the Host Can Send

8.2 Recommended Demo Sequence

1. Power on helper; OLED shows startup screen
2. Host discovers and pairs with helper; OLED shows "WiFi: OK"
3. Host sends RGB_Power ON; all LEDs light up white
4. Host sends RGB_ColorSet 255,0,0; LEDs turn red
5. Host sends RGB_EffectSet flow,60,0,255,255; cyan dot flows
6. Touch a fruit; buzzer sounds + LEDs change (touch takes priority over wireless lighting)
7. Hold first fruit 5s; enters guided mode
8. Host sends PIANO_PlayNote 3; buzzer plays fa for 0.3s

9. Troubleshooting Common Issues

Hardware Issues

Communication Issues

10. Appendix: Code Structure Overview

Seven-Step Pipeline

Step 1: Wireless communication — receive host commands
Step 2: Mode switch detection — hold Pin 1 for 5s to toggle guided mode
Step 3: Remote piano timeout — remote notes auto-stop after 300ms
Step 4: Touch piano scan — poll all 7 fruits
Step 5: Guide feedback timeout — correct/wrong feedback auto-clears on timeout
Step 6: Wireless lighting takeover — when nobody is playing, wireless lighting controls LEDs
Step 7: OLED refresh — update display content

Priority

Touch play has the highest priority. When someone is touching fruit, the host's lighting commands won't override the visual effect. Once the finger is released, wireless lighting takes over again.

Changing the Song

Guided mode has "Twinkle Twinkle Little Star" built in. To change the song, edit the GUIDE_NOTES[] array. Use C4 through B4 for do through si, and " " (a space) for rests. Update GUIDE_NOTE_COUNT to match the new total.