用户命令接口

本文档用于给用户介绍如何使用用户命令接口，分为以下两部分：

• 用户命令的实现

• Data UART 连接

使用用户命令的蓝牙 LE 示例工程可参考：

• LE Central

• LE Scatternet

• LE Central Extended Scan

用户需要通过电脑的 Data UART 输入命令来执行交互（电脑的 USB 口通过 USB 转串口模块连接到 EVB）。

用户命令的实现

相关文件

每个文件的描述如下：

用户命令接口文件

文件名	描述
data_uart.c	初始化 Data UART，通过 Data UART 打印数据
data_uart_dlps.c	Data UART DLPS 初始化，相关的 callback，及事件的处理
user_cmd_parse.c	用于处理来自底层的 Data UART 数据，执行相应命令
user_cmd.c	定义用户命令

备注

• data_uart.c, data_uart_dlps.c, user_cmd_parse.c 及它们的头文件位于路径 src\mcu\module\data_uart_cmd 下。

• user_cmd.c 文件需要用户自己定义和添加。

配置选项

开发者可以在 user_cmd_parse.h 中配置以下数值：

/*============================================================================*
 *                         Macros
 *============================================================================*/
/** @defgroup USER_CMD_PARSE_Exported_Micros User Command Parse Module Exported Micros
   @brief  command parse related macros.
   * @{
   */

#define USER_CMD_MAX_COMMAND_LINE       80  /**< max. length of command line in bytes */
#define USER_CMD_MAX_HISTORY_LINE       3   /**< max. num of history command line */
#define USER_CMD_MAX_PARAMETERS         20  /**< max. number of parameters that the parser will scan */
/** End of USER_CMD_PARSE_Exported_Micros
* @}
*/

初始化

void app_main_task(void *p_param)
{
   uint8_t event;
   ......
   data_uart_init(evt_queue_handle, io_queue_handle);
   user_cmd_init(&user_cmd_if, "central");
   ......
}

• data_uart_init() 用于初始化 Data UART。

• user_cmd_init() 用于初始化用户命令模块。

Data UART RX 处理

void app_handle_io_msg(T_IO_MSG io_msg)
{
   uint16_t msg_type = io_msg.type;
   uint8_t rx_char;

   switch (msg_type)
   {
   ......
   case IO_MSG_TYPE_UART:
      /* We handle user command information from Data UART in this branch. */
      rx_char = (uint8_t)io_msg.subtype;
      user_cmd_collect(&user_cmd_if, &rx_char, sizeof(rx_char), user_cmd_table);
      break;
   default:
      break;
   }
}

user_cmd_collect() 用于收集命令字符并执行命令。 用户可以在串口助手中输入命令，命令使用 ENTER 作为结束。

Data UART TX 处理

Data UART TX 用于输出信息。

void app_handle_conn_state_evt(uint8_t conn_id, T_GAP_CONN_STATE new_state, uint16_t disc_cause)
{
   ......
   case GAP_CONN_STATE_CONNECTED:
      {
         le_get_conn_addr(conn_id, app_link_table[conn_id].bd_addr,
                           &app_link_table[conn_id].bd_type);
         data_uart_print("Connected success conn_id %d\r\n", conn_id);
      }
      break;
   ......
}

data_uart_print() 用于通过 Data UART 打印数据。 用户可以在串口助手端看到打印的信息。

如何添加命令

应用端需定义用户命令表。

命令格式如下:

/** @brief Prototype of functions that can be called from command table. */
typedef T_USER_CMD_PARSE_RESULT(*T_USER_CMD_FUNC)(T_USER_CMD_PARSED_VALUE *p_parse_value);

/**
* @brief Command table entry.
*
*/
typedef struct
{
   char               *p_cmd;
   char               *p_option;
   char               *p_help;
   T_USER_CMD_FUNC     func;
} T_USER_CMD_TABLE_ENTRY;

参数说明：

p_cmd:

包含可在串口通信软件中使用的命令。

p_option:

描述用户命令的格式。

p_help:

提供关于命令的功能描述。

func:

指向当命令被调用时，会执行的函数。

示例如下:

static T_USER_CMD_PARSE_RESULT cmd_conupdreq(T_USER_CMD_PARSED_VALUE *p_parse_value)
{
   T_GAP_CAUSE cause;
   uint8_t  conn_id = p_parse_value->dw_param[0];
   uint16_t conn_interval_min = p_parse_value->dw_param[1];
   uint16_t conn_interval_max = p_parse_value->dw_param[2];
   uint16_t conn_latency = p_parse_value->dw_param[3];
   uint16_t supervision_timeout = p_parse_value->dw_param[4];


   cause = le_update_conn_param(conn_id,
                                 conn_interval_min,
                                 conn_interval_max,
                                 conn_latency,
                                 supervision_timeout,
                                 2 * (conn_interval_min - 1),
                                 2 * (conn_interval_max - 1)
                              );
   return (T_USER_CMD_PARSE_RESULT)cause;
}
const T_USER_CMD_TABLE_ENTRY user_cmd_table[] =
{
   /************************** Common cmd *************************************/
   {
      "conupdreq",
      "conupdreq [conn_id] [interval_min] [interval_max] [latency] [supervision_timeout]\n\r",
      "LE connection param update request\r\n\
      sample: conupdreq 0 0x30 0x40 0 500\n\r",
      cmd_conupdreq
   },
   ......
};

如何使用命令

以 conupdreq [conn_id] [interval_min] [interval_max] [latency] [supervision_timeout] 为例， conupdreq 即为 command 名，conupdreq 之后跟着的是该 command 的参数，多个参数以空格隔开。

用户可以在电脑的串口助手端输入命令，然后按 ENTER 或点击 Send 发送命令。 推荐的串口助手是 Tera Term。

用户命令使用示例

如何显示命令

输入 ? 显示所有支持的 commands。

输入 xxx ? 显示 command 格式 ，例如 conupdreq ?。

Data UART 连接

蓝牙 LE 示例工程均默认使用 P3_0 作为 Data UART 的 TX 引脚，使用 P3_1 作为 Data UART 的 RX 引脚。

每个工程都有一份 board.h 文件，该文件定义了 Data UART 的引脚设置。

#define DATA_UART_TX_PIN    P3_0
#define DATA_UART_RX_PIN    P3_1

Data UART 引脚可以根据实际硬件环境自行配置。

PC 通过 USB 转串口模块连接到运行有蓝牙 LE 示例工程的 EVB 的 Data UART，如图所示：

PC 和 EVB 之间的 Data UART 连接

Data UART 的波特率设为 115200， 电脑串口助手工具的参数设置如图所示：

串口设置