controller-hd/User/hart

介绍

HART 协议模块是 C 语言编写的，使用者无需对 HART 协议了解，通过接口文档可以快速完成应用层协议开发。 模块可以分别被主机和从机使用，调用少量接口完成开发，模块接口测试覆盖率 100%。

架构

架构说明

HART 协议模块是设备与主机之间的通信协议，主机和从机之间通过串口通信，主机通过串口发送命令，从机接收命令并返回响应数据。因此，主机和从机都需要使用 HART 协议模块，主机和从机的接口不同，主机接口主要是发送命令，从机接口主要是接收命令并返回响应数据。

考虑到移植性在设计阶段模块因避免使用操作系统相关的接口，模块接口使用回调函数的方式实现，主机和从机需要实现不同的回调函数，主机需要实现发送数据的回调函数，从机需要实现接收数据的回调函数。

内容说明

1. 7.9 版本认证支持命令 78、79、534
2. safeHART 数字化安全连锁，一种通讯协议，主要是对数据部分增加了 CRC 校验和序列号，打开 Burst-Mode 后发送的命令发送的是 safeHART 命令。 https://library.fieldcommgroup.org/20085/TS20085/4.0/#page=36
3. 2024 年 3 月 8 日后提交测试必须是 3.8 版本测试
4. 新增 548-553 指令

软件设计

结构图

│ hart.c │ hart_cache.c │ hart_frame.c │ readme.md ├─inc │ hart.h │ hart_common_tables_specification.h │ hart_frame.h │ hart_frame_user.h │ ├─lib │ ├─flow │ │ example.c │ │ flow.h │ │ flow_core.c │ │ flow_core.h │ │ flow_def.h │ │ flow_sem.h │ │ README.md │ │ │ ├─inc │ │ data_type_def.h │ │ debug.h │ │ lib.h │ │ log.h │ │ malloc.h │ │ osel_arch.h │ │ sqqueue.h │ │ │ └─src │ debug.c │ lib.c │ malloc.c │ sqqueue.c │ ├─master │ ├─inc │ │ hart_master.h │ │ hart_master_frame.h │ │ hart_master_req.h │ │ hart_master_rsp.h │ │ │ └─src │ hart_master.c │ hart_master_frame.c │ hart_master_req.c │ hart_master_req_user.c │ hart_master_rsp.c │ ├─public │ └─slave ├─inc │ hart_slave.h │ hart_slave_frame.h │ hart_slave_req.h │ └─src hart_slave.c hart_slave_frame.c hart_slave_req.c hart_slave_req_user.c

组织结构

模块说明

文件	路径	说明
hart.c	./	用于处理 HART（高阶实时通信技术）模块的接口。这个文件包含了模块的初始化、数据处理、Flash 读写等函数，以及一个用于处理用户事件的回调函数
hart_cache.c	./	一个缓存消息模块，用于处理设备操作需要时间暂时不回复消息的情况
hart_frame.c	./	包含了用于处理帧数据结构、响应码、RTC 时间转换、日期检测等功能
hart_slave.c	./slave	Hart 从机处理函数，用于处理主机的请求并返回相应的响应
hart_slave_req.c	./slave	从机命令响应的处理函数
hart_slave_req_user.c	./slave	从机命令响应用户自定义指令的处理函数

主机模块说明暂时省略

hart.c

1. hart_init 函数：用于初始化 Hart 模块，根据传入的参数配置模块的工作模式（主模块或从模块）和接口。
2. hart_handle 函数：用于处理接收到的数据，根据模块的工作模式将数据分发给对应的主机或从机处理。
3. hart_storage_write 和 hart_storage_read 函数：用于实现 Flash 的读写操作。
4. perform_self_test 和 perform_self_test_finish 函数：用于自检设备。
5. device_reset 函数：用于设备复位。
6. squawk_control 函数：用于呼叫，根据传入的参数打开或关闭呼叫功能。
7. armed 函数：用于判断是否有技术人员按下一个特殊的按钮或按钮组合。
8. common_event 函数：用于处理用户自定义的事件。

hart_cache.c

1. 全局变量：sqqueue_ctrl_t cache，这是一个队列控制结构体，用于控制缓存队列的属性。
2. 缓存消息结构体：hart_cache_t，这个结构体包含了一个 uuid 字段，用于存储消息的唯一标识。还有其他一些与具体设备相关的字段，例如设备状态、操作结果等。
3. hart_cache_init()，用于初始化缓存队列。
4. hart_cache_add()，用于向缓存中添加一条消息。首先检查缓存是否已满，如果满则返回。然后分配内存，拷贝数据，并设置 uuid。最后将数据入队。
5. hart_cache_free()，用于释放缓存中一条消息的内存。
6. hart_cache_get()，用于根据 uuid 获取缓存中一条消息。首先检查缓存是否为空，如果为空则返回 NULL。然后遍历缓存中的消息，如果找到匹配的 uuid，则返回该消息。否则将当前消息出队，然后重新入队。

hart_frame.c

1. hart_frame_data_length_start 和 hart_frame_data_length_end 函数用于在处理请求开始和结束时记录帧数据长度位置。
2. hart_frame_response_code_start 和 hart_frame_response_code_end 函数用于在处理请求开始和结束时记录帧响应码起始位置。
3. hart_frame_response_communication_code 和 hart_frame_master_response_operate_code 函数用于设置和获取响应码第一个字节和第二个字节。
4. hart_is_write_command 函数用于判断指令是否是写。
5. hart_is_support_command 函数用于判断版本是否支持当前指令。
6. rtc_to_timestamp 函数用于将 RTC 时间转时间戳。
7. get_rtc_date 函数用于获取 RTC 的日期。
8. check_date 函数用于检测日期是否有效。
9. is_broadcast_address 函数用于判断地址是否为广播地址。
10. timestamp_to_hmsms 函数用于将时间戳转换为小时:分钟:秒:毫秒的格式。

hart_slave.c

1. hart_slave_state_check 来检查命令是否合法。如果命令合法，它将调用相应的处理函数 hart_command_ptr_arr[command]来处理命令。如果处理成功，它将返回 True，否则返回 False。 在处理完命令后，函数将响应数据的长度存储在 handle->response->cache_data.payload_length 中。如果响应数据长度不为 0，它将分配内存来存储响应数据，并将数据复制到分配的内存中。最后，它将响应数据结构 handle->response->cache_data 添加到缓存中，并发送响应数据。

2. hart_slave_handle 函数，该函数用于处理从机的请求。

• 首先，检查输入参数是否有效。
• 获取从机的地址。
• 比较主机请求的地址和从机地址是否一致。如果不一致，返回错误。
• 获取命令码。
• 根据命令码查找对应的处理函数。如果找不到对应的处理函数，返回错误。
• 执行处理函数，并将结果存储在 handle->response 结构体中。
• 计算响应数据的长度。
• 如果响应数据长度不为 0，为响应数据分配内存。
• 将响应数据结构体添加到缓存中。
• 返回处理成功。

3. hart_slave_init 函数，用于初始化从机。

• 检查输入参数是否有效。
• 初始化从机的请求处理结构体。
• 返回处理成功

4. hart_slave_device_send 函数,用于发送响应帧给一个 HART 从设备

• 定义一些变量，如响应数据长度、异或校验、数据长度指针、响应码指针等。
• 填充响应帧的数据，包括前导码、地址、命令、负载等。
• 计算响应帧的数据长度，并将结果存储在 data_len_p 中。
• 计算响应帧的校验码，并将结果存储在 response_code_p 中。
• 更新响应帧的长度字段和响应码字段。
• 如果响应帧的数据长度大于 0，调用 handle->response_call 函数将响应帧发送给指定的 UART 索引。同时，增加设备属性的消息计数器。

5. hart_slave_device_attribute_init 函数,用于从机设备属性初始化

hart_slave_req.c

1. hart_slave_req_init 函数，用于初始化哈希表，用于注册从端发送给主端的命令的处理函数。

• hart_command_ptr_arr 数组，用于存储命令码和处理函数的映射关系。因为命令码的使用不是连续的，因此占用了大量的空间，但是提高了查找效率。

hart_slave_req_user.c

实现方式上同 hart_slave_req.c，和通用命令做区分

移植步骤

这里以 STM32 为例，介绍如何移植 HART 协议模块。

1. 将 HART 协议模块的源码添加到工程中。 HART 协议模块中用到的 lib 也一并加入到工程中。

2. 添加宏定义和头文件 宏定义：STM32,SLAVE 头文件路径

3. HART 协议和应用层的中间层 该文件主要实现 HART 模块需要的和 MCU 相关的接口，例如串口发送、Flash 读写等。

hart_user_data_refush(): 刷新用户实时数据，包括模拟量和数字量。 response(uint8_t uart_index, uint8_t *data, uint16_t len): 发送数据(hart 协议数据帧)。 flash_read(uint32_t addr, uint8_t *data, uint16_t len): flash 读取接口。 flash_write(uint32_t addr, uint8_t *data, uint16_t len): flash 写入接口。 perform_self_test(void): 执行自检。 device_reset(void): 设备复位。 squawk_control(BOOL open, uint8_t second): 设备呼叫,0 一直呼叫，1-255 秒。 armed(void): 技术人员按下一个特殊的按钮或按钮组合，指示从机应响应 command74。 set_dynamics(device_variable_dynamics_t *const dynamics): 设置动态变量。 hart_rx_cb(uint8_t uart_index, uint8_t *data, uint16_t len): 串口 1、5 接收中断回调函数。 hart_tx_complete_cb(void): 串口 1 发送完成回调函数。 hart_uart_init(void): 串口 1 初始化。 hart_uart_dinit(void): 串口 1 去初始化。 hart_ble_init(void): BLE 初始化。 hart_ble_dinit(void): BLE 去初始化。 hart_init(void): HART 初始化。 hart_dinit(void): HART 去初始化。 hart_task(void): HART 任务。

源码实现：

/*
 * @Author: xxx
 * @Date: 2023-08-02 08:28:36
 * @LastEditors: xxx
 * @LastEditTime: 2023-08-23 14:15:44
 * @Description: 此文件主要实现板卡的HART功能
 * Copyright (c) 2023 by xxx, All Rights Reserved.
 */

#include "app.h"
#include "hart.h"
#include "hart_frame.h"
#include "uarts.h"
#include "test_bsp.h"

#define HART_UART1 USART1
#define HART_UART2 USART5

#define UART_RXSIZE (240u)
#define UART_TXSIZE (240u)
uart_t *uarts[APP_UART_MAX];

app_dynamics_t app_dynamics;
static __IO BOOL hart_idle = TRUE;

static void hart_user_data_refush(void)
{
    app_analog_quantity_t *analog_quantity = &app_dynamics.analog_quantity;
    app_digital_quantity_t *digital_quantity = &app_dynamics.digital_quantity;

    // 模拟量
    analog_quantity->input_current = adc_raw[ADC_LOOP_CHANNEL];             // 输入电流
    analog_quantity->valve_feedback = adc_raw[ADC_PSB_CHANNEL];             // 阀门反馈
    analog_quantity->atmospheric_pressure_source = adc_raw[ADC_BP_CHANNEL]; // 气压源压力
    analog_quantity->pressure_at_port_a = 0;                                // A口压力
    analog_quantity->pressure_at_port_b = 0;                                // B口压力
    analog_quantity->amplifier_circuit = adc_raw[ADC_IPSB_CHANNEL];         // 放大器回路
    analog_quantity->built_in_temperature = 0;                              // 内置温度
    analog_quantity->ip_output_detection = rt_data.ip_output;                         // IP输出检测
    analog_quantity->valve_percentage = actual_travel;                      // 阀位百分比

    // 数字量
    digital_quantity->input_current = loop_current;                          // 输入电流
    digital_quantity->valve_feedback = adc_raw[ADC_PSB_CHANNEL];             // 阀门反馈
    digital_quantity->atmospheric_pressure_source = adc_raw[ADC_BP_CHANNEL]; // 气压源压力
    digital_quantity->pressure_at_port_a = 0;                                // A口压力
    digital_quantity->pressure_at_port_b = 0;                                // B口压力
    digital_quantity->amplifier_circuit = adc_raw[ADC_IPSB_CHANNEL];         // 放大器回路
    digital_quantity->built_in_temperature = 0;                              // 内置温度
    digital_quantity->ip_output_detection = rt_data.ip_output;                         // IP输出检测

    digital_quantity->target_row = target_travel;  // 目标行程
    digital_quantity->current_row = actual_travel; // 实际行程
    digital_quantity->friction = 0;                // 摩擦力
    digital_quantity->spring_force = 0;            // 弹簧力
}

/**
 * @brief 发送数据(hart协议数据帧)
 * @param {uint8_t} *txBuf
 * @param {uint16_t} len
 * @return {*}
 */
static void response(uint8_t uart_index, uint8_t *data, uint16_t len)
{
#ifdef STM32
    if (uart_index == APP_UART_1)
    {
        HART_CD_OFF(); // 因为DMA发送调用uart_send_data接口后会立即退出，不需要等待发送是否成功，因此HART_CD_ON需要在DMA发送完成中断中调用
    }

    uart_send_data(uarts[uart_index], data, len);
#else
    LOG_HEX(data, len);
#endif
}

/**
 * @brief flash读取接口
 * @param {uint32_t} addr
 * @param {uint8_t} *data
 * @param {uint16_t} len
 * @return {*}
 */
static BOOL flash_read(uint32_t addr, uint8_t *data, uint16_t len)
{
    m95_1_normal_read(addr, data, len);
    return TRUE;
}

/**
 * @brief flash写入接口
 * @param {uint32_t} addr
 * @param {uint8_t} *data
 * @param {uint16_t} len
 * @return {*}
 */
static BOOL flash_write(uint32_t addr, uint8_t *data, uint16_t len)
{
    m95_1_normal_write(addr, data, len);
    return TRUE;
}

/**
 * @brief 执行自检
 * @param {*}
 * @return {*}
 */
static void perform_self_test(void)
{
}

/**
 * @brief 设备复位
 * @param {*}
 * @return {*}
 */
static void device_reset(void)
{
}

/**
 * @brief 设备呼叫,0一直呼叫，1-255秒
 * @param {*}
 * @return {*}
 */
static void squawk_control(BOOL open, uint8_t second)
{
}

/**
 * @brief 技术人员按下一个特殊的按钮或按钮组合，指示从机应响应command74
 * @param {*}
 * @return {*}
 */
static BOOL armed(void)
{
    return TRUE;
}

/**
 * @brief 设置动态变量
 * @return {*}
 */
static BOOL set_dynamics(device_variable_dynamics_t *const dynamics)
{
    app_analog_quantity_t *analog_quantity = &app_dynamics.analog_quantity;
    app_digital_quantity_t *digital_quantity = &app_dynamics.digital_quantity;

    // 模拟量
    dynamics->dynamics_user.analog_quantity.input_current = &analog_quantity->input_current;                             // 输入电流
    dynamics->dynamics_user.analog_quantity.valve_feedback = &analog_quantity->valve_feedback;                           // 阀门反馈
    dynamics->dynamics_user.analog_quantity.atmospheric_pressure_source = &analog_quantity->atmospheric_pressure_source; // 大气压力源
    dynamics->dynamics_user.analog_quantity.pressure_at_port_a = &analog_quantity->pressure_at_port_a;                   // A口压力
    dynamics->dynamics_user.analog_quantity.pressure_at_port_b = &analog_quantity->pressure_at_port_b;                   // B口压力
    dynamics->dynamics_user.analog_quantity.amplifier_circuit = &analog_quantity->amplifier_circuit;                     // 放大器电路
    dynamics->dynamics_user.analog_quantity.built_in_temperature = &analog_quantity->built_in_temperature;               // 内置温度
    dynamics->dynamics_user.analog_quantity.ip_output_detection = &analog_quantity->ip_output_detection;                 // IP输出检测
    dynamics->dynamics_user.analog_quantity.valve_percentage = &analog_quantity->valve_percentage;                       // 阀位百分比

    // 数字量
    dynamics->dynamics_user.digital_quantity.input_current = &digital_quantity->input_current;                             // 输入电流
    dynamics->dynamics_user.digital_quantity.valve_feedback = &digital_quantity->valve_feedback;                           // 阀门反馈
    dynamics->dynamics_user.digital_quantity.atmospheric_pressure_source = &digital_quantity->atmospheric_pressure_source; // 大气压力源
    dynamics->dynamics_user.digital_quantity.pressure_at_port_a = &digital_quantity->pressure_at_port_a;                   // A口压力
    dynamics->dynamics_user.digital_quantity.pressure_at_port_b = &digital_quantity->pressure_at_port_b;                   // B口压力
    dynamics->dynamics_user.digital_quantity.amplifier_circuit = &digital_quantity->amplifier_circuit;                     // 放大器电路
    dynamics->dynamics_user.digital_quantity.built_in_temperature = &digital_quantity->built_in_temperature;               // 内置温度
    dynamics->dynamics_user.digital_quantity.ip_output_detection = &digital_quantity->ip_output_detection;                 // IP输出检测
    dynamics->dynamics_user.digital_quantity.target_row = &digital_quantity->target_row;                                   // 目标行程
    dynamics->dynamics_user.digital_quantity.current_row = &digital_quantity->current_row;                                 // 当前行程
    dynamics->dynamics_user.digital_quantity.friction = &digital_quantity->friction;                                       // 摩擦力
    dynamics->dynamics_user.digital_quantity.spring_force = &digital_quantity->spring_force;                               // 弹簧力

    return TRUE;
}

static BOOL common_event(hart_interface_user_event_e event, const void *const data)
{
    switch (event)
    {
    case HART_COMMAND_257_EVENT:
        // 寻找、计算P / I / D
        break;
    case HART_COMMAND_258_EVENT:
        // 计算 摩擦力
        break;
    case HART_COMMAND_259_EVENT:
        // 计算 弹簧力
        break;
    case HART_COMMAND_UPDATE_EVENT:
        // 刷新用户实时数据
        hart_user_data_refush();
        break;
    case HART_COMMAND_500_EVENT:
        // 测试命令
        return hart_user_test((hart_user_req_t *)data);
    default:
        return FALSE;
    }
    return TRUE;
}

// 串口1、5接收中断回调函数
static void hart_rx_cb(uint8_t uart_index, uint8_t *data, uint16_t len)
{
    DBG_ASSERT(uart_index < APP_UART_MAX __DBG_LINE);
    hart_idle = FALSE;
    // 串口1接收HART数据，因为是空闲中断处理这里只过滤掉前导码
    hart_handle(uart_index, data, len);
    hart_idle = TRUE;
}

static void hart_tx_complete_cb(void)
{
    // 串口1发送完成回调函数
    HART_CD_ON();
}

void hart_uart_init(void)
{
    LL_APB2_GRP1_EnableClock(LL_APB2_GRP1_PERIPH_USART1);
    GPIO_SET_OUTPUT(HART_EN_GPIO_Port, HART_EN_Pin);
    GPIO_SET_OUTPUT(HART_RST_GPIO_Port, HART_RST_Pin);
    GPIO_SET_OUTPUT(HART_CD_GPIO_Port, HART_CD_Pin);
    GPIO_SET_ALTERNATE(HART_TX_GPIO_Port, HART_TX_Pin);
    GPIO_SET_ALTERNATE(HART_RX_GPIO_Port, HART_RX_Pin);
    delay_ms(10);
    // 串口1初始化开始
    HART_CD_ON();
    HART_RST_OFF();
    delay_ms(20);
    HART_RST_ON();
    HART_EN_DISABLE();
    HART_EN_ENABLE();
    HART_CD_ON();

    if (uarts[APP_UART_1] == NULL)
    {
        uarts[APP_UART_1] = uart_create(HART_UART1, TRUE, UART_RXSIZE, hart_rx_cb, TRUE, UART_TXSIZE, hart_tx_complete_cb);
        uarts[APP_UART_1]->uart_index = APP_UART_1;
        uarts[APP_UART_1]->dma = DMA1;
        uarts[APP_UART_1]->dma_rx_channel = LL_DMA_CHANNEL_3;
        uarts[APP_UART_1]->dma_tx_channel = LL_DMA_CHANNEL_2;
        uart_recv_en(uarts[APP_UART_1]);
    }
    // 串口1初始化结束
}

void hart_uart_dinit(void)
{
    HART_EN_DISABLE();
    LL_APB2_GRP1_DisableClock(LL_APB2_GRP1_PERIPH_USART1);
    LL_USART_Disable(USART1);
    GPIO_SET_ANALOG(HART_EN_GPIO_Port, HART_EN_Pin);
    GPIO_SET_ANALOG(HART_RST_GPIO_Port, HART_RST_Pin);
    GPIO_SET_ANALOG(HART_CD_GPIO_Port, HART_CD_Pin);
    GPIO_SET_ANALOG(HART_TX_GPIO_Port, HART_TX_Pin);
    GPIO_SET_ANALOG(HART_RX_GPIO_Port, HART_RX_Pin);
}

void hart_ble_init(void)
{
    LL_APB1_GRP1_EnableClock(LL_APB1_GRP1_PERIPH_USART5);
    GPIO_SET_OUTPUT(BLE_PWR_GPIO_Port, BLE_PWR_Pin);
    GPIO_SET_INPUT(BLE_STATE_GPIO_Port, BLE_STATE_Pin);
    GPIO_SET_ALTERNATE(BLE_TX_GPIO_Port, BLE_TX_Pin);
    GPIO_SET_ALTERNATE(BLE_RX_GPIO_Port, BLE_RX_Pin);
    BLE_EN_ENABLE();
    delay_ms(100);
    if (uarts[APP_UART_2] == NULL)
    {
        uarts[APP_UART_2] = uart_create(HART_UART2, TRUE, UART_RXSIZE, hart_rx_cb, TRUE, UART_TXSIZE, NULL);
        uarts[APP_UART_2]->uart_index = APP_UART_2;
        uarts[APP_UART_2]->dma = DMA1;
        uarts[APP_UART_2]->dma_rx_channel = LL_DMA_CHANNEL_6;
        uarts[APP_UART_2]->dma_tx_channel = LL_DMA_CHANNEL_7;
        uart_recv_en(uarts[APP_UART_2]);
    }
}

void hart_ble_dinit(void)
{
    BLE_EN_DISABLE();
    LL_APB1_GRP1_DisableClock(LL_APB1_GRP1_PERIPH_USART5);
    LL_USART_Disable(USART5);
    GPIO_SET_ANALOG(BLE_PWR_GPIO_Port, BLE_PWR_Pin);
    GPIO_SET_ANALOG(BLE_STATE_GPIO_Port, BLE_STATE_Pin);
    GPIO_SET_ANALOG(BLE_TX_GPIO_Port, BLE_TX_Pin);
    GPIO_SET_ANALOG(BLE_RX_GPIO_Port, BLE_RX_Pin);
}

BOOL app_hart_is_idle(void)
{
    return hart_idle;
}

BOOL app_hart_init(void)
{
    hart_init_t init;
    init.hart_protocol_version = HART_PROTOCOL_VERSION_7;
    init.dir = MODULE_SLAVE;
    init.interface.response = response;
    init.interface.flash_read = flash_read;
    init.interface.flash_write = flash_write;
    init.interface.perform_self_test = perform_self_test;
    init.interface.device_reset = device_reset;
    init.interface.squawk_control = squawk_control;
    init.interface.armed = armed;
    init.interface.set_dynamics = set_dynamics;
    init.interface.common_event = common_event;

    uarts[APP_UART_1] = NULL;
    uarts[APP_UART_2] = NULL;
    // 判断当前电流  >=8mA启动蓝牙  >=3.8mA启动uart
    // 注：串口初始化移动到all_flow
    // hart_uart_init();
    // hart_ble_init();
    return hart_init(&init);
}