🐾 Pet-to-Pet (P2P) Protocol
🌍 让每一个数字宠物都不再孤单 | Make Every Digital Pet Social
简介：
Pet-to-Pet是一个去中心化的、基于 NFC 的开源协议与固件套件。它旨在赋予现有的桌面机器人、电子手办、DIY 智能硬件以“社交灵魂”。无需云端服务器，两个设备只需轻轻“碰一碰”，即可交换身份、计算性格匹配度，并触发独特的互动表情与动作。愿景：打破硬件孤岛，构建一个万物互联的“数字宠物元宇宙”。
🚀 核心特性 (Features)
- 🤝 离线社交 (Offline-First)：所有交互基于本地 NFC 通信与边缘计算，无需联网，隐私安全，响应毫秒级。
- 🧠 性格向量匹配 (Personality Vector Match)：内置轻量级算法，通过对比双方存储的“喜好/性格向量”，实时计算匹配度（0-100%）。
- 🎭 动态表情反馈 (Dynamic Expression)：根据匹配结果，自动驱动屏幕显示开心、惊讶、生气等表情，或触发动作（如跳舞、震动）。
- 🔌 硬件无关性 (Hardware Agnostic)：支持 ESP32, M5Stack, Raspberry Pi Pico, Arduino 等多种主流开源硬件平台。
- 🎨 可定制皮肤 (Customizable Skins)：社区驱动的表盘与表情包库，支持 AI 生成的像素头像。
🛠️ 快速开始 (Quick Start)
1. 准备硬件 (Hardware Requirements)
你需要至少两套以下配置的设备来体验 P2P 社交：
表格
| 组件 | 推荐型号 | 备注 |
|---|---|---|
| 主控板 | ESP32-S3 / M5StickC Plus2 / RPI Pico W | 需带屏幕 (OLED/TFT) |
| NFC模块 | PN532 (推荐) / RC522 | 支持读写与卡模拟模式 |
| 电源 | 3.7V 锂电池 | 或通过 USB 供电 |
| 外壳 | 3D打印件 / 现有机器人外壳 | 需将 NFC 天线贴近表面 |
💡 懒人方案：直接购买两个 M5StickC Plus2 + PN532 Hat，无需焊接，插上即用。
2. 烧录固件 (Flash Firmware)
我们提供预编译的固件 (.bin) 和完整的源代码。
bash
编辑
1# 克隆仓库 2git clone https://github.com/yourname/pet-to-pet.git 3cd pet-to-pet/firmware 4 5# 使用 PlatformIO 或 Arduino IDE 打开 6# 配置你的 WiFi (仅用于初始配网，后续交互无需WiFi) 7# 上传代码到设备
3. 初始化配置 (Initialization)
首次启动时，设备会进入“配网模式”：
- 手机连接设备热点
PetSetup_XXXX。 - 访问
192.168.4.1打开配置页。 - 设置性格：滑动滑块设置你的宠物属性（如：活泼度、内向度、喜爱颜色等），系统会自动生成 特征向量。
- 上传头像：上传一张图片，系统会自动转换为适合屏幕显示的像素图。
- 数据写入 NFC 芯片，配置完成！
4. 开始社交 (Start Socializing)
- 动作：将两个已配置好的设备背部（NFC 区域）贴近。
- 现象：
- 🔵 蓝光闪烁：正在读取数据…
- 🟢 绿灯常亮 + ❤️表情：匹配度 > 80% (灵魂伴侣！)
- 🟡 黄灯呼吸 + 😐表情：匹配度 40%-80% (普通朋友)
- 🔴 红灯快闪 + 😡表情：匹配度 < 40% (气场不合)
- 日志：双方设备都会记录这次相遇的时间、对象 ID 和匹配度。
📡 技术原理 (How It Works)
协议架构
P2P 协议运行在 NFC Forum Type 4 Tag 标准之上，数据存储在 NDEF 记录中。
数据结构 (JSON Payload)
每个设备的 NFC 芯片中存储如下核心数据块（最大 1KB）：
json
编辑
1{
2 "proto_ver": "1.0",
3 "device_id": "uuid-v4-string",
4 "owner_sig": "sha256_hash",
5 "vector": [0.85, 0.12, 0.99, 0.45, 0.30], // 归一化后的5维性格向量
6 "skin_id": "pixel_cat_01",
7 "last_seen": 1709123456
8}
匹配算法 (Matching Logic)
为了适应微控制器 (MCU) 的低算力，我们采用简化的 余弦相似度 (Cosine Similarity) 算法：
Similarity=∥A∥∥B∥A⋅B
- 计算耗时：< 10ms (ESP32 @ 240MHz)
- 无需浮点单元 (FPU) 优化，纯整数运算版本可选。
状态机 (State Machine)
固件内部运行一个简单的状态机：IDLE (休眠/待机) ➔ DETECT (检测到射频场) ➔ READ (读取对方数据) ➔ CALC (本地计算) ➔ REACT (驱动屏幕/LED/马达) ➔ LOG (记录日志) ➔ IDLE
📂 项目结构 (Project Structure)
text
编辑
1pet-to-pet/ 2├── docs/ # 详细文档与原理图 3├── firmware/ # 嵌入式固件源码 4│ ├── src/ 5│ │ ├── nfc_driver/ # NFC 驱动层 (PN532/RC522) 6│ │ ├── match_engine/ # 向量匹配算法核心 7│ │ ├── ui_renderer/ # 屏幕渲染引擎 (支持多种分辨率) 8│ │ └── main.cpp # 主逻辑 9│ ├── platforms/ # 不同硬件平台的配置文件 10│ │ ├── m5stickc/ 11│ │ ├── esp32_devkit/ 12│ │ └── pico_w/ 13│ └── lib/ # 依赖库 14├── hardware/ # 硬件设计文件 15│ ├── pcb/ # KiCad 工程文件 (核心扩展板) 16│ ├── stl/ # 3D打印外壳模型 17│ └── bom.csv # 元件清单 18├── app/ # (可选) 手机配置 App 源码 (Flutter) 19├── tools/ # 向量生成器、皮肤转换工具 20└── README.md
🤝 如何贡献 (Contributing)
我们要构建的是生态，不仅仅是一个项目！欢迎各种形式的贡献：
- 适配新硬件：让你的旧玩具支持 P2P 协议。
- 设计新皮肤：提交像素风表情包或 UI 主题。
- 优化算法：让匹配更精准，或引入更有趣的互动逻辑（如“石头剪刀布”游戏）。
- 翻译文档：帮助全球开发者理解项目。
请查看 CONTRIBUTING.md 了解详细指南。
📜 许可证 (License)
本项目采用 MIT License 开源。
- 你可以自由地使用、修改、分发代码。
- 你可以基于此协议制造并销售商业硬件（我们鼓励这样做！）。
- 唯一的要求是：保留原作者署名，并开源你对核心协议的修改。
🌟 社区展示 (Showcase)
- [视频] 两个 M5Stack 机器人的第一次约会 – by @MakerA
- [教程] 如何给 Eilik 机器人加装 P2P 社交模块 – by @RobotLover
- [设计] 赛博朋克风格 P2P 外壳分享 – by @DesignerX
(此处链接指向社区实际内容)
📬 联系方式
- Discord 社区: 加入讨论
- Issues: 提交 Bug 或建议
- Email: mailto:hello@pet-to-pet.org
“Technology is best when it brings people together.”
但首先，它得让他们的宠物先聊起来。 🐶🤝🐱