# 双臂魔方机器人机械动作寻优算法

**Repository Path**: hemn1990/two-arm-two-phase

## Basic Information

- **Project Name**: 双臂魔方机器人机械动作寻优算法
- **Description**: 适用于双臂魔方机器人的动作优化算法，输入魔方54个色块的状态，输出可直接控制机械臂的动作指令。
该算法在求解魔方时，按照每种动作的预估时间来选取合适的操作，而不仅仅按照步数最少求解。
从而尽量减少翻面等耗时较长的操作。
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-10
- **Last Updated**: 2025-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 双臂魔方机器人动作优化算法

## 简介
本算法专为双臂魔方机器人设计，通过输入魔方的54个色块状态，输出可直接控制机械臂的动作指令。核心创新点在于：求解魔方时依据每种动作的预估时间进行优化选择（而非仅追求最少步数），显著减少耗时操作（如翻面动作），从而提升整体解魔方效率。

## 版本说明
### v1
- 基于 https://github.com/cs0x7f/min2phase 二次开发
- 资源消耗少，适合移植到单片机
- 性能稍逊于v2版本

### v2 (当前文档版本)
- 调用 https://github.com/efrantar/rob-twophase 引擎
- 计算同一魔方状态的多重解法方案
- 对比各方案机械操作耗时，选择最优解
- 性能优势：平均耗时较v1缩短0.4-0.5秒
- 资源需求较高，适合PC端运行

> **维护说明**  
> 双版本同步维护，v1文档详见：  
> https://gitee.com/hemn1990/dual-arm-rubiks-cube-robot-v2

---

## 系统支持
1. **核心算法** (`optimizer.c`)  
   - 完全跨平台（基于纯C标准库实现）

2. **硬件交互层** (`main.c`)  
   - 仅支持符合POSIX标准的系统

---

## 编译指南
### 1. 获取第三方库
```bash
# 使用 gitee 仓库：
git clone https://gitee.com/hemn1990/rob-twophase.git
# 或使用 GitHub 仓库：
# git clone https://github.com/efrantar/rob-twophase.git

# 编译 rob-twophase：
cd rob-twophase
make
```

### 2. 编译主项目
```bash
# 返回项目目录编译：
make
# 生成可执行文件: cube
```

### 3. 生成查找表
```bash
# 首次运行 twophase 生成查找表：
cp ../rob-twophase/twophase ./
./twophase  # 自动生成 twophase-ht.tbl（耗时较长）
```

---

## 使用说明
### 文件准备
确保以下文件位于同一目录：
```
cube        # 主程序
twophase    # 魔方求解
twophase-ht.tbl  # 查找表
```

### 命令行参数
```bash
./cube [参数] [-v]
```

| 参数 | 功能 | 示例 |
|------|------|------|
| `-s` | 魔方求解 | `./cube -s BBBFULRUBUURFRRRDFDFLUFDLRUUUFFDRLDLRRFLLBBLFDLUBBDDBD` |
| `-t` | 批量测试 | `./cube -t log/testcase.txt` |
| `-d` | **开启后台服务，作为魔方机器人解算上位机使用** | `./cube -d /dev/ttyACM0` |
| `-v` | 调试输出 | 可组合使用（必须置于命令末尾） |

> **串口设备获取方法**  
> 使用 `esptool.py read_mac` 查询可用串口
```bash
two-arm-two-phase % esptool.py read_mac
esptool.py v4.9.0
Found 1 serial ports
Serial port /dev/cu.usbmodem1301 （此处就是串口号）
Connecting...
```
将./cube -d /dev/ttyACM0中的/dev/ttyACM0替换为实际查询到的串口设备

### 机械步骤输出示例
可通过./cube -s BBBFULRUBUURFRRRDFDFLUFDLRUUUFFDRLDLRRFLLBBLFDLUBBDDBD测试求解功能
```bash
two-arm-two-phase % ./cube -s BBBFULRUBUURFRRRDFDFLUFDLRUUUFFDRLDLRRFLLBBLFDLUBBDDBD
检测到逻辑核心: 8
优化设置: -t 8 (线程数), -s 2 (分割数), 比例: 4.00
等待twophase准备就绪...
机械步骤: R1 L-F R0 L+T L1 R*F L0 R*T L-T R1 L-F R0 L1 R+F L0 R*T R2 R+N L*F R0 L*T R*T L1 R*F L0 L*T L1 R+F L0 R2 R+N R0 L+T L2 L+N L0 R*T R1 L-F R0 L+T L1 R+F L0 R+T L+T L2 L+N L0 R-T R2 R+N L-F R0 L-T R-T L1 R-F L0 L*T L1 R-F L0 R-T L+T L2 L+N R-F L0 R-T L*T R*T 
预估时间: 4445ms
```

---

## 机械指令格式解析
### 指令类型速查表
| 指令格式 | 说明 | 
|----------|------|
| `L0/R0` | 夹爪夹紧 |
| `L1/R1` | 夹爪松开 |
| `L2/R2` | 夹爪张开最大角度 |
| `L+T/R+T` | 90°顺时针旋转（单层） |
| `L-T/R-T` | 90°逆时针旋转（单层） |
| `L*T/R*T` | 180°旋转（单层） |
| `L+F/R+F` | 90°顺时针翻面（整魔方） |
| `L-F/R-F` | 90°逆时针翻面（整魔方） |
| `L*F/R*F` | 180°翻面（整魔方） |
| `L+N/R+N` | 旋转臂空转90° |

> 注：详细指令生成逻辑见 `tools/cube_optimizer.py`

### 典型操作组合
| 操作类型 | 指令序列 |
|----------|---------|
| 空转操作 | `['L2', 'L+N', 'L0']` |
| 90°翻面 | `['R1', 'L+F', 'R0']` |
| 180°翻面 | `['L1', 'R*F', 'L0']` |
| 90°旋转 | `['L+T']` |
| 180°旋转 | `['L*T']` |

> T/F/N类动作差异点：角速度、角加速度、使用场景不同

---

## 性能测试
### 测试环境
- 硬件：Apple M1处理器 / 8GB内存
- 系统：macOS 14.7.2 (23H311)
- 测试集：rob-twophase/bench.cubes (10,000随机魔方状态)

```bash
# 测试命令（建议重定向输出）：
time ./cube -t ../rob-twophase/bench.cubes > log.txt
```

### 测试结果
| 指标 | 值 |
|------|----|
| **总用时** | 5分32秒 |
| **单状态平均耗时** | 33ms |
| **时间分布** | min=2875ms / max=4795ms / avg=4214.77ms |
| **步骤分布** | min=49步 / max=91步 / avg=70.30步 |

#### 时间分布直方图 (100ms间隔)
```
2800-2899:    1 [#.......................................]
3100-3199:    2 [#.......................................]
3200-3299:    7 [#.......................................]
3300-3399:    9 [#.......................................]
3400-3499:   31 [#.......................................]
3500-3599:   56 [##......................................]
3600-3699:  127 [###.....................................]
3700-3799:  242 [######..................................]
3800-3899:  423 [##########..............................]
3900-3999:  787 [##################......................]
4000-4099: 1115 [#########################...............]
4100-4199: 1547 [##################################......]
4200-4299: 1835 [########################################]
4300-4399: 1623 [####################################....]
4400-4499: 1243 [############################............]
4500-4599:  647 [###############.........................]
4600-4699:  238 [######..................................]
4700-4799:   67 [##......................................]
```

#### 步骤数量分布 (1步间隔)
```
 49步:    2 [#.......................................]
 50步:    1 [#.......................................]
 51步:    1 [#.......................................]
 53步:    4 [#.......................................]
 54步:   10 [#.......................................]
 55步:   11 [#.......................................]
 56步:   12 [#.......................................]
 57步:   21 [#.......................................]
 58步:   51 [###.....................................]
 59步:   54 [###.....................................]
 60步:   94 [#####...................................]
 61步:  112 [######..................................]
 62步:  160 [########................................]
 63步:  252 [############............................]
 64步:  339 [#################.......................]
 65步:  481 [#######################.................]
 66步:  539 [##########################..............]
 67步:  611 [##############################..........]
 68步:  736 [###################################.....]
 69步:  755 [####################################....]
 70步:  834 [########################################]
 71步:  842 [########################################]
 72步:  808 [#######################################.]
 73步:  746 [####################################....]
 74步:  609 [#############################...........]
 75步:  525 [#########################...............]
 76步:  402 [####################....................]
 77步:  321 [################........................]
 78步:  264 [#############...........................]
 79步:  157 [########................................]
 80步:   98 [#####...................................]
 81步:   73 [####....................................]
 82步:   29 [##......................................]
 83步:   20 [#.......................................]
 84步:   10 [#.......................................]
 85步:    8 [#.......................................]
 86步:    4 [#.......................................]
 87步:    1 [#.......................................]
 88步:    1 [#.......................................]
 89步:    1 [#.......................................]
 91步:    1 [#.......................................]
```

---

## 许可证
- 项目采用 **MIT 许可证** 授权
- 允许免费商业使用

> 许可证文件详见项目目录 `LICENSE`