MPCli Tool

MPCli Tool 是一款兼容 Windows、Linux 和 macOS 的多平台命令行工具，支持 UART 一对一运行模式。其核心功能包括：

  • 烧录文件

  • 读取 Flash 内容

  • 修改指定 Flash 地址的内容

  • 设置蓝牙地址和 TX Power

  • 写入 eFuse

可以前往 RealMCU_ 平台获取 MPCli Tool 程序。

命令选项简介

运行命令 mpcli -h 可查看应用程序支持的所有命令选项，长选项与短选项功能一致。

命令选项简介

短选项

长选项

功能

-h

--help

菜单

-V

--version

工具版本

-c

--com

设置串口号

-b

--baud

设置串口波特率

-a

--auto

和 -f 一起选用，指定多个分立的镜像文件烧录模式

-f

--json

烧录配置 json 文件

-P

--packetimage

输入已打包烧录文件

-e

--pageerase

擦除功能，需指定擦除 Flash 起始地址和擦除范围

-p

--program

烧录二进制文件，需指定烧录文件和烧录 Flash 地址

-v

--verify

验证指定文件是否已烧录到指定 Flash 地址

-s

--savebin

保存为二进制文件，需指定 Flash 起始地址和读取范围和二进制文件名

/

--dump_data

把 Flash 内容显示在命令提示符窗口，需指定 Flash 范围

-m

--modify

修改 Flash 指定地址范围的内容，需指定地址

-A

--address

输入 16 进制 Flash 地址

-S

--size

指定范围

-F

--filepath

指定二进制文件路径

/

--spi_pin_config_json

设定外挂 Flash PIN

/

--set_tx_power

设置 TX Power

-T

--set_xtal_calibration

设置 40MHz XTAL Internal Cap Calibration

-x

--set_mac

设置蓝牙地址

-u

--efuse_json

烧录 eFuse 文件

-U

--efuse_otp

write eFuse as OTP

-I

--get_euid_mac

显示 EUID 和蓝牙地址

-B

--get_back_mac

烧录时保持原蓝牙地址不变

/

--get_back_xtal_calibration

烧录时保持原 xtal calibration 不变

-D

--debugpassword

输入 16Bytes 的密码

-E

--chiperase

全片擦除

-C

--erase

保留前 4k 的全片擦除

-r

--reboot

重启 IC

备注

接下来将以 Windows 平台为示例，详细介绍命令格式和常用功能，帮助用户轻松完成烧录任务。需要注意的是，命令行中的参数信息仅作为示例说明其作用，实际使用时请根据具体需求替换为正确的配置信息。

基本烧录功能

MPCli Tool 支持如下两种烧录模式，用户可以通过一条命令完成多个文件的烧录任务。

多个独立镜像文件的烧录模式

准备文件

在 mpcli.exe 的同目录下，找到 mptoolconfig.json 配置模板文件，并补充以下必要信息：

  • 配置串口： 在 “port” 项中输入待烧录设备的串口号，并在 “baud” 项中输入波特率。

  • 文件信息： 将多个独立镜像文件所在的文件夹 bin 填写在 “relativepath” 项中。请确保该文件夹位于 mptoolconfig.json 的同级目录中。

  • 烧录信息： 在 “address” 项中输入各个独立镜像文件的烧录地址，将文件名填写在 “name” 项中，并通过 “enable” 项来启用烧录该独立文件。

../../_images/Burn_JSON_File_Template.png

多个独立镜像文件 JSON 填写示例

备注

  1. 所有填写内容均需放在双引号内。

  2. 为确保烧录过程的稳定性，建议将波特率设置为不超过 2Mbps，默认波特率为 1Mbps。

  3. 烧录地址需使用十六进制字符串格式填写。

  4. 如果删除 enable 字段，则将默认执行烧录操作。

  5. 增加或删除 id 条目时，注意标点符号，以避免引发 JSON 解析错误。

烧录

  1. 确保待烧录设备进入烧录模式。（具体操作为：拉低 P0_3，然后重置 IC 100ms）

  2. 调用 mpcli.exe -a -f "mptoolconfig.json" -r 或者 mpcli.exe -c com27 -b 115200 -a -f "mptoolconfig.json" -r

  • 参数说明：

    • 如果在命令参数中使用了 -c 选项指定串口号，则以该串口号为准。

    • 如果命令参数中包含 -b 选项，则使用 -b 指定的波特率。

    • 建议使用 -r 选项，在烧录完成后自动重启。这可以省略手动进入烧录模式的步骤，从而实现连续烧录测试。

包文件的烧录模式

  1. 参考 MP Pack Tool 将多个独立的镜像文件打包成一个包文件 ImagePackedFile.bin。

  2. 执行 mpcli.exe -c com27 -P ImagePackedFile.bin -r 完成烧录。

  • 参数说明：

    • -c：指定串口号（必须）。

    • -P：指定包文件的路径（必须），可以是完整路径，也可以是相对于 mpcli.exe 的相对路径。

    • -b：指定波特率，如果未指定，将使用程序的默认值。

    • -r：指定是否在烧录完成后重启 IC，建议启用该选项。

    • 启动烧录前，确认 DUT 进入烧录模式

备注

  • 擦除说明 在上述模式下，mpcli.exe 会自动计算并擦除所需的 Flash 范围。该过程根据烧录文件的地址和大小自动确定，无需手动设置。

选项功能

MPCli Tool 的调用方法如下：mpcli [option] [value]。

备注

  • [option]: 请参阅 命令选项简介，可以使用长选项或短选项

  • [value]： 根据选项属性决定是否需要传入值。

烧录一个镜像文件

用户可以在命令行参数中指定 Flash 擦除范围、烧录文件和烧录地址。 mpcli.exe 将根据这些参数执行擦除 Flash, 烧录和验证镜像文件的操作。通过这种方式，用户能灵活地控制烧录过程，确保数据准确写入指定的地址区域，并在烧录完成后进行验证以保证数据的正确性。

有两种方式可以实现一个镜像文件的烧录：

  • 一步执行

    一步完成擦除，烧录和验证：mpcli.exe -c com27 -e -p -v -F "filename.bin" -A 0x801000 -S 4096 -r

  • 分步执行

    1. 擦除：mpcli.exe -c com27 -e -A 0x801000 -S 4096 -r

    2. 烧录：mpcli.exe -c com27 -p -A 0x801000 -F "filename.bin" -r

    3. 验证：mpcli.exe -c com27 -v -A 0x801000 -F "filename.bin" -r

  • 参数说明：

    • -e：使能擦除功能。

    • -p：使能烧录功能。

    • -v：使能验证功能。

    • -A：指定设备的 Flash 地址，必须以十六进制字符串格式填写，例如 0x801000。

    • -S：指定擦除范围，向上对齐到最近的 4K 边界。

    • -F：指定烧录文件。

备注

如果确认设备上的 Flash 区域为空，可以跳过擦除 -e 以节省时间。

修改指定位置内容

mpcli.exe 支持修改设备 Flash 中的指定位置起始的连续字节内容。

  • 命令示例：mpcli.exe -c com27 -m 01:02:03:04:05:06 -A 0x801409 -r

  • 参数说明：

    • -c：指定设备的串口号，确保选择正确的端口号。

    • -m：定义要写入的内容。以英文冒号分隔的十六进制数值，每个数值由两位字符表示。单次命令执行的最大修改长度为 32 字节。

    • -A：指定修改操作在 Flash 的起始地址。地址需用十六进制字符串格式表示，如 0x801409。

    • -r：用于在操作完成后重启设备。

保存指定位置内容文件

mpcli.exe 支持将设备 Flash 中指定地址的连续内容保存到指定文件中。

  • 命令示例：mpcli.exe -c com27 -s -A 0x801000 -S 128 -F "output.bin" -r

  • 参数说明：

    • -c：指定设备的串口号，确保选择正确的端口号。

    • -s：指示进行保存操作，将指定的 Flash 内容保存到文件中。

    • -F：指定将读取的数据保存到的文件名（包含路径）。确保路径有效且有写入权限。

    • -A：指定要保存的 Flash 内容的起始地址。用十六进制格式表示起始地址，以确保读取正确的内存位置。

    • -S：指定要读取和保存的数据长度（以字节为单位）。在此示例中为 128 字节，可根据实际需要进行调整。

显示指定位置内容

mpcli.exe 支持将设备 Flash 中一段连续内容显示在命令提示符窗口。

  • 命令示例：mpcli.exe -c com27 --dump_data -A 0x801000 -S 64 -r

  • 参数说明：

    • -c：指定设备的串口号，确保选择正确的端口号。

    • --dump_data：指示把内容显示在命令提示符窗口。

    • -A：指定显示 Flash 内容的起始地址。用十六进制格式表示起始地址，以确保读取正确的内存位置。

    • -S：指定要数据长度（以字节为单位）。在此示例中为 64 字节，可根据实际需要进行调整。

../../_images/display_specified_flash_content.png

显示指定位置内容

修改蓝牙地址

mpcli.exe 支持修改设备 Flash 中的蓝牙地址。

  • 命令示例：mpcli.exe -c com27 -x 01:02:03:04:05:06 -r

../../_images/Modify_BT_ADDR.png

修改蓝牙地址

备注

  1. 参数格式： 确保蓝牙地址的每个字节都用两位的十六进制数表示，字节之间使用英文冒号进行分隔。

  2. 更新限制： 如果 Flash 中的配置区域（config region）为空，则无法进行蓝牙地址的修改操作。

  3. 更新逻辑： 若配置区域已初始化但尚未包含蓝牙地址项，则会新增该项；如果已存在地址项，则只需替换其中的 6 字节蓝牙地址即可。

  4. 参数搭配： 可以和烧录镜像文件一起选用，提升生产效率。

修改 XTAL Internal Cap Calibration

mpcli.exe 支持修改设备 Flash 中的 XTAL Internal Cap Calibration。

  • 命令示例：mpcli.exe -c com27 -T 3F -r

  • 参数说明：

    • -c：指定设备的串口号，确保选择正确的端口号。

    • -T：设定频偏值，需为长度为 2 的十六进制字符，范围应在 00 至 7F 之间。

../../_images/Modify_XTALInternalCapCalibration.png

修改 XTAL Internal Cap Calibration

备注

  1. 更新限制： 如果 Flash 中的配置区域（config region）是空的，则无法进行修改操作。

  2. 参数搭配： 可以和烧录镜像文件一起选用，提升生产效率。

修改 TX Power

mpcli.exe 支持修改设备 Flash 中的 TX Power。

  • 命令示例：mpcli.exe -c com27 --set_tx_power 7.5 -r

  • 参数说明：

    • -c：指定设备的串口号，确保选择正确的端口号。

    • --set_tx_power：设定 TX Power（以 dBm 为单位），保证参数值在设备支持范围内，以免影响设备性能。

../../_images/Modify_TXPower.png

修改 TX Power

备注

  • 更新限制： 如果 Flash 中的配置区域（config region）是空的，则无法进行修改操作。

Password 调试

mpcli.exe 支持解锁被锁定的芯片，芯片以启用调试功能。

mpcli.exe 通过 HCI UART 传入 16 字节 Password ，然后 IC 会自动重启并检查 Password 是否正确，如果正确则打开该功能。

  • 命令示例：mpcli.exe -c com27 -D 00:01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F -r

  • 参数说明：

    • -c：指定设备的串口号，确保选择正确的端口号。

    • -D：设定密码，以冒号分隔的 16 字节十六进制数据格式输入。

../../_images/DebugPassword.png

Password 调试

备注

  • 每次 IC 重启都需要重新输入 Password 才能打开该功能。

全片擦除命令

mpcli.exe 支持将设备的 Flash 的内容全部擦除。

  • 命令示例：mpcli.exe -c com27 -E -r

  • 参数说明：

    • -E 选项可用于多个独立镜像文件烧录模式和包文件烧录模式。在这些模式下，mpcli.exe 将优先执行全片擦除操作。

备注

使用 mpcli.exe -c com27 -C -r 可以从 Flash 的起始处偏移 4K 的位置开始执行全片擦除操作。

控制串口流的配置

mpcli.exe 支持解析位于其目录中的 serial.ini 文件，无需手动操作即可自动控制指定串口引脚的高低电平，从而轻松实现特定动作。 下图是 demo_serial.ini 文件的内容示例。

具体配置步骤如下：

  1. 在 mpcli.exe 所在目录下新建 serial.ini 文件。

  2. 配置所需的模块动作，如 RTS、DTR 和 sleep 操作。

  3. 当 mpcli.exe 打开串口时，将自动解析 serial.ini 文件

  4. 如果不需要相关功能，可以重命名或删除 serial.ini 文件。

../../_images/serial.ini_config_instructions.png

serial.ini 配置说明

备注

  • 可以在红色方框内添加或删除条目。

  • 仅支持以下三个关键字：RTSControl、DTRControl 和 sleep。

写 eFuse 文件

eFuse 文件采用 JSON 格式，用于记录需烧录到设备中的数据，包括安全机制和 Flash 上电参数的设置。其文件格式可参考以下 EfuseWriteFile.json 示例。

mpcli.exe 支持将eFuse文件中的数据烧写至设备。 在将 EfuseWriteFile.json 的内容写入设备之前，FW Loader 会执行空白检查以验证当前的密钥是否有效。如果当前的密钥被认定为有效，程序将提示通过，并且不会写入任何字节。如果当前密钥无效，程序将提示失败，同样不会写入任何字节。

  • 命令示例：mpcli.exe -c com27 -u EfuseWriteFile.json -r

../../_images/Write_eFuse_json_file.png

写 eFuse 文件

备注

  • 使用 eFuse json 格式，可以在 EfuseWriteFile.json 配置多个节点，从而实现一次性写入多个信息的效率提升。

  • EfuseWriteFile.json 的节点类型必须是设备支持的类型，否则写入操作将失败。请在 JSON 文件中仅使用支持的节点类型，以确保配置正确应用。

  • 适合批量配置和快速应用多项参数设置。

写 eFuse as OTP

mpcli.exe 支持将 eFuse 数据烧写到指定地址。烧写完成后， mpcli.exe 会在命令提示符窗口显示目标位置的数据，便于用户进行验证和检查。

  • 命令示例：mpcli.exe -c com27 -U 010203040506 -A 0x8800119 -r

  • 参数说明：

    • -U： 指定 eFuse 数据，字符数必须为偶数，即完整的字节。

    • -A：指定烧写地址。如果目标地址的现有内容与待烧写内容完全一致，系统将提示已有有效的 eFuse 内容，表示操作成功并正常退出；若内容不一致，则提示发生冲突，导致操作失败并退出。

备注

  • 此操作需要指定写入 eFuse 的具体地址，这意味着需要明确在哪个位置进行数据的烧写。

  • 每次操作只能写入单条信息，这要求用户在进行多次写入时，需要逐个指定和操作。

  • 适合精准和个性化地写入特定信息。

  • 该功能只有 RTL8762C/D 两颗芯片支持。

  • 在 RTL8762C 板上进行烧写时，eFuse 数据的长度限制为 32 字符（16 字节）。

  • RTL8762C/D 两颗芯片具有较大的 eFuse 空间，可以为 APP 保留最大36字节，记录只写一次的数据，例如 Serial Number。

显示蓝牙地址

mpcli.exe 支持读取 EUID 和设备 Flash 中的蓝牙地址，并将读取结果以固定格式显示在命令提示符窗口，便于用户提取和解析。

  • 命令示例：mpcli.exe -c com27 -I -r

../../_images/display_BTAddr_EUID.png

显示蓝牙地址和 EUID

备注

  • 图中 EUID 的值仅作打印式样，无含义。

  • -I 选项没有使用限制，可以与其他选项在同一条命令中使用。

读回蓝牙地址并烧录

mpcli.exe 支持使用 -B 选项，在烧录镜像文件时保护设备的蓝牙地址不被覆盖。

工具的具体做法如下：

  1. 在擦除 Flash 之前，mpcli.exe 先从 Flash 中读取出设备当前的蓝牙地址。

  2. 读取待烧录文件的内容，并将设备的原始蓝牙地址替换到 configFile.bin 中的相应位置。

  3. 执行擦除，烧录，验证的操作。

  • 命令示例：mpcli.exe -c com27 -a -f mptoolconfig.json -B -r ，工具执行日志如下。

../../_images/Readback_burn_BT_addr.png

读回蓝牙地址并烧录

备注

  • 使用要求： 当选用 -B 但未选用烧录选项时，无法完成读回并写入的动作。

  • 使用要求： 当选用 -B 且选用烧录选项时，但烧录文件中不包含 configFile.bin 时， -B 选项无效。

  • 内容检查： 在读取 Flash 的配置区（config region）时，如果蓝牙地址为空，程序提示错误日志后退出。

  • 替换原则： 在 mpcli.exe 运行过程中实现蓝牙地址的替换，但不修改原始文件

读回 XTAL Internal Cap Calibration 并烧录

mpcli.exe 支持使用 --get_back_xtal_calibration 选项，在烧录镜像文件时保护设备的频偏校准值不被覆盖。

工具的具体做法如下：

  1. mpcli.exe 先从 Flash 中读取出设备当前的频偏校准值。

  2. 读取待烧录文件的内容，并将设备的原始频偏校准值替换到 configFile.bin 中的相应位置。

  3. 执行擦除，烧录，验证的操作。

  • 命令示例：mpcli.exe -c com27 -a -f mptoolconfig.json --get_back_xtal_calibration -r ，工具执行日志如下。

../../_images/Readback_burn_XTALInternalCapCalibration.png

读回 XTAL Internal Cap Calibration 并烧录

配置 SPI Flash PIN

mpcli.exe 支持使用 ----spi_pin_config_json 选项，在文件中配置 SPI Flash Pin 实现烧录。

用户的配置步骤如下：

  1. 打开 SPI_PIN_config.json 文件，更新其中 SCLK、MISO、MOSI 和 CS 对应的引脚配置

  2. 使用 mpcli.exe 完成烧录操作。

  • 命令示例：

    • mpcli.exe –c comX –P packedimage.bin --spi_pin_config_json SPI_PIN_config.json –r

    • mpcli.exe –c comX –a –f fileconfig.json --spi_pin_config_json SPI_PIN_config.json –r

  • 参数说明：

    • --spi_pin_config_json： 指定 SPI_PIN_config.json 文件，内容如下图所示。

    • 必须和烧录镜像文件选项一起选用。

../../_images/config_FlashSPIPINJsonFile.png

配置 SPI Flash PIN

注意事项

烧录参数说明

  • 烧录地址

    • 烧录地址必须是 4 字节对齐的。

  • 擦除范围

    • 烧录镜像文件时，如果命令行选项中未包含 -E 或者 -C ，那么擦除的 Flash 大小会根据待烧录文件的大小向上扩展，达到 4KB 对齐。

  • 烧录固件

    • mpcli.exe 根据 IC 类型自动从 fw 文件夹中加载固件文件，用户不得修改或删除发布包中 fw 文件。

跨平台使用问题

在 Linux 平台或者 macOS 上使用 mpcli 时应注意下列内容：

  • 注意串口的格式设置。

    • 命令示例：./mpcli -c /dev/tty.usbserial-XXXX -r

  • 如果遇到串口无法访问或打开失败的问题，可以通过更改设备文件的权限来解决。参考如下：

    • 使用 chmod 命令授予对串口设备的读写权限 sudo chmod 777 /dev/ttyXXXX

    • 使用 adduser 命令将当前用户添加到 dialout 组 sudo adduser username dialout

错误码

mpcli.exe 工具执行完成后会返回一个整数值（错误码），用于指示程序的运行状态。

用户可以通过 捕获错误码 来判断 mpcli.exe 的执行结果，并对照如下 错误码 分析错误原因。

错误码表

错误码

Error Code

Indication

原因

0

success

1

parameter error

用户需要确保传入的参数、文件路径和选项等内容的准确性

2

port number error

用户输入的串口号不正确或串口已被占用

3

open file error

首先，请检查文件路径是否存在，然后确认文件是否完整无损

4

IC type error

无法匹配到相应的固件或者是该工具不支持此 IC 类型的选项功能

5

no ready error

由于未加载运行的固件或者串口未打开所导致的

6

hci Event error

常见原因是 DUT 未进入烧录模式

7

mp event error

烧录传输过程中出现的错误

8

crc check error

UART 传输数据时出现 CRC 校验不正确的情况

9

timeout error

超时通常是由于串口连接不稳定所致

10

flash read error

读取 Flash 内容失败

11

flash verify error

写入 Flash 后的校验错误通常是由于数据没有正确写入导致的

12

configuration signature error

校验 Flash Config Region 时不符合预期

13

packed image parse error

解析打包文件时出现错误，可能是由于文件长度错误或者文件内容存在问题

14

make temp dir error

创建临时文件路径时出现失败

15

alloc error

申请堆内存时发生失败

16

save error

保存文件时出现错误

17

delete error

删除文件时发生失败

18

dump data error

显示 Flash 内容时失败

捕获错误码

以下是几种捕获错误码的方式，用户可以自行参考。

  • 日志文件

    解析 mpcli.exe 的运行日志：

    • 执行成功时，打印出日志 Task executed successfully

    • 执行失败时，打印错误码，并打印出日志 Task execution failure

  • 批处理脚本

    • 可以使用 %errorlevel% 获取返回值。

  • PowerShell

    • 可以使用 $LASTEXITCODE 获取返回值。

  • Python

    • 可以使用 subprocess 模块获取返回值。

  • VS 解决方案

    • 可以使用获取进程返回值的方式得到，示例：Process.ExitCode