3. CAPL脚本入门：从零开始写你的第一行测试代码

说实话，很多刚接触CANoe的朋友，一看到CAPL就头大。觉得它像C语言又不像，语法看着眼熟，写起来却处处碰壁。我当年刚入行时也是这样，对着帮助文档啃了三天，结果写个定时器还跑飞了。

但你别怕。CAPL说白了就是CANoe的"脚本语言"，专门用来处理总线上的报文、信号和事件。你不需要成为编程高手，只要掌握几个核心概念，就能写出实用的测试脚本。

3.1 CAPL语言基础：语法其实很简单

CAPL的语法脱胎于C语言，但做了大量简化。没有指针，没有内存管理，没有复杂的继承多态。你只需要记住几个基本规则。

3.1.1 变量与数据类型

CAPL支持的数据类型不多，常用的就这些：

类型	说明	示例
int	32位有符号整数	int count = 0;
long	64位有符号整数	long timestamp;
float	32位浮点数	float voltage = 12.5;
char	8位字符	char ch = 'A';
byte	8位无符号整数	byte data[8];
word	16位无符号整数	word id = 0x123;
dword	32位无符号整数	dword mask = 0xFF00FF00;

变量声明必须在代码块的开头，这是CAPL的一个硬性规定。我刚开始写的时候经常忘记，编译报错才反应过来。

// 正确写法：变量声明在开头
on start
{
  int i;
  float temp;
  char buffer[256];
  
  i = 0;
  temp = 25.6;
}

// 错误写法：变量声明在中间
on start
{
  int i = 0;
  i = i + 1;
  int j;  // 编译报错！变量声明必须在最前面
}

3.1.2 控制结构

if-else、while、for这些都有，用法和C语言几乎一样。唯一要注意的是，CAPL不支持switch-case，需要用if-else if链替代。

on message 0x100
{
  if(this.byte(0) == 0xAA)
  {
    write("收到启动报文");
  }
  else if(this.byte(0) == 0xBB)
  {
    write("收到停止报文");
  }
  else
  {
    write("未知报文类型");
  }
}

3.2 事件处理函数：CAPL的灵魂

CAPL没有main函数。它的执行入口是各种"事件处理函数"。系统检测到某个事件发生时，自动调用对应的函数。你只需要把逻辑写在函数体里就行。

3.2.1 常用事件类型

事件函数	触发时机	典型用途
on start	测量开始	初始化变量、启动定时器
on preStart	测量开始前	配置仿真总线参数
on stop	测量停止	保存日志、清理资源
on message XXX	收到指定ID报文	报文解析、信号检测
on timer XXX	定时器到期	周期性发送、超时检测
on key 'X'	按下键盘按键	手动触发测试步骤
on sysvar XXX	系统变量变化	响应面板操作、环境变量

我见过不少新手把逻辑写在 on start 里，以为它会循环执行。其实 on start 只执行一次。需要周期性执行的任务，得用定时器。

3.2.2 报文事件实战

报文事件是车载网络测试中最常用的。来看一个实际例子：检测发动机转速信号是否超限。

on message 0x100
{
  // this 关键字指向当前收到的报文
  // 提取第2、3字节作为转速值（假设是大端格式）
  word engineSpeed = this.word(1);
  
  if(engineSpeed > 6000)
  {
    write("警告：发动机转速超限！当前值：%d rpm", engineSpeed);
    // 触发故障注入
    setSignal("EngineStatus", 0x03);
  }
}

3.3 定时器与系统变量：让脚本活起来

没有定时器的CAPL脚本，就像没有秒针的手表——只能看个大概时间。定时器让脚本具备了"时间感知"能力，系统变量则让脚本能和外界交互。

3.3.1 定时器的两种用法

CAPL支持两种定时器：msTimer（毫秒级）和 timer（秒级）。声明后，用 setTimer 启动，到期后触发 on timer 事件。

// 声明定时器
msTimer cycleTimer;
timer slowTimer;

on start
{
  // 启动周期定时器，每100ms触发一次
  setTimer(cycleTimer, 100);
  // 启动单次定时器，5秒后触发
  setTimer(slowTimer, 5);
}

on timer cycleTimer
{
  // 周期性任务：发送心跳报文
  message 0x200 msg;
  msg.byte(0) = 0x55;
  msg.byte(1) = 0xAA;
  output(msg);
  
  // 重新启动定时器，实现连续周期
  setTimer(cycleTimer, 100);
}

on timer slowTimer
{
  write("5秒到了，执行慢速任务");
  // 单次定时器不需要重新启动
}

这里有个细节：setTimer 的第二个参数单位取决于定时器类型。msTimer用毫秒，timer用秒。我刚开始总搞混，后来养成习惯：周期短的任务用msTimer，周期长的用timer。

3.3.2 系统变量：脚本的"对外接口"

系统变量（System Variables）是CAPL脚本和CANoe环境、测试面板、其他节点通信的桥梁。你可以把它理解成"全局变量"，但它的值变化会触发事件。

类型	命名空间	访问方式
普通系统变量	::Namespace::Variable	@sysvar::Namespace::Variable
系统变量数组	::Namespace::ArrayVar	@sysvar::Namespace::ArrayVar[0]
系统变量（带单位）	::Namespace::VarWithUnit	自动转换单位

// 在系统变量定义中（System Variables窗口）
// 定义：SysVar::Test::EngineSpeed (int)

// 在CAPL中读取
on sysvar SysVar::Test::EngineSpeed
{
  int speed = @this;
  write("发动机转速变更为：%d rpm", speed);
}

// 在CAPL中写入
on key 's'
{
  @sysvar::Test::EngineSpeed = 3000;
  write("手动设置转速为3000");
}

3.4 CAPL调试技巧：别让Bug过夜

写脚本难免出Bug。关键是找到高效的调试方法，而不是对着屏幕干瞪眼。我总结了几个实战中最好用的调试手段。

3.4.1 三板斧：write、write、write

write() 函数是CAPL调试的第一利器。它把信息输出到Write Window，支持格式化字符串。

on message 0x100
{
  // 打印报文原始数据
  write("收到报文 ID=0x%X, DLC=%d", this.id, this.dlc);
  
  // 打印信号值
  int speed = this.word(1);
  write("  转速 = %d rpm", speed);
  
  // 打印时间戳
  write("  时间 = %f 秒", timenow());
}

但要注意：write() 在高速报文场景下会拖慢系统。我一般只在调试阶段用，调试完就注释掉或加上条件编译。

3.4.2 断点调试：单步跟踪

CANoe的CAPL Browser支持设置断点。双击行号左侧，出现红点就是断点。运行时遇到断点会暂停，你可以查看变量值、单步执行。

我个人习惯的调试流程：

1. 先加几个 write() 定位问题范围
2. 在可疑代码段设断点
3. 单步执行，观察变量变化
4. 修完Bug后移除所有调试代码

3.4.3 使用Watch窗口监控变量

在CAPL Browser的Watch窗口添加变量名，运行时可以实时看到变量值变化。比 write() 更直观，而且不影响执行速度。

3.4.4 编译错误快速定位

CAPL编译错误信息有时候不太友好。常见的错误原因：

• 变量未声明：检查是否在代码块开头声明了
• 类型不匹配：比如把 int 赋值给 word
• 缺少分号：CAPL对分号要求严格，漏一个就报错
• 事件函数名写错：比如 on messge 少了个a

双击错误信息，CANoe会自动跳转到出错行。这个功能很实用，别自己满屏找。

3.5 本章知识体系总览

下面这张图把CAPL脚本的核心知识点串起来了。你可以把它当成学习地图，哪里不会看哪里。

这张图把CAPL的三大核心模块和调试方法串在了一起。你学完本章后，应该能看懂这张图里的每个节点，并且能动手写出简单的测试脚本。