Arduino命令解析库(Commander)的使用和实现
Arduino命令解析库(Commander)的使用和实现
在嵌入式系统中，特别是在Arduino平台上，命令解析是一种常见的通信方式。
本文将介绍一个简单的Arduino命令解析库(Commander)，并提供使用示例、头文件和源文件。
内容摘自simpleFOC的Commander部分。
使用示例
以下是一个简单的使用示例，演示如何在Arduino中使用Commander库：
#include <Commander.h>
Commander command = Commander('\n', false);
Commander command2 = Commander('\n', false);
// 一级命令
void doL(char *cmd)
{
// L-0.02
// 取出cmd中的带符号浮点数
float value_1 = atof(cmd);
Serial.printf("L: %f\n", value_1);
// 将后续目录进行解析
command2.run(cmd);
};
// 二级命令
void doLA(char *cmd)
{
// LA-0.02
// 取出cmd中的带符号浮点数
float value_1 = atof(cmd);
Serial.printf("LA: %f\n", value_1);
};
void setup()
{
Serial.begin(115200);
// 添加新命令 (命令关键字，回调函数，标签文本)
command.add('L', doL, "getL");
command2.add('A', doLA, "getLA");
delay(100);
}
void loop()
{
delay(2);
command.run(Serial);
}
在这个示例中，我们创建了两个Commander实例：command和command2，分别用于处理一级命令和二级命令。通过定义回调函数 doL 和 doLA，我们可以在收到相应命令时执行自定义的操作。
Commander.h
#ifndef COMMANDS_H
#define COMMANDS_H
#include "Arduino.h"
// commander configuration
#define CMD_SCAN '?' //!< command scaning the network - only for commander
#define CMD_VERBOSE '@' //!< command setting output mode - only for commander
#define CMD_DECIMAL '#' //!< command setting decimal places - only for commander
#define MAX_COMMAND_LENGTH 20
// Commander用于显示用户类型的详细信息
enum VerboseMode : uint8_t
{
nothing = 0x00, // 无显示 - 适合监控
on_request = 0x01, // 仅在用户请求时显示
user_friendly = 0x02 // 向用户显示文本消息
};
// 回调函数指针定义
typedef void (*CommandCallback)(char *); //!< 命令回调函数指针
/**
* 这是一个Commander类，它实现了基于IDvalue（例如"AB5.321" - 命令ID A，子命令ID B，值 5.321）的字符串通信协议。
* - 该类可以与HardwareSerial实例结合使用，它将读写，或者可以用来解析从用户外部获得的字符串。
* - Commander还提供了一个非常简单的命令>回调接口，使用户可以将回调函数附加到某个命令ID，详见函数add()。
*/
class Commander
{
public:
/**
* 默认构造函数接收一个串行接口，它用于输出值。
* 如果使用run()函数，它将使用此串行实例读取串行用户命令。
*
* @param serial - 串行通信端口实例
* @param eol - 换行符号字符
* @param echo - 回显最后一个输入字符（用于命令行反馈）
*/
Commander(Stream &serial, char eol = '\n', bool echo = false);
Commander(char eol = '\n', bool echo = false);
/**
* run()函数，它读取串行端口并触发已添加到Commander的回调函数，当用户请求它们时，即当他发送命令时。
*
* 它有默认命令（字母可以在commands.h文件中更改）
* '@' - 详细模式
* '#' - 小数位数
* '?' - 扫描命令 - 显示所有附加节点的标签。
*/
void run();
/**
* run()函数，它读取用户输入的字符串并触发已添加到Commander的回调函数，
* 当用户请求它们时，即当他发送命令时。
*
* 它有默认命令（字母可以在commands.h文件中更改）
* '@' - 详细模式
* '#' - 小数位数
* '?' - 扫描命令 - 显示所有附加节点的标签。
* @param reader - 读取用户输入的临时流
* @param eol - 临时的换行符。
*/
void run(Stream &reader, char eol = '\n');
/**
* run()函数，它读取用户输入的字符串并触发已添加到Commander的回调函数，
* 当用户请求它们时，即当他发送命令时。
*
* 它有默认命令（字母可以在commands.h文件中更改）
* '@' - 详细模式
* '#' - 小数位数
* '?' - 扫描命令 - 显示所有附加节点的标签。
* @param user_input - 用户输入的字符串。
*/
void run(char *user_input);
/**
* add()函数，用于在Commander上添加具有命令ID的回调函数。
*
* @param id - char命令字母
* @param onCommand - void函数指针（char *）
* @param label - 发送扫描命令时显示的字符串标签（可选）
*/
void add(char id, CommandCallback onCommand, char *label = nullptr);
// 输出变量
VerboseMode verbose = VerboseMode::user_friendly; //!< 标志该命令应输出用户易于理解的文本的标志
uint8_t decimal_places = 3; //!< 用于显示数字时使用的小数位数
// 监视函数
Stream *com_port = nullptr; //!< 如果提供了，则是串行端口终端变量
char eol = '\n'; //!< 结束符字符
bool echo = false; //!< 回显最后一个输入的字符（用于命令行反馈）
private:
// 订阅的命令回调变量
CommandCallback call_list[20]; //!< 存储命令回调函数指针的数组，20是任意数字
char call_ids[20]; //!< 已添加的回调命令
char *call_label[20]; //!< 已添加的回调标签
int call_count = 0; //!< 订阅的回调函数数量
// 帮助串行通信读取的变量
char received_chars[MAX_COMMAND_LENGTH] = {0}; //!< 目前接收到的用户信息，等待换行
int rec_cnt = 0; //!< 接收到的字符数量
// 串行打印功能
/**
* 如果verbose模式打开，则仅打印字符串消息
* @param message - 要打印的消息
*/
void printVerbose(const char *message);
/**
* 仅在verbose模式打开时打印字符串消息
* - 处理由F宏定义的字符串的函数
* @param message - 要打印的消息
*/
void printVerbose(const __FlashStringHelper *message);
/**
* 使用所需的小数点数将数字打印到串行
* @param message - 要打印的数字
*/
void print(const float number);
void print(const int number);
void print(const char *message);
void print(const __FlashStringHelper *message);
void print(const char message);
void println(const float number);
void println(const int number);
void println(const char *message);
void println(const __FlashStringHelper *message);
void println(const char message);
void printError();
bool isSentinel(char ch);
};
#endif
Commander.cpp
#include "Commander.h"
Commander::Commander(Stream &serial, char eol, bool echo)
{
com_port = &serial;
this->eol = eol;
this->echo = echo;
}
Commander::Commander(char eol, bool echo)
{
this->eol = eol;
this->echo = echo;
}
void Commander::add(char id, CommandCallback onCommand, char *label)
{
call_list[call_count] = onCommand;
call_ids[call_count] = id;
call_label[call_count] = label;
call_count++;
}
void Commander::run()
{
if (!com_port)
return;
run(*com_port, eol);
}
void Commander::run(Stream &serial, char eol)
{
Stream *tmp = com_port; // save the serial instance
char eol_tmp = this->eol;
this->eol = eol;
com_port = &serial;
// a string to hold incoming data
while (serial.available())
{
// get the new byte:
int ch = serial.read();
received_chars[rec_cnt++] = (char)ch;
// end of user input
if (echo)
print((char)ch);
if (isSentinel(ch))
{
// execute the user command
run(received_chars);
// reset the command buffer
received_chars[0] = 0;
rec_cnt = 0;
}
if (rec_cnt >= MAX_COMMAND_LENGTH)
{ // prevent buffer overrun if message is too long
received_chars[0] = 0;
rec_cnt = 0;
}
}
com_port = tmp; // reset the instance to the internal value
this->eol = eol_tmp;
}
void Commander::run(char *user_input)
{
// execute the user command
char id = user_input[0];
switch (id)
{
case CMD_SCAN:
for (int i = 0; i < call_count; i++)
{
print(call_ids[i]);
print(":");
if (call_label[i])
println(call_label[i]);
else
println("");
}
break;
case CMD_VERBOSE:
if (!isSentinel(user_input[1]))
verbose = (VerboseMode)atoi(&user_input[1]);
printVerbose(F("Verb:"));
switch (verbose)
{
case VerboseMode::nothing:
println(F("off!"));
break;
case VerboseMode::on_request:
case VerboseMode::user_friendly:
println(F("on!"));
break;
}
break;
case CMD_DECIMAL:
if (!isSentinel(user_input[1]))
decimal_places = atoi(&user_input[1]);
printVerbose(F("Decimal:"));
println(decimal_places);
break;
default:
for (int i = 0; i < call_count; i++)
{
if (id == call_ids[i])
{
call_list[i](&user_input[1]);
break;
}
}
break;
}
}
bool Commander::isSentinel(char ch)
{
if (ch == eol)
return true;
else if (ch == '\r')
{
printVerbose(F("Warn: \\r detected! \n"));
}
return false;
}
void Commander::print(const int number)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->print(number);
}
void Commander::print(const float number)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->print((float)number, (int)decimal_places);
}
void Commander::print(const char *message)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->print(message);
}
void Commander::print(const __FlashStringHelper *message)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->print(message);
}
void Commander::print(const char message)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->print(message);
}
void Commander::println(const int number)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->println(number);
}
void Commander::println(const float number)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->println((float)number, (int)decimal_places);
}
void Commander::println(const char *message)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->println(message);
}
void Commander::println(const __FlashStringHelper *message)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->println(message);
}
void Commander::println(const char message)
{
if (!com_port || verbose == VerboseMode::nothing)
return;
com_port->println(message);
}
void Commander::printVerbose(const char *message)
{
if (verbose == VerboseMode::user_friendly)
print(message);
}
void Commander::printVerbose(const __FlashStringHelper *message)
{
if (verbose == VerboseMode::user_friendly)
print(message);
}
void Commander::printError()
{
println(F("err"));
}
在源文件中，我们实现了Commander类的构造函数和一些成员函数，其中包括添加命令、运行解析器等功能。这个简单的库通过串口与用户进行交互，解析用户输入的命令，并根据命令执行相应的回调函数。
在使用Commander库时，用户只需要定义自己的回调函数，并在setup函数中添加命令即可。这样，Arduino就可以通过串口接收命令并执行相应操作，实现了简单而灵活的命令解析功能。
