Metadata-Version: 2.4
Name: tkmid-chassis
Version: 1.0.0
Summary: TK-mid chassis CAN driver
Home-page: https://gitee.com/tydfgt/ysdyjld
Author: TK-mid Development Team
Author-email: support@example.com
License: MIT
Keywords: can,robot,chassis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-can>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: author-email
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python


# ysdyjld - TK-mid Chassis CAN Driver

## 简介

这是一个完整的Python驱动包，用于控制TK-mid中型履带式机器人底盘，通过CAN总线实现运动控制和状态监控。

## 快速安装（推荐）

### 方式1：从PyPI安装（最简单）

```bash
# 安装
pip install tkmid-chassis

# 或者使用国内镜像（更快）
pip install tkmid-chassis -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 方式2：从源代码安装

```bash
# 克隆项目
git clone https://gitee.com/tydfgt/ysdyjld.git
cd ysdyjld

# 安装
pip install -e .
```

## 树莓派快速开始

### 1. 硬件连接

#### 推荐方案：USB CAN适配器
- 使用USB转CAN适配器（如CANable、PCAN-USB等）
- 连接到树莓派的USB端口
- 接线：
  - CAN_H &lt;-&gt; TK-mid航空插头引脚11
  - CAN_L &lt;-&gt; TK-mid航空插头引脚10
  - GND &lt;-&gt; TK-mid电源负极
  - 如果需要，连接120Ω终端电阻

#### 备选方案：MCP2515模块
- 使用SPI接口连接到树莓派
- 配置见 `docs/RASPBERRY_PI_SETUP.md`

### 2. 软件安装

```bash
# 1. 更新系统
sudo apt update
sudo apt upgrade -y

# 2. 安装依赖
sudo apt install -y python3 python3-pip git can-utils

# 3. 安装驱动（PyPI方式，推荐）
pip install tkmid-chassis

# 或者从Gitee克隆
# git clone https://gitee.com/tydfgt/ysdyjld.git
# cd ysdyjld
# pip install -e .

# 4. 配置CAN接口
sudo ip link set can0 up type can bitrate 500000
```

### 3. 配置CAN接口（开机自动配置）

```bash
# 编辑系统配置
sudo nano /etc/network/interfaces.d/can0
```

添加以下内容：
```
auto can0
iface can0 can static
    bitrate 500000
```

### 4. 运行测试程序

```bash
# 使用Python运行
python3 -c "import tkmid_chassis; print('OK')"

# 或者运行示例（如果有克隆代码）
# cd ysdyjld/examples
# python3 example1_kinematic_control.py
```

### 5. 测试硬件连接

```bash
# 在另一个终端查看CAN数据
candump can0

# 在原终端运行实际控制程序
cd ysdyjld/examples
python3 example1_kinematic_control.py
```

## 基础示例

```python
# simple_test.py
import sys
import time

from tkmid_chassis import TKmidChassis, Gear

def main():
    # 创建底盘控制实例
    chassis = TKmidChassis(can_interface='can0')
    
    try:
        # 连接CAN总线
        chassis.connect()
        
        # 启动控制循环
        chassis.start()
        
        # 切换到运动学控制档
        chassis.set_gear(Gear.KINEMATIC)
        time.sleep(0.5)
        
        # 前进
        print("Moving forward...")
        chassis.set_kinematic_control(speed=0.5, angular=0)
        time.sleep(2)
        
        # 停止
        print("Stopping...")
        chassis.set_kinematic_control(speed=0, angular=0)
        time.sleep(1)
        
        # 左转
        print("Turning left...")
        chassis.set_kinematic_control(speed=0.3, angular=30)
        time.sleep(2)
        
        # 停止
        print("Stopping...")
        chassis.set_kinematic_control(speed=0, angular=0)
        time.sleep(1)
        
    except KeyboardInterrupt:
        print("\nUser stopped")
    except Exception as e:
        print(f"Error: {e}")
    finally:
        # 紧急停止并断开连接
        chassis.emergency_stop()
        time.sleep(0.3)
        chassis.stop()
        chassis.disconnect()
        print("Disconnected")

if __name__ == "__main__":
    main()
```

## 完整的使用指南

### 运行示例

```bash
# 如果你从Gitee克隆了代码
cd ysdyjld/examples

# 运动学控制
python3 example1_kinematic_control.py

# 自由控制（左右轮独立）
python3 example2_free_control.py

# 状态监控
python3 example3_status_monitor.py

# 完整演示
python3 example4_comprehensive.py

# 键盘遥控（WSAD）
python3 example5_keyboard_control.py
```

### 使用上下文管理器（推荐方式）

```python
import time

from tkmid_chassis import TKmidChassis, Gear

with TKmidChassis(can_interface='can0') as chassis:
    chassis.set_gear(Gear.KINEMATIC)
    chassis.set_kinematic_control(0.5, 0)
    time.sleep(2)
    chassis.set_kinematic_control(0, 0)
    time.sleep(1)
```

## 项目结构

当你从PyPI安装后，包结构如下：

```
site-packages/
└── tkmid_chassis/
    ├── __init__.py
    ├── protocol.py
    └── chassis.py
```

完整开发项目结构（Gitee）：
```
ysdyjld/
├── README.md                    # 项目说明（本文件）
├── LICENSE                     # MIT许可证
├── pyproject.toml             # PyPI项目配置
├── MANIFEST.in                # 打包清单
├── requirements.txt           # Python依赖
├── setup.py                   # 安装脚本
├── src/                       # 源代码
│   └── tkmid_chassis/       # 驱动包
│       ├── __init__.py
│       ├── protocol.py
│       └── chassis.py
├── examples/                   # 示例代码
│   ├── example1_kinematic_control.py
│   ├── example2_free_control.py
│   ├── example3_status_monitor.py
│   ├── example4_comprehensive.py
│   └── example5_keyboard_control.py
└── docs/                      # 文档
    ├── RASPBERRY_PI_SETUP.md  # 树莓派详细配置
    └── TK-mid_CAN总线手册.md # 完整CAN协议文档
```

## 功能特性

- ✅ 运动学控制（速度 + 角速度）
- ✅ 自由控制（左右轮独立速度控制）
- ✅ 实时状态反馈（运动/轮系/电池/I/O状态）
- ✅ I/O控制（安全停车解锁）
- ✅ 心跳保护机制（Alive Counter + Checksum）
- ✅ 完善的日志和错误处理
- ✅ 回调函数机制
- ✅ 支持多种CAN接口（SocketCAN/PCAN/USB2CAN等）

## 安全建议

1. **首次测试请将底盘悬空**，避免发生意外
2. **保持遥控器在手边**，随时可以接管控制
3. **从低速开始测试**（建议从0.1 m/s开始）
4. **始终保持急停功能可用**
5. **测试时确保周围安全**
6. **定期检查电池状态**

## 调试和故障排查

### 检查CAN接口

```bash
# 查看CAN接口
ip -details -statistics link show can0

# 发送测试帧
cansend can0 18C4D1D0#0300000000000000

# 接收CAN数据
candump can0
```

### 常见问题

1. **找不到模块**：确保已正确安装 `pip install tkmid-chassis`
2. **CAN接口连接失败**：检查硬件连接和权限
3. **底盘无响应**：检查档位、遥控器模式和急停
4. **反馈数据异常**：检查Alive Counter和校验和

## 详细文档

- `docs/RASPBERRY_PI_SETUP.md` - 树莓派详细配置和常见问题
- `docs/TK-mid_CAN总线手册.md` - 完整的CAN协议说明

## 依赖

- Python 3.7+
- python-can 4.0+

## 许可证

MIT License

## 项目来源

- Gitee: https://gitee.com/tydfgt/ysdyjld
- PyPI: https://pypi.org/project/tkmid-chassis

## 联系方式

如有问题，请查阅文档或提交Issue。

## 开发指南

如果你想开发或贡献：

```bash
# 克隆项目
git clone https://gitee.com/tydfgt/ysdyjld.git
cd ysdyjld

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest
```

## 上传到PyPI（维护者用）

参考 `docs/PYPI_GUIDE.md` 文件了解如何上传到PyPI。

