# FocLib

**Repository Path**: matace/focLib

## Basic Information

- **Project Name**: FocLib
- **Description**: C99标准的FocLib
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FOC电机控制库 - 重构版本

## 项目概述

本项目是一个现代化的FOC（磁场定向控制）电机控制库，按照2026年的最佳实践进行了完全重构。采用分层架构设计，支持多电机实例、观测器可插拔、硬件抽象层解耦等特性。

## 架构特点

### 🎯 核心特性
- **多实例支持**：同一MCU可同时控制多个电机
- **观测器可插拔**：支持SMO、PLL、HFI等多种观测器算法
- **硬件抽象层**：算法与硬件完全解耦，便于移植
- **Opaque Handle**：使用不透明句柄隐藏内部实现
- **分层架构**：清晰的core/hal/driver/motor/app分层

### 📁 目录结构
```
focLib/
├── core/                    # 纯算法层（无硬件依赖）
│   ├── math/               # 数学变换（Clarke/Park/SVPWM）
│   ├── control/            # 控制算法（PID/电流环/速度环）
│   ├── observer/           # 观测器算法（SMO/PLL等）
│   └── filter/             # 滤波算法
├── hal/                    # 硬件抽象层
│   ├── interface/          # 抽象接口定义
│   └── impl/              # 具体平台实现
├── driver/                 # 外设驱动
│   ├── current/           # 电流采样驱动
│   ├── position/          # 位置传感器驱动
│   └── vbus/              # 母线电压驱动
├── motor/                  # 电机控制核心
├── app/                    # 应用层
├── port/                   # 平台相关代码
├── include/                # 对外API
├── common/                 # 公共组件
└── README.md
```

## 快速开始

### 1. 创建电机实例
```c
#include "foc_api.h"

// 创建电机（7极对，0.1Ω电阻，100uH电感，0.01Wb磁链）
foc_motor_t *motor = foc_create_motor(7, 0.1f, 0.0001f, 0.01f, 10.0f, 3000.0f);
```

### 2. 绑定硬件驱动
```c
// 绑定PWM、ADC驱动（需要平台实现）
foc_start_motor(motor, &pwm_driver, &current_adc, &vbus_adc);
```

### 3. 控制电机
```c
// 设置速度 (RPM)
foc_set_speed(motor, 1000.0f);

// 获取状态
float speed, iq, id, angle;
foc_get_status(motor, &speed, &iq, &id, &angle);
```

### 4. 主控制循环
```c
// 在定时器中断中调用（10kHz）
void control_timer_isr(void) {
    foc_motor_1tick(motor);
}
```

## 构建和测试

### 依赖
- GCC 9.0+
- CMake 3.16+ (可选)

### 构建
```bash
# 构建库
make

# 运行演示
make test

# 清理
make clean
```

### 平台移植
1. 实现 `hal/impl/` 下的具体硬件驱动
2. 修改 `port/board.h/c` 中的引脚定义
3. 实现 `sys_if.h` 中的系统服务

## API参考

### 电机控制API
- `foc_motor_create()` - 创建电机实例
- `foc_motor_start()` - 启动电机
- `foc_motor_set_speed_ref_rpm()` - 设置速度
- `foc_motor_1tick()` - 主控制循环

### 观测器API
- `smo_create()` - 创建SMO观测器
- `observer_update()` - 更新观测器
- `observer_get_theta_rad()` - 获取角度

### 控制算法API
- `pid_init()` - 初始化PID控制器
- `pid_calculate()` - PID计算
- `current_loop_execute()` - 电流环控制

## 技术规格

### 支持的观测器
- **SMO (Sliding Mode Observer)** - 滑模观测器
- **PLL (Phase Locked Loop)** - 锁相环
- **HFI (High Frequency Injection)** - 高频注入

### 支持的传感器
- 无传感器（观测器）
- 霍尔传感器
- 编码器（ABZ、正交）
- 旋转变压器

### 控制模式
- 速度控制（外环）
- 电流控制（内环）
- 转矩控制
- 位置控制

## 性能参数

- **控制频率**：最高20kHz
- **ADC分辨率**：12位
- **PWM分辨率**：16位
- **电机数量**：最多4个（可扩展）

## 开发规范

### 注释风格
使用Doxygen风格中文注释：
```c
/**
 * @brief 函数功能描述
 * @param param 参数描述
 * @return 返回值描述
 */
```

### 代码风格
- C99标准
- 4空格缩进
- 行宽不超过120字符
- 使用有意义的变量名

### 命名约定
- 函数：`module_action()`
- 结构体：`module_type_t`
- 宏：`MODULE_CONSTANT`

## 许可证

本项目采用MIT许可证。

## 贡献

欢迎提交Issue和Pull Request！

## 版本历史

- **v1.0.0** (2026-01-28): 初始重构版本
  - 实现分层架构
  - 支持多电机实例
  - 观测器可插拔设计