# YADAN-Flex

**Repository Path**: egg2bot/yadan-flex

## Basic Information

- **Project Name**: YADAN-Flex
- **Description**: YADAN-Flex 是“蛋壳计划”旗下的开源硬件项目，旨在革新传统咸鸭蛋的生产模式。我们通过构建柔性化、智能化的微型腌制单元，结合云端控制平台，实现**单颗/小批量咸鸭蛋的按需生产、远程监控与个性化定制**，将集中式、经验驱动的传统腌制，转变为分布式、数据驱动的柔性生产。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YADAN-Flex 🥚

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen)](docs/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](docs/4-贡献指南.md)

**按需腌制，一枚咸蛋的物联网革命。**

YADAN-Flex 是"蛋壳计划"旗下的开源硬件项目，旨在革新传统咸鸭蛋的生产模式。我们通过构建柔性化、智能化的微型腌制单元，结合云端控制平台，实现**单颗/小批量咸鸭蛋的按需生产、远程监控与个性化定制**，将集中式、经验驱动的传统腌制，转变为分布式、数据驱动的柔性生产。

## ✨ 核心特性

*   **单颗级精准控制**：每个智能腌制单元独立工作，可对不同蛋品实施不同的腌制配方。
*   **环境实时监测**：集成盐度与温度传感器，全程监控腌制核心参数，数据透明可视。
*   **云端配方驱动**：通过 Web 界面或 API 下发个性化腌制指令（时间、目标盐度等），实现 C2M (Consumer to Manufacture) 模式。
*   **全栈开源**：从硬件原理图、固件代码，到云端服务与前端界面，完全开源，可自由复刻、修改与商用（遵循 GPL v3 协议）。
*   **模块化设计**：硬件接口、软件协议均采用模块化设计，便于功能扩展（如增加湿度控制、蛋重监测）。

## 🏗 系统架构

YADAN-Flex 采用典型的三层物联网架构：

```
┌─────────────────────────────────────────────────────────────┐
│                       用户交互层                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Web界面   │  │ 移动端App   │  │   API调用   │        │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
│         │                 │                 │               │
└─────────┼─────────────────┼─────────────────┼───────────────┘
          │ HTTP/WebSocket  │                 │
┌─────────▼─────────────────▼─────────────────▼───────────────┐
│                     云端平台层                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │  Web服务器  │◄──►│ 业务逻辑    │◄──►│  数据库     │    │
│  │  (Flask)    │    │ (Node-RED)  │    │ (可选)      │    │
│  └──────┬──────┘    └──────┬──────┘    └─────────────┘    │
│         │                  │                                │
│  ┌──────▼──────────────────▼────────────────────────────┐  │
│  │              消息代理 (MQTT Broker)                   │  │
│  │                 (Mosquitto)                           │  │
│  └────────────────────────┬─────────────────────────────┘  │
└───────────────────────────┼─────────────────────────────────┘
                            │ MQTT/HTTP
┌───────────────────────────▼─────────────────────────────────┐
│                    边缘设备层                               │
│  ┌─────────────────────────────────────────────┐          │
│  │           智能腌制单元 (ESP32)                │          │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐   │          │
│  │  │盐度  │ │温度  │ │蠕动泵│ │加热控制  │   │          │
│  │  │传感器│ │传感器│ │      │ │ (继电器) │   │          │
│  │  └──────┘ └──────┘ └──────┘ └──────────┘   │          │
│  └─────────────────────────────────────────────┘          │
│                    (可扩展更多传感器/执行器)                │
└───────────────────────────────────────────────────────────┘
```

**数据流向**：
1. **用户指令下发**：用户通过 Web/App 提交腌制请求 → Web服务器 → MQTT Broker → 智能腌制单元
2. **状态数据上报**：腌制单元采集传感器数据 → MQTT Broker → 业务逻辑处理 → 数据库存储 → Web界面展示
3. **实时控制闭环**：云端根据实时数据与目标配方的偏差，动态调整执行器状态

## 📁 项目结构

```
yadan-flex/
├── README.md                 # 项目总览文档
├── docker-compose.yml        # 一键部署所有云端服务
├── docs/                     # 详细技术文档
│   ├── 1-项目背景与愿景.md
│   ├── 2-硬件设计指南.md
│   ├── 3-软件部署手册.md
│   └── 4-贡献指南.md
├── firmware/                 # 固件代码 (ESP32)
│   ├── src/
│   └── platformio.ini
├── backend/                  # 后端服务 (Python Flask)
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app.py
├── frontend/                 # 前端界面
│   └── dashboard.html
├── mosquitto/                # MQTT Broker 配置
│   ├── config/
│   │   └── mosquitto.conf
│   ├── data/
│   └── log/
└── node-red/                 # Node-RED 流程配置
    └── data/
```

## 🚀 快速开始

### 1. 环境准备
- 安装 [Docker](https://docs.docker.com/engine/install/) 和 [Docker Compose](https://docs.docker.com/compose/install/)
- 确保 1880, 1883, 5000 端口未被占用
- Git 客户端

### 2. 获取代码
```bash
git clone https://gitee.com/your-org/yadan-flex.git
cd yadan-flex
```

### 3. 启动云端服务
```bash
# 一键启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看实时日志
docker-compose logs -f
```

### 4. 访问服务
- **Node-RED 流程编辑器**: http://localhost:1880
  - 用于配置业务逻辑和数据流
- **Web API 接口**: http://localhost:5000/api/start
  - 测试命令: `curl -X POST http://localhost:5000/api/start -H "Content-Type: application/json" -d '{"target_salt":5.0,"target_temp":25,"duration_h":360}'`
- **前端监控面板**: 打开 `frontend/dashboard.html` 文件
  - 修改文件中的服务器地址为 `localhost`
- **MQTT Broker**: `tcp://localhost:1883`
  - 可用 MQTTX 等客户端测试连接

### 5. 部署硬件
1. 按照 [硬件设计指南](docs/2-硬件设计指南.md) 搭建硬件原型
2. 参考 [软件部署手册](docs/3-软件部署手册.md) 烧录固件
3. 修改固件中的 Wi-Fi 和 MQTT 服务器配置
4. 上电后，硬件将自动连接云端并等待指令

### 6. 开始腌制
1. 在前端界面或通过 API 发送腌制指令
2. 观察硬件开始工作，数据实时更新
3. 腌制完成后接收通知

### 7. 停止服务
```bash
docker-compose down
```

## 📚 详细文档

按顺序阅读以下文档以深入了解项目：

1. [项目背景与愿景](docs/1-项目背景与愿景.md) - 了解项目解决的问题和愿景
2. [硬件设计指南](docs/2-硬件设计指南.md) - 硬件搭建指南和 BOM 清单
3. [软件部署手册](docs/3-软件部署手册.md) - 软件安装和配置详细步骤
4. [贡献指南](docs/4-贡献指南.md) - 如何为项目贡献代码和文档

## 🤝 如何参与

我们热烈欢迎所有贡献！无论你是硬件工程师、嵌入式开发者、全栈工程师还是文档写手，都能找到适合的任务。

**开始贡献前请阅读**：[贡献指南](docs/4-贡献指南.md)

### 贡献方向
- **硬件/电气**：优化电路设计，选型更适合的传感器，设计 PCB
- **嵌入式开发**：完善固件功能，增加 OTA 升级，优化功耗
- **后端开发**：构建更强大的云端 API，设计数据库 schema
- **前端开发**：开发美观的 Web 管理界面和移动端适配
- **文档/测试**：改进文档，编写教程，添加测试用例
- **设计/产品**：设计 UI/UX，优化用户体验，提出产品建议

### 社区交流
- **Issue 反馈**: 在 Gitee Issues 中报告问题或提出建议
- **Pull Request**: 提交代码改进
- **讨论区**: (待补充：如微信群、Discord 等联系方式)

## 📄 许可证

本项目采用 GNU General Public License v3.0 开源协议。详情请查看 [LICENSE](LICENSE) 文件。

## 🙏 致谢

感谢所有为 YADAN-Flex 项目做出贡献的开发者、测试者和文档撰写者！

---

**蛋壳计划 · 让每一枚蛋都有自己的故事** 🥚


> 本回答由 AI 生成，内容仅供参考，请仔细甄别。 2025-12-02