裁判系统（Referee）设备组件¶

裁判系统串口协议子模块，需要结合 https://github.comZJU-HelloWorldHW-Components 的 cpp24 分支使用

外设驱动配置¶

在使用 UART 发送接收裁判系统数据时，使用 CubeMX 配置时将对应串口波特率调整至 115200，无校验位。

DMA 配置详见通用通信驱动中 UART 部分的 DMA 配置。

使用前准备¶

使用前需要做以下准备：

在 config.cmake 文件中设置 use_hwcomponents_devices_referee 选项为 ON，若为 OFF 则根驱动配置需求在 CMakeLists.txt 文件中重配置为 ON。
外设驱动配置请查看通用通信驱动中 UART 部分的配置。

1. 使用示例¶

在项目中引用头文件：

C++
#include "referee.hpp"
#include "rfr_official_pkgs.hpp"
#include "uart_rx_mgr.hpp"
#include "uart_tx_mgr.hpp"

namespace hw_rfr = hello_world::referee;
namespace hw_comm = hello_world::comm;

实例化一个 Referee 对象，添加需要接收的数据包指针，然后将其添加到 UART 的发送与接收管理器中，如：

C++
hw_rfr::Referee referee;

hw_comm::UartRxMgr* rfr_rx_mgr_ptr = nullptr;
hw_comm::UartTxMgr* rfr_tx_mgr_ptr = nullptr;

/* 所需接收的数据包 */
hw_rfr::RobotPerformancePackage robot_perf_pkg;
hw_rfr::RobotPowerHeatPackage robot_power_heat_pkg;
hw_rfr::RobotShooterPackage robot_shooter_pkg;
/* 更多的包... */

void RfrInit(void)
{
  /* 事先完成管理器的初始化 */
  rfr_rx_mgr_ptr = new hw_comm::UartRxMgr(
      &huart6, hw_comm::UartRxMgr::EofType::kManual, 32, 32);
  rfr_tx_mgr_ptr = new hw_comm::UartTxMgr(
      &huart6, hw_rfr::kRefereeMaxFrameLength);

  referee.init(0)  // 自动计算离线阈值

  /* 添加数据包 */
  referee.appendRxPkg(&robot_perf_pkg);
  referee.appendRxPkg(&robot_power_heat_pkg);
  referee.appendRxPkg(&robot_shooter_pkg);

  rfr_rx_mgr_ptr->addReceiver(&referee);
  rfr_tx_mgr_ptr->addTransmitter(&referee);

  /* 事后调用接收管理器的开启接收 */
}

注意:

添加的数据包指针必须是 ProtocolRxPackage 及其子类的指针，且其指向的对象生命周期必须大于等于 Referee 对象。
解包时，Refereee 对象会自动跳过 0x5A 之前的无效字节。

对于发送，在发送时添加所需发送的数据包，并设置为需发送状态。

C++
hw_rfr::InterGraphic7Package inter_graphic7_pkg1;
hw_rfr::InterGraphic7Package inter_graphic7_pkg2;
hw_rfr::InterGraphic7Package inter_graphic7_pkg3;

void Loop1ms(void) {
  static uint32_t pkg_cnt = 0;

  /* 交替发送包 */
  if (pkg_cnt % 3 == 0) {
    if (referee.setTxPkg(&inter_graphic7_pkg1)) {
      /* 设置为需要发送 */
      uart_tx_mgr_ptr->setTransmitterNeedToTransmit(&referee);
      pkg_cnt++; // 设置成功后切换为下一个包
    }
  } else if (pkg_cnt % 3 == 1) {
    if (referee.setTxPkg(&inter_graphic7_pkg2)) {
      /* 设置为需要发送 */
      uart_tx_mgr_ptr->setTransmitterNeedToTransmit(&referee);
      pkg_cnt++; // 设置成功后切换为下一个包
    }
  } else {
    if (referee.setTxPkg(&inter_graphic7_pkg3)) {
      /* 设置为需要发送 */
      uart_tx_mgr_ptr->setTransmitterNeedToTransmit(&referee);
      pkg_cnt++; // 设置成功后切换为下一个包
    }
  }

  /* 开启串口管理器的发送 */
};

注意:

添加的数据包指针必须是 ProtocolTxPackage 及其子类的指针，且其指向的对象生命周期必须大于等于 Referee 对象。
设置要发送的包时，Referee 对象会在不满足发送间隔、传入非法数据、 CRC8 校验码设置失败、CRC16 校验码设置失败、传入数据包数据编码失败等情况时，返回 false，并且不会将包发出；只有当所有编码流程都成功完成时，才会包编码并拷贝至换从去，并返回 true。因此需要自行检查返回值。

接收与发送管理器的其他配置按要求进行，详见通用通信驱动中 UART 部分的使用方法。

RfrDecoder 与 RfrEncoder 为旧版裁判系统设备组件，如今功能被整合至 Referee，并为串口通信驱动做了适配，后续建议不再使用 RfrDecoder 与 RfrEncoder。

2. 维护指南¶

在 rfr_pkg 文件夹中包含了所有的裁判系统通信包，每当官方更新了新的版本的裁判系统通信协议，需从 main 分支派生一个新的分支，例如对于版本 v1.6.4，将对应分支命名为 v1.6.4，然后对包进行修改，若有添加新的通信包的需求，则参照其他包的写法进行编写，再完成编写并确保无误后，将当前分支合并到 main 分支下。

邪道用法¶

编译宏定义缓冲区大小¶

在 rfr_pkg_core.hpp 中，存在常数 const size_t kRefereeMaxFrameLength，可被宏 RFR_MAX_FRAME_LENGTH 定义覆盖，以改变缓冲区大小。默认为 135，即最大帧长为 135 字节。除此之外，RFR_MAX_FRAME_LENGTH 不超过 135 字节不会覆盖默认值。此常数会改变 RfrDecoder、RfrEncoder 及 Referee 对象的缓冲区大小。