C语言入门_SCPI 库 API 介绍

背景故事

上大学一直在划水，刚毕业时几乎啥也不会，是大佬的这个库拯救了我。

SCPI 是一种字符串解析协议。刚工作时，点完灯开完串口，就让我实现 SCPI 协议。那时还很菜，花了两周时间才把这个协议库开起来。

这个库中的内容真的特别丰富，也没有很动态的指针，基本上都是绑定性质的"静态"指针，哪怕 C 语言不怎么样的我也可以慢慢看得懂。

在慢慢使用大约两个月后，其中的大部分内容都浏览过，C 语言也正式入门了，

而且后续的应届生，我也是让他们先看这个库。

源码地址在这里

这个代码库的优势

Note

这是一个纯粹的协议解析库，与硬件并非强关联，需要关注的 port 也仅仅是数据流入和数据流出。非常迅速就可以使用起来(哪怕是 CodeBlocks 或 DEV-C++ 这样的学习环境)。
这是一个能胜任业务功能的库，SCPI 协议解析所需的所有功能或机制它都可以胜任，学习后的应用场景非常广，不会白白学习。
这是一个稳健的库，我目前还没有在这个库中发现致命 bug。举个反例，最近期望移植和修改的 freemodbus 库，其中就存在致命 bug 以及大大小小的设计缺陷。
这是一个相对简单的库，比起 rtos 内核、网络库、文件系统库等等，这个库几乎可以称得上非常易懂了，只要花时间，就能从其中学到面向对象、宏翻译、宏条件编译、回调绑定、字符处理等等 C 语言的常用语法及设计。

应该看什么

由于是要写给 C 语言入门级选手的，哪怕这个库的结构如此简单，也依然需要介绍一下。整个库只有两个文件夹如下

examples 其中是一些示例，也是我们期望将库用起来首先要看的。
libscpi 其中就是所有的库源码。在这个文件夹下有test文件夹，是带有 main 入口的单元测试，实际工程中不必引入libscpi/test文件夹的源码。

在examples 中建议重点查看如下两个文件夹

examples/common 下是例程所支持的指令表，以及对应指令的回调，其中可以学习一些库 API 的用法

examples/test-parser 下是最简单例程的 main 入口，以及如 SCPI_Write()、SCPI_Error()等接口函数的定义，还有少量指令的回调，在指令表中都可以找到绑定。

大致使用流程如下

使用 SCPI_Init() 函数绑定对象、设备 ID、各种 port 函数
使用 SCPI_Input() 函数输入一条所支持的完整指令，库自动触发指令回调，自动使用 port 函数发送信息

优秀的库，使用就是如此简单。

一些库 API 介绍

在官方文档中实际上也有 API 介绍，但是几乎没有有效信息，毕竟官方也只有一个人，可参考。

About · SCPI parser (jaybee.cz)

Scpi-Def.c 中声明了整个 SCPI 处理过程中用到的接口参数 scpi interface

指令参数处理 API

scpi_bool_t SCPI_ParamErrorOccurred(scpi_t* context);
用于处理函数中，检测处理函数时是否产生错误，若存在错误则应立即停止处理函数。


scpi_bool_t SCPI_ParamInt32(
    scpi_t* context,
    int32_t* value,
 scpi_bool_t mandatory);
从 context 取出32位有符号参数，赋值给 value，若 mandatory 为 ture 且没有参数，则生成-109错误(无参数错
误)；若 mandatory 为 false(通常不使用)，则参数应为表达式字符串，否则产生-151错误(无效字符串错误)

scpi_bool_t SCPI_ParamInt64(
    scpi_t* context,
    int64_t* value,
 scpi_bool_t mandatory);
同上述取32位有符号参数逻辑，取出64位有符号参数


与上述两个函数相同逻辑的还有如下 API 函数


SCPI_ParamUInt32() 取无符号32位数据
SCPI_ParamUInt64()取无符号64位数据
SCPI_ParamDouble()取 double 类型数据
SCPI_ParamFloat()取 float 类型数据
SCPI_ParamBool()取 bool 类型数据

SCPI_ParamChoice(
 scpi_t * context,
 const scpi_choice_def_t * options,
 int32_t * value,
 scpi_bool_t mandatory)
取选项列表中的值 *options 为提取数据的参数 选项的索引赋值给 Value

SCPI_ParamCopyText(
 scpi_t * context,
 char * buffer,
 size_t buffer_len,
 size_t * copy_len,
 scpi_bool_t mandatory)
 提取数据赋给 buffer

SCPI_ParamCharacters(
 scpi_t * context,
 const char ** value,
 size_t * len,
 scpi_bool_t mandatory)
 提取字符参数 给 value，len 为提取成功的字符长度

SCPI_ParamArbitraryBlock(
 scpi_t * context,
 const char ** value,
 size_t * len,
 scpi_bool_t mandatory)
 获取任意块程序数据 给 value，len 为提取成功的字符

SCPI_ParamNumber(
   scpi_t * context,
   const scpi_choice_def_t * special,
   scpi_number_t * value,
 scpi_bool_t mandatory)
将下一个参数解析为数字 or 带单位数字 or 特定规则的数字赋值给 value。若需按特定规则解析——special 标识了
解析规则：MINimum、MAXimum、DEFaylt、
UP、DOWN 等，详查 scpi_choice_numbers_def[]定义

CodeBlock Loading...

产生回传 API

经结果生成处理 API，产生的回传参数会存入接口参数 scpi interface 中，并最终均会调用 SCPI_Write() 函

数，目前该函数为：将回传参数经 uart4口发出

size_t
SCPI_ResultArbitraryBlock(
   scpi_t * context,
   const char * data,
  size_t len)
将任意块数据加上(#1+字节数据长度)头——更换头查找 SCPI_ResultArbitraryBlockHeader()函数定义，加
上\r\n 尾，调用 SCPI_Write()函数发出

该函数实际上调用下列两个函数

size_t
SCPI_ResultArbitraryBlockHeader(
   scpi_t * context,
 size_t len)
运算数据块应添加的头并发送
size_t
SCPI_ResultArbitraryBlockData(
   scpi_t * context,
   const char * data,
 size_t len)
带错误检测的数据块发送函数，若 context 的 arbitrary_reminding 参数小于指定长度 len，
则产生一个系统错误 SCPI_ERROR_SYSTEM_ERROR

size_t
SCPI_ResultText(
 scpi_t * context,
 const char * data)
查找带有 “的数据，将带有 “ 的字符串写入结果(没什么用的 API)，可能是一个 FUNC

size_t
SCPI_ResultBool(
 scpi_t * context
 scpi_bool_t val)
将 bool 值写入结果

size_t
SCPI_ResultCharacters(
 scpi_t * context,
 const char * data,
 size_t len)
将原始字符串结果写入输出，先发出一个回传分割符“,”，后将字符串发出

size_t
SCPI_ResultMnemonic(
 scpi_t * context,
 const char * data)
与 SCPI_ResultCharacters()字符串发送函数等价，但本函数 len 为 sizeof

CodeBlock Loading...

size_t
SCPI_ResultArbitraryBlock(
   scpi_t * context,
   const char * data,
  size_t len)
将任意块数据加上(#1+字节数据长度)头——更换头查找 SCPI_ResultArbitraryBlockHeader()函数定义，加
上\r\n 尾，调用 SCPI_Write()函数发出

该函数实际上调用下列两个函数

size_t
SCPI_ResultArbitraryBlockHeader(
   scpi_t * context,
 size_t len)
运算数据块应添加的头并发送
size_t
SCPI_ResultArbitraryBlockData(
   scpi_t * context,
   const char * data,
 size_t len)
带错误检测的数据块发送函数，若 context 的 arbitrary_reminding 参数小于指定长度 len，
则产生一个系统错误 SCPI_ERROR_SYSTEM_ERROR

size_t
SCPI_ResultText(
 scpi_t * context,
 const char * data)
查找带有 “的数据，将带有 “ 的字符串写入结果(没什么用的 API)，可能是一个 FUNC

size_t
SCPI_ResultBool(
 scpi_t * context
 scpi_bool_t val)
将 bool 值写入结果

size_t
SCPI_ResultCharacters(
 scpi_t * context,
 const char * data,
 size_t len)
将原始字符串结果写入输出，先发出一个回传分割符“,”，后将字符串发出

size_t
SCPI_ResultMnemonic(
 scpi_t * context,
 const char * data)
与 SCPI_ResultCharacters()字符串发送函数等价，但本函数 len 为 sizeof

以下写入结果的 API 若无 Base 传参则均以十进制转换为字符串

size_t
SCPI_ResultDouble(
 scpi_t * context,
 double val)
将一个双精度值写入结果，先发出一个结果分割符“,”，后将值发出

与上述函数相同逻辑的还有如下 API 函数
SCPI_ResultFloat(scpi_t * context,float val)写入 float 值
SCPI_ResultInt16(scpi_t * context,int16_t val)写入有符号16位值
SCPI_ResultInt32(scpi_t * context,int32_t val) 
SCPI_ResultInt64(scpi_t * context,int64_t val) 
SCPI_ResultInt8(scpi_t * context,int8_t val) 
SCPI_ResultUInt16(scpi_t * context,uint16_t val) 写入无符号16位值
SCPI_ResultUInt32(scpi_t * context,uint32_t val)
SCPI_ResultUInt64(scpi_t * context,uint64_t val)
SCPI_ResultUInt8(scpi_t * context,uint8_t val) 
SCPI_ResultUInt16Base(scpi_t * context,uint16_t val,int8_t base) 将无符号 16 位值转换为 Base 进制，并转换为字符串写入结果
SCPI_ResultUInt32Base(scpi_t * context,uint32_t val,int8_t base) 
SCPI_ResultUInt64Base(scpi_t * context,uint64_t val,int8_t base) 
SCPI_ResultUInt8Base(scpi_t * context,uint8_t val,int8_t base)

CodeBlock Loading...

以数组形式产生回传 API

与上一部分产生回传的 API 类似，本部分 API 产生数组存入接口参数 scpi interface 的结果存储中，并触发 SCPI_Write() 函数

size_t 
SCPI_ResultArrayDouble(
    scpi_t * context,
    const double * array,
    size_t count,
    scpi_array_format_t format);
将 array 指向的 count 个 double 元素 转换为数组 format 选择系统大小端

SCPI_ResultArrayFloat(scpi_t * context,const Float * array,
size_t count,scpi_array_format_t format);
SCPI_ResultArrayInt16(scpi_t * context,const int16_t * array,
size_t count,scpi_array_format_t format);
SCPI_ResultArrayInt32(scpi_t * context,const int32_t * array,
size_t count,scpi_array_format_t format);
SCPI_ResultArrayUInt64(scpi_t * context,const uint64_t * array,
size_t count,scpi_array_format_t format);
SCPI_ResultArrayUInt8(scpi_t * context,const uint8_t * array,
size_t count,scpi_array_format_t format);

CodeBlock Loading...

数据转字符串的 API

默认不对接口参数的回传值进行操作

size_t
SCPI_DoubleToStr(
    double val,
    char * str,
    size_t len)
将双精度值转换为字符串，向 str 指向的地址赋值，len 为允许的最长缓存区字节长度

SCPI_FloatToStr(float val,char * str,size_t len)
SCPI_Int32ToStr(int32_t val,char * str,size_t len)
SCPI_Int64ToStr(int64_t val,char * str,size_t len)
SCPI_UInt32ToStrBase(uint32_t val,char * str,size_t len,int8_t base)转化后的字符串为 base 进制
SCPI_UInt64ToStrBase(uint64_t val,char * str,size_t len,int8_t base)

size_t
SCPI_NumberToStr(
    scpi_t * context,
    const scpi_choice_def_t * special,
    scpi_number_t * value,
    char * str,
    size_t len)
将特殊规则下的数字转换为带有单位的字符串，与 SCPI_ParamNumber 是一对反函数

CodeBlock Loading...

拓展的参数处理 API

scpi_bool_t
SCPI_ChoiceToName(
    const scpi_choice_def_t * options,
    int32_t tag,
        const char ** text)
options 是一个{字符串，int_t 数据}的表结构，该函数会根据 tag 数据查表并将对应的字符串的地址赋值给 text 指向的地址

scpi_bool_t
SCPI_ParamIsNumber(
    scpi_parameter_t * parameter,
    scpi_bool_t suffixAllowed)
检查参数是否为数字类型，通常使用 SCPI_Parameter(context, &param, mandatory)取参数后使用

scpi_bool_t
SCPI_ParamIsValid(
    scpi_parameter_t * parameter)
此函数检查赋值函数时是否有出错

scpi_bool_t
SCPI_ParamToChoice(
    scpi_t * context,
    scpi_parameter_t * parameter,
    const scpi_choice_def_t * options,
    int32_t * value)
options 是一个{字符串，int_t 数据}的表结构，该函数根据 contexet 中的参数查表，
并将参数转换为字符串，通常使用 SCPI_Parameter(context, &param, mandatory)取参数后使用

CodeBlock Loading...

scpi_bool_t
SCPI_ParamToDouble(
    scpi_t* context,
    scpi_parameter_t* parameter,
    double* value)
将参数转换为 double 值，通常使用 SCPI_Parameter(context, &param, mandatory)取参数后使用


与上述函数有相似逻辑的还有如下函数
SCPI_ParamToFloat(scpi_t* context,scpi_parameter_t* parameter,float* value);
SCPI_ParamToInt32(scpi_t* context,scpi_parameter_t* parameter,int32_t* value);
SCPI_ParamToInt64(scpi_t* context,scpi_parameter_t* parameter,int64_t* value);
SCPI_ParamToUInt32(scpi_t* context,scpi_parameter_t* parameter,uint32_t* value);
SCPI_ParamToUInt64(scpi_t* context,scpi_parameter_t* parameter,uint64_t* value);


scpi_bool_t
SCPI_Parameter(
    scpi_t* context,
    scpi_parameter_t* parameter,
    scpi_bool_t mandatory)
从命令行取一个参数并赋值给 parameter，parameter 中还会存入数据长度、数据类型。

CodeBlock Loading...

命令处理 API

int32_t
SCPI_CmdTag(
    scpi_t* context)
返回检测到的命令标记；看不懂，待测试

scpi_bool_t
SCPI_CommandNumbers(
    scpi_t* context,
    int32_t* numbers,
        size_t len)
在命令列表中，指定允许数字的位置，在处理函数中，可以将这些位置的数字填充给 numbers，len 为数组长度例如{.pattern = "TEST#:NUMbers#", .callback = TEST_Numbers,},
若收到 TEST3:NUMbers2，则可使用 SCPI_CommandNumbers(context,&data[0],2),则 data[0]赋值为3，data[1]赋值为2

CodeBlock Loading...

C语言入门_SCPI 库 API 介绍

关键洞察

Search

C语言入门_SCPI 库 API 介绍

关键洞察

背景故事

这个代码库的优势

应该看什么

一些库 API 介绍

指令参数处理 API

产生回传 API

以数组形式产生回传 API

数据转字符串的 API

拓展的参数处理 API

命令处理 API

背景故事

这个代码库的优势

应该看什么

一些库 API 介绍

指令参数处理 API

产生回传 API

以数组形式产生回传 API

数据转字符串的 API

拓展的参数处理 API

命令处理 API