ysdyjld 1.0.0

TK-mid chassis CAN driver

ysdyjld - TK-mid Chassis CAN Driver

简介

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

快速安装（推荐）

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

# 安装
pip install ysdyjld

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

方式2：从源代码安装

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

# 安装
pip install -e .

树莓派快速开始

1. 硬件连接

推荐方案：USB CAN适配器

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

备选方案：MCP2515模块

• 使用SPI接口连接到树莓派
• 配置见 docs/RASPBERRY_PI_SETUP.md

2. 软件安装

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

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

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

# 或者从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接口（开机自动配置）

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

添加以下内容：

auto can0
iface can0 can static
    bitrate 500000

4. 运行测试程序

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

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

5. 测试硬件连接

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

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

基础示例

# 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()

完整的使用指南

运行示例

# 如果你从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

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

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接口

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

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

# 接收CAN数据
candump can0

常见问题

1. 找不到模块：确保已正确安装 pip install ysdyjld
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/ysdyjld

联系方式

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

开发指南

如果你想开发或贡献：

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

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

# 运行测试
pytest

上传到PyPI（维护者用）

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