硬件设备注解（Hardware Annotations）

概述

FTC 机器人编程中，硬件设备相关的注解帮助开发者管理设备配置、声明设备类型和处理硬件交互。本文档详细介绍这些注解的用法和作用。

硬件设备基础注解

@HardwareDevice

@HardwareDevice(name="基础电机", description="直流电机设备")
public class MyCustomMotor implements DcMotor {
    // 实现代码
}

详细解释：

• 定义：标记一个类实现了硬件设备接口
• 参数：
  • name：硬件设备的默认名称
  • description：设备的描述信息
• 使用场景：
  • 创建自定义硬件设备类
  • 为新设备类型提供基本信息
• 技术细节：
  • 主要用于 SDK 内部和硬件开发，普通团队较少直接使用
  • 提供给硬件系统识别和分类设备的信息

@DeviceProperties

@DeviceProperties(name="自定义传感器", xmlTag="customSensor")
public class MyCustomSensor implements HardwareDevice {
    // 实现代码
}

详细解释：

• 定义：定义硬件设备的属性，包括其在 XML 配置中的表示
• 参数：
  • name：设备类型的人类可读名称
  • xmlTag：在硬件配置 XML 文件中使用的标签
  • builtIn：是否为内置设备类型
• 使用场景：
  • 创建自定义设备类型
  • 定义如何在机器人配置文件中表示此设备
• 技术细节：
  • 影响设备在机器人配置工具中的显示
  • 与 XML 配置系统集成

硬件映射注解

@Deprecated

@Deprecated
public void oldMotorMethod() {
    // 过时的方法实现
}

详细解释：

• 定义：标记一个类、方法或字段已过时，不推荐使用
• 参数：无
• 使用场景：
  • 标记已被更新 API 替代的旧硬件接口
  • 指示应使用的新替代方法
• 技术细节：
  • 编译器会对使用带有此注解的元素发出警告
  • 通常与 Javadoc 的@deprecated标记一起使用，提供迁移建议

@DontObfuscate

@DontObfuscate
public class ExposedHardwareInterface {
    // 需要保留原始名称的代码
}

详细解释：

• 定义：指示代码混淆工具不应修改类、方法或字段的名称
• 参数：无
• 使用场景：
  • 通过反射访问的硬件接口类
  • 需要与外部系统以固定名称交互的组件
• 技术细节：
  • 影响 ProGuard 等代码混淆工具的行为
  • 确保硬件交互代码在优化后仍能正常工作

I2C 设备注解

@I2cDeviceType

@I2cDeviceType(value=123, name="自定义I2C传感器")
public class MyI2cSensor extends I2cDeviceSynch {
    // 实现代码
}

详细解释：

• 定义：标记一个类代表特定类型的 I2C 设备
• 参数：
  • value：设备类型 ID（通常是厂商指定的编码）
  • name：设备类型的友好名称
  • xmlTag：可选的 XML 配置标签
• 使用场景：
  • 定义与特定 I2C 设备交互的类
  • 允许硬件配置系统识别设备类型
• 技术细节：
  • 用于 I2C 总线设备的自动识别
  • 帮助驱动站匹配正确的设备驱动程序

@I2cAddr

@I2cAddr(value=0x76)
public class MyI2cDevice extends I2cDevice {
    // 实现代码
}

详细解释：

• 定义：指定 I2C 设备的默认地址
• 参数：
  • value：默认的 7 位 I2C 地址（十六进制）
  • `