# OpenDropper

**Repository Path**: GuotongC/OpenDropper

## Basic Information

- **Project Name**: OpenDropper
- **Description**: 这是一个开源抛投器项目。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-29
- **Last Updated**: 2025-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenDropper

## 项目概述
OpenDropper是一个基于RT-Thread实时操作系统的开源无人机抛投控制系统，专为降低无人机抛投技术门槛而设计。该项目运行于STM32F103C6微控制器上，通过简洁的串口命令控制舵机精确动作，实现可靠的物品投放功能。

### 应用场景
无人机抛投技术可广泛应用于以下领域：
- **应急救援**：向灾区精确投放急救药品、食品、通信设备等物资
- **农业应用**：精准播种、肥料投放、病虫害防治
- **物流配送**：在交通不便地区进行小件物品快速投递
- **科学研究**：环境监测设备投放、野生动物跟踪器安装
- **影视拍摄**：特殊视角的设备投放与回收

### 项目价值
OpenDropper项目致力于解决传统抛投系统面临的技术门槛问题：
- **降低技术门槛**：提供开箱即用的解决方案，无需深厚的电子工程背景
- **促进创新应用**：开源架构设计，鼓励社区基于此平台进行创新与扩展
- **保障系统安全**：经过验证的稳定代码，减少因控制不当引发的安全隐患
- **推动行业发展**：通过开源协作，加速无人机抛投技术在各行业的应用

### 核心特性
- 基于RT-Thread实时操作系统，确保可靠运行
- 支持0-6共7个档位的精确舵机控制
- 提供串口通信和按键控制两种操作方式
- 模块化设计，易于扩展和定制
- 适配标准PWM舵机，兼容性强
- 简洁的命令系统，易于集成到各类无人机平台

## 硬件要求与连接

### 核心硬件组件
- **主控芯片**：STM32F103C6（ARM Cortex-M3内核，72MHz主频，32KB Flash，4KB RAM）
- **舵机**：支持标准PWM控制的舵机（工作电压：4.8V-6V）
- **按键**：轻触式按键（紧急操作）
- **串口通信**：UART2接口（PA2-TX, PA3-RX）
- **电源模块**：稳定的5V和3.3V电源（需提供足够电流驱动舵机）

### 硬件连接示意图

系统硬件连接方式如下图所示：

![OpenDropper 硬件连接示意图](images/hardware_connection.svg)

### 关键参数
- **舵机控制**：PWM频率50Hz，占空比5%-10%（对应0-180度）
- **串口通信**：波特率115200，8N1（数据位8，无校验，停止位1）
- **工作环境**：温度-20°C ~ 60°C，需做好防护措施

### 舵机选型指南
- **轻量级投放**（<500g）：推荐SG90等微型舵机
- **中等重量投放**（500g-1kg）：推荐MG996R等标准舵机
- **重载投放**（>1kg）：建议使用大扭矩舵机并增加机械传动机构

### 安装注意事项
- 确保所有地线连接良好，避免信号干扰
- 户外应用需进行防水处理
- 注意舵机与投放机构的机械连接可靠性

## 软件架构
OpenDropper采用基于RT-Thread实时操作系统的模块化分层架构，确保系统的可维护性和可扩展性。项目通过清晰的接口设计实现了各模块间的低耦合，便于功能扩展和定制。

### 系统架构概览

系统整体架构设计如下图所示：

![OpenDropper 系统架构图](images/system_architecture.svg)

### 核心模块详解

#### 1. 硬件抽象层
提供底层硬件的统一访问接口：
- **RT-Thread内核**：提供任务调度、内存管理、定时器等核心功能
- **STM32F1xx HAL库**：封装STM32系列微控制器的底层寄存器操作
- **板级支持包（BSP）**：提供针对STM32F103C6的初始化和配置

#### 2. 驱动层
位于`drivers/`目录，实现硬件设备的直接控制：

- **串口驱动（drv_uart2.c/h）**：
  - 实现UART2初始化、配置和中断处理
  - 提供数据发送和接收功能
  - 支持回调函数机制处理接收到的数据

- **按键驱动（key.c/h）**：
  - 实现按键GPIO配置和初始化
  - 提供软件防抖算法
  - 检测短按和长按事件并触发回调

- **舵机驱动（servo.c/h）**：
  - 配置TIM3定时器生成PWM控制信号
  - 实现0-6共7个档位的精确位置控制
  - 提供舵机当前位置查询功能

#### 3. 应用层
位于`applications/`目录，包含系统主要业务逻辑：

- **main.c**：系统入口点，负责初始化各模块和注册回调函数
- **命令处理**：解析串口命令并控制舵机执行相应动作
- **用户交互**：处理按键事件和生成状态反馈信息

### 数据流与交互关系

1. **串口控制流程**：
   - 上位机通过串口发送命令字符(0-6)
   - UART2接收中断触发，数据通过回调函数传递
   - 应用层解析命令并调用舵机控制接口
   - 舵机驱动控制PWM信号使舵机转动到目标位置
   - 系统通过串口返回执行结果

2. **按键控制流程**：
   - 按键驱动检测到按键事件（短按/长按）
   - 触发注册的回调函数
   - 执行预设动作（前进/后退一个档位）
   - 系统通过串口反馈操作结果

### 核心功能实现

#### 舵机控制
系统支持0-6共7个档位（30°到120°，每档15°）的精确控制，通过TIM3定时器通道1(PWM)输出控制信号。舵机初始位置设为中间档位(3档，90°)。

#### 命令解析
串口接收的命令通过回调函数处理，支持0-6的数字命令，每个命令对应一个舵机档位。命令执行后，系统会返回确认信息。

#### 按键操作
按键支持短按和长按两种模式，分别对应前进一个档位和后退一个档位的功能。按键检测采用状态机实现的软件防抖算法。

## 主要功能详解

### 1. 串口通信系统
串口通信系统是OpenDropper与外部设备（上位机或无人机飞控系统）进行数据交换的主要接口，具有以下特性：

- **全双工通信**：支持同时发送和接收数据
- **中断驱动**：采用中断方式处理数据收发，提高系统响应速度
- **命令解析**：能够解析和识别0-6的数字命令
- **错误处理**：具备基本的命令错误检测和反馈机制
- **配置参数**：波特率115200，数据位8位，停止位1位，无校验位

### 2. 舵机控制系统
舵机控制系统是OpenDropper的核心功能模块，负责精确控制舵机的转动角度，具有以下特性：

- **PWM精确控制**：通过控制PWM信号的占空比实现舵机角度的精准调节
  - PWM周期为20ms
  - 0度对应的PWM值为500
  - 180度对应的PWM值为2500
- **多档位控制**：支持0-6共7个预设档位，每个档位对应特定的舵机角度（0°到180°，每个档位间隔30°）
  - **档位0**：30°位置（通常为关闭位置）
  - **档位1-5**：45°、60°、75°、90°、105°（中间过渡位置）
  - **档位6**：120°位置（通常为释放位置）

- **硬件配置**：
  - 连接到TIM3的通道1
  - 控制引脚为GPIOA的引脚6

### 3. 按键输入系统
按键输入系统提供了一种物理触发方式，用于在没有串口通信的情况下控制抛投器，具有以下特性：

- **防抖处理**：采用状态机实现的软件防抖算法，消除按键机械抖动的影响
- **多模式支持**：支持短按和长按两种触发模式
- **功能映射**：
  - 短按：舵机前进一个档位
  - 长按：舵机后退一个档位
- **操作反馈**：通过串口向上位机反馈按键操作结果

### 4. 系统状态管理
OpenDropper实现了基本的系统状态管理功能：

- **档位记录**：实时记录并可查询当前舵机档位
- **操作反馈**：对每一个有效操作提供明确的响应信息
- **初始化状态**：系统启动时自动初始化各模块并设置默认状态

### 5. 可扩展功能
OpenDropper的模块化设计使其具有良好的可扩展性：

- **命令扩展**：可通过修改串口接收回调函数添加新的控制命令
- **功能定制**：可根据需求调整舵机控制参数和按键功能映射
- **硬件适配**：易于适配不同型号的舵机和控制板

## 命令系统详解

OpenDropper采用简单直观的命令系统，用于控制舵机的运动状态。以下是命令系统的详细说明：

### 1. 命令格式
OpenDropper的命令格式非常简洁，每条命令包含一个ASCII字符，表示具体的操作指令。目前支持的命令格式为单字符数字命令：

- **数字命令 '0'-'6'**：直接设置舵机到对应的档位（0到6档）

### 2. 当前支持命令
目前OpenDropper支持以下命令：

- **'0'**：设置舵机到0档（30度）
- **'1'**：设置舵机到1档（45度）
- **'2'**：设置舵机到2档（60度）
- **'3'**：设置舵机到3档（75度，初始档位）
- **'4'**：设置舵机到4档（90度）
- **'5'**：设置舵机到5档（105度）
- **'6'**：设置舵机到6档（120度）

### 3. 响应机制
当OpenDropper接收到有效命令并执行相应操作后，会通过串口发送响应信息，告知命令执行的结果。响应信息格式如下：

- **成功响应**：
  - 格式：'Set to gear X'
  - 例如：接收到命令'3'后，响应'Set to gear 3'

- **错误响应**：
  - 格式：'Invalid command'
  - 例如：接收到无效命令后，响应'Invalid command'

### 4. 通信协议示例
以下是OpenDropper与上位机通信的协议示例：

#### 通信示例1：设置舵机档位
- **上位机发送**：'3'
- **OpenDropper响应**：'Set to gear 3'

#### 通信示例2：处理错误命令
- **上位机发送**：'A'
- **OpenDropper响应**：'Invalid command'

### 5. 注意事项
在使用命令系统时，请注意以下事项：

- **命令格式**：仅支持单个数字字符'0'-'6'
- **数据完整性**：确保发送的命令完整无误
- **通信速率**：串口波特率为115200bps

### 6. 通信示例代码
以下是一个简单的Python通信示例，演示如何与OpenDropper进行通信：

```python
import serial
import time

# 配置串口参数
ser = serial.Serial(
    port='COM3',  # 根据实际端口修改
    baudrate=115200,
    parity=serial.PARITY_NONE,
    stopbits=serial.STOPBITS_ONE,
    bytesize=serial.EIGHTBITS,
    timeout=1
)

# 发送命令函数
def send_command(cmd):
    ser.write(cmd.encode())
    response = ser.readline().decode().strip()
    print(f"发送: {cmd}, 接收: {response}")
    return response

# 测试命令发送
if ser.isOpen():
    try:
        # 发送设置档位命令
        send_command('3')  # 设置为3档（75度）
        time.sleep(0.5)
        
        send_command('6')  # 设置为6档（120度，释放位置）
        time.sleep(0.5)
        
        send_command('0')  # 设置为0档（30度，关闭位置）
        
    except Exception as e:
        print(f"错误: {e}")
    finally:
        ser.close()
```


### 项目构建与开发指南

为了帮助开发者快速上手并参与OpenDropper项目的开发，我们提供了详细的项目构建与开发指南。

### 1. 开发环境准备
在开始开发之前，您需要准备以下开发环境：

- **开发工具**：
  - RT-Thread Studio IDE（推荐版本：V2.1.0或更高版本）
  
- **硬件需求**：
  - STM32F103系列开发板
  - 舵机（如SG90、MG90S等）
  - USB转串口模块（用于调试）
  
- **软件依赖**：
  - RT-Thread操作系统（4.0.0或更高版本）
  - STM32F1系列固件库

### 2. 项目导入与编译
完成环境配置后，可以按照以下步骤导入和编译项目：

1. **导入项目**：
   - 打开RT-Thread Studio IDE
   - 选择"文件" > "导入" > "RT-Thread项目"
   - 选择项目所在的文件夹
   - 点击"完成"按钮，等待项目导入完成
   
2. **项目编译**：
   - 在项目资源管理器中选中项目
   - 点击工具栏中的"编译"按钮，或使用快捷键Ctrl+B
   - 等待编译完成，查看编译结果

### 3. 程序烧录与调试
编译成功后，可以按照以下步骤烧录和调试程序：

1. **连接硬件**：
   - 使用调试器连接开发板和计算机
   - 确认硬件连接正确
   
2. **配置烧录设置**：
   - 在RT-Thread Studio中打开项目属性
   - 选择"C/C++构建" > "设置" > "调试器"选项卡
   - 配置调试器类型、端口等参数
   
3. **烧录程序**：
   - 点击工具栏中的"烧录"按钮，或使用快捷键Ctrl+Alt+B
   - 等待烧录完成

### 4. 常见问题解决
在项目构建与开发过程中，可能会遇到一些常见问题，以下是这些问题的解决方法：

- **编译错误**：检查头文件包含路径和代码语法
- **烧录失败**：检查调试器连接和驱动安装
- **程序运行异常**：检查硬件连接和外设初始化

### 5. 开发建议
为了提高开发效率和代码质量，我们提供以下开发建议：

- **代码风格**：遵循RT-Thread的代码风格规范
- **模块化开发**：按照功能模块划分代码，提高可维护性
- **版本控制**：使用Git等版本控制工具管理代码
- **文档编写**：为关键代码添加注释，编写开发文档


## 项目目录结构详解

OpenDropper项目采用模块化设计，代码结构清晰，便于维护和扩展。以下是项目的主要目录结构：

```
OpenDropper/
├── applications/           # 应用层代码
│   └── main.c              # 主程序文件，包含核心业务逻辑
├── drivers/                # 驱动层代码
│   ├── servo.c/h           # 舵机驱动实现与头文件
│   ├── key.c/h             # 按键驱动实现与头文件
│   ├── uart2.c/h           # UART2通信驱动实现与头文件
│   ├── board.c/h           # 板级初始化文件
│   └── stm32f1xx_hal_conf.h # HAL库配置文件
├── libraries/              # 第三方库目录
│   ├── CMSIS/              # CMSIS标准库
│   └── STM32F1xx_HAL_Driver/ # STM32 HAL库
├── rt-thread/              # RT-Thread操作系统源码
└── rtconfig.h              # RT-Thread配置文件
```

### 功能模块对应文件路径

| 功能模块 | 主要文件 | 功能描述 |
|---------|---------|---------|
| 主程序 | applications/main.c | 系统初始化、主循环和业务逻辑 |
| 舵机控制 | drivers/servo.c, drivers/servo.h | 舵机初始化和档位控制 |
| 按键处理 | drivers/key.c, drivers/key.h | 按键检测和事件处理 |
| 串口通信 | drivers/uart2.c, drivers/uart2.h | 串口初始化和数据收发 |
| 硬件配置 | drivers/board.c, drivers/stm32f1xx_hal_conf.h | 板级初始化和硬件配置 |

### 文件修改指南
- 添加应用功能：修改applications/main.c或创建新源文件
- 调整硬件配置：修改drivers/board.c和stm32f1xx_hal_conf.h
- 更改舵机参数：修改drivers/servo.c/h中的相关定义
- 扩展命令系统：修改drivers/uart2.c/h中的命令解析逻辑

## 使用指南

本章节提供OpenDropper项目的详细使用指南，帮助用户快速上手和使用系统。

### 1. 硬件准备与连接

**需要准备的硬件：**
- STM32F103C6T6开发板
- 舵机（推荐SG90或MG90S）
- USB转串口模块
- 按键（或使用开发板上的用户按键）
- 5V电源适配器（为舵机供电）

**连接方式：**
- **舵机连接**：
  - 信号线连接到PA6引脚
  - 电源线连接到5V电源
  - 地线连接到开发板GND
- **按键连接**：
  - 一端连接到PA0引脚
  - 另一端连接到GND
- **串口连接**：
  - USB转串口模块的TX连接到开发板PA3
  - USB转串口模块的RX连接到开发板PA2
  - 地线连接到开发板GND

### 2. 系统初始化

- 将程序烧录到开发板后，上电启动系统
- 系统会自动初始化舵机、按键和串口功能
- 初始化完成后，舵机会自动设置到3档（90度）位置
- 串口会发送就绪提示信息

### 3. 控制方法

OpenDropper提供两种控制方式：串口控制和按键控制。

#### 3.1 串口控制

1. 打开串口调试助手，设置参数：
   - 波特率：115200
   - 数据位：8位
   - 停止位：1位
   - 无校验位

2. 发送命令：
   - 发送数字'0'-'6'控制舵机到对应档位
   - 系统会返回'Set to gear X'确认执行成功
   - 发送无效命令会返回'Invalid command'

#### 3.2 按键控制

- **短按**：舵机前进一个档位（0→1→2→3→4→5→6→0循环）
- **长按（超过1秒）**：舵机后退一个档位（0←1←2←3←4←5←6←0循环）
- 按键操作后，系统会通过串口发送操作结果

### 4. 应用场景

#### 4.1 物资投放
1. 将需要投放的物资固定在舵机的执行机构上
2. 通过串口或按键发送命令，控制舵机转动到释放位置（通常是6档）
3. 投放完成后，将舵机恢复到初始位置（通常是0档）

#### 4.2 多批次投放
1. 如需在一次任务中投放多个物资，可以依次控制舵机动作
2. 每投放一批后，等待适当时间再进行下一批投放
3. 全部投放完成后，将系统恢复到初始状态

### 5. 系统维护

- 定期检查连接线是否松动或损坏
- 避免舵机长时间处于极限位置
- 不要超过舵机的最大扭矩和电压范围
- 存储时，将系统放置在干燥、通风的环境中

## 许可证信息

OpenDropper项目采用以下开源许可模式：

### 1. RT-Thread 操作系统许可证
RT-Thread操作系统采用 Apache License 2.0 许可证，允许用户在商业产品中使用、修改和分发。

### 2. OpenDropper 项目许可证
OpenDropper项目的源代码采用 MIT License 许可证，允许自由使用、修改和分发。

## 版本历史

### 当前版本
- **版本号**：beta_V1
- **主要功能**：
  - 支持通过串口发送命令控制舵机档位（0-6档）
  - 支持通过按键实现前进/后退档位操作
  - 实现了基本的串口通信和命令解析功能
  - 实现了基本的舵机控制功能
  - 实现了按键检测和事件处理功能

### 版本规划

#### beta_V2（规划中）
- 添加电压监测功能，防止电池过放
- 增加温度监测功能，保护硬件安全
- 优化串口通信协议，提高可靠性
- 增加多舵机控制支持

#### beta_V3（规划中）
- 增加GPS定位功能，支持定点投放
- 增加无线通信模块，支持远程控制
- 增加姿态传感器，提高投放精度
- 优化系统功耗，延长电池使用寿命

## 注意事项

### 1. 安全使用
- 在使用OpenDropper进行无人机抛投操作时，请确保遵守当地法律法规
- 请在安全的环境中进行测试，避免造成人员伤害或财产损失
- 请勿在人群密集区域或敏感区域进行测试

### 2. 硬件安全
- 请确保舵机的电源连接正确，避免短路或过载
- 请定期检查硬件连接，确保连接牢固可靠
- 请勿超过舵机的最大负载和工作温度范围

### 3. 软件安全
- 在修改代码前，请备份原始代码，以便在出现问题时恢复
- 请勿在未经测试的情况下，将修改后的代码用于实际飞行
- 请定期更新系统软件，以获取最新的功能和安全修复

## 联系方式

如果您在使用OpenDropper项目过程中遇到任何问题，或者有任何建议和意见，欢迎联系项目维护者。