diff --git a/README.md b/README.md index 2d0884b..748ba0f 100644 --- a/README.md +++ b/README.md @@ -247,6 +247,16 @@ auto state_arc = hand.getStateArc(); - 使用示例和注意事项 - 版本兼容性说明 +### 命名规范 + +项目已进行命名规范改进,详细信息请参考:[命名规范改进文档](docs/NAMING_IMPROVEMENTS.md) + +主要改进包括: +- 统一命名空间结构(所有型号实现类迁移到 `linkerhand::hand` 命名空间) +- 类名改进(不同型号使用不同类名,如 `L10Hand`, `L20Hand` 等) +- 参数命名修正(`handJoint` → `handModel`) +- 完全向后兼容(旧命名仍可使用) + ## 🧪 测试 ### 运行测试 diff --git a/docs/API-Reference.md b/docs/API-Reference.md index fd51c44..108a687 100644 --- a/docs/API-Reference.md +++ b/docs/API-Reference.md @@ -55,14 +55,14 @@ LinkerHand C++ API 提供了完整的接口用于控制灵心巧手系列灵巧 ### LinkerHandApi ```cpp -LinkerHandApi(const LINKER_HAND &handJoint, const HAND_TYPE &handType, const COMM_TYPE commType = COMM_CAN_0); +LinkerHandApi(const LINKER_HAND &handModel, const HAND_TYPE &handType, const COMM_TYPE commType = COMM_CAN_0); ``` **功能描述** 创建并初始化 LinkerHand API 实例。 **参数说明** -- `handJoint` (LINKER_HAND): 机械手型号 +- `handModel` (LINKER_HAND): 机械手型号 - 可选值: `LINKER_HAND::O6`, `LINKER_HAND::L6`, `LINKER_HAND::L7`, `LINKER_HAND::L10`, `LINKER_HAND::L20`, `LINKER_HAND::L21`, `LINKER_HAND::L25` - `handType` (HAND_TYPE): 机械手类型 - `HAND_TYPE::LEFT` - 左手 @@ -623,7 +623,7 @@ void setCurrent(const std::vector ¤t); **使用示例** ```cpp // 仅 L20 支持 -if (hand.handJoint_ == LINKER_HAND::L20) { +if (hand.handModel_ == LINKER_HAND::L20) { std::vector current = {100, 100, 100, 100, 100}; hand.setCurrent(current); } @@ -655,7 +655,7 @@ void setEnable(const std::vector &enable = std::vector(5, 0)); **使用示例** ```cpp // 仅 L25 支持 -if (hand.handJoint_ == LINKER_HAND::L25) { +if (hand.handModel_ == LINKER_HAND::L25) { std::vector enable = {1, 1, 1, 1, 1}; // 使能所有手指 hand.setEnable(enable); } @@ -687,7 +687,7 @@ void setDisable(const std::vector &disable = std::vector(5, 1) **使用示例** ```cpp // 仅 L25 支持 -if (hand.handJoint_ == LINKER_HAND::L25) { +if (hand.handModel_ == LINKER_HAND::L25) { std::vector disable = {1, 1, 1, 1, 1}; // 禁用所有手指 hand.setDisable(disable); } @@ -718,7 +718,7 @@ void clearFaultCode(const std::vector &torque = std::vector(5, **使用示例** ```cpp // 仅 L20 支持 -if (hand.handJoint_ == LINKER_HAND::L20) { +if (hand.handModel_ == LINKER_HAND::L20) { hand.clearFaultCode(); } ``` diff --git a/docs/NAMING_IMPROVEMENTS.md b/docs/NAMING_IMPROVEMENTS.md new file mode 100644 index 0000000..745db8d --- /dev/null +++ b/docs/NAMING_IMPROVEMENTS.md @@ -0,0 +1,187 @@ +# LinkerHand C++ SDK 命名规范改进指南 + +## 概述 + +本文档描述了 LinkerHand C++ SDK 的命名规范改进,这些改进旨在提高代码一致性、可维护性和可读性。 + +## 改进内容 + +### 1. 统一命名空间结构 + +所有手型号实现类已迁移到统一的 `linkerhand::hand` 命名空间: + +**改进前:** +```cpp +namespace LinkerHandL10 { + class LinkerHand : public linkerhand::hand::IHand { ... }; +} +``` + +**改进后:** +```cpp +namespace linkerhand { +namespace hand { + class L10Hand : public IHand { ... }; +} // namespace hand +} // namespace linkerhand +``` + +### 2. 类名改进 + +不同型号的手现在使用不同的类名,便于区分: + +| 型号 | 旧类名 | 新类名 | 命名空间 | +|------|--------|--------|---------| +| L6/O6 | `LinkerHandL6::LinkerHand` | `linkerhand::hand::L6Hand` | `linkerhand::hand` | +| L7 | `LinkerHandL7::LinkerHand` | `linkerhand::hand::L7Hand` | `linkerhand::hand` | +| L10 | `LinkerHandL10::LinkerHand` | `linkerhand::hand::L10Hand` | `linkerhand::hand` | +| L20 | `LinkerHandL20::LinkerHand` | `linkerhand::hand::L20Hand` | `linkerhand::hand` | +| L25/L21 | `LinkerHandL25::LinkerHand` | `linkerhand::hand::L25Hand` | `linkerhand::hand` | +| Modbus L10 | `ModbusLinkerHandL10::LinkerHand` | `linkerhand::hand::ModbusL10Hand` | `linkerhand::hand` | + +### 3. 帧属性枚举重命名和改进 + +各型号的帧属性枚举已重命名,使用更清晰的命名,并改为使用 `enum class` 以避免命名冲突: + +| 型号 | 旧枚举名 | 新枚举名 | +|------|---------|---------| +| L6/O6 | `LinkerHandL6::FRAME_PROPERTY` | `linkerhand::hand::L6FrameProperty` | +| L7 | `LinkerHandL7::FRAME_PROPERTY` | `linkerhand::hand::L7FrameProperty` | +| L10 | `LinkerHandL10::FRAME_PROPERTY` | `linkerhand::hand::L10FrameProperty` | +| L20 | `LinkerHandL20::FRAME_PROPERTY` | `linkerhand::hand::L20FrameProperty` | +| L25/L21 | `LinkerHandL25::FRAME_PROPERTY` | `linkerhand::hand::L25FrameProperty` | + +**重要改进**: +- 枚举类型从 `typedef enum` 改为 `enum class`(C++11 强类型枚举) +- 解决了多个枚举类型之间的命名冲突问题 +- 枚举值现在需要使用作用域限定符访问(如 `L6FrameProperty::JOINT_POSITION`) + +**使用示例**: +```cpp +// 旧方式(已废弃,但仍可通过向后兼容别名使用) +LinkerHandL6::FRAME_PROPERTY prop = LinkerHandL6::FRAME_PROPERTY::JOINT_POSITION; + +// 新方式(推荐) +linkerhand::hand::L6FrameProperty prop = linkerhand::hand::L6FrameProperty::JOINT_POSITION; + +// 转换为整数(用于 CAN 帧) +uint8_t frameProperty = static_cast(linkerhand::hand::L6FrameProperty::JOINT_POSITION); +``` + +### 4. 参数命名修正 + +修正了错误的参数命名: + +**改进前(错误)**: +```cpp +LinkerHandApi(const LINKER_HAND &handJoint, ...); +LINKER_HAND handJoint_; // 这是手型号,不是关节 +``` + +**改进后(正确)**: +```cpp +LinkerHandApi(const LINKER_HAND &handModel, ...); +LINKER_HAND handModel_; // 手型号(L6, L7, L10, L20, L21, L25 等) +``` + +**说明**: +- `handJoint` 命名不准确,因为这是手型号(Model),不是关节(Joint) +- 已统一修正为 `handModel`,更准确地表示手型号 + +## 向后兼容性 + +为了保持向后兼容,所有旧的命名空间和类名都通过 `using` 别名保留: + +```cpp +// 向后兼容:在旧命名空间中提供别名 +namespace LinkerHandL10 { + using FRAME_PROPERTY = linkerhand::hand::L10FrameProperty; + using LinkerHand = linkerhand::hand::L10Hand; +} // namespace LinkerHandL10 +``` + +这意味着现有代码可以继续使用旧的命名,无需立即修改。 + +## 使用示例 + +### 使用新命名(推荐) + +```cpp +#include "LinkerHandL10.h" +#include "HandFactory.h" + +// 使用新的命名空间和类名 +using namespace linkerhand; + +auto hand = factory::HandFactory::createHand( + LINKER_HAND::L10, + HAND_TYPE::RIGHT, + COMM_CAN_0 +); +// hand 的类型是 std::unique_ptr +// 实际类型是 hand::L10Hand +``` + +### 使用旧命名(向后兼容) + +```cpp +#include "LinkerHandL10.h" +#include "HandFactory.h" + +// 仍然可以使用旧的命名空间 +LinkerHandL10::LinkerHand hand(0x27, "can0", 1000000); +``` + +## 迁移建议 + +### 阶段一:保持兼容(当前) + +- ✅ 所有新命名已实现 +- ✅ 向后兼容别名已添加 +- ✅ 现有代码无需修改即可继续工作 + +### 阶段二:逐步迁移(推荐) + +1. **新代码使用新命名**:所有新编写的代码应使用新的命名空间和类名 +2. **更新文档和示例**:逐步更新文档和示例代码使用新命名 +3. **代码审查**:在代码审查中鼓励使用新命名 + +### 阶段三:完全迁移(未来) + +在未来版本中,可以考虑: +- 移除向后兼容别名(需要主版本号升级) +- 更新所有内部代码使用新命名 +- 更新所有文档和示例 + +## 优势 + +1. **一致性**:所有型号使用统一的命名空间结构 +2. **可读性**:类名直接反映型号(`L10Hand` vs `LinkerHand`) +3. **可维护性**:统一的命名空间便于管理和查找 +4. **扩展性**:新型号可以轻松添加到同一命名空间 + +## 注意事项 + +1. **工厂类**:`HandFactory` 已更新为使用新类名,但返回类型仍然是 `IHand` 接口 +2. **头文件**:头文件名暂时保持不变,未来可以考虑重命名 +3. **枚举**: + - 帧属性枚举已重命名,枚举值保持不变 + - 枚举类型已改为 `enum class`,需要使用作用域限定符访问枚举值 + - 这解决了多个枚举类型之间的命名冲突问题(如 `JOINT_POSITION`、`TORQUE_LIMIT` 等) + - 如果需要将枚举值转换为整数,使用 `static_cast()` + +## 相关文件 + +- `include/LinkerHandL6.h` - L6/O6 型号实现 +- `include/LinkerHandL7.h` - L7 型号实现 +- `include/LinkerHandL10.h` - L10 型号实现 +- `include/LinkerHandL20.h` - L20 型号实现 +- `include/LinkerHandL25.h` - L25/L21 型号实现 +- `include/ModbusLinkerHandL10.h` - Modbus L10 型号实现 +- `include/HandFactory.h` - 工厂类 + +## 版本信息 + +- **改进版本**:1.1.7+ +- **兼容性**:完全向后兼容 + diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index e3b5e88..2578d46 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -107,6 +107,39 @@ undefined reference to `LinkerHandApi::...` --- +### 问题:枚举命名冲突编译错误 + +**错误信息**: +``` +error: 'JOINT_POSITION' conflicts with a previous declaration +error: 'TORQUE_LIMIT' conflicts with a previous declaration +error: 'TOUCH_SENSOR_TYPE' conflicts with a previous declaration +``` + +**可能原因**: +在旧版本中,多个枚举类型(`L6FrameProperty`、`L7FrameProperty`、`L10FrameProperty` 等)使用 `typedef enum`,导致枚举值泄漏到外层命名空间,当多个头文件同时被包含时会发生命名冲突。 + +**解决方案**: +此问题已在最新版本中修复。所有枚举类型已改为使用 `enum class`(C++11 强类型枚举),每个枚举值都在自己的作用域内,不会发生命名冲突。 + +**如果使用旧版本**: +1. 升级到最新版本的 SDK +2. 如果必须使用旧版本,可以: + - 避免同时包含多个型号的头文件 + - 使用前向声明和单独编译单元 + - 使用命名空间别名隔离不同的枚举类型 + +**新版本使用方式**: +```cpp +// 使用作用域限定符访问枚举值 +linkerhand::hand::L6FrameProperty prop = linkerhand::hand::L6FrameProperty::JOINT_POSITION; + +// 转换为整数(用于 CAN 帧) +uint8_t frameProperty = static_cast(linkerhand::hand::L6FrameProperty::JOINT_POSITION); +``` + +--- + ### 问题:CMake 版本过低 **错误信息**: @@ -398,7 +431,7 @@ CMake 3.5 or higher is required ```cpp std::vector pose; - switch (hand.handJoint_) { + switch (hand.handModel_) { case LINKER_HAND::L6: case LINKER_HAND::O6: pose.resize(6); @@ -423,7 +456,7 @@ CMake 3.5 or higher is required ```cpp void safeFingerMove(LinkerHandApi& hand, const std::vector& pose) { int expected_size = 0; - switch (hand.handJoint_) { + switch (hand.handModel_) { case LINKER_HAND::L10: expected_size = 10; break; case LINKER_HAND::L20: expected_size = 20; break; // ... @@ -451,7 +484,7 @@ CMake 3.5 or higher is required 1. **检查型号支持**: ```cpp // 仅 L20 支持 setCurrent - if (hand.handJoint_ == LINKER_HAND::L20) { + if (hand.handModel_ == LINKER_HAND::L20) { hand.setCurrent(current); } else { std::cerr << "警告: setCurrent 仅支持 L20" << std::endl; diff --git a/examples/toolset_example.cpp b/examples/toolset_example.cpp index d6436b9..96eb13e 100644 --- a/examples/toolset_example.cpp +++ b/examples/toolset_example.cpp @@ -281,7 +281,7 @@ void interactiveMode(LinkerHandApi &hand) } break; case 11: - if (hand.handJoint_ == LINKER_HAND::L6) { + if (hand.handModel_ == LINKER_HAND::L6) { std::cout << "L6 - Execute action" << std::endl; for (size_t i = 0; i < 10; i++) { @@ -293,7 +293,7 @@ void interactiveMode(LinkerHandApi &hand) } - } else if (hand.handJoint_ == LINKER_HAND::L7) { + } else if (hand.handModel_ == LINKER_HAND::L7) { hand.setSpeed(std::vector(7, HAND_SPEED)); // L7 need 7 speed hand.setTorque(std::vector(7, HAND_TORQUE)); // L7 need 7 torque //--------------------------------------------------------- @@ -309,7 +309,7 @@ void interactiveMode(LinkerHandApi &hand) std::this_thread::sleep_for(std::chrono::seconds(1)); //--------------------------------------------------------- } - else if (hand.handJoint_ == LINKER_HAND::L10) + else if (hand.handModel_ == LINKER_HAND::L10) { hand.setSpeed(std::vector(5, HAND_SPEED)); // L10 need 5 speed hand.setTorque(std::vector(5, HAND_TORQUE)); // L10 need 5 torque @@ -344,7 +344,7 @@ void interactiveMode(LinkerHandApi &hand) std::this_thread::sleep_for(std::chrono::seconds(1)); //--------------------------------------------------------- } - else if (hand.handJoint_ == LINKER_HAND::L20) + else if (hand.handModel_ == LINKER_HAND::L20) { hand.setSpeed(std::vector(5, HAND_SPEED)); // L20 need 5 speed //--------------------------------------------------------- @@ -358,7 +358,7 @@ void interactiveMode(LinkerHandApi &hand) hand.fingerMove(L20_POSE_OPEN); std::this_thread::sleep_for(std::chrono::seconds(1)); } - else if (hand.handJoint_ == LINKER_HAND::L25 || hand.handJoint_ == LINKER_HAND::L21) + else if (hand.handModel_ == LINKER_HAND::L25 || hand.handModel_ == LINKER_HAND::L21) { hand.setSpeed(std::vector(25, HAND_SPEED)); hand.setTorque(std::vector(25, HAND_TORQUE)); diff --git a/include/HandFactory.h b/include/HandFactory.h index cde1e7d..41566a8 100644 --- a/include/HandFactory.h +++ b/include/HandFactory.h @@ -61,25 +61,25 @@ class HandFactory { if (canChannel == "can0" || canChannel == "can1" || canChannel == "ethercat") { switch (type) { case O6: - return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); + return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); break; case L6: - return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); + return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); break; case L7: - return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); + return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); break; case L10: - return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); + return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); break; case L20: - return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); + return std::unique_ptr(std::make_unique(handId, canChannel, baudrate)); break; case L21: - return std::unique_ptr(std::make_unique(handId, canChannel, baudrate, 1)); + return std::unique_ptr(std::make_unique(handId, canChannel, baudrate, 1)); break; case L25: - return std::unique_ptr(std::make_unique(handId, canChannel, baudrate, 0)); + return std::unique_ptr(std::make_unique(handId, canChannel, baudrate, 0)); break; default: throw std::invalid_argument("Unknown hand type"); @@ -88,7 +88,7 @@ class HandFactory { #if USE_RMAN switch (type) { case L10: - return std::unique_ptr(std::make_unique(handId)); + return std::unique_ptr(std::make_unique(handId)); default: throw std::invalid_argument("Unknown hand type"); break; diff --git a/include/LinkerHandApi.h b/include/LinkerHandApi.h index 3acdeef..5aef66c 100644 --- a/include/LinkerHandApi.h +++ b/include/LinkerHandApi.h @@ -21,11 +21,11 @@ class LinkerHandApi public: /** * @brief 构造函数 - * @param handJoint 手型号(LINKER_HAND 枚举) + * @param handModel 手型号(LINKER_HAND 枚举) * @param handType 手类型(左手/右手) * @param commType 通信类型(默认 CAN_0) */ - LinkerHandApi(const LINKER_HAND &handJoint, const HAND_TYPE &handType, + LinkerHandApi(const LINKER_HAND &handModel, const HAND_TYPE &handType, const COMM_TYPE commType = COMM_CAN_0); ~LinkerHandApi(); @@ -80,7 +80,7 @@ class LinkerHandApi std::unique_ptr hand; uint32_t handId; public: - LINKER_HAND handJoint_; + LINKER_HAND handModel_; // 手型号(L6, L7, L10, L20, L21, L25 等) HAND_TYPE handType_; }; diff --git a/include/LinkerHandL10.h b/include/LinkerHandL10.h index ca26216..5bce8d4 100644 --- a/include/LinkerHandL10.h +++ b/include/LinkerHandL10.h @@ -12,10 +12,11 @@ #include "IHand.h" #include "CanBusFactory.h" -namespace LinkerHandL10 -{ +namespace linkerhand { +namespace hand { -typedef enum +// L10 型号的帧属性枚举 +enum class L10FrameProperty { // INVALID_FRAME_PROPERTY = 0x00, // 无效的can帧属性 JOINT_POSITION_RCO = 0x01, // 关节1-6的关节位置 @@ -50,13 +51,18 @@ typedef enum RING_TOUCH = 0xB4, // 无名指触觉传感 LITTLE_TOUCH = 0xB5, // 小拇指触觉传感 PALM_TOUCH = 0xB6, // 手掌指触觉传感 -}FRAME_PROPERTY; +}; -class LinkerHand : public linkerhand::hand::IHand +/** + * @brief L10 型号灵巧手实现类 + * + * 提供 L10 型号的所有功能实现 + */ +class L10Hand : public IHand { public: - LinkerHand(uint32_t handId, const std::string &canChannel, int baudrate); - ~LinkerHand(); + L10Hand(uint32_t handId, const std::string &canChannel, int baudrate); + ~L10Hand(); // 设置关节位置 void setJointPositions(const std::vector &jointAngles) override; @@ -144,5 +150,14 @@ class LinkerHand : public linkerhand::hand::IHand uint8_t sensor_type = 0; }; + +} // namespace hand +} // namespace linkerhand + +// 向后兼容:在旧命名空间中提供别名 +namespace LinkerHandL10 { + using FRAME_PROPERTY = linkerhand::hand::L10FrameProperty; + using LinkerHand = linkerhand::hand::L10Hand; } // namespace LinkerHandL10 + #endif // LINKERHAND_L10_H \ No newline at end of file diff --git a/include/LinkerHandL20.h b/include/LinkerHandL20.h index 53cd1d9..0a44ea7 100644 --- a/include/LinkerHandL20.h +++ b/include/LinkerHandL20.h @@ -11,10 +11,11 @@ #include "IHand.h" #include "CanBusFactory.h" -namespace LinkerHandL20 -{ +namespace linkerhand { +namespace hand { -typedef enum +// L20 型号的帧属性枚举 +enum class L20FrameProperty { INVALID_FRAME_PROPERTY = 0x00, // 无效的can帧属性 | 无返回 JOINT_PITCH_R = 0x01, // 短帧俯仰角-手指根部弯曲程度 | 返回本类型数据 @@ -59,13 +60,17 @@ typedef enum RING_TOUCH = 0xB4, // 无名指触觉传感 LITTLE_TOUCH = 0xB5, // 小拇指触觉传感 PALM_TOUCH = 0xB6 // 手掌指触觉传感 -}FRAME_PROPERTY; - +}; -class LinkerHand : public linkerhand::hand::IHand { +/** + * @brief L20 型号灵巧手实现类 + * + * 提供 L20 型号的所有功能实现 + */ +class L20Hand : public IHand { public: - LinkerHand(uint32_t handId, const std::string& canChannel, int baudrate); - ~LinkerHand(); + L20Hand(uint32_t handId, const std::string& canChannel, int baudrate); + ~L20Hand(); // 设置关节位置 void setJointPositions(const std::vector &jointAngles) override; @@ -168,5 +173,14 @@ class LinkerHand : public linkerhand::hand::IHand { uint8_t sensor_type = 0; }; -} + +} // namespace hand +} // namespace linkerhand + +// 向后兼容:在旧命名空间中提供别名 +namespace LinkerHandL20 { + using FRAME_PROPERTY = linkerhand::hand::L20FrameProperty; + using LinkerHand = linkerhand::hand::L20Hand; +} // namespace LinkerHandL20 + #endif // LINKERHAND_L20_H \ No newline at end of file diff --git a/include/LinkerHandL25.h b/include/LinkerHandL25.h index 01a3684..b660f85 100644 --- a/include/LinkerHandL25.h +++ b/include/LinkerHandL25.h @@ -12,10 +12,11 @@ #include "IHand.h" #include "CanBusFactory.h" -namespace LinkerHandL25 -{ +namespace linkerhand { +namespace hand { -typedef enum +// L25/L21 型号的帧属性枚举 +enum class L25FrameProperty { INVALID_FRAME_PROPERTY = 0x00, // 无效的can帧属性 | 无返回 // 并行指令区域 @@ -125,13 +126,17 @@ typedef enum HAND_SAVE_PARAMETER = 0xCF, // 保存参数 WHOLE_FRAME = 0xF0, // 整帧传输 | 返回一字节帧属性+整个结构体485及网络传输专属 -}FRAME_PROPERTY; - +}; -class LinkerHand : public linkerhand::hand::IHand { +/** + * @brief L25/L21 型号灵巧手实现类 + * + * 提供 L25 和 L21 型号的所有功能实现 + */ +class L25Hand : public IHand { public: - LinkerHand(uint32_t handId, const std::string& canChannel, int baudrate, const int currentHandType = 0); - ~LinkerHand(); + L25Hand(uint32_t handId, const std::string& canChannel, int baudrate, const int currentHandType = 0); + ~L25Hand(); // 设置关节位置 void setJointPositions(const std::vector &jointAngles) override; @@ -425,5 +430,14 @@ class LinkerHand : public linkerhand::hand::IHand { std::vector>> touch_mats; }; -} + +} // namespace hand +} // namespace linkerhand + +// 向后兼容:在旧命名空间中提供别名 +namespace LinkerHandL25 { + using FRAME_PROPERTY = linkerhand::hand::L25FrameProperty; + using LinkerHand = linkerhand::hand::L25Hand; +} // namespace LinkerHandL25 + #endif // LINKERHAND_L25_H \ No newline at end of file diff --git a/include/LinkerHandL6.h b/include/LinkerHandL6.h index e96c20f..e8eeac1 100644 --- a/include/LinkerHandL6.h +++ b/include/LinkerHandL6.h @@ -12,10 +12,11 @@ #include "IHand.h" #include "CanBusFactory.h" -namespace LinkerHandL6 -{ +namespace linkerhand { +namespace hand { -typedef enum +// L6/O6 型号的帧属性枚举 +enum class L6FrameProperty { // 指令码 指令功能 数据长度 CAN发送DLC CAN接收DLC 数据范围 JOINT_POSITION = 0x01, // 关节1-6的关节位置 6 7 7 0-0xFF @@ -47,17 +48,22 @@ typedef enum RING_TOUCH = 0xB4, // 无名指触觉传感 LITTLE_TOUCH = 0xB5, // 小拇指触觉传感 PALM_TOUCH = 0xB6 // 手掌触觉传感 -} FRAME_PROPERTY; +}; // 协议辅助常量 static constexpr uint8_t TOUCH_TYPE_MATRIX = 0x02; // 矩阵型触觉类型值 static constexpr uint8_t TOUCH_PAGE_REQ = 0xC6; // 触觉分页读取的请求子命令 -class LinkerHand : public linkerhand::hand::IHand +/** + * @brief L6/O6 型号灵巧手实现类 + * + * 提供 L6 和 O6 型号的所有功能实现 + */ +class L6Hand : public IHand { public: - LinkerHand(uint32_t handId, const std::string &canChannel, int baudrate); - ~LinkerHand(); + L6Hand(uint32_t handId, const std::string &canChannel, int baudrate); + ~L6Hand(); // 设置关节位置 void setJointPositions(const std::vector &jointAngles) override; @@ -142,5 +148,14 @@ class LinkerHand : public linkerhand::hand::IHand void parseSerialNumber(const std::vector& data); std::string getErrorDescription(uint8_t error_code); }; + +} // namespace hand +} // namespace linkerhand + +// 向后兼容:在旧命名空间中提供别名 +namespace LinkerHandL6 { + using FRAME_PROPERTY = linkerhand::hand::L6FrameProperty; + using LinkerHand = linkerhand::hand::L6Hand; } // namespace LinkerHandL6 + #endif // LINKERHAND_L6_H diff --git a/include/LinkerHandL7.h b/include/LinkerHandL7.h index dbe4d59..ddbb8f1 100644 --- a/include/LinkerHandL7.h +++ b/include/LinkerHandL7.h @@ -12,10 +12,11 @@ #include "IHand.h" #include "CanBusFactory.h" -namespace LinkerHandL7 -{ +namespace linkerhand { +namespace hand { -typedef enum +// L7 型号的帧属性枚举 +enum class L7FrameProperty { // 指令码 指令功能 数据长度 CAN发送DLC CAN接收DLC 数据范围 JOINT_POSITION = 0x01, // 关节1-7的关节位置 7 8 8 0-0xFF @@ -43,13 +44,18 @@ typedef enum RING_TOUCH = 0xB4, // 无名指触觉传感 LITTLE_TOUCH = 0xB5, // 小拇指触觉传感 PALM_TOUCH = 0xB6 // 手掌指触觉传感 -}FRAME_PROPERTY; +}; -class LinkerHand : public linkerhand::hand::IHand +/** + * @brief L7 型号灵巧手实现类 + * + * 提供 L7 型号的所有功能实现 + */ +class L7Hand : public IHand { public: - LinkerHand(uint32_t handId, const std::string &canChannel, int baudrate); - ~LinkerHand(); + L7Hand(uint32_t handId, const std::string &canChannel, int baudrate); + ~L7Hand(); // 设置关节位置 void setJointPositions(const std::vector &jointAngles) override; @@ -129,5 +135,14 @@ class LinkerHand : public linkerhand::hand::IHand uint8_t sensor_type = 0; }; + +} // namespace hand +} // namespace linkerhand + +// 向后兼容:在旧命名空间中提供别名 +namespace LinkerHandL7 { + using FRAME_PROPERTY = linkerhand::hand::L7FrameProperty; + using LinkerHand = linkerhand::hand::L7Hand; } // namespace LinkerHandL7 + #endif // LINKERHAND_L7_H \ No newline at end of file diff --git a/include/ModbusLinkerHandL10.h b/include/ModbusLinkerHandL10.h index 2da7ea4..0efa7d5 100644 --- a/include/ModbusLinkerHandL10.h +++ b/include/ModbusLinkerHandL10.h @@ -12,10 +12,15 @@ #include "ModBus.h" #include "IHand.h" -namespace ModbusLinkerHandL10 -{ +namespace linkerhand { +namespace hand { -class LinkerHand : public linkerhand::hand::IHand +/** + * @brief Modbus L10 型号灵巧手实现类 + * + * 提供通过 Modbus 协议通信的 L10 型号功能实现 + */ +class ModbusL10Hand : public IHand { public: LinkerHand(uint32_t handId); @@ -51,6 +56,14 @@ class LinkerHand : public linkerhand::hand::IHand std::vector torque; }; -} + +} // namespace hand +} // namespace linkerhand + +// 向后兼容:在旧命名空间中提供别名 +namespace ModbusLinkerHandL10 { + using LinkerHand = linkerhand::hand::ModbusL10Hand; +} // namespace ModbusLinkerHandL10 + #endif #endif // LINKERHAND_MODBUS_L10_H diff --git a/tests/README.md b/tests/README.md index cf6143a..76dd2a8 100644 --- a/tests/README.md +++ b/tests/README.md @@ -325,6 +325,52 @@ TEST(NewFeatureTest, BasicFunctionality) { } ``` +### 命名规范说明 + +在编写测试时,请注意以下命名规范: + +1. **使用新的命名空间**(推荐): +```cpp +#include "LinkerHandL10.h" +#include "HandFactory.h" + +TEST(HandTest, L10HandCreation) { + using namespace linkerhand; + auto hand = factory::HandFactory::createHand( + LINKER_HAND::L10, + HAND_TYPE::RIGHT, + COMM_CAN_0 + ); + // 测试代码 +} +``` + +2. **向后兼容的旧命名**(可用但不推荐): +```cpp +#include "LinkerHandL10.h" + +TEST(HandTest, L10HandCreation) { + // 旧命名仍然可用,但建议使用新命名 + LinkerHandL10::LinkerHand hand(0x27, "can0", 1000000); + // 测试代码 +} +``` + +3. **接口测试**: +```cpp +#include "IHand.h" + +TEST(IHandTest, InterfaceTest) { + // 使用正确的命名空间 + class TestHand : public linkerhand::hand::IHand { + // 实现接口 + }; + // 测试代码 +} +``` + +更多关于命名规范的详细信息,请参考 [命名规范改进文档](../docs/NAMING_IMPROVEMENTS.md)。 + ### 步骤 2: 更新 CMakeLists.txt 在 `tests/CMakeLists.txt` 的 `TEST_SOURCES` 列表中添加新文件: @@ -599,6 +645,7 @@ CMake Error: ... - **API 参考**: [API 参考文档](../docs/API-Reference.md) - **故障排查**: [故障排查指南](../docs/TROUBLESHOOTING.md) - **常见问题**: [常见问题解答](../docs/FAQ.md) +- **命名规范**: [命名规范改进文档](../docs/NAMING_IMPROVEMENTS.md) ### Google Test 文档