跳到主要内容

API

1. 介绍​

1.1 什么是C小程序​

C 小程序是用 C/C++ 语言编写、可在 ETStudio 中运行的小型程序。通过 ETStudio 提供的 API，可方便实现定时器、CAN/LIN 报文收发、数字/模拟信号读写、电源控制与系统变量访问等功能。

1.2 文档说明​

本文档描述 C 小程序提供的 API 接口与用法示例。

2. 初始化函数与主函数​

2.1 简单示例​

title="./sample.cpp"
#include "BaseMiniProgram.h"

void OnStart()
{
   CAN::Frame frame(0x1F1, 8, CAN::Channel_1::ChannelMappingID);
   for(int i = 0; i < 8; i++) frame.Data(i) = 1;
   frame.Transmit();
}

void OnExit()
{
}

2.2 返回码定义​

typedef enum
{
ErrCode_Success = 0,
ErrCode_NullArgument,
ErrCode_NotImplemented,
ErrCode_ChannelDisabled,
ErrCode_DriverNotSupport = 254,
ErrCode_DriverError = 255,
} KAPI_ErrCode;

2.3 小程序初始化函数​

  1. OnStart：小程序启动后调用一次，可在此注册周期函数或启动定时器。
void OnStart()
{
}
  1. OnExit：小程序结束时调用。
void OnExit()
{
}

3. 全局变量​

3.1 GetCurrentChannelMappingID​

  • int GetCurrentChannelMappingID();
  • 说明
    • Channel Mapping ID 用于标识当前节点所属的通道映射，该 ID 在 ETStudio 中配置。

alt text

4. 定时器​

4.1 start_timer​

void* start_timer(uint64_t interval, boolean onceTimer, void (*onTimer)(void* pTimer));

说明

  • 启动一个定时器

参数

  • interval 定时器间隔，单位为毫秒
  • onceTimer
    • TRUE 单次定时器（超时后自动停止）
    • FALSE 周期定时器（超时后自动重启）
  • onTimer 定时器到时回调函数

返回

  • void* 定时器句柄

示例

// 创建一个 1 秒定时器
void onTimer(void* pTimer)
{
 	// 执行操作
}
start_timer(1000, FALSE, onTimer);

4.2 stop_timer​

void stop_timer(void* pTimer);

说明

  • 停止指定定时器

参数

示例

void onTimer(void* pTimer)
{
 	// 执行操作
}
void* timer = start_timer(1000, FALSE, onTimer);
...
stop_timer(timer);

5. 系统变量​

5.1 访问系统变量​

  1. 在 ETStudio 系统变量界面创建系统变量
    • alt text
  2. 读取系统变量值 
    int32_t varValue = namespace_example::int32value;
  3. 设置系统变量值 
    namespace_example::int32value = 30;

5.2 SetOnChange​

void SetOnChange(void (*onChange)())

说明

  • 注册系统变量变更时的回调函数

参数

  • onChange 系统变量变更时的回调函数

示例

void on_namespace_example_int32valueChange()
{
      int32_t varValue = namespace_example::int32value; 
}
void OnStart()
{
      namespace_example::int32value.SetOnChange(on_namespace_example_int32valueChange);
}

注意： 当前版本中新增或修改的系统变量在 Code Editor 中可能不会立即被识别，若 Code Editor 未检测到新变量，请重启 ETStudio。

6. 通过接口发送 DBC/LDF 定义的报文​

6.1 发送报文​

  1. void Transmit();

说明

  • 根据 Simulation Node 配置发送 CAN、CAN FD 或 LIN 报文。

示例

  • 假设已将 dbc/ldf 文件导入到 Simulation Network（LIN/CANBus），其中包含名为 Gateway_1 的报文，以下代码可用于发送该报文：
CANBus::Gateway_1 msg;
msg.Gear = 1;
msg.EngineRunning = 2;
msg.Ig_15 = 3;
msg.Ig_15R = 4;
msg.StarterKey = 5;
msg.Transmit();
  • 发送到指定 Channel Mapping ID：
CANBus::Gateway_1 msg(2);
msg.Gear = 1;
msg.EngineRunning = 2;
msg.Ig_15 = 3;
msg.Ig_15R = 4;
msg.StarterKey = 5;
msg.Transmit();
  • 发送到指定 BusType（例如 BUS_TYPE_CAN）：
CANBus::Gateway_1 msg;
msg.Gear = 1;
msg.EngineRunning = 2;
msg.Ig_15 = 3;
msg.Ig_15R = 4;
msg.StarterKey = 5;
msg.BusType = BUS_TYPE_CAN;
msg.Transmit();
  • CANBus 为仿真网络名
  • Gateway_1 为帧名
  • BusType 可为 BUS_TYPE_CAN、BUS_TYPE_CANFD、BUS_TYPE_LIN
  1. void TransmitHeader();

说明

  • 根据 Simulation Node 配置发送 LIN 帧头。

示例

LINBus::LIN_Test_message msg;
msg.TransmitHeader();
  • LINBus 为仿真网络名
  • LIN_Test_message 为 LIN 帧名

6.2 通过面板设置的信号值发送报文​

static int StaticTransmit(int channelMappingID = 0);

说明

  • 发送 CAN/CANFD/LIN 报文，报文中的信号值由面板（Panel）配置。

参数

  • channelMappingID 通道映射 ID，0 表示当前节点的默认通道 ID
  • busType BUS_TYPE_CAN、BUS_TYPE_CANFD 或 BUS_TYPE_LIN

示例

CANBus::Gateway_1::StaticTransmit();

6.3 接收报文回调​

void on_recv_message(<NetworkName>::<FrameName> *msg)

说明

  • 在接收到 CAN/CANFD/LIN 报文时注册回调函数

参数

  • msg 指向接收报文的指针，类型由导入的 dbc/ldf 文件决定

示例

void on_recv_message(CANBus::Gateway_1 *msg)
{
      // 处理接收报文
}
void OnStart()
{
   CANBus::Gateway_1::OnMessage = on_recv_message;
}

7. Frame​

7.1 注册报文​

7.1.1 注册CAN/LIN报文​

Frame(uint32_t frameID, uint32_t frameDataLen, uint32_t channelMappingID);

说明

  • 注册一个 CAN/LIN 报文

参数

  • frameID 报文 ID
  • frameDatalen 报文长度
  • channelMappingID 通道映射 ID，0 表示当前节点的默认通道 ID

示例

CAN::Frame frame(0x1F1, 8, CAN::Channel_1::ChannelMappingID);

LIN::Frame frame(0x3C, 8,LIN::Channel_1::ChannelMappingID);
  • 如需为所有通道注册报文，请参考以下示例

示例

CAN::Frame frame(0x1F1, 0, 0xFFFFFFFFL);

7.1.2 注册UDP报文​

Frame(uint32_t frameDataLen, uint32_t channelMappingID, UDPNodeInfo nodeInfo);

说明

  • 注册一个 UDP 报文

参数

  • frameDatalen 报文长度
  • channelMappingID 通道映射 ID，0 表示当前节点的默认通道 ID
  • nodeInfo UDP 节点网络信息

示例

Ethernet::UDPNodeInfo nodeInfo;
nodeInfo.setSrcMac( 1, 2, 3, 4, 5, 6 )
        .setSrcIp( 127, 0, 0, 1 )
        .setSrcPort(11)
        .setDstMac( 1, 2, 3, 4, 5, 6 )
        .setDstIp( 192, 168, 0, 1 )
        .setDstPort(29)
        .setTtl(64)
        .setVlan(129);
Ethernet::Frame frame(8, Ethernet::Channel_1::ChannelMappingID, nodeInfo);

7.2 修改注册信号数据​

说明

  • 定义信号后，可通过以下两种方式修改信号数据

示例

// 方法一
CAN::Frame frame(0x1F1, 8, CAN::Channel_1::ChannelMappingID);
for (int i = 0; i < 8; i++) frame.Data(i) = 1;//修改字节的值

// 方法二
CAN::Frame frame(0x1F1, 8, CAN::Channel_1::ChannelMappingID);
uint8_t* dataBuf = frame.Data();//获取起始指针
for (int i = 0; i < 8; i++) dataBuf[i] = 1;

7.3 发送信号​

  • 若仅需发送帧头，请参考以下代码

示例

LIN::Frame frame(0x3C, 8, LIN::Channel_1::ChannelMappingID);
for (int i = 0; i < 8; i++) frame.Data(i) = 1;
frame.TransmitHeader();
  • 如需发送完整信号，请参考以下代码

示例

CAN::Frame frame(0x1F1, 8, CAN::Channel_1::ChannelMappingID);
for (int i = 0; i < 8; i++) frame.Data(i) = 1;
frame.Transmit();

7.4 获取时间戳​

  • 如需获取时间戳，请参考以下代码

示例

void CAN_OnMessage(CAN::Frame* msg)
{
  char buf[255];
  uint64_t current_time = msg->GetFrameTimestamp();
  sprintf(buf, "Receive Callback:timestamp=%d", current_time);
  show_console_message(buf);
}
CAN::OnMessage = CAN_OnMessage;

7.5 帧内的变量信息​

参数

  • _channelMappingID 帧的逻辑信道映射 ID

示例

void CAN_OnMessage(CAN::Frame* msg)
{
  char buf[255];
  sprintf(buf, "Receive Callback:channelMappingID=%d", msg->_channelMappingID);
  show_console_message(buf);
}
CAN::OnMessage = CAN_OnMessage;
  • _frameID CAN 帧 ID（包括标准 / 扩展 ID）

示例

void CAN_OnMessage(CAN::Frame* msg)
{
  char buf[255];
  sprintf(buf, "Receive Callback:frameID=0x%X", msg->_frameID);
  show_console_message(buf);
}
CAN::OnMessage = CAN_OnMessage;
  • BusType 帧传输所在总线的类型

若需在 CAN FD 通道上发送通用 CAN 报文，请参考以下代码

示例

CAN::Frame frame(0x1F1, 8, CAN::Channel_1::ChannelMappingID);
for (int i = 0; i < 8; i++) frame.Data(i) = 1;
frame.BusType = BUS_TYPE_CAN;
frame.Transmit();
  • Channel 物理硬件通道编号

示例

void CAN_OnMessage(CAN::Frame* msg)
{
  char buf[255];
  sprintf(buf, "Receive Callback:Channel=%d", msg->Channel);
  show_console_message(buf);
}
CAN::OnMessage = CAN_OnMessage;
  • Dir 帧方向（接收 = 0，发送 = 1）

示例

void CAN_OnTxMessage(CAN::Frame* msg)
{
  char buf[255];
  sprintf(buf, "Transmit Complete Callback:Dir =%s", msg->Dir == 1 ? "Tx" : "Rx");
  show_console_message(buf);
}
CAN::OnTxMessage = CAN_OnTxMessage;
  • ExtendedFrame 帧 ID 格式标志（0 = 11 位 ID 标准帧，1 = 29 位 ID 扩展帧）

示例

void CAN_OnMessage(CAN::Frame* msg)
{
  char buf[255];
  sprintf(buf, "Receive Callback:ExtendedFrame =%d", msg->ExtendedFrame);
  show_console_message(buf);
}
CAN::OnMessage = CAN_OnMessage;
  • Dlc 帧的数据长度码（CAN：0-8，CAN FD：0-15）

示例

void CAN_OnMessage(CAN::Frame* msg)
{
  char buf[255];
  sprintf(buf, "Receive Callback:Dlc =%d", msg->Dlc);
  show_console_message(buf);
}
CAN::OnMessage = CAN_OnMessage;
  • DataLength 帧的实际有效数据长度

示例

void CAN_OnMessage(CAN::Frame* msg)
{
  char buf[255];
  sprintf(buf, "Receive Callback:DataLength =%d", msg->DataLength);
  show_console_message(buf);
}
CAN::OnMessage = CAN_OnMessage;
  • Reserved 保留字段（填充固定值 0，用于协议兼容性及未来功能扩展）
  • RtrFrame 远程帧标志（0 = 数据帧，1 = 远程传输请求帧）

8. CAN / CANFD​

类型定义（保持原样以便调用方使用）

typedef struct
{
      uint32_t timestamp_us;
      uint8_t bus_type;
      uint8_t event_type;
      uint8_t channel;
      uint8_t dir;
      uint8_t dlc;
      uint8_t extended_frame;
      uint8_t subDeviceNumber;
      uint8_t reserved;
      uint32_t id;
      uint8_t data[64];
} EM_ReceiveFrame_t;

typedef struct
{
      uint32_t can_id;
      bool rtr_frame;
      bool extended_frame;
      uint8_t can_dlc;
      uint8_t channel;
      uint8_t data[64];
      uint32_t timestamp_us;
} EM_CANSendFrame_t;

8.1 发送 CAN 报文​

说明

  • 发送一条 CAN 报文

8.1.1 CAN_Tx​

注意： 该遗留 API 不建议继续使用，建议采用 8.1.2 节规定的格式

KAPI_ErrCode CAN_Tx(uint32_t channelMappingID, uint32_t id, uint8_t dlc, uint8_t* data);

参数

  • channelMappingID 通道映射 ID，0 表示当前节点的默认通道 ID
  • id CAN ID
  • dlc 数据长度
  • data 指向数据缓冲区的指针

返回值

  • 0 成功
  • 其他 失败

示例

uint8_t data[8] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};
CAN_Tx(0, 0x123, 8, data);

8.1.2 CAN::Frame frame​

Frame(uint32_t frameID, uint32_t frameDataLen, uint32_t channelMappingID);

说明

  • 发送一条 CAN 报文

参数

  • frameID 信号ID
  • frameDataLen 信号长度
  • channelMappingID 通道映射 ID，0 表示当前节点的默认通道 ID

示例

CAN::Frame frame(0x1F1, 8, CAN::Channel_1::ChannelMappingID);
for (int i = 0; i < 8; i++) frame.Data(i) = 1;//修改字节的值
frame.Transmit();
CAN::Frame frame(0x1F1, 8, CAN::Channel_1::ChannelMappingID);
uint8_t* dataBuf = frame.Data();//获取起始指针
for (int i = 0; i < 8; i++) dataBuf[i] = 1;
frame.Transmit();

注意： 若需发送 CAN FD 报文，可进入设备->通道设置，将模式设置为 CAN FD，并把帧长度修改为对应的值.

示例

CAN::Frame frame(0x1F1, 12, CAN::Channel_1::ChannelMappingID);
for (int i = 0; i < 12; i++) frame.Data(i) = 1;
frame.Transmit();

8.2 注册 CAN 接收回调​

说明

  • 注册 CAN 报文接收回调

8.2.1 register_CANRxEvent​

注意： 该遗留 API 不建议继续使用，建议采用 8.2.2 节规定的格式

KAPI_ErrCode register_CANRxEvent(uint32_t channelMappingID, uint32_t id, ReceiveFrameHandler callback);

参数

  • channelMappingID 通道映射 ID，0 表示当前节点的默认通道 ID
  • id 待过滤的 CAN ID
  • callback 接收处理函数（typedef void (ReceiveFrameHandler)(EM_ReceiveFrame_t const)）

返回

  • 0 成功
  • 其他 失败

示例

void onCANRx(EM_ReceiveFrame_t const* frame)
{
	// 处理接收帧
}

uint32_t channelMappingID = 0;
uint32_t id = 0x123;
register_CANRxEvent(channelMappingID, id, onCANRx);

8.2.2 CAN::OnMessage​

示例

void CAN_OnMessage(CAN::Frame* msg)
{
 // 处理接收帧事件
}
CAN::OnMessage = CAN_OnMessage;//所有 CAN 通道上的所有报文，都会触发CAN_OnMessage回调函数

CAN::Channel_1::OnMessage = CAN_OnMessage;//CAN 通道 1 上的所有报文，都会触发CAN_OnMessage回调函数

CAN::Frame frame(0x101, 0, CAN::Channel_1::ChannelMappingID);
frame.OnMessage = CAN_OnMessage;//CAN 通道 1 上 ID 为 0x101 的报文，会触发CAN_OnMessage回调函数

CAN::Frame frame(0x101, 0, 0xFFFFFFFFL);
frame.OnMessage = CAN_OnMessage;//所有 CAN 通道上 ID 为 0x101 的报文，都会触发CAN_OnMessage回调函数

注意： CAN FD 接收回调函数的格式与 CAN 的保持一致

8.3 注册 CAN 发送完成回调​

说明

  • 注册 CAN 报文发送完成回调

8.3.1 register_CANTxEvent​

注意： 该遗留 API 不建议继续使用，建议采用 8.3.2 节规定的格式

KAPI_ErrCode register_CANTxEvent(uint32_t channelMappingID, uint32_t id, CANSendFrameHandler callback);

参数

  • channelMappingID 通道映射 ID，0 表示当前节点的默认通道 ID
  • id 待过滤的 CAN ID
  • callback 发送完成处理函数（typedef void (CANSendFrameHandler)(EM_CANSendFrame_t)）

返回

  • 0 成功
  • 其他 失败

示例

void onCANTx(EM_CANSendFrame_t* frame)
{
	// 处理发送完成事件
}
uint32_t channelMappingID = 0;
uint32_t id = 0x123;
register_CANTxEvent(channelMappingID, id, onCANTx);

8.3.2 CAN_OnTxMessage​

示例

void CAN_OnTxMessage(CAN::Frame* msg)
{
 // 处理发送完成事件
}
CAN::OnTxMessage = CAN_OnTxMessage;//所有 CAN 通道上的所有报文， 都会触发 CAN_OnTxMessage 回调函数

CAN::Channel_1::OnTxMessage = CAN_OnTxMessage;//CAN 通道1上的所有报文， 都会触发 CAN_OnTxMessage 回调函数

CAN::Frame frame(0x101, 0, CAN::Channel_1::ChannelMappingID);
frame.OnTxMessage = CAN_OnTxMessage;//CAN 通道1上 ID 为0x101的报文，会触发 CAN_OnTxMessage 回调函数

CAN::Frame frame(0x101, 0, 0xFFFFFFFFL);
frame.OnTxMessage = CAN_OnTxMessage;//所有 CAN 通道上的 ID 为0x101的报文， 都会触发 CAN_OnTxMessage 回调函数

注意： CAN FD 传输完成回调函数的格式与 CAN 的保持一致

8.4 注册 CAN 预发送回调​

说明

  • 注册 CAN 报文即将发送时的回调

8.4.1 register_CANPreTxEvent​

注意： 该遗留 API 不建议继续使用，建议采用 8.4.2 节规定的格式

KAPI_ErrCode register_CANPreTxEvent(uint32_t channelMappingID, uint32_t id, CANSendFrameHandler callback);

参数

  • channelMappingID 通道映射 ID，0 表示当前节点的默认通道 ID
  • id 待过滤的 CAN ID
  • callback 预发送处理函数（typedef void (CANSendFrameHandler)(EM_CANSendFrame_t)）

返回

  • 0 成功
  • 其他 失败

示例

void onCANPreTx(EM_CANSendFrame_t* frame)
{
 // 处理发送前事件
}
uint32_t channelMappingID = 0;
uint32_t id = 0x123;
register_CANPreTxEvent(channelMappingID, id, onCANPreTx);

8.4.2 CAN::OnPreTxMessage​

示例

void CAN_OnPreTxMessage(CAN::Frame* msg)
{
 // 处理发送前事件
}
CAN::OnPreTxMessage = CAN_OnPreTxMessage;//所有 CAN 通道上的所有报文，都会触发 CAN_OnPreTxMessage 回调函数

CAN::Channel_1::OnPreTxMessage = CAN_OnPreTxMessage;//CAN 通道1上的所有报文，都会触发 CAN_OnPreTxMessage 回调函数

CAN::Frame frame(0x101, 0, CAN::Channel_1::ChannelMappingID);
frame.OnPreTxMessage = CAN_OnPreTxMessage;//CAN 通道1上ID为0x101的报文，会触发 CAN_OnPreTxMessage 回调函数

CAN::Frame frame(0x101, 0, 0xFFFFFFFFL);
frame.OnPreTxMessage = CAN_OnPreTxMessage;//所有CAN 通道上ID为0x101的报文，都会触发 CAN_OnPreTxMessage 回调函数

注意： CAN FD 报文发送前回调函数的格式，与标准 CAN 报文发送前回调函数的格式完全一致

8.5 注册 CAN 紧急回调​

说明

  • 当需要处理高优先级 CAN 紧急帧时，注册一个回调函数（该处理流程先于普通 CAN 帧的发送与接收）

8.5.1 register_CANRxUrgentEvent​

注意： 该遗留 API 不建议继续使用，建议采用 8.5.2 节规定的格式

KAPI_ErrCode register_CANRxUrgentEvent(uint32_t channelMappingID, uint32_t id, CANSendFrameHandler callback);

参数

  • channelMappingID 通道映射 ID，0 表示当前节点的默认通道 ID
  • id 待过滤的 CAN ID
  • callback 预发送处理函数（typedef void (CANSendFrameHandler)(EM_CANSendFrame_t)）

返回

  • 0 成功
  • 其他 失败

示例

void onCANUrgent(EM_CANSendFrame_t* frame)
{
 // 处理紧急帧事件
}
uint32_t channelMappingID = 0;
uint32_t id = 0x123;
register_CANRxUrgentEvent(channelMappingID, id, onCANUrgent);

8.5.2 CAN::OnUrgentMessage​

示例

void CAN_OnUrgentMessage(CAN::Frame* msg)
{
 // 处理紧急帧事件
}
CAN::OnUrgentMessage = CAN_OnUrgentMessage;//所有 CAN 通道上的所有报文，都会触发 CAN_OnUrgentMessage 回调函数

CAN::Channel_1::OnUrgentMessage = CAN_OnUrgentMessage;//CAN 通道1上的所有报文，都会触发 CAN_OnUrgentMessage 回调函数

CAN::Frame frame(0x101, 0, CAN::Channel_1::ChannelMappingID);
frame.OnUrgentMessage = CAN_OnUrgentMessage;//CAN 通道1上 ID 为0x101的报文，会触发 CAN_OnUrgentMessage 回调函数

CAN::Frame frame(0x101, 0, 0xFFFFFFFFL);
frame.OnUrgentMessage = CAN_OnUrgentMessage;//所有 CAN 通道上 ID 为0x101的报文，都会触发 CAN_OnUrgentMessage 回调函数

注意： CAN FD 紧急回调函数的格式与 CAN 的保持一致.OnUrgentMessage 回调函数可被接收（Rx）和发送（Tx）两类报文触发。OnMessage 与 OnUrgentMessage 回调函数之间不存在任何优先级关系。也就是说，若同时注册了这两个回调函数，不会出现高优先级回调函数被调用而低优先级回调函数不执行的情况。

8.6 注册 CAN 错误帧回调​

说明

  • 注册一个会在 CAN 帧传输错误发生时（例如总线关闭）触发的回调函数，以实现对 CAN 总线传输错误事件的实时监控与处理

示例

void CAN_OnErrorMessage(CAN::Frame* msg)
{
 // 处理错误帧事件
}
CAN::OnErrorMessage = CAN_OnErrorMessage;//所有 CAN 通道上的所有报文，都会触发 CAN_OnErrorMessage 回调函数

CAN::Channel_1::OnErrorMessage = CAN_OnErrorMessage;//CAN 通道1上的所有报文，都会触发 CAN_OnErrorMessage 回调函数

CAN::Frame frame(0x101, 0, CAN::Channel_1::ChannelMappingID);
frame.OnErrorMessage = CAN_OnErrorMessage;//CAN 通道1上 ID 为0x101的报文，会触发 CAN_OnErrorMessage 回调函数

CAN::Frame frame(0x101, 0, 0xFFFFFFFFL);
frame.OnErrorMessage = CAN_OnErrorMessage;//所有 CAN 通道上ID 为0x101的报文，都会触发 CAN_OnErrorMessage 回调函数

注意： CAN FD 错误帧回调函数的格式与 CAN 的保持一致

8.7 CAN 报文接收优先级​

说明

  • 对于同一条 CAN 报文， 若为其注册了多个回调函数， 则高优先级的回调函数会被调用， 而低优先级的回调函数不会被执行。

示例

// 最高优先级
CANBus::Gateway_1::OnTxMessage  = CAN_OnTxMessage;

// 次高优先级
CAN::Frame frame(0x101, 0, CAN::Channel_1::ChannelMappingID); frame.OnTxMessage = CAN_OnTxMessage;

// 再次高优先级
CAN::Channel_1::OnTxMessage = CAN_OnTxMessage;

// 最低优先级
CAN::Frame frame(0x101, 0, 0xFFFFFFFFL); frame.OnTxMessage = CAN_OnTxMessage;

9. LIN​

类型定义

typedef struct
{
	uint8_t lin_head;
	uint8_t lin_dlc;
	uint8_t channel;
	uint8_t data[8];
	uint32_t timestamp_us;
} EM_LINSendFrame_t;

9.1 LIN 主站发送帧头​

注意： 该遗留 API 不建议继续使用，建议采用 9.2.2 节规定的格式

KAPI_ErrCode LinMaster_TxHeader(uint32_t channelMappingID, uint8_t header);

说明

  • 发送 LIN 帧头

参数

  • channelMappingID LIN 通道 ID，0 表示当前节点的默认通道 ID
  • header LIN 帧头

返回

  • 0 成功
  • 其他 失败

示例

LinMaster_TxHeader(0, 0x3C);

9.2 LIN 主站发送帧头与数据​

说明

  • 发送一条 LIN 报文

9.2.1 LinMaster_Tx​

注意： 该遗留 API 不建议继续使用，建议采用 9.2.2 节规定的格式

KAPI_ErrCode LinMaster_Tx(uint32_t channelMappingID, uint8_t header, uint8_t dlc, uint8_t* data);

参数

  • channelMappingID LIN 通道 ID，0 表示当前节点的默认通道 ID
  • header LIN 帧头
  • dlc 数据长度码
  • data 指向数据缓冲区的指针

返回

  • 0 成功
  • 其他 失败

示例

uint8_t data[8] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};
LinMaster_Tx(0, 0x3C, 8, data);

9.2.2 LIN::Frame frame​

示例

LIN::Frame frame(0x3C, 8, LIN::Channel_1::ChannelMappingID);
for (int i = 0; i < 8; i++) frame.Data(i) = 1;
frame.Transmit();//发送帧头与数据

frame.TransmitHeader();//发送帧头

9.3 注册 LIN 主站接收回调​

说明

  • 当接收到 LIN 报文时注册回调函数

9.3.1 register_LinMasterRxEvent​

注意： 该遗留 API 不建议继续使用，建议采用 9.3.2 节规定的格式

KAPI_ErrCode register_LinMasterRxEvent(uint32_t channelMappingID, uint8_t header, ReceiveFrameHandler callback);

参数

  • channelMappingID LIN 通道 ID，0 表示当前节点的默认通道 ID
  • header 待过滤的 LIN 帧头
  • callback 接收处理函数（typedef void (ReceiveFrameHandler)(EM_ReceiveFrame_t const)）

返回

  • 0 成功
  • 其他 失败

示例

void onLinMasterRx(EM_ReceiveFrame_t const* frame)
{
	// 处理接收帧
}

uint32_t channelMappingID = 0;
uint8_t header = 0x3C;
register_LinMasterRxEvent(channelMappingID, header, onLinMasterRx);

9.3.2 lIN::OnMessage​

示例

void LIN_OnMessage(LIN::Frame* msg)
{
  // 处理接收帧
}
lIN::OnMessage = LIN_OnMessage;//所有 LIN 通道上的所有报文，都会触发 LIN_OnMessage 回调函数

LIN::Channel_1::OnMessage = LIN_OnMessage;//LIN 通道1上的所有报文，都会触发 LIN_OnMessage 回调函数

LIN::Frame frame(0x3C, 0, LIN::Channel_1::ChannelMappingID);
frame.OnMessage = LIN_OnMessage;//LIN 通道1上 ID 为0x3C的报文，会触发 LIN_OnMessage 回调函数

LIN::Frame frame(0x3C, 0, 0xFFFFFFFFL);
frame.OnMessage = LIN_OnMessage;//所有 LIN 通道上 ID 为0x3C的报文，都会触发 LIN_OnMessage 回调函数

9.4 注册 LIN 主站发送完成回调​

说明

  • 当 LIN 报文发送完成时注册回调函数

9.4.1 register_LinMasterTxEvent​

注意： 该遗留 API 不建议继续使用，建议采用 9.4.2 节规定的格式

KAPI_ErrCode register_LinMasterTxEvent(uint32_t channelMappingID, uint8_t header, LINSendFrameHandler callback);

参数

  • channelMappingID LIN 通道 ID，0 表示当前节点的默认通道 ID
  • header 待过滤的 LIN 帧头
  • callback 发送完成处理函数（typedef void (LINSendFrameHandler)(EM_LINSendFrame_t)）

返回

  • 0 成功
  • 其他 失败

示例

void onLinMasterTx(EM_LINSendFrame_t* frame)
{
	// 处理发送完成事件
}

uint32_t channelMappingID = 0;
uint8_t header = 0x3C;
register_LinMasterTxEvent(channelMappingID, header, onLinMasterTx);

9.4.2 LIN::OnTxMessage​

示例

void LIN_OnTxMessage(LIN::Frame* msg)
{
  // 处理发送完成事件
}
lIN::OnTxMessage  = LIN_OnTxMessage;//所有 LIN 通道上的所有报文，都会触发 LIN_OnTxMessage 回调函数

LIN::Channel_1::OnTxMessage = LIN_OnTxMessage;//LIN 通道1上的所有报文，都会触发 LIN_OnTxMessage 回调函数

LIN::Frame frame(0x3C, 0, LIN::Channel_1::ChannelMappingID);
frame.OnTxMessage = LIN_OnTxMessage;//LIN 通道1上 ID 为0x3C的报文，会触发 LIN_OnTxMessage 回调函数

LIN::Frame frame(0x3C, 0, 0xFFFFFFFFL);
frame.OnTxMessage = LIN_OnTxMessage;//所有 LIN 通道上 ID 为0x3C的报文，都会触发 LIN_OnTxMessage 回调函数

9.5 注册 LIN 主站预发送回调​

说明

  • 当 LIN 报文即将发送时注册回调函数

9.5.1 register_LinMasterPreTxEvent​

注意： 该遗留 API 不建议继续使用，建议采用 9.5.2 节规定的格式

KAPI_ErrCode register_LinMasterPreTxEvent(uint32_t channelMappingID, uint8_t header, LINSendFrameHandler callback);

参数

  • channelMappingID LIN 通道 ID，0 表示当前节点的默认通道 ID
  • header 待过滤的 LIN 帧头
  • callback 预发送处理函数（typedef void (LINSendFrameHandler)(EM_LINSendFrame_t)）

返回

  • 0 成功
  • 其他 失败

示例

void onLinMasterPreTx(EM_LINSendFrame_t* frame)
{
	// 处理预发送事件
}

uint32_t channelMappingID = 0;
uint8_t header = 0x3C;
register_LinMasterPreTxEvent(channelMappingID, header, onLinMasterPreTx);

9.5.2 lIN::OnPreTxMessage​

示例

void LIN_OnPreTxMessage(LIN::Frame* msg)
{
  // 处理预发送事件
}
lIN::OnPreTxMessage = LIN_OnPreTxMessage;//所有 LIN 通道上的所有报文，都会触发 LIN_OnPreTxMessage 回调函数

LIN::Channel_1::OnPreTxMessage = LIN_OnPreTxMessage;//LIN 通道1上的所有报文，都会触发 LIN_OnPreTxMessage 回调函数

LIN::Frame frame(0x3C, 0, LIN::Channel_1::ChannelMappingID);
frame.OnPreTxMessage = LIN_OnPreTxMessage;//LIN 通道1上 ID 为0x3C的报文，会触发 LIN_OnPreTxMessage 回调函数

LIN::Frame frame(0x3C, 0, 0xFFFFFFFFL);
frame.OnPreTxMessage = LIN_OnPreTxMessage;//所有 LIN 通道上 ID 为0x3C的报文，都会触发 LIN_OnPreTxMessage 回调函数

9.6 注册 LIN 紧急回调​

说明

  • 当需要处理高优先级紧急 LIN 帧时，注册一个回调函数（该处理流程优先于常规 LIN 帧的发送与接收）

示例

void LIN_OnUrgentMessage(LIN::Frame* msg)
{
  // 处理紧急事件
}
lIN::OnUrgentMessage = LIN_OnUrgentMessage;//所有 LIN 通道上的所有报文，都会触发 LIN_OnUrgentMessage 回调函数

LIN::Channel_1::OnUrgentMessage = LIN_OnUrgentMessage;//LIN 通道1上的所有报文，都会触发 LIN_OnUrgentMessage 回调函数

LIN::Frame frame(0x3C, 0, LIN::Channel_1::ChannelMappingID);
frame.OnUrgentMessage = LIN_OnUrgentMessage;//LIN 通道1上 ID 为0x3C的报文，会触发 LIN_OnUrgentMessage 回调函数

LIN::Frame frame(0x3C, 0, 0xFFFFFFFFL);
frame.OnUrgentMessage = LIN_OnUrgentMessage;//所有 LIN 通道上 ID 为0x3C的报文，都会触发 LIN_OnUrgentMessage 回调函数

9.7 注册 LIN 错误帧回调​

说明

  • 注册一个回调函数，该函数会在 LIN 帧传输错误发生时触发（例如 LIN 总线关闭），以此实现对 LIN 总线传输错误事件的实时监控与处理

示例

void LIN_OnErrorMessage(LIN::Frame* msg)
{
  // 处理错误帧事件
}
lIN::OnErrorMessage = LIN_OnErrorMessage;//所有 LIN 通道上的所有报文，都会触发 LIN_OnErrorMessage 回调函数

LIN::Channel_1::OnErrorMessage = LIN_OnErrorMessage;//LIN 通道1上的所有报文，都会触发 LIN_OnErrorMessage 回调函数

LIN::Frame frame(0x3C, 0, LIN::Channel_1::ChannelMappingID);
frame.OnErrorMessage = LIN_OnErrorMessage;//LIN 通道1上 ID 为0x3C的报文，会触发 LIN_OnErrorMessage 回调函数

LIN::Frame frame(0x3C, 0, 0xFFFFFFFFL);
frame.OnErrorMessage = LIN_OnErrorMessage;//所有 LIN 通道上 ID 为0x3C的报文，都会触发 LIN_OnErrorMessage 回调函数

10. DDS​

10.1 发送报文​

10.1.1 发送UDP报文​

说明

  • 发送一个UDP报文

示例

Ethernet::UDPNodeInfo nodeInfo;
nodeInfo.setSrcMac( 1, 2, 3, 4, 5, 6 )
        .setSrcIp( 127, 0, 0, 1 )
        .setSrcPort(11)
        .setDstMac( 1, 2, 3, 4, 5, 6 )
        .setDstIp( 192, 168, 0, 1 )
        .setDstPort(29)
        .setTtl(64)
        .setVlan(129);//配置UDP节点信息

Ethernet::Frame frame(8, Ethernet::Channel_1::ChannelMappingID, nodeInfo);
frame.Data(0) = 1;
frame.Data(1) = 2;
frame.Data(2) = 3;
frame.Data(3) = 4;
frame.Data(4) = 5;
frame.Data(5) = 6;
frame.Data(6) = 7;
frame.Data(7) = 8;

10.1.2 发送特定的DDS报文​

说明

  • 发送一个特定的DDS报文

示例

  • 假设我们已经在DDS系统中导入一个xml文件，我们可以将域名定义为Domain_5。 alt text
  • 一个域里可以包含多个节点，我们将一个节点名定义为GCS。 alt text
  • 在Publishers下使能的topic可以发送信号 alt text
DDS::Domain_5::GCS::GCS_LEFT_1_MFSW msg;
msg.CLU_RhstaLvlSta_MFSW = 0xab;
msg.Transmit();

10.2 注册一个以太网所有通道的回调​

  • 以太网回调可接收 DDS/UDP/RTPS 报文。若回调被触发，可按以下方式对该回调执行相关操作。

示例

void OnEthFrameMessage(Ethernet::Frame* msg)
{
   if (msg->EventType == Ethernet::DDS_Data)
    {
      //Do something for DDS data
    }
   if (msg->EventType == Ethernet::UDP_Data)
    {
      //Do something for UDP data
    }
   if (msg->EventType == Ethernet::RTPS_Data)
    {
      //Do something for RTPS data
    } 
}

10.2.1 注册全以太网通道接收回调​

说明

  • 所有通道下所有 DDS/UDP/RTPS 帧的接收回调，均会触发OnMessage。

示例

Ethernet::OnMessage = OnEthFrameMessage;

10.2.2 注册全以太网通道发送完成回调​

说明

  • 所有通道下所有 DDS/UDP/RTPS 帧的发送完成回调，均会触发OnTxMessage。

示例

Ethernet::OnTxMessage = OnEthFrameMessage;

10.2.3 注册全以太网通道紧急回调​

说明

  • 所有通道下所有 DDS/UDP/RTPS 帧的紧急回调，均会触发OnUrgentMessage。

示例

Ethernet::OnUrgentMessage = OnEthFrameMessage;

10.2.4 注册全以太网通道错误帧回调​

说明

  • 若所有通道的 DDS/UDP/RTPS 报文出现错误帧，将触发错误帧回调OnErrorMessage。

示例

Ethernet::OnErrorMessage = OnEthFrameMessage;

10.2.5 注册全以太网通道发送前回调​

说明

  • 所有通道下所有 DDS/UDP/RTPS 帧的全部发送前回调，均会触发 OnPreTxMessage。

示例

Ethernet::OnPreTxMessage = OnEthFrameMessage;

10.3 注册一个以太网特定通道的回调​

注意： OnEthCh1FrameMessage 的形式与10.2章节中 OnEthFrameMessage 的形式完全一致。

10.3.1 注册以太网 Channel1 接收回调​

说明

  • 以太网 Channel1 通道下所有 DDS/UDP/RTPS 帧的所有接收回调，均会触发 OnMessage。

示例

Ethernet::Channel_1::OnMessage = OnEthCh1FrameMessage;

10.3.2 注册以太网 Channel1 发送完成回调​

说明

  • 以太网 Channel1 通道下所有 DDS/UDP/RTPS 帧的所有发送完成回调，均会触发 OnTxMessage。

示例

Ehernet::Channel_1::OnTxMessage = OnEthCh1FrameMessage;

10.3.3 注册以太网 Channel1 紧急回调​

说明

  • 以太网 Channel1 通道下所有 DDS/UDP/RTPS 帧的所有紧急回调，均会触发 OnUrgentMessage。

示例

Ethernet::Channel_1::OnUrgentMessage = OnEthCh1FrameMessage;

10.3.4 注册以太网 Channel1 错误帧回调​

说明

  • 若以太网 Channel1 通道的 DDS/UDP/RTPS 报文出现错误帧，将触发错误帧回调 OnErrorMessage。

示例

Ethernet::Channel_1::OnErrorMessage = OnEthCh1FrameMessage;

10.3.5 注册以太网 Channel1 发送前回调​

说明

  • 以太网 Channel1 通道下所有 DDS/UDP/RTPS 帧的所有发送前回调，均会触发 OnPreTxMessage。

示例

Ethernet::Channel_1::OnPreTxMessage  = OnEthCh1FrameMessage;

10.4 接收特定的DDS信号​

注意： 以下面的形式注册的回调只能接收10.1.2的报文

  • 若需要特定的DDS信号触发接收回调，可使用下面的代码

示例

void OnDDSFrame(DDS::Domain_5::GCS::GCS_LEFT_1_MFSW *msg)
{
   //DO something 
}

DDS::Domain_5::GCS::GCS_LEFT_1_MFSW::OnMessage = OnDDSFrame;
  • 若需要特定的DDS信号触发发送前回调，可使用下面的代码

示例

void OnDDSPreTxFrame(DDS::Domain_5::GCS::GCS_LEFT_1_MFSW *msg)
{
   //DO something 
}

DDS::Domain_5::GCS::GCS_LEFT_1_MFSW::OnPreTxMessage  = OnDDSPreTxFrame;
  • 若需要特定的DDS信号触发发送完成回调，可使用下面的代码

示例

void OnDDSTxFrame(DDS::Domain_5::GCS::GCS_LEFT_1_MFSW *msg)
{
   //DO something 
}

DDS::Domain_5::GCS::GCS_LEFT_1_MFSW::OnTxMessage   = OnDDSTxFrame;
  • 若需要特定的DDS信号触发紧急回调，可使用下面的代码

示例

void OnDDSUrgentFrame(DDS::Domain_5::GCS::GCS_LEFT_1_MFSW *msg)
{
   //DO something 
}

DDS::Domain_5::GCS::GCS_LEFT_1_MFSW::OnUrgentMessage    = OnDDSUrgentFrame;

11. Digital​

11.1 设置数字输出电平​

说明

  • 设置数字输出电平

11.1.1 Do_Set​

注意： 该遗留 API 不建议继续使用，建议采用 11.1.2 节规定的格式

KAPI_ErrCode Do_Set(uint32_t channelMappingID, boolean lvl);

参数

  • channelMappingID 数字输出通道 ID
  • lvl
    • 0 低电平
    • 1 高电平

返回

  • 0 成功
  • 其他 失败

示例

Do_Set(0, 1);

11.1.2 Digital::Output::ChannelMappingID::Value​

示例

Digital::Output::Channel_1::Value = 1;

11.2 获取数字输入状态​

说明

  • 获取数字输入状态

11.2.1 Di_Get​

注意： 该遗留 API 不建议继续使用，建议采用 11.2.2 节规定的格式

KAPI_ErrCode Di_Get(uint32_t channelMappingID, boolean* value);

参数

  • channelMappingID 数字输入通道 ID
  • value 存储输入状态的指针
    • 0 低电平
    • 1 高电平

返回

  • 0 成功
  • 其他 失败

示例

boolean value;
Di_Get(0, &value);

11.2.2 Digital::Input::ChannelMappingID::Value​

示例

boolean DiInValue;
DiInValue = Digital::Input::Channel_1::Value;

12. Analog​

12.1 获取模拟输入电压​

说明

  • 获取模拟输入电压值

12.1.1 Ai_Get​

注意： 该遗留 API 不建议继续使用，建议采用 12.1.2 节规定的格式

KAPI_ErrCode Ai_Get(uint32_t channelMappingID, double* value);

参数

  • channelMappingID 模拟输入通道 ID
  • value 存储电压值的指针

返回

  • 0 成功
  • 其他 失败

示例

double value;
Ai_Get(0, &value);

12.1.2 Analog::Input::ChannelMappingID::Value​

示例

boolean AnInValue;
AnInValue = Analog::Input::Channel_1::Value;

13. 其他​

13.1 注册键盘按键回调​

void (*resgister_onKey)(char key, void (*onKey)(void));

说明

  • 注册按键按下时的回调函数

参数

  • key 键字符
  • onKey 回调函数（typedef void (*onKey)(void)）

返回

  • void

示例

void onKey(void)
{
	// 处理按键事件
}

resgister_onKey('a', onKey);

注意： 该功能不区分大小写

13.2 系统消息输出（到宿主应用）​

说明

  • 向宿主应用输出一条系统消息

13.2.1 show_system_message​

注意： 该遗留 API 不建议继续使用，建议采用 13.2.2 节规定的格式

void show_system_message(const char* str);

参数

  • str 消息内容

返回

  • void

示例

show_system_message("Hello World");

13.2.2 system_message_printf​

template<typename... Args>

void system_message_printf(const std::string& format_str, const Args&... args)

参数

  • format_str 用于定义输出报文结构的格式字符串
  • args 用于为 format_str 中的占位符提供实际填充值的可变参数包

返回

  • void

示例

int32_t DiGetValue = Digital::Output::Channel_1::Value;
system_message_printf("% - %", UI::ActionClose, Digital::Output::Channel_1::Value);

13.3 控制台消息输出（到小程序控制台）​

说明

  • 向小程序控制台输出一条消息

13.3.1 show_console_message​

注意： 该遗留 API 不建议继续使用，建议采用 13.3.2 节规定的格式

void show_console_message(const char* str);

参数

  • str 消息内容

返回

  • void

示例

show_console_message("Hello World");

13.3.2 console_printf​

template<typename... Args>

void console_printf(const std::string& format_str, const Args&... args)

参数

  • format_str 用于定义输出报文结构的格式字符串
  • args 用于为 format_str 中的占位符提供实际填充值的可变参数包

返回

  • void

示例

int32_t DiGetValue = Digital::Output::Channel_1::Value;
console_printf("% - %", UI::ActionClose, Digital::Output::Channel_1::Value);

13.4 微秒级延时（忙等待）​

void delay_us(uint32 delaytime_us);

说明

  • 以忙等待方式延时指定时间（以微秒为单位）

参数

  • delaytime_us 延时时间（微秒）

返回

  • void

示例

delay_us(1000);

注意： 此函数会阻塞当前线程直到延时结束，建议优先使用 start_timer 来实现定时功能。

13.5 毫秒级延时（休眠）​

void delay_ms(uint32 delaytime_ms);

说明

  • 延迟指定时长（采用休眠模式）

参数

  • delaytime_ms 延时时间（毫秒）

返回

  • void

示例

delay_ms(1000);

注意： 此函数需谨慎使用，不建议将其用于长时间延时场景。该函数已在底层实现，禁止通过delay_us手动定义并实现毫秒级延时。

13.6 获取工程绝对路径​

const char* GetAbsProjectPath();

说明

  • 获取当前工程的绝对路径

参数

  • void

返回

  • const char* 当前工程的绝对路径

示例

const char* path = GetAbsProjectPath();

const wchar_t* GetAbsProjectPathW();

说明

  • 获取当前工程的绝对路径（宽字符版本）

参数

  • void

返回

  • const wchar_t* 当前工程的绝对路径（宽字符）

示例

const wchar_t* path = GetAbsProjectPathW();