FindItem · 寻物

Light up the bin that holds your part. A reference parts-locator prototype with distributed devices and a centralized FastAPI/MQTT control plane.

English · 中文

---

English

Status — reference prototype. This repository contains the FastAPI/MQTT control plane, ESP32-C3 firmware, web client, and automated tests. The current hardware target is a single GPIO LED, buzzer, and stop button. The public experience is a static simulation: it does not connect to a live backend, broker, or physical device. Automated tests and firmware compilation are not a substitute for end-to-end hardware validation, which has not yet been completed for this competition build.

What it does

FindItem is designed to turn storage bins into a searchable, addressable system. You search for a part from a phone or web page; the reference control path sends a command to the target ESP32-C3, which drives an LED and buzzer. Devices are distributed and driven over MQTT via a centralized FastAPI control plane.

Built for makerspaces, labs, and robotics teams — anywhere "which box is it in?" is a daily question.

How it works

flowchart LR
    UI["📱 Phone / Web UI"] -->|"HTTPS · POST /api/search-events"| BE
    BE["⚙️ Backend<br/>FastAPI reference<br/>(the only MQTT publisher)"]
    CAT[("📒 items.json<br/>hot-reloadable catalog")] -. "read per request" .-> BE
    BE -->|"publish findit/device/{id}/command"| BR["🦟 Mosquitto<br/>MQTT broker (auth)"]
    BR -->|"command"| ESP["🔌 ESP32-C3<br/>LED + buzzer + stop button"]
    ESP -->|"publish .../status"| BR
    BR -->|"status: state · stop_reason"| BE
    BE -. "/api/events live feed" .-> UI

Loading

The frontend only ever talks HTTPS to the backend. The backend is the single place that publishes MQTT commands to devices — clients never touch the broker directly; devices report back on a status topic, which the backend turns into live state and a user-attributed recent event feed.

Features

• 🔦 Visual + audio locate — LED lights the target bin, buzzer confirms
• 🔕 Per-search buzzer toggle — light-only mode for quiet rooms, end to end
• 🔁 Live status & event feed — poll device state and a recent-activity timeline
• 🧩 Hot-reloadable catalog — edit config/items.json, no backend restart
• 🔒 Password-auth MQTT + HTTPS frontend — broker requires credentials (unencrypted on the LAN; enable an 8883 TLS listener for production); the Python backend serves the frontend over HTTPS with self-signed certs

Not implemented in this reference build: WS2812/RGB output, multi-user multi-color concurrency, LWT/heartbeat offline detection, persistent SQLite history, Feishu login, battery monitoring, and admin CRUD.

Tech stack

Layer	Tech
Firmware	ESP32 · Arduino (C++) · PubSubClient · ArduinoJson
Backend	Python · FastAPI · paho-mqtt
Broker	Mosquitto (MQTT)
Frontend	Vanilla HTML / CSS / JS

The Python FastAPI backend is the primary reference implementation. Java/Spring Boot backends exist in the repository but are not guaranteed to implement the full contract — verify feature parity before using them.

• backend/ — Python · FastAPI (reference implementation)
• backend-java/ — Java 17 · Spring Boot 3.2
• backend-java8/ — Java 8 · Spring Boot 2.7

Quick start (Windows + PowerShell)

Requires Python, Mosquitto, and Git for Windows (ships with openssl).

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

.\scripts\init-mqtt-passwd.ps1   # create the MQTT password file
.\scripts\gen-certs.ps1          # generate a self-signed HTTPS cert
.\scripts\start-all.ps1          # start Mosquitto + the backend

The backend listens on https://0.0.0.0:8443. On the same LAN, open https://<your-laptop-ip>:8443 from a phone (accept the self-signed cert warning).

Flash the firmware

1. Install the ESP32 board package in Arduino IDE.
2. Install libraries PubSubClient and ArduinoJson.
3. Open esp32/findit_esp32.ino and edit the config block at the top: WIFI_SSID / WIFI_PASSWORD, MQTT_HOST (your laptop's LAN IP), and a unique DEVICE_ID matching an entry in config/items.json.
4. Select board + port, upload. The device connects to Wi-Fi → MQTT on boot.

Default wiring (override the macros at the top of the .ino):

Component	GPIO	Notes
LED	2	active-high (onboard LED works)
Buzzer	5	passive buzzer, driven with tone() at 2 kHz
Button	4	to GND, INPUT_PULLUP, press = low (stops the ring)

API

HTTPS REST (frontend ↔ backend)

Method	Path	Purpose
GET	/api/items	catalog (hot-reloaded)
POST	/api/search-events	start / stop a locate
GET	/api/devices	all device states
GET	/api/devices/{id}	one device
GET	/api/events?limit=N	recent event feed

POST /api/search-events:

{ "user_id": "u1", "user_name": "Alice", "item_id": "FINDIT-001", "action": "start", "buzzer": true, "duration": 15 }

buzzer:false → light only. Omit duration to use the item's default. A busy device returns 409 device_busy.

MQTT (backend ↔ ESP32)

Topic	Direction
findit/device/{id}/command	backend → device
findit/device/{id}/status	device → backend

// command
{"cmd":"start","item_id":"FINDIT-001","event_id":"...","duration":15,"buzzer":true}
// status
{"state":"ringing","device_id":"esp32-001","buzzer_on":true}
{"state":"idle","stop_reason":"button"}   // button | timeout | backend

Project layout

backend/app/main.py         FastAPI app & REST endpoints
backend/app/mqtt_bridge.py  MQTT client, device state, event log
frontend/index.html         web client (with buzzer toggle)
config/items.json           part catalog (hot-reloaded)
mosquitto/mosquitto.conf    broker config
esp32/findit_esp32.ino      device firmware
scripts/*.ps1               cert / password / launch helpers

Security

mosquitto/passwords and the TLS keys under certs/ are gitignored and never committed. The findit123 in the code is a placeholder default — change it before any real deployment and update both the ESP32 sketch and the backend's MQTT_PASS. The demo uses a self-signed certificate; for a public domain, terminate HTTPS with Let's Encrypt or a Cloudflare Tunnel.

License

MIT © 2026 Harry Xin (@HarryXin0919)

---

中文

状态——参考原型。 本仓库包含 FastAPI/MQTT 控制面、ESP32-C3 固件、网页 客户端与自动化测试。当前硬件目标是单色 GPIO LED、蜂鸣器和停止按钮。 公开体验页 是静态模拟，不连接真实后端、MQTT broker 或实体设备。自动化测试和固件编译 不等于真机端到端验证；本次参赛版本尚未完成该验证。

是什么

FindItem 的设计目标是把存储箱变成可搜索、可寻址的系统。你在手机或网页上搜索 零件，参考控制链路会向目标 ESP32-C3 下发指令，由它驱动单色 LED + 蜂鸣器。 设备分布式部署，通过集中式 FastAPI/MQTT 控制面驱动。

适合创客空间、实验室、机器人队 —— 任何"这玩意儿在哪个箱"是日常问题的场景。

工作原理

手机 / 网页  ──HTTPS──▶  FastAPI  ──MQTT──▶  Mosquitto  ──MQTT──▶  ESP32(LED + 蜂鸣器)

前端只通过 HTTPS 与后端通信;后端是唯一向设备发布 MQTT 命令的地方 —— 客户端永远 不直连 broker。

功能

• 🔦 声光定位 —— LED 点亮目标箱,蜂鸣器确认
• 🔕 逐次蜂鸣器开关 —— 安静场合可只亮灯,开关贯通全链路
• 🔁 实时状态与事件流 —— 轮询设备状态 + 近期活动时间线
• 🧩 热加载物品库 —— 改 config/items.json 不用重启后端
• 🔒 MQTT 鉴权 + HTTPS —— broker 要求账密,局域网用自签证书

当前参考版本尚未实现：WS2812/RGB、多用户多颜色并发、LWT/心跳离线 判定、SQLite 持久历史、飞书登录、电量监控和管理员 CRUD。

技术栈

层	技术
固件	ESP32 · Arduino(C++)· PubSubClient · ArduinoJson
后端	Python · FastAPI · paho-mqtt
Broker	Mosquitto(MQTT)
前端	原生 HTML / CSS / JS

Python FastAPI 后端是主要参考实现。Java/Spring Boot 后端在仓库中存在, 但不保证实现了完整契约 —— 使用前请验证功能一致性。

快速开始(Windows + PowerShell)

需要 Python、Mosquitto、Git for Windows(自带 openssl)。

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

.\scripts\init-mqtt-passwd.ps1   # 生成 MQTT 密码文件
.\scripts\gen-certs.ps1          # 生成自签 HTTPS 证书
.\scripts\start-all.ps1          # 启动 Mosquitto + 后端

后端监听 https://0.0.0.0:8443。同一局域网下,手机打开 https://<笔记本-IP>:8443(自签证书首次会弹安全警告,选"继续访问")。

烧录固件

1. Arduino IDE 装好 ESP32 板包。
2. 安装库 PubSubClient 和 ArduinoJson。
3. 打开 esp32/findit_esp32.ino,改顶部配置块:WIFI_SSID / WIFI_PASSWORD、 MQTT_HOST(笔记本局域网 IP)、唯一的 DEVICE_ID(与 config/items.json 对齐)。
4. 选板子 + 端口,上传。上电后自动连 Wi-Fi → MQTT。

默认接线(改顶部宏即可):

元件	GPIO	说明
LED	2	高电平亮(板载 LED 也行)
蜂鸣器	5	无源蜂鸣器,tone() 输出 2 kHz
按钮	4	接 GND,INPUT_PULLUP,按下 = 低(停止响铃)

安全说明

mosquitto/passwords 和 certs/ 下的密钥都已 gitignore,不会提交。代码里的 findit123 只是占位默认密码 —— 正式部署前请更换,并同步改 ESP32 固件与后端的 MQTT_PASS。demo 用自签证书;要上正式域名,用 Let's Encrypt 或 Cloudflare Tunnel 终止 HTTPS。

许可

MIT © 2026 Harry Xin(@HarryXin0919)