对于之前没有接触过类似概念的小伙伴来说，MPU 和 Cache 都是比较难理解的概念，我尽量把这一部分写的简单易懂一些。

在之前的系列中，比如 F1、F4 甚至是 F7 中，我们都很少接触到 MPU 这个概念，F7 中虽然有，但是即使 F7 不用 MPU，也可以正常使用下去，但是到了 H7，MPU 从可选进阶变为了基础建设，所以必须先了解一下。

MPU 就是 Memory Protection Unit，内存保护单元，单纯看名字，可能会以为是什么防止内存被攻击的东西，其实不然，MPU 的主要作用并不是安全，而是“给内存立规矩”，告诉 CPU 这块内存应该如何使用。

大体上思路和 HAL 库实现是一样的，只是使用 libopencm3 库的 API 来实现。

本文代码仓库：stm32h7-libopencm3，不想看我啰嗦的，可以直接拉代码，目录结构清晰，还写了详细注释。

本文对应于仓库中的 2gpio-lib 文件夹

工程导入

在这一次的代码中，我进行了一些管理上的变更，也算是一个新的工程，所以可以新建一个文件夹，我来引导大家一步一步来。

文件夹还是需要创建在和 stm32h7-libopencm3 同级的目录下，我们可以从之前的工程中复制 cortex-m-generic.ld 以及 user 文件夹到当前工程下，这些都是和之前保持一致的。

下载 easy_button

• Github仓库：https://github.com/bobwenstudy/easy_button

考虑到国内网络问题，部分读者可能无法访问 Github，所以我自己部署了 Gitea，将 easy_button 仓库同步到了我的 Gitea 服务器上，地址：https://git.orangetime.top/EMTime/easy_button

添加 easy_button 文件

我们要新增第三方库，这些库的源码，我建议单独放到一个文件夹中，这样方便管理，所以新建一个 lib 文件夹，在里面再创建 ebtn 文件夹，我们将下载的 easy_button 仓库中的所有文件复制到这个文件夹中。

xmake 配置

我主要修改了规则的位置和对于库的依赖，整体的配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

-- 工程名
set_project("stm32h7")

-- 定义工具链，确定位置和名称
toolchain("arm-none-eabi")
    set_kind("standalone")
    set_sdkdir("/home/time/doc/mybin/arm-none-eabi")
toolchain_end()

-- 让工程使用我们定义的工具链
set_toolchains("arm-none-eabi")

-- 设置平台与架构
set_plat("MCU")
set_arch("ARM Cortex-M7")

-- 设置编译优化等级与编译模式
set_optimize("none")
set_symbols("debug")

-- 设置架构 & FPU
add_cxflags("-mthumb", "-mcpu=cortex-m7", "-mfpu=fpv5-d16", "-mfloat-abi=hard", {force = true})
add_asflags("-mthumb", "-mcpu=cortex-m7", "-mfpu=fpv5-d16", "-mfloat-abi=hard", {force = true})
add_ldflags("-mthumb", "-mcpu=cortex-m7", "-mfpu=fpv5-d16", "-mfloat-abi=hard", {force = true})

-- 设置全局头文件路径位置 (libopencm3)
add_includedirs("../../libopencm3/include")

-- 设置全局链接库 (libopencm3)
add_linkdirs("../../libopencm3/lib")
add_links("opencm3_stm32h7")

-- 设置全局额外链接选项
add_ldflags("-T./cortex-m-generic.ld", "--static", "-nostartfiles", "-Wl,--gc-sections", {force = true})
add_syslinks("c", "gcc", "nosys")

-- 设置全局宏定义
add_defines("STM32H7")

-- 设置全局用户头文件搜索路径
add_includedirs("user/inc")

-- 目标程序
target("gpio-lib")
    -- 设置目标类型为二进制，就是编译输出可执行文件
    set_kind("binary")
    add_files("user/src/*.c")
    set_targetdir("$(projectdir)/bin")

    -- 依赖于 lib 目标，这个目标在后面定义
    add_deps("lib")

    on_load(function (target)
        target:set("filename", target:name() .. ".elf")
        -- 生成 map 文件并带 cref，显示 cross reference
        target:add("ldflags",
            "-Wl,-Map=" .. path.join(target:targetdir(), target:name() .. ".map") .. ",-cref",
            {force = true}
        )
    end)

    -- 生成额外文件
    after_build(function (target)
        local elf = target:targetfile()
        local bindir = target:targetdir()
        local name = target:name()

        -- 常见格式
        os.execv("arm-none-eabi-objcopy", {"-Obinary", elf, path.join(bindir, name .. ".bin")})
        os.execv("arm-none-eabi-objcopy", {"-Oihex",   elf, path.join(bindir, name .. ".hex")})
        os.execv("arm-none-eabi-objcopy", {"-Osrec",   elf, path.join(bindir, name .. ".srec")})
        os.execv("arm-none-eabi-objdump", {"-S", elf}, {stdout = path.join(bindir, name .. ".list")})

        -- 🔥 符号表 (对应 MDK Image Symbol Table)
        os.execv("arm-none-eabi-nm", {"-n", elf}, {stdout = path.join(bindir, name .. ".sym")})

        -- 🔥 段大小统计 (对应 MDK Image component sizes)
        os.execv("arm-none-eabi-size", {"-B", elf}, {stdout = path.join(bindir, name .. ".size")})
    end)

    on_clean(function (target)
        os.rm("build")
        os.rm("bin")
    end)

-- lib 目标，负责整合所有第三方库 (libopencm3除外)
target("lib")
    -- 设置目标类型为phony，即伪目标，不会生成文件，仅负责将不同的目标整合到一起
    set_kind("phony")

    -- 依赖于 easybutton 目标，之后有新的目标，都可以添加到这里
    add_deps("lib-ebtn")

target("lib-ebtn")
    -- 设置目标类型为静态库，依赖于他的目标会链接这个库
    set_kind("static")
    add_includedirs("lib/ebtn", {public = true})
    add_files("lib/ebtn/*.c")

代码实现

为了方便管理，我在 ebtn.c 同路径下创建了 ebtn_cb.c 和 ebtn_cb.h 文件，用于存放 easy_button 的具体实现函数。

初始化

easy_button 的初始化主要包含：

• 按键的时间配置参数（如消抖时间、长按时间等）
• 按键定义（区分按键）
• 实现按键状态读取函数
• 获取系统时间函数
• 实现事件回调函数

时间配置

直接上代码：

1
2
3
4
5
6
7
8
9
10

static const ebtn_btn_param_t default_param = EBTN_PARAMS_INIT
    (
      20,   // 按下去抖时间(ms)
      20,   // 释放去抖时间(ms)
      20,   // 点击最短时间(ms)
      300,  // 点击最长时间(ms)
      200,  // 连击间隔最大值(ms)
      500,  // 长按KEEPALIVE间隔(ms)
      10    // 最大连续点击次数
    );

easy_button 可以给每一个不同的按键设置不同的时间参数，这里我就定义了一个变量 default_param，之后所有的按键都使用这个参数。

按键定义

1
2
3
4
5
6
7
8
9
10

typedef enum
{
  USER_BUTTON1 = 0,
  USER_BUTTON_MAX,
} user_button_t;

static ebtn_btn_t btns[] =
{
  EBTN_BUTTON_INIT(USER_BUTTON1, &default_param),
};

用枚举来给我们的按键定义一个编号，实际上你不用枚举也是可以的，不过这样更方便管理。
然后使用 EBTN_BUTTON_INIT 宏来初始化我们的按键，第一个参数是按键编号，第二个参数是之前定义的时间参数。

按键状态读取函数

1
2
3
4
5
6
7
8
9
10

static uint8_t prv_btn_get_state(struct ebtn_btn* btn)
{
  switch(btn->key_id)
  {
  case USER_BUTTON1:
    return gpio_get(GPIOC, GPIO13) == GPIO13;
  default:
    return 0;
  }
}

我们自己实现一个参数为 struct ebtn_btn* btn 的函数，根据按键编号来读取按键状态，我的按键按下时为高电平，所以我们判断是否为高电平，然后返回 1（表示true，按下了按键） 或者 0（表示false，按键没有被按下）。

获取系统时间函数

1
2
3
4

static uint32_t ebtn_user_get_tick(void)
{
  return systick;
}

在前面 libopencm3 的文章中，我们初始化了 SysTick，并且实现了对应的延时功能，在这里我们包含 systick.h 就可以直接使用 systick 变量，获取系统运行的时间（毫秒）。

实现事件回调函数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

static void prv_btn_event(struct ebtn_btn* btn, ebtn_evt_t evt)
{
  switch(evt)
  {
  case EBTN_EVT_ONPRESS:

    break;
  case EBTN_EVT_ONRELEASE:

    break;
  case EBTN_EVT_ONCLICK:
    if((ebtn_click_get_count(btn) == 2) && (btn->key_id == USER_BUTTON1))
    {
      gpio_toggle(GPIOE, GPIO3);
    }
    //printf("[BTN %d] Clicked, count=%d\r\n", btn->key_id, ebtn_click_get_count(btn));
    break;
  case EBTN_EVT_KEEPALIVE:
    if(btn->key_id == USER_BUTTON1)
    {
      gpio_toggle(GPIOE, GPIO3);
    }
    //printf("[BTN %d] Keepalive, cnt=%d\r\n", btn->key_id, ebtn_keepalive_get_count(btn));
    break;
  default:
    break;
  }
}

我们自己实现一个参数为 struct ebtn_btn* btn 和 ebtn_evt_t evt 的函数，我们根据事件类型来处理不同的按键事件，在不同的事件中通过判断按键编号来执行不同的操作。

其中：

• EBTN_EVT_ONPRESS：按键按下事件，当按键按下时触发。
• EBTN_EVT_ONRELEASE：按键释放事件，当按键释放时触发。
• EBTN_EVT_ONCLICK：按键点击事件，当按键被点击时触发，easy_button 将单击和多击进行了合并，统一都叫 EBTN_EVT_ONCLICK，在代码中可以看到，我们可以通过使用 ebtn_click_get_count() 函数来获取连续点击的次数，从而区分单击和双击以及更多的点击次数。
• EBTN_EVT_KEEPALIVE：按键长按事件，当按键被长按时持续触发，执行的周期和时间参数中的 KEEPALIVE 间隔一致，我千面写的是500，那么长按期间，每隔500ms就会触发一次 EBTN_EVT_KEEPALIVE 事件。
  • 那么如果想实现长按后只执行一次操作，应该怎么处理呢？在代码中其实你也看到了，注释掉的部分有一个函数 ebtn_keepalive_get_count，通过这个函数，我们可以获取到长按期间，keepalive 事件触发的次数，当这个次数为1时，表示长按后第一次触发 keepalive 事件，那么我们就可以执行我们想要执行的操作，之后值为2，3，4…，表示 keepalive 事件被多次触发，那么我们简单的通过 if 判断就可以不再执行长按的操作了。

加入到代码逻辑中

上面的代码，只是分别定义了按键的时间参数、按键定义、按键状态读取函数、获取系统时间函数、事件回调函数，但是并没有将他们关联起来，更没有实现按键事件的执行，所以我们还需要一些函数，将他们关联起来，并且实现真正的逻辑执行，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

void ebtn_user_init(void)
{
  ebtn_init(btns,
            EBTN_ARRAY_SIZE(btns),
            NULL, 0,                    // 无组合键
            prv_btn_get_state,
            prv_btn_event);
}

void ebtn_user_process(void)
{
  ebtn_process(ebtn_user_get_tick());
}

ebtn_user_init 就是 easy_button 的初始化函数，第一个参数是之前定义的按键数组，包含了按键 ID和按键时间参数，第二个参数是按键数组的长度，第三个参数是组合键数组，第四个参数是组合键数组的长度，这里我们不需要组合键，所以都设置为 NULL 和 0，第五个参数是按键状态读取函数，第六个参数是事件回调函数。

ebtn_user_process 是用于周期性调用的函数，进行按键的状态读取、消抖、状态判断、事件执行等，它可以在定时器中断中调用，也可以在主循环中调用，如果你使用 RTOS，那么还可以单独开一个线程，调用这个函数，我这里就放在主循环中调用了。

预期效果

对于已经定义的 USER_BUTTON1，我通过按键状态读取函数将 PC11 与其关联起来，然后在事件回调函数中，实现了点击事件和长按事件，当双击按钮时，LED 灯会闪烁，当长按按钮时，LED 灯会每隔500ms闪烁一次，直到松开按键。

总结

通过使用 easy_button 库，我们可以很方便的实现按键的点击、长按、连击等功能，并且可以很方便的扩展到多个按键，只需要在 ebtn_btn_t 数组中添加按键对象即可，非常方便。

工程导入

在这里我们依然沿用之前的工程，如果你打算新建工程，或者说没有看前面的文章，请先看 STM32H7开发笔记(二):GPIO-HAL库实现

下载 easy_button

• Github仓库：https://github.com/bobwenstudy/easy_button

考虑到国内网络问题，部分读者可能无法访问 Github，所以我自己部署了 Gitea，将 easy_button 仓库同步到了我的 Gitea 服务器上，地址：https://git.orangetime.top/EMTime/easy_button

添加 easy_button 文件

进入下载好的 easy_button 路径，进入 ebtn 文件夹，将其中的所有文件复制到我们的工程目录中，在 MDK 软件中添加对应的源码文件，同时设置好头文件搜索路径，如下图：

代码实现

为了方便管理，我在 ebtn.c 同路径下创建了 ebtn_cb.c 和 ebtn_cb.h 文件，用于存放 easy_button 的具体实现函数。

初始化

easy_button 的初始化主要包含：

• 按键的时间配置参数（如消抖时间、长按时间等）
• 按键定义（区分按键）
• 实现按键状态读取函数
• 获取系统时间函数
• 实现事件回调函数

时间配置

直接上代码：

1
2
3
4
5
6
7
8
9
10

static const ebtn_btn_param_t default_param = EBTN_PARAMS_INIT
    (
      20,   // 按下去抖时间(ms)
      20,   // 释放去抖时间(ms)
      20,   // 点击最短时间(ms)
      300,  // 点击最长时间(ms)
      200,  // 连击间隔最大值(ms)
      500,  // 长按KEEPALIVE间隔(ms)
      10    // 最大连续点击次数
    );

easy_button 可以给每一个不同的按键设置不同的时间参数，这里我就定义了一个变量 default_param，之后所有的按键都使用这个参数。

按键定义

1
2
3
4
5
6
7
8
9
10

typedef enum
{
  USER_BUTTON1 = 0,
  USER_BUTTON_MAX,
} user_button_t;

static ebtn_btn_t btns[] =
{
  EBTN_BUTTON_INIT(USER_BUTTON1, &default_param),
};

用枚举来给我们的按键定义一个编号，实际上你不用枚举也是可以的，不过这样更方便管理。
然后使用 EBTN_BUTTON_INIT 宏来初始化我们的按键，第一个参数是按键编号，第二个参数是之前定义的时间参数。

按键状态读取函数

1
2
3
4
5
6
7
8
9
10

static uint8_t prv_btn_get_state(struct ebtn_btn* btn)
{
  switch(btn->key_id)
  {
  case USER_BUTTON1:
    return HAL_GPIO_ReadPin(GPIOC, GPIO_PIN_13) == GPIO_PIN_SET;
  default:
    return 0;
  }
}

我们自己实现一个参数为 struct ebtn_btn* btn 的函数，根据按键编号来读取按键状态，我的按键按下时为高电平，所以我们判断是否为高电平，然后返回 1（表示true，按下了按键） 或者 0（表示false，按键没有被按下）。

获取系统时间函数

1
2
3
4

static uint32_t ebtn_user_get_tick(void)
{
  return HAL_GetTick();
}

这个函数很简单，直接调用 HAL 库提供的 HAL_GetTick() 函数即可，或者也可以直接获取 uwTick这个值，看你个人的习惯。

实现事件回调函数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

static void prv_btn_event(struct ebtn_btn* btn, ebtn_evt_t evt)
{
  switch(evt)
  {
  case EBTN_EVT_ONPRESS:

    break;
  case EBTN_EVT_ONRELEASE:

    break;
  case EBTN_EVT_ONCLICK:
    if((ebtn_click_get_count(btn) == 2) && (btn->key_id == USER_BUTTON1))
    {
      HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
    }
    //printf("[BTN %d] Clicked, count=%d\r\n", btn->key_id, ebtn_click_get_count(btn));
    break;
  case EBTN_EVT_KEEPALIVE:
    if(btn->key_id == USER_BUTTON1)
    {
      HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
    }
    //printf("[BTN %d] Keepalive, cnt=%d\r\n", btn->key_id, ebtn_keepalive_get_count(btn));
    break;
  default:
    break;
  }
}

我们自己实现一个参数为 struct ebtn_btn* btn 和 ebtn_evt_t evt 的函数，我们根据事件类型来处理不同的按键事件，在不同的事件中通过判断按键编号来执行不同的操作。

其中：

• EBTN_EVT_ONPRESS：按键按下事件，当按键按下时触发。
• EBTN_EVT_ONRELEASE：按键释放事件，当按键释放时触发。
• EBTN_EVT_ONCLICK：按键点击事件，当按键被点击时触发，easy_button 将单击和多击进行了合并，统一都叫 EBTN_EVT_ONCLICK，在代码中可以看到，我们可以通过使用 ebtn_click_get_count() 函数来获取连续点击的次数，从而区分单击和双击以及更多的点击次数。
• EBTN_EVT_KEEPALIVE：按键长按事件，当按键被长按时持续触发，执行的周期和时间参数中的 KEEPALIVE 间隔一致，我千面写的是500，那么长按期间，每隔500ms就会触发一次 EBTN_EVT_KEEPALIVE 事件。
  • 那么如果想实现长按后只执行一次操作，应该怎么处理呢？在代码中其实你也看到了，注释掉的部分有一个函数 ebtn_keepalive_get_count，通过这个函数，我们可以获取到长按期间，keepalive 事件触发的次数，当这个次数为1时，表示长按后第一次触发 keepalive 事件，那么我们就可以执行我们想要执行的操作，之后值为2，3，4…，表示 keepalive 事件被多次触发，那么我们简单的通过 if 判断就可以不再执行长按的操作了。

加入到代码逻辑中

上面的代码，只是分别定义了按键的时间参数、按键定义、按键状态读取函数、获取系统时间函数、事件回调函数，但是并没有将他们关联起来，更没有实现按键事件的执行，所以我们还需要一些函数，将他们关联起来，并且实现真正的逻辑执行，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

void ebtn_user_init(void)
{
  ebtn_init(btns,
            EBTN_ARRAY_SIZE(btns),
            NULL, 0,                    // 无组合键
            prv_btn_get_state,
            prv_btn_event);
}

void ebtn_user_process(void)
{
  ebtn_process(ebtn_user_get_tick());
}

ebtn_user_init 就是 easy_button 的初始化函数，第一个参数是之前定义的按键数组，包含了按键 ID和按键时间参数，第二个参数是按键数组的长度，第三个参数是组合键数组，第四个参数是组合键数组的长度，这里我们不需要组合键，所以都设置为 NULL 和 0，第五个参数是按键状态读取函数，第六个参数是事件回调函数。

ebtn_user_process 是用于周期性调用的函数，进行按键的状态读取、消抖、状态判断、事件执行等，它可以在定时器中断中调用，也可以在主循环中调用，如果你使用 RTOS，那么还可以单独开一个线程，调用这个函数，我这里就放在主循环中调用了。

预期效果

对于已经定义的 USER_BUTTON1，我通过按键状态读取函数将 PC11 与其关联起来，然后在事件回调函数中，实现了点击事件和长按事件，当双击按钮时，LED 灯会闪烁，当长按按钮时，LED 灯会每隔500ms闪烁一次，直到松开按键。

完整代码

ebtn_cb.c

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

include "ebtn_cb.h"

/* ---------------- 按钮参数配置 ---------------- */
static const ebtn_btn_param_t default_param = EBTN_PARAMS_INIT
    (
      20,   // 按下去抖时间(ms)
      20,   // 释放去抖时间(ms)
      20,   // 点击最短时间(ms)
      300,  // 点击最长时间(ms)
      200,  // 连击间隔最大值(ms)
      500,  // 长按KEEPALIVE间隔(ms)
      10    // 最大连续点击次数
    );

/* ---------------- 按钮ID定义 ---------------- */
typedef enum
{
  USER_BUTTON1 = 0,
  USER_BUTTON_MAX,
} user_button_t;

/* ---------------- 按钮对象 ---------------- */
static ebtn_btn_t btns[] =
{
  EBTN_BUTTON_INIT(USER_BUTTON1, &default_param),
};

/* ---------------- 获取按键状态 ---------------- */
static uint8_t prv_btn_get_state(struct ebtn_btn* btn)
{
  switch(btn->key_id)
  {
  case USER_BUTTON1:
    // 如果按下时为高电平
    return HAL_GPIO_ReadPin(GPIOC, GPIO_PIN_13) == GPIO_PIN_SET;
  default:
    return 0;
  }
}

/* ---------------- 事件回调函数 ---------------- */
static void prv_btn_event(struct ebtn_btn* btn, ebtn_evt_t evt)
{
  switch(evt)
  {
  case EBTN_EVT_ONPRESS:

    break;
  case EBTN_EVT_ONRELEASE:

    break;
  case EBTN_EVT_ONCLICK:
    if((ebtn_click_get_count(btn) == 2) && (btn->key_id == USER_BUTTON1))
    {
      HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
    }
    //printf("[BTN %d] Clicked, count=%d\r\n", btn->key_id, ebtn_click_get_count(btn));
    break;
  case EBTN_EVT_KEEPALIVE:
    if(btn->key_id == USER_BUTTON1)
    {
      HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
    }
    //printf("[BTN %d] Keepalive, cnt=%d\r\n", btn->key_id, ebtn_keepalive_get_count(btn));
    break;
  default:
    break;
  }
}

/* ---------------- 系统时间 ---------------- */
static uint32_t ebtn_user_get_tick(void)
{
  return HAL_GetTick();
}

/* ---------------- 初始化函数 ---------------- */
void ebtn_user_init(void)
{
  ebtn_init(btns,
            EBTN_ARRAY_SIZE(btns),
            NULL, 0,                    // 无组合键
            prv_btn_get_state,
            prv_btn_event);
}

/* ---------------- 周期处理函数 ---------------- */
void ebtn_user_process(void)
{
  ebtn_process(ebtn_user_get_tick());
}

ebtn_cb.h

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

#ifndef __EBTN_CB_H_
#define __EBTN_CB_H_

#include "gpio.h"
#include "ebtn.h"

#ifdef __cplusplus
extern "C" {
#endif

void ebtn_user_init(void);
void ebtn_user_process(void);

#ifdef __cplusplus
}
#endif

#endif

main.c

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

...
#include "ebtn_cb.h"
...

int main(void)
{
  ...
  ebtn_user_init();
  ...
  while (1)
  {
    ...
    ebtn_user_process();
    HAL_Delay(5);
  }
}

总结

通过使用 easy_button 库，我们可以很方便的实现按键的点击、长按、连击等功能，并且可以很方便的扩展到多个按键，只需要在 ebtn_btn_t 数组中添加按键对象即可，非常方便。

平时写博客的时候，我经常会遇到一个小麻烦：
有时候想给大家分享一些工具、项目资源或者其它一些文件，但这些文件要么太大不方便放在仓库里，要么托管在网盘上又容易过期或者限速。久而久之，我就萌生了一个想法——干脆自己搭一个网盘吧！

不过我又不想再去折腾复杂的文件系统，于是想到用对象存储来做底层存储，既省心又稳定；再配合一个界面好看、功能齐全的文件管理面板，比如可道云（KodCloud），就能轻松实现上传、预览、分享等功能。

这篇文章就来记录一下我用 Docker 部署可道云 + 对象存储的全过程，让博客文件分享这件小事变得优雅又高效。

为什么选择可道云 + 对象存储的组合

其实在写这个文章之前，或者说有了文件分享的需求之后，我其实已经尝试过很多种方案了，比如：

• 国内的网盘：百度网盘、阿里云盘、腾讯微云等，这些网盘都非常省心，但是缺点也很明显，就是限速、限流量、限空间，以及可能会对部分文件进行审查，导致文件时不时就会失效。此外，网盘并不统一，可能你用的网盘是百度网盘，但是别人用的网盘是阿里云盘，这就导致了分享文件的时候，需要将文件上传到多个网盘，然后再下载下来，非常麻烦。
• 自建网盘：比如 Nextcloud、Owncloud 以及可道云等，这些网盘都是开源的，可以自己搭建，自由度比较高，并且服务掌握在自己手里，非常灵活，但是缺点也很明显，就是文件存储于本地，如果服务器挂了，那么文件也就丢失了。此外，直接这样分享的话，文件传输速度也会受到服务器带宽的限制（我的小水管只有不到 100 Mbps），如果多个人同时下载，那么速度就会非常慢，严重影响用户体验。

所以，我最终选择了可道云 + 对象存储的组合，既省心又稳定。

• 可道云可以像网盘一样进行文件的共享，其他人可以通过分享链接进行文件的下载，不用在意自己用的什么网盘，只要有安装浏览器，就可以直接下载。
• 对象存储通过分布式存储，保证了文件的安全与稳定性，即使服务器挂了，文件也不会丢失，而且文件传输速度也不会受到服务器带宽的限制，可以支持高并发的下载，因为文件存储于对象存储中，文件传输速度是由对象存储的带宽决定的，而不是服务器带宽决定的（一般来说，对象存储的带宽都比较高）。

在本文中，将会使用小兔互联的对象存储和 CloudFlare R2 存储为例子进行说明。

• 小兔互联的对象存储是收费的（价格还是比较实惠的），其上游是雨云，服务器位于国内，无论是访问速度还是稳定性都很高，并且默认只会使用你所选择的套餐内的流量，不开启弹性计费的情况下，即使流量被刷干了，也不会产生额外费用，只是会暂停服务，到下个月刷新（不过一般也不会有人去刷流量吧）。
• CloudFlare R2 存储是免费的，每个月拥有 10G 的空间（一个月每天占用的最大空间之和的平均数 < 10G 就是免费的，超出会收取额外费用），也有上传和下载的次数限制，其速度在国内也是不错的，这些限制对于个人使用来说，基本上是够用的。

部署可道云

官方文档：https://docs.kodcloud.com/setup/docker

我们按照官方文档的说明，进行以下的操作：

• 创建目录，作为可道云容器的映射目录，用于映射可道云的配置文件、数据文件、日志文件以及数据库等。

1
2

# 注意，这里是我自己服务器对应的目录，大家可以根据自己的需求进行修改
mkdir -p ~/doc/docker/kodcloud

• 创建数据库环境变量配置文件 db.env，用于配置可道云的数据库信息，其中内容如下：

1
2
3

MYSQL_PASSWORD=0YXl7Q^kBGFO*&g8p96^
MYSQL_DATABASE=kodbox
MYSQL_USER=kodbox

MYSQL_PASSWORD 是数据库密码，我生成了一个随机密码，大家可以根据自己的需求进行修改。

• 创建 compose.yml 文件，用于配置可道云的容器信息，其中内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

services:
  db:
    image: mariadb:lts
    command: --transaction-isolation=READ-COMMITTED
    restart: always
    volumes:
      - "./db:/var/lib/mysql"       #./db是数据库持久化目录，可以修改
      # - "./etc/mysql/conf.d:/etc/mysql/conf.d"       #增加自定义mysql配置
    environment:
      - MYSQL_ROOT_PASSWORD=0YXl7Q^kBGFO*&g8p96^ # 和上面的MYSQL_PASSWORD保持一致
      - MARIADB_AUTO_UPGRADE=1
      - MARIADB_DISABLE_UPGRADE_BACKUP=1
    env_file:
      - db.env
      
  app:
    image: kodcloud/kodbox
    restart: always
    ports:
      - 80:80                       #左边80是映射到宿主机的端口，可以修改并且建议修改，因为80端口可能被其它服务占用
    volumes:
      - "./site:/var/www/html"      #./site是站点目录位置，可以修改
    environment:
      - MYSQL_HOST=db
      - REDIS_HOST=redis
    env_file:
      - db.env
    depends_on:
      - db
      - redis

  redis:
    image: redis:alpine
    restart: always

• MYSQL_ROOT_PASSWORD 和上面的数据库密码保持一致。
• ports 中的 80 端口可以根据自己的需求进行修改，因为 80 端口可能被其它服务占用，这时候因为端口为非标准的 http 端口，所以需要配置 nginx 或其它反向代理服务器，才能正常访问。

配置完成，使用以下命令启动可道云：

1

docker compose up -d

Caddy 配置反向代理

我使用的是 caddy 进行了反向代理，具体可以参考我的另一篇文章：Caddy反向代理。
在这里，我们只需要在 Caddyfile 中增加以下配置即可：

1
2
3
4

你的域名或者端口 {
        tls 证书.crt 证书.key
        reverse_proxy 127.0.0.1:21773
}

• “你的域名或者端口”需要替换成你自己的域名或者端口。
• 21773 是上面 compose.yml 文件中 app 服务的端口，也就是刚刚强调过的可以修改的 80 端口，我的compose.yml 文件中已经修改成了 21773。

配置完之后，重启 caddy 即可生效，使用配置的域名或者端口即可正常访问可道云。

进入可道云并配置对象存储

使用配置的域名或者端口访问可道云，进入可道云后，首先需要配置管理员账号和密码，这一部分就不用我过多赘述了，你自己配置好管理员账号和密码后，登录即可。

进入可道云后，首先需要配置对象存储，因为可道云默认使用的是本地存储，我们需要将其修改为对象存储，才能实现文件的存储和分享。

小兔互联对象存储配置

1. 获取访问凭证信息

进入小兔互联的对象存储控制台，选择我们购买的对象存储实例，点击管理即可看到相关信息，如下：

2. 创建存储桶并添加网络挂载

我们点击创建存储桶，自己取一个名字（只能是字母数字和 ‘-’，不能是其它字符），比如我取的是 emtime，所属实例选择我们购买的实例，点击创建即可创建好我们对应的存储桶。

回到可道云，我们点击左侧的文件管理，然后点击网络挂载，点击新增网络挂载，存储类型选择 MinIO。

• 名称：自定义，比如我这里填写的是小兔互联。
• 空间大小：根据购买的套餐填写，比如我这里填写的是 10，表示 10GB。
• Access Key ID：对应访问凭证信息图片中 Access Key。
• Access Key Secret：对应访问凭证信息图片中 Secret Key。
• Bucket 名称：就是我们自己创建的存储桶名称，比如我这里填写的是 emtime。
• 地域节点：对应访问凭证信息图片中的 API 端点。
• 存储区域：无需填写。
• 存储目录：默认即可。
• 允许文件缩略图：按自己的需求选择，我这里没有开启。
• 服务器中转：如果开启，文件传输会先经过可道云服务器，然后通过服务器再传输到对象存储，一般会占用服务器带宽。除非网络不通或直连不稳定，否则建议关闭，让客户端直接访问对象存储效率会更高。
• 设为默认：按自己的需求选择，我这里将小兔存储设置为了默认存储。

这样我们的对象存储就配置好了，接下来我们就可以上传文件了，上传的文件会自动存储到我们配置的对象存储中。

CloudFlare R2 配置

说来 CloudFlare 也算是“赛博善人”了，免费功能非常多：CDN 加速、虚拟组网、内网穿透（Cloudflare Tunnel），甚至还有 SSL 证书自动签发与续期。对个人开发者或小项目来说，这些工具几乎能解决大部分对外访问和安全的烦恼，省钱又省心。不过比较可惜的是，在国内用的话体验没那么理想，偶尔会遇到访问慢或者节点不太稳定的情况。

1. 订阅 R2 存储并添加存储桶

如图所示，我们在对应菜单中点击 R2 对象存储，然后在界面的右上角点击创建存储桶，根据图片进行设置即可。

2. 获取 API

CloudFlare 的对象存储提供了兼容 S3 的 API，而可道云也支持 S3，所以我们直接创建 S3 API 即可。按照我图片中的步骤进行操作即可。

最后这个图片是我们创建的 API 的信息，将图片中的信息最好全都复制出来，后面配置可道云的时候需要用到。

3. 可道云添加网络挂载

和前面差不多，回到可道云，我们点击左侧的文件管理，然后点击网络挂载，点击新增网络挂载，存储类型选择 S3 存储。

• 名称：自定义，比如我这里填写的是 Cloudflare R2。
• 空间大小：CloudFlare R2 对象存储，免费版本也是 10GB，所以这里填写 10。
• Access Key ID：对应 API 信息中的访问密钥 ID。
• Access Key Secret：对应 API 信息中的机密访问密钥。
• Bucket 名称：创建存储桶时填写的名称。
• 地域节点：对应 API 信息中的为 S3 客户端使用管辖权地特定的终结点。
• 存储区域：无需填写。
• 存储目录：默认即可。
• 签名版本：默认 V4 即可。
• 允许文件缩略图：按自己的需求选择，我这里没有开启。
• 服务器中转：和之前一样，除非网络不通或直连不稳定，否则建议关闭，让客户端直接访问对象存储效率会更高。
• 设为默认：按自己的需求选择，因为我设置了小兔互联的对象存储为默认存储，所以这里就不勾选了。

这样我们的 CloudFlare R2 对象存储就配置好了，接下来我们就可以上传文件了，上传的文件会自动存储到我们配置的对象存储中。

测试使用

配置完成后，我们就可以像使用普通网盘一样上传、下载和分享文件了。
上传一个文件后，直接生成分享链接，其他人点击即可下载，整个传输过程都会通过对象存储完成，不再占用你服务器的带宽。

我分别测试了小兔互联和 Cloudflare R2 两个对象存储的下载速度（本地带宽为 1000 Mbps）：

小兔互联：

可以看到，小兔互联的下载速度还是很快的，而且完全不占用服务器流量，体验非常好。

CloudFlare R2：

Cloudflare R2 的速度也很不错，只是由于节点主要在国外，在国内的访问速度和稳定性稍差一些。
不过对于个人使用来说，它依然是一个非常有性价比（甚至可以说“白嫖友好”）的方案。

总结

整体来说，这套 “可道云 + 对象存储” 的组合，既能拥有类似网盘的便捷体验，又不必担心限速等问题。

如果你手上也有一台闲置的服务器，不妨试试这套方案。
搭建过程不复杂，但带来的便利却很明显——让博客文件分享更轻、更快，也更优雅。

这个小实验虽然验证了 GPIO 已经可以工作，但如果把它用到真正的项目里，很快就会遇到新需求——

比如，我们希望一个按键可以支持：

• 单击控制 LED
• 双击切换让单片机进入低功耗模式
• 长按触发期间，LED 灯闪烁

很明显，按键不仅仅是“开关”这么简单，它可能承载多种操作事件。为了让按键在项目中表现得灵活而可靠，我们就需要对按键进行更系统的处理。

这些库的功能大同小异，都是对按键进行消抖、长按、双击等处理，本文使用了 Github 中开源的 easy_button 库进行按键的处理。

和之前一样，仓库都是在 Github 中，如果你访问 Github 没有那么顺畅，可以使用我提供的链接，我将仓库同步到了我自部署的 Git 服务器上：https://git.orangetime.top/EMTime/easy_button

easy_button 是一个轻量级但功能丰富的按键处理库，作者人家也说了，核心的按键管理机制是借鉴的 lwbtn，具备以下的特点：

• 多按键支持：理论上按键数量无限制
• 灵活事件机制：支持单击、双击、多击、长按、超长按
• 组合按键支持：基于 bit_array 实现组合逻辑，无需重复扫描逻辑
• 静态/动态注册按键：可按需选择，节省代码空间
• 可配置时间参数：每个按键可独立配置消抖、长按、双击间隔等参数

基于作者个人的角度进行横向对比，结果如下：

可以看到，easy_button 在保证了代码体积最小化的同时，还提供了非常全面且灵活的按键处理功能，因此本文选择它作为按键处理的方案。

主要代码介绍

本来想着写一些源码解释，以及相关的一些说明的，但是发现我写出来之后，只有我能看懂，在我表述的过程中，又丢失了很多细节，所以还是主要介绍一下用到的部分，然后直接上代码吧。

事件类型

easy_button 仅保留了 4 种核心类型，可以满足大部分按键需求：

1
2
3
4
5
6
7

typedef enum
{
    EBTN_EVT_ONPRESS = 0x00,
    EBTN_EVT_ONRELEASE,
    EBTN_EVT_ONCLICK,
    EBTN_EVT_KEEPALIVE,
} ebtn_evt_t;

其中：

• EBTN_EVT_ONPRESS 为按下事件，当按键按下的时候就会触发
• EBTN_EVT_ONRELEASE 为抬起事件，当按键松开的时候就会触发
• EBTN_EVT_ONCLICK 为点击事件，easy_button 将单击和双击以及更多次点击事件合并为一种类型，只要你是按下并抬起，就会记录为一次点击事件，至于如何区分，这个放在应用的时候再讲
• EBTN_EVT_KEEPALIVE 为长按事件，当按键按下并持续一段时间，就会触发，easy_button 也将长按做了和点击事件同样的处理，根据配置的时间，会记录长按的次数；结合记录的次数，我们可以独立实现进入长按时的功能，和持续长按时的功能

按键时长配置

easy_button 可以为每个按键提供不同的时间配置，基于这些配置，easy_button 不仅实现了软件消抖，同时还提供了更灵活的长按/多击自定义方案，每个按键都可以根据应用场景和物理电路特性配置为不同的参数：

1
2
3
4
5
6
7
8
9
10

typedef struct ebtn_btn_param
{
    uint16_t time_debounce;
    uint16_t time_debounce_release;
    uint16_t time_click_pressed_min;
    uint16_t time_click_pressed_max;
    uint16_t time_click_multi_max;
    uint16_t time_keepalive_period;
    uint16_t max_consecutive;
} ebtn_btn_param_t;

其中：

• time_debounce 为按下消抖时间，防止按下时的按键抖动
• time_debounce_release 为松开消抖时间，防止松开时的按键抖动
• time_click_pressed_min 为单击按下最小时间，高于这个时间，才能算一次有效点击
• time_click_pressed_max 为单击按下最大时间，高于这个时间，通常会视为长按
• time_click_multi_max 为多击最大时间间隔，用于检测双击、三击等多击事件
• time_keepalive_period 为长按事件触发间隔，按键持续按下时，周期性触发长按事件的间隔时间
• max_consecutive 为连续点击最大次数，也就是多击上限，比如最多支持 5 次连续点击，超出 5 次后，系统会立即通知应用层进行处理

总结

easy_button 的使用其实非常的简单，接下来两篇文章，我会分别根据 HAL 库和 libopencm3 库，分别使用 easy_button 实现一个按键处理示例，通过这个示例，你可以了解到 easy_button 的使用方法，以及如何结合按键处理实现一些实际的功能。

以为 H7 的 libopencm3 开发也和 F1、F4 用起来一样简单，结果发现还是有些不一样的，自己先小折腾了半天，差点刚开坑就结束了。

在上一篇文章中我们使用 HAL 库实现了 STM32H7 的 GPIO 控制功能，本文我们使用 libopencm3 库来实现同样的功能，有关于 libopencm3 的介绍可以参考我前面写的libopencm3 开发STM32体验笔记。

强烈推荐大家看一下这篇文章，才好理解 libopencm3 的使用方式，否则可能很难快速上手。

本文代码仓库：stm32h7-libopencm3，不想看我啰嗦的，可以直接拉代码，目录结构清晰，还写了详细注释。

本文对应于仓库中的 1gpio 文件夹

开发环境简单说明

• 系统：Ubuntu 24.04 LTS（没啥特别的，装好 git、make 等基础工具即可）。
• 开发工具链：arm-none-eabi-gcc
  • apt 里有老版本。
  • ARM 官网可下最新版：ARM GNU Toolchain。
  • 我用的是 14.3 版本。装完记得把路径加到环境变量。
• 构建工具：xmake
  • 上手比 cmake 直观，能生成 makefile、ninja 等多种配置。
  • 我这边用 xmake 生成了一份 makefile，习惯 make 的同学也能直接用。
• 调试工具、烧录工具等：参考我之前的那篇 libopencm3 笔记。

工程结构

工程目录结构如下：

工程与 libopencm3 的结构

1
2
3
4
5

./
├── libopencm3/           # 库源码
├── libopencm3-examples/  # 官方示例
└── stm32h7/              # 我自己的项目
    └── 1gpio

• libopencm3/：库源码，首次拉取后要进目录 make 一下，生成库文件和头文件。
• libopencm3-examples/：示例仓库，可惜目前还没 STM32H7 的例子。
• stm32h7/：我自己的代码。建议你要玩 F1/F4 的话，也建个同级目录，比如 stm32f1/，方便区分不同型号。

libopencm3 与 libopencm3-examples 两个目录是 libopencm3 的官方仓库，为了方便大家拉取，我也将这两个仓库同步到了我自己部署的 Gitea 中。
地址分别是：

• libopencm3
• libopencm3-examples。

工程内部目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

./
├── bin/                # 编译产物（elf、hex、bin）
├── build/              # 临时文件
├── user/               # 用户代码
│   ├── inc/            # 头文件
│   │   ├── gpio.h
│   │   ├── main.h
│   │   └── systick.h
│   └── src/            # 源文件
│       ├── gpio.c
│       ├── main.c
│       └── systick.c
├── cortex-m-generic.ld # 链接脚本
├── makefile
└── xmake.lua

• bin/ 目录用于存放编译生成的可执行文件，如果使用 xmake，则会一并生成 hex、bin 文件。
• build/ 目录用于存放编译生成的临时文件。

保持源代码和生成物分离是一个好习惯，能避免 Git 仓库污染。

• user/ 目录用于存放用户代码，我按照 HAL 的目录结构，将代码分成了 inc 和 src 两个目录，其中 inc 目录用于存放头文件，src 目录用于存放源文件。之后随着功能的增多，我还会增加 lib 等目录，分别用于存放相关的库文件。
• cortex-m-generic.ld 是链接脚本，用于指定程序的内存布局。
• makefile 是 make 的构建文件，这里我是使用 xmake 生成的，可以编译生成 elf 文件，但没有添加 hex、bin 文件的生成，如果需要生成 hex、bin 文件，可以自行添加。
• xmake.lua 是 xmake 的构建文件，用于指定项目的构建规则，我的工程也是使用 xmake 进行构建的。

功能实现

用 libopencm3 写 GPIO，需要先准备几个“地基”：

• 系统时钟配置
• SysTick 延时
• GPIO 初始化与操作

顺序差不多就是这样的，我们一步一步来。

时钟配置

我的核心板外部晶振为 25 MHz，芯片是 STM32H743VIT6，最大主频为 480 MHz，需要配置 PLL 把晶振倍频到 480 MHz，再分频给各个总线和外设。

CubeMX 的时钟树很直观，所以我通常用它来进行对照，libopencm3 的结构体配置和 CubeMX 的参数差不多是一一对应的：

在 libopencm3 中，有一个结构体定义如下，分别对应了我们图片中的倍频、分频因子：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

struct rcc_pll_config {
enum rcc_osc sysclock_source;     /**< SYSCLK source input selection. */
uint8_t pll_source;               /**< RCC_PLLCKSELR_PLLSRC_xxx value. */
uint32_t hse_frequency;           /**< User specified HSE frequency, 0 if none. */
struct pll_config {
uint8_t divm;                   /**< Pre-divider value for each PLL. 0-64 integers. */
uint16_t divn;                  /**< Multiplier, 0-512 integer. */
uint8_t divp;                   /**< Post divider for PLLP clock. */
uint8_t divq;                   /**< Post divider for PLLQ clock. */
uint8_t divr;                   /**< Post divider for PLLR clock. */
} pll1, pll2, pll3;               /**< PLL1-PLL3 configurations. */
uint8_t core_pre;                 /**< Core prescaler  note: domain 1. */
uint8_t hpre;                     /**< HCLK3 prescaler note: domain 1. */
uint8_t ppre1;                    /**< APB1 Peripheral prescaler note: domain 2. */
uint8_t ppre2;                    /**< APB2 Peripheral prescaler note: domain 2. */
uint8_t ppre3;                    /**< APB3 Peripheral prescaler note: domain 1. */
uint8_t ppre4;                    /**< APB4 Peripheral prescaler note: domain 3. */
uint8_t flash_waitstates;         /**< Latency Value to set for flahs. */
enum pwr_vos_scale voltage_scale; /**< LDO/SMPS Voltage scale used for this frequency. */
enum pwr_sys_mode power_mode;     /**< LDO/SMPS configuration for device. */
uint8_t smps_level;               /**< If using SMPS, voltage level to set. */
};

我们对其进行逐项解释：

• sysclock_source：系统时钟源选择，对应上面图片中的 System Clock Mux 部分，一般来说，我们都是选择 PLL 作为系统时钟源。可选参数如下：

  • RCC_PLL：选择 PLL 作为系统时钟源，这个是常用的配置。
  • RCC_HSE：选择 HSE 作为系统时钟源。
  • RCC_HSI：选择 HSI 作为系统时钟源。
  • 其实还有一些参数，但我觉得不能用在系统时钟源的选择上，所以就不一一列举了。

• pll_source：PLL 时钟源选择，对应图片中的 PLL Clock Mux 部分，我们通常选择 HSE 作为 PLL 时钟源，可选参数如下：

  • RCC_PLLCKSELR_PLLSRC_HSE：选择 HSE 作为 PLL 时钟源，有外部晶振的情况下，我们通常选择这个配置。
  • RCC_PLLCKSELR_PLLSRC_CSI：选择 CSI 作为 PLL 时钟源，CSI 是比较新的单片机（如 H7、U5）引入的 4 MHz 的内部时钟源，功耗低，但精度不高，如果说有低功耗方面的需求，可以考虑这个配置。
  • RCC_PLLCKSELR_PLLSRC_HSI：选择 HSI 作为 PLL 时钟源，HSI 是一个 64 MHz 的内部时钟源，单片机上电默认就是这个时钟源，在没有外部晶振的情况下，我们通常选择这个配置（精度也不是很高）。

• hse_frequency：HSE 频率，是一个 uint32_t 的变量，在配置的时候我们直接填写 HSE 的频率即可（如 25000000U），如果选择的是 HSI，则填写 0。

• pll1、pll2、pll3：PLL 配置，对应图片中 PLL Source Mux 出来之后分叉出来的三条线，这三条线大同小异，我们以 pll1 为例，逐项解释：

  • divm：PLL 预分频因子，对应图片中的 DIVM1，图片里面是几，我们赋值的值就是几，比如图片中是 5，我们赋值 5 即可。
  • divn：PLL 倍频因子，对应图片中的 DIVN1，图片里面是几，同理，图片中是 192，我们就是赋值 192 即可。
  • divp、divq、divr：PLL 后分频因子，根据 pqr 即可在锁相环上输出三个不同的时钟，对应图片中的 DIVP1、DIVQ1、DIVR1，图片里面是几，我们赋值几即可。
    • divp：该通道的输出常用于系统时钟。
    • divq：该通道的输出常用于 USB、SDMMC、ETH 等外设。
    • divr：该通道的输出常用于 SPI、ADC、DAC 等外设。

• core_pre：核心时钟预分频因子，对应图片中的 D1CPRE Prescaler，决定了核心时钟的频率，可选参数如下：

  • RCC_D1CFGR_D1CPRE_BYP：不进行分频，对应于图片中的 1 分频。
  • RCC_D1CFGR_D1CPRE_DIV2：2 分频。
  • RCC_D1CFGR_D1CPRE_DIV4：4 分频。
  • RCC_D1CFGR_D1CPRE_DIV8：8 分频。
  • RCC_D1CFGR_D1CPRE_DIV16：16 分频。
  • …：其他分频因子。

• hpre、ppre1、ppre2、ppre3、ppre4：和核心时钟预分频因子类似，其意义在上面展示结构体 rcc_pll_config 的代码中标有注释，在图片中都分别有对应的配置可以参考，要注意图片中类似于 D2PPRE1 这样的名字，在 libopencm3 中，对应的参数是 RCC_D2CFGR_D2PPRE_DIV2，要注意区分。

• flash_waitstates：闪存等待周期，这个在图片中还真没对应的，可以生成一份同样配置的 MDK 工程，在 SystemClock_Config 函数中，有如下代码：

1
2
3
4
5

if (HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_4) != HAL_OK)
{
  Error_Handler();
}

可以看到函数的参数是 FLASH_LATENCY_4，这个参数对应于 libopencm3 中的 FLASH_ACR_LATENCY_4WS，所以我们赋值为 FLASH_ACR_LATENCY_4WS 即可。

• voltage_scale：电压缩放，也是新系列的单片机中出现的东西，缩放影响内核电压与最高主频，0 为高档位，档位越高，功耗越大，但主频越高。同样在 SystemClock_Config 函数中，有如下代码：

1
2
3
4

__HAL_PWR_VOLTAGESCALING_CONFIG(PWR_REGULATOR_VOLTAGE_SCALE0);

while(!__HAL_PWR_GET_FLAG(PWR_FLAG_VOSRDY)) {}

可以看到函数的参数是 PWR_REGULATOR_VOLTAGE_SCALE0，这个参数对应于 libopencm3 中的 PWR_VOS_SCALE_0，所以我们赋值为 PWR_VOS_SCALE_0 即可。

• power_mode：电源模式，同样是新系列带来的新功能，可以选择 LDO 或者 SMPS，LDO 简单易用，但功耗较大，SMPS 功耗低，但需要外部电路支持。同样在 SystemClock_Config 函数中，有如下代码：

1

HAL_PWREx_ConfigSupply(PWR_LDO_SUPPLY);

我们和 MDK 工程保持一致，所以也是选择 LDO 的供电方式，对应于 libopencm3 中的 PWR_SYS_LDO，所以我们赋值为 PWR_SYS_LDO 即可。

• smps_level：如果选择的是 SMPS，则需要设置电压等级，libopencm3 也提供了对应的选项，如 PWR_CR3_SMPSLEVEL_VOS，我没没有使用 SMPS，所以这里设置为什么都没关系。

在配置完参数之后，我们调用 rcc_clock_setup_pll(&pll_config); 即可进行系统时钟的初始化，该函数会根据我们配置的参数，设置到寄存器中，完成系统时钟的初始化。

对于时钟的初始化来说，执行顺序其实是一个值得考虑的事情，先初始化什么，后初始化什么，都是有考量的，不过 libopencm3 已经做好这一步了，如果你对执行的顺序有所疑惑，可以查看 libopencm3 源码，在libopencm3/lib/stm32/h7/rcc.c中，可以看到 rcc_clock_setup_pll 函数的执行顺序，对于理解时钟的初始化过程，有很大的帮助。

使用第三方库，需要多看源码，多找定义，多翻阅文档，多动手实践，才能熟练使用。

SysTick 延时

众所周知，HAL 库的 HAL_Delay 是基于 SysTick 实现的，延时/计时对于单片机程序来说，是一个非常重要的功能，所以 SysTick 定时器的初始化，也是我们必须要做的。

因为 SysTick 是 ARM 内核提供的，并不是 STM32 系列单片机独有的，所以在初始化思路上来说，你可以借鉴任何一个 ARM 内核处理器的相关代码，我这里还是以 CubeMX 生成的代码作为参考，进行滴答定时器的初始化。

在 HAL_Init 这个函数中，有如下代码：

1
2
3
4
5

if(HAL_InitTick(TICK_INT_PRIORITY) != HAL_OK)
{
  return HAL_ERROR;
}

这个函数实现了 SysTick 的初始化，主要包含了如下几步：

• SysTick 时钟源选择。
• SysTick 重装值设置。
• SysTick 计数值清零。
• SysTick 中断优先级设置。
• SysTick 中断使能。
• SysTick 使能。

对应于 libopencm3 中的代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

void systick_init(uint32_t ticks)
{
  systick_set_clocksource(STK_CSR_CLKSOURCE_AHB);

  systick_set_reload((rcc_get_bus_clk_freq(RCC_CPUCLK) / ticks) - 1UL);

  systick_clear();

  nvic_set_priority(NVIC_SYSTICK_IRQ, 15);

  systick_interrupt_enable();
  systick_counter_enable();
}

SysTick 可以正常工作之后，我们写好中断和延时函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

volatile uint32_t systick = 0;

// 进入低功耗模式
static inline __attribute__((always_inline)) void __WFI(void)
{
  __asm volatile("wfi");
}

void user_delay_ms(uint32_t ms)
{
  uint32_t start = systick;
  while (systick -  start < ms)
  {
    __WFI();
  }
}

// SysTick 定时器中断处理函数
void sys_tick_handler(void)
{
  systick++;
}

这样就能愉快用 user_delay_ms() 进行毫秒级延时了。

补充：延时时间展示

那么我们这样初始化之后，到底对不对呢，能不能实现延时的功能呢？我写了一个简单的程序，在无限循环中，每隔 100ms，翻转一次 PE3 引脚，如下：

1
2
3
4
5

while (1)
{
  user_delay_ms(100);
  gpio_toggle(GPIOE, GPIO3);
}

然后我们使用逻辑分析仪，采集 PE3 引脚的电平，如下：

可以看到，PE3 引脚高电平+低电平的持续时间为200.021 ms，结合逻辑分析仪和定时器本身的误差，我们可以认为，这个延时是准确的。

GPIO

GPIO 初始化

绕了一大圈才回到主题，接下来的事情反而很简单，我们只需要像标准库一样，进行时钟使能，然后配置引脚的模式即可，libopencm3 中，GPIO 的配置，需要分两步进行，第一步是配置引脚的模式，第二步是配置引脚的属性。

这一部分函数名就可以表达出其功能，所以直接上代码：

1
2
3
4
5
6
7
8
9
10
11
12
13

void user_gpio_setup(void)
{
  rcc_periph_clock_enable(RCC_GPIOE);
  gpio_mode_setup(GPIOE, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE, GPIO3);
  gpio_set_output_options(GPIOE, GPIO_OTYPE_PP, GPIO_OSPEED_2MHZ, GPIO3);

  gpio_clear(GPIOE, GPIO3);

  PWR_CR1 |= PWR_CR1_DBP;
  rcc_periph_clock_enable(RCC_GPIOC);
  gpio_mode_setup(GPIOC, GPIO_MODE_INPUT, GPIO_PUPD_PULLDOWN, GPIO13);
}

基本思路就是使能时钟->配置引脚模式->配置引脚属性，然后就可以使用对应的引脚了。

但是，在 STM32 中，PC13 - PC15 这三个引脚是比较特殊的，有以下一些需要注意的地方：

• 他们属于低速I/O，最大只能工作在 2MHz。
• 驱动能力弱，一般用作输入或者低速输出（所以核心板用这个引脚作为按键还是有一定合理性的）。
• 在 STM32H7 中，这三个引脚属于备份域（Backup Domain），为了防止程序误操作，也为了保持主电源掉电之后的可靠性，单片机在默认上电的时候是禁止访问备份域的，所以我们需要在初始化的时候，先使能备份域的访问权限，也就是在代码中，先执行 PWR_CR1 |= PWR_CR1_DBP; 这一行代码。

可能你会问，为什么在使用 HAL 库的时候没有这样的问题，因为 HAL 库在 SystemClock_Config 函数中，调用了 HAL_RCC_OscConfig，而这个函数中进行了备份域的写使能：PWR->CR1 |= PWR_CR1_DBP;，所以在使用 HAL 库的时候，不需要手动写使能备份域的代码。

GPIO 读写

和上一篇的代码逻辑一致，当按键按下的时候，进行 LED 的翻转，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

int main(void)
{
  ...

  user_gpio_setup();

  while (1)
  {
    if(gpio_get(GPIOC, GPIO13))
    {
      user_delay_ms(20);
      if(gpio_get(GPIOC, GPIO13))
      {
        gpio_toggle(GPIOE, GPIO3);
      }
      while(gpio_get(GPIOC, GPIO13));
    }
  }

  return 0;
}

如果要直接控制电平，可以使用 gpio_set 和 gpio_clear 函数，如 gpio_set(GPIOE, GPIO3); 和 gpio_clear(GPIOE, GPIO3);。

对于读取函数来说，虽然看起来没有什么问题，但是要注意 gpio_get 函数返回的并不是电平的逻辑值，而是包含所选引脚状态的位掩码。例如：

• 当 PC13 引脚为高电平时，gpio_get(GPIOC, GPIO13) 返回 0x2000（即 1 << 13），而不是单纯的 1。
• 当 PC13 为低电平时，返回值才是 0。

因此，在读取引脚电平的时候，应当判断它是不是 0，才能保证引脚电平的正确性。

总结

这一篇文章还是比较啰嗦了，本来只是想点亮一个灯，结果为了把地基打稳，写了大半篇。

用 libopencm3 开发 STM32H7，最大的心得是：

• 要习惯自己写初始化，不像 HAL 那样一口气帮你包好。
• 多看源码，多对照 CubeMX，少走弯路。
• 习惯把工程目录分层，方便后面扩展。

在 STM32H7 上，GPIO（通用输入输出口）依然是最基础、最常用的外设。无论是后续的串口通信、外设控制，还是复杂的总线接口，几乎都离不开 GPIO 的支撑。

本文将从 HAL 库 的角度出发，介绍如何完成 GPIO 的初始化与配置，并通过点亮开发板上的 LED 来完成第一个小实验。这也是我们深入 STM32H7 开发的起点。

CubeMX 配置

意法半导体为 STM32H7 提供了两套官方开发库：HAL 库 和 LL 库。

• HAL 库：官方推荐，封装更高，开发效率更快；
• LL 库：更接近寄存器，性能可控，但门槛更高。

本文使用 HAL 库来实现 GPIO 的配置和控制。

顺带一提，HAL 和 LL 库是可以混用的，但需要你有一定的寄存器基础，否则很容易出问题。我后续还会写 libopencm3 的使用笔记，它和 LL 思路类似，可以作为参考。

新建一个 CubeMX 工程，选择 STM32H743VIT6 作为目标芯片。创建时会提示 MPU（内存保护单元）的配置，暂时不用管，直接点击 “Yes” 即可。

配置时钟

在左侧的 System Core → RCC 中进入时钟配置，选择合适的时钟源，并配置相应的时钟，如下所示：

配置 GPIO

在本篇文章中，我们会同时演示 GPIO 输出（点亮 LED）和 输入（读取按键）。

在我的核心板上：

• LED 接在 PE3
• 按键 接在 PC13

对应的原理图如下：

这里 PE3 并不是直接接 LED，而是通过一个三极管来驱动。简单来说：

• 当 PE3 输出高电平时，三极管导通，LED 亮；
• 当 PE3 输出低电平时，三极管截止，LED 灭。

配置效果如下图所示：

小技巧：看到这种三极管驱动电路时，不用慌，直接看三极管箭头方向——引脚电流和箭头方向一致时，三极管导通，LED 就会亮。

在 CubeMX 中还可以给引脚加上 User Label，这样在生成代码时会有 LED_GPIO_Port 和 LED_Pin 这样的宏，方便后续编程。

对于输入引脚 PC13，电路中串了一个电阻和 ESD 保护器件。ESD 可以忽略，把它当作导线即可。限流电阻保证安全。
但需要注意的是：按键松开时，PC13 会悬空（电平不确定），所以我们在 CubeMX 里要把它配置为 下拉输入。

配置效果如下：

代码编写

配置完外设后，生成对应的工程。我这里使用 MDK，你也可以选择其他 IDE。

在 main.c 中，我们添加简单的按键检测和 LED 控制逻辑：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

#include "main.h"
#include "gpio.h"

...

int main(void)
{
  ...

  /* USER CODE BEGIN WHILE */
  while (1)
  {
    if(HAL_GPIO_ReadPin(KEY_GPIO_Port, KEY_Pin) == GPIO_PIN_SET)
    {
      HAL_Delay(20);
      if(HAL_GPIO_ReadPin(KEY_GPIO_Port, KEY_Pin) == GPIO_PIN_SET)
      {
        HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
      }
      while(HAL_GPIO_ReadPin(KEY_GPIO_Port, KEY_Pin) == GPIO_PIN_SET);
    }
    /* USER CODE END WHILE */

    /* USER CODE BEGIN 3 */
  }
}

这段代码实现了一个最经典的“按键控制 LED”功能：

• 按下按键 → LED 状态反转（亮 ↔ 灭）
• 松开按键后才能继续检测（避免长按一直触发）

当然，如果需要直接控制电平，也可以用 HAL_GPIO_WritePin：

1
2

HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET);   // 点亮 LED
HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET); // 熄灭 LED

总结

GPIO 是单片机开发的起点，也是后续一切外设驱动的基础。

• 输出方面：常见用法是点灯，比如在多线程或异步场景下，周期性闪烁的 LED 就能作为“心跳指示灯”，帮助我们快速判断设备是否运行正常。
• 输入方面：最常见的就是按键，不仅能作为人机交互入口，还可以用外部中断的方式捕获事件，这部分我会在后续文章中单独展开。

为了更好地梳理和沉淀开发经验，我决定开启一个新的系列：STM32H7 开发笔记。
这个系列将系统性地记录 H7 平台的常用功能与应用实践，帮助有类似需求的朋友快速上手并深入理解。

系列定位

• 覆盖范围广：从最基础的 GPIO、串口，到较为复杂的 USB、SDIO 等常用外设；
• 注重实践：结合实际应用场景，给出可运行的示例代码与配置方法；
• 对比不同库：既会基于 ST 官方的 HAL 库实现功能，也会尝试使用 libopencm3 实现相同功能，从而更直观地理解二者的差异和特点。

注意：本系列并不是零基础入门教程，阅读这些笔记的前提是你已经具备一定的嵌入式开发经验，了解基本的 C 语言编程和单片机外设的使用。如果你已经有一定的 STM32 或其他 MCU 开发背景，那么这些内容会帮助你快速上手并熟悉 STM32H7 的特性；但如果你完全没有嵌入式开发经验，本系列可能并不是最合适的起点。

说到起点，之后可能会出入门系列的手把手教程，可能是51，也可能是32，敬请期待。

使用的库

1. HAL 库
   ST 官方提供的硬件抽象层库，功能全面，封装完善，能够快速实现大部分外设功能，非常适合快速搭建和验证项目。
   系列将以 HAL 为主，确保功能完整性和可移植性。

2. libopencm3
   一个轻量、开源的外设驱动库，更贴近底层寄存器操作，结构简洁清晰。
   在掌握 HAL 基础上，我会尝试使用 libopencm3，展示更灵活、更贴近标准库的实现方式，并通过对比加深对外设和底层机制的理解。

系列安排

本系列的内容会按照由浅入深的方式展开，主要包括以下方面：

• 工程环境与工具链配置
• GPIO 控制与外设基础
• 串口通信（UART/USART）
• I2C / SPI 总线应用
• DMA 高速数据传输
• USB 设备与主机模式
• SDIO/SD 卡文件系统
• RTOS 在 H7 平台上的使用（比如nuttx、FreeRTOS、RT-Thread等）

在每个主题中，都会给出相应的代码示例和注意事项，帮助快速定位问题、验证功能。

结语

这套笔记并不是简单的“功能演示”，而是希望成为一份系统化的开发记录。
无论你是刚接触 STM32H7，还是已经在项目中使用它，都能在这里找到一些实用的方法和思路。

让我们从这里开始，一起探索 STM32H7 的开发之旅 🚀。

教程使用的是淘宝店铺 WeAct 售卖的 STM32H743VIT6 的核心板，如果引脚资源和你手上的不同，请自行调整代码。

应朋友的要求，写一篇关于 ThingsBoard 的文章，记录一下安装与使用的过程；

近年来，物联网平台（IoT Platform） 在智慧农业、工业监测、智能城市等应用中扮演着越来越关键的角色；随着传感器网络的普及，单一设备的数据采集和本地显示早已无法满足需求，集中式的远程管理、实时监控与可视化平台 成为构建现代物联网系统的重要组成部分；

在众多开源物联网平台中，ThingsBoard 凭借插件机制灵活、支持多种协议（如 MQTT、HTTP、CoAP），以及强大的仪表盘功能，成为中小型物联网项目中极具性价比的选择；

如果你正在寻找一个稳定易用的物联网平台，并满足以下需求：

• 需要远程监控嵌入式/传感器设备；
• 希望快速搭建一个支持 MQTT、HTTP、CoAP 的平台；
• 苦于其他平台太重或收费昂贵……

那么，ThingsBoard 是你值得一试的开源解决方案；

本系列将基于实操视角，逐步记录我从零开始搭建 ThingsBoard 环境、连接设备、上传数据并实现可视化展示的过程；涉及内容包括但不限于：

• ThingsBoard 的快速部署（Docker 方式）；
• 基于 MQTT 协议的数据上报与遥控；
• Dashboard 可视化配置；
• 与嵌入式终端（如 STM32、ESP32、树莓派等）的对接实践；

使用 Docker 部署 ThingsBoard

ThingsBoard 提供了多种安装方式，包括 Docker、Kubernetes、本地安装包等；考虑到 ThingsBoard 的 Docker 镜像已经非常完善，且易于部署，本文将采用 Docker 方式进行安装；

环境依赖

在开始安装之前，请确保你的系统满足以下环境依赖：

• Docker：ThingsBoard 需要 Docker 来运行；请确保你的系统已经安装了 Docker；如果没有安装，可以参考 Docker 官方文档进行安装；

• Docker Compose：ThingsBoard 使用 Docker Compose 来管理多个容器；请确保你的系统已经安装了 Docker Compose；如果没有安装，可以参考 Docker Compose 官方文档进行安装；

Docker compose 配置文件

进入某一个目录（你自己定义，最好和其他任何软件不产生交集），编辑 docker-compose.yml 文件：

1

nano docker-compose.yml

在文件中添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

services:
  postgres:
    restart: always
    image: "postgres:16"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
  thingsboard-ce:
    restart: always
    image: "thingsboard/tb-node:4.0.1.1"
    ports:
      - "8080:8080"
      - "7070:7070"
      - "1883:1883"
      - "8883:8883"
      - "5683-5688:5683-5688/udp"
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "10"
    environment:
      TB_SERVICE_ID: tb-ce-node
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
    depends_on:
      - postgres

volumes:
  postgres-data:
    name: tb-postgres-data
    driver: local

服务说明：

• postgres ：用于存储 ThingsBoard 的数据；

  • image: postgres:16：使用官方维护的 PostgreSQL 16 镜像，稳定可靠；
  • ports: “5432”：数据库默认端口，未映射到宿主机，确保安全（可按需映射，可以通过 Docker 创建的网络使用容器名访问）；
  • environment：配置 PostgreSQL 的数据库信息；
    • POSTGRES_DB=thingsboard：初始化时创建名为 thingsboard 的数据库；
    • POSTGRES_PASSWORD=postgres：数据库密码为 postgres，可自行修改；
  • volumes：将数据库数据挂载到宿主机上的 tb-postgres-data 卷中，实现数据持久化，容器重启不会丢失数据（但不会直接在本地映射出来），建议定期备份 tb-postgres-data，以便灾难恢复；

• thingsboard-ce：ThingsBoard 的核心服务；

  • image: thingsboard/tb-node:4.0.1.1：指定 ThingsBoard CE 版本为 4.0.1.1，可根据需求更新为最新版本；
  • ports：映射到宿主机的端口，如下：
    • 8080:8080：Web UI 访问端口（默认使用 http://localhost:8080 打开平台）
    • 7070:7070：用于 WebSocket 和服务间通信
    • 1883:1883：MQTT 协议端口（设备上报数据）
    • 8883:8883：MQTT over TLS 加密端口
    • 5683-5688:5683-5688/udp：CoAP 协议端口（适用于轻量设备）
  • logging：限制日志大小防止磁盘爆满，每个日志文件最大 100MB，最多保留 10 个文件；
  • environment：配置 ThingsBoard 的环境变量；
    • TB_SERVICE_ID=tb-ce-node：设置服务 ID，适用于集群或多节点部署；
    • SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/thingsboard：指定数据库连接字符串，注意这里的 postgres 为 Compose 内部服务名（自动 DNS），无需写成 IP 地址；
  • depends_on: postgres：确保在启动 thingsboard-ce 之前，postgres 服务已经启动；

• volumes：数据持久化，用于保存 PostgreSQL 数据的宿主机挂载卷，避免容器重启后数据丢失；

注意：端口配置中，冒号前面的是宿主机端口，后面的端口是容器内端口；如果需要修改端口，注意只能修改宿主机端口，容器内端口不能修改；
若设备运行在非 Docker 主机，请确保防火墙/路由规则允许连接映射到的 MQTT/CoAP/Web 端口；

初始化数据库与加载系统资源

在首次启动 ThingsBoard 服务之前，我们需要先 初始化数据库的表结构 并 加载系统内置资源；这一步非常关键，否则平台无法正常运行；

ThingsBoard 官方镜像已经内置了初始化命令，可以通过一条 Docker Compose 命令完成：

1
2
3
4

docker compose run --rm \
  -e INSTALL_TB=true \
  -e LOAD_DEMO=true \
  thingsboard-ce

该命令会：

• 启动一个临时的 thingsboard-ce 容器；
• 执行内置的数据库初始化流程；
• 结束后自动退出并删除临时容器（因为加了 –rm 参数）；

启动与登录平台

启动平台

完成数据库初始化后，我们即可正式启动 ThingsBoard 平台服务；

使用以下命令启动所有容器，并实时查看 ThingsBoard 的运行日志：

1

docker compose up -d && docker compose logs -f thingsboard-ce

这条命令做了两件事：

• docker compose up -d：在后台启动所有定义在 docker-compose.yml 中的服务（包括 PostgreSQL 和 ThingsBoard 容器）；
• docker compose logs -f thingsboard-ce：持续输出 thingsboard-ce 容器的运行日志，方便我们第一时间看到启动进度和是否成功；

如果你看到 Started ThingsBoardServerApplication 或类似提示，说明平台已经成功启动；
如果不想看日志，可以按下 Ctrl C 退出日志输出（容器本身不会停止，ThingsBoard 服务仍然会在后台运行）；
如果你想重新查看运行日志，可以随时使用 docker compose logs -f thingsboard-ce；

登录平台

默认情况下，ThingsBoard 会监听本地的 8080 端口；你可以在浏览器中访问：

1

http://localhost:8080

或者在非本地部署时，替换为你的主机 IP 地址：

1

http://{your-host-ip}:8080

打开网页后，即可看到 ThingsBoard 的登录界面；

首次登录系统，你可以使用以下默认账户：

建议登录后尽快修改各个账户的密码，以保证平台安全；

ThingsBoard 使用

添加设备

其实我们第一步应该是创建租户和租户管理员账号的，但是平台默认提供了三个账号，我们直接使用即可；

登录租户管理员账号后，点击左侧导航栏的 设备 选项，进入设备管理页面即可添加设备；

可选择 default 或 thermostat 模板，这些模板预配置了 MQTT、HTTP 与 CoAP 通信协议，便于多种方式测试连通性（在我当前使用的版本中，MQTT 功能运行最稳定，CoAP反而无法正常使用）；

分配给客户，我选择了公开，这个决定了用户账户可以查看的设备；

我们设置 MQTT 凭据，要注意，每一个设备的凭据不能相同，凭据是设备与平台通信的唯一标识；

测试设备

连接平台

我们可以使用客户端，或者 Linux 命令行工具，来测试设备与平台之间的连通性，这里我使用 MQTTX 工具进行测试；

选择你运行的 Docker ThingsBoard 的机器地址，端口选择 Docker 配置映射出来的端口（默认是 1883），填入在 ThingsBoard 中设备的凭据，然后点击连接即可连接到平台；

订阅、发布与平台设备配置

在说订阅与发布之前，我们先来看一下 ThingsBoard 的属性，ThingsBoard 分为客户端属性、服务端属性和最新属性值，如下：

在平台点击设备，进入设备详情页面，可以看到设备的属性，如下：

接下来我就根据上面的表格，来演示一下 ThingsBoard 的属性与设备之间的交互；

服务端属性

服务端属性通常是由平台维护、设备通过请求获取的一类静态或配置属性；它常用于存储平台侧记录的设备参数，例如部署位置、设备负责人、安装时间等；

• 平台侧应用获取服务端属性

因为服务端属性仅能通过平台侧应用进行读写，所以无法使用 MQTT 订阅的方式获取，只能通过 API 获取，如下：

1. 获取 JWT 令牌

1

curl -X POST https://iot.140105.xyz/api/auth/login   -H "Content-Type: application/json"   -d '{"username":"tenant@thingsboard.org","password":"tenant"}' 

以我的平台为例，将地址替换为你的平台地址，用户名和密码替换为你的租户管理员账号和密码，即可获取 JWT 令牌，返回示例如下（返回的信息比较长，注意仔细比对）：

1
2
3
4

{
    "token": "xxxxx",
    "refreshToken": "xxxxx"
}

2. 获取设备服务端属性

使用上一步获得的 JWT 令牌，通过下面的方法获取设备的服务端属性：

1

curl -X GET 'https://iot.140105.xyz/api/plugins/telemetry/DEVICE/4d453110-4e91-11f0-aa54-d1bcfb4dde7b/values/attributes/SERVER_SCOPE'   -H 'Content-Type: application/json'   -H 'X-Authorization: Bearer JWT 令牌'

其中 DEVICE 后面的 4d453110-4e91-11f0-aa54-d1bcfb4dde7b 是设备的 ID，在平台网页点击设备，网址链接中可以看到，JWT 令牌就是上一步获取的 token，返回结果如下；

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

[
    {
        "lastUpdateTs": 1750619760822,
        "key": "lastConnectTime",
        "value": 1750619760822
    },
    {
        "lastUpdateTs": 1750619852183,
        "key": "test",
        "value": "1"
    },
    {
        "lastUpdateTs": 1750621040988,
        "key": "lastDisconnectTime",
        "value": 1750621040987
    },
    {
        "lastUpdateTs": 1750621041491,
        "key": "lastActivityTime",
        "value": 1750621040963
    },
    {
        "lastUpdateTs": 1750621684069,
        "key": "inactivityAlarmTime",
        "value": 1750621684069
    },
    {
        "lastUpdateTs": 1750621684069,
        "key": "active",
        "value": false
    }
]

注意：token 是有有效期的，如果过期了，需要重新获取；
以上的演示方式，均在命令行中完成，可以使用其他编程语言，如 Python、Java、Go 等作为 curl 的替代；

• 平台侧应用设置服务端属性

我们同样使用 JWT 令牌，通过下面的方法设置设备的服务端属性：‘

1
2
3

curl -v 'https://iot.140105.xyz/api/plugins/telemetry/DEVICE/4d453110-4e91-11f0-aa54-d1bcfb4dde7b/SERVER_SCOPE'   -H 'Content-Type: application/json'   -H 'X-Authorization: Bearer JWT 令牌' \
-H 'content-type: application/json' \
--data-raw '{"test":"2"}'

其中最后一行的 test 是你要设置的属性键名，2 是你要设置的属性值，运行之后平台对应设备的服务端属性就会发生变化；

客户端属性

客户端属性常用于平台的分组管理、版本控制、规则引擎判断等场景，是设备与平台之间状态同步的基础结构之一；

• 设备发送数据到平台

客户端属性的主题是 v1/devices/me/attributes，通过表格我们能看到，这个是由设备发送到平台的，所以我们使用 MQTTX 工具模拟设备，向平台发布一条消息，如下：

1
2
3
4
5

{
  "serialNumber": "SN-001-ABC",
  "firmwareVersion": "v1.2.5",
  "model": "X200"
}

平台可以根据设备上报的属性，在仪表盘中展示设备信息，也可以在规则链库中根据属性值进行判断，如下：

如上图即为在仪表盘中显示设备信息；

如上图即为设置规则链库，当版本信息小于脚本中所配置的版本时，便会触发提醒；

• 设备从平台获取数据

设备可以主动请求平台侧的客户端属性，请求主题为 v1/devices/me/attributes/request/<request_id>，其中 <request_id> 是请求 ID，可以任意指定，订阅主题可以是 v1/devices/me/attributes/request/<request_id> 或者 v1/devices/me/attributes/response/+，发送的数据如下：

1
2
3

{
  "clientKeys": "firmwareVersion,serialNumber"
}

其中， firmwareVersion 和 serialNumber 是设备在 ThingsBoard 中配置的客户端属性；

在主题 v1/devices/me/attributes/request/1 或者 v1/devices/me/attributes/response/+ 中会得到从平台返回的数据，如下：

1
2
3
4
5
6

{
  "client": {
    "serialNumber": "SN-001-ABC",
    "firmwareVersion": "v1.2.5"
  }
}

对 json 进行解析，即可得到平台返回的属性值；

在 ThingsBoard 中，每个设备都有唯一的连接凭据，因此平台能够识别出请求来源的具体设备；即使多个设备同时使用相同的 request_id 发起属性请求，平台也能正确分发并返回各自的响应结果，不会互相影响；
但如果你使用一个设备代理器，代理器会使用相同的凭据，那么平台会认为所有的请求都来自同一个设备，导致响应混乱，这时候就需要你对代理的设备进行额外的代码编写，给每个被代理的设备分配不同的请求 ID，实现设备之间的请求隔离；

• 平台侧应用获取数据

平台侧可以和设备一样使用 MQTT 获取数据，也可以使用 API 获取数据，如下：

1

curl -X GET 'https://iot.140105.xyz/api/plugins/telemetry/DEVICE/4d453110-4e91-11f0-aa54-d1bcfb4dde7b/values/attributes/CLIENT_SCOPE'   -H 'Content-Type: application/json'   -H 'X-Authorization: Bearer JWT 令牌'

和服务端属性获取的方式大同小异，只是将 SERVER_SCOPE 替换为 CLIENT_SCOPE 即可，运行之后结果如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

[
    {
        "lastUpdateTs": 1750613652969,
        "key": "serialNumber",
        "value": "SN-001-ABC"
    },
    {
        "lastUpdateTs": 1750613652969,
        "key": "model",
        "value": "X200"
    },
    {
        "lastUpdateTs": 1750613652969,
        "key": "firmwareVersion",
        "value": "v1.2.5"
    }
]

共享属性

共享属性是平台侧应用给设备分发数据的一种方式，共享属性可以用于平台侧应用之间的数据共享（也可以用于平台向设备发送数据）；

和客户端属性的区别是，客户端属性是设备主动请求平台返回数据，而共享属性是当属性发生变化或者新建属性时候，平台会主动向设备发送数据（当然，也可以主动请求）；

• 设备从平台请求数据

和客户端属性一样，设备可以主动请求平台侧的共享属性，请求主题为 v1/devices/me/attributes/request/<request_id>，其中 <request_id> 是请求 ID，可以任意指定，订阅主题可以是 v1/devices/me/attributes/request/<request_id> 或者 v1/devices/me/attributes/response/+，发送的数据如下：

1
2
3

{
  "sharedKeys": "test"
}

其中， test 是你要获取的属性键名；

在主题 v1/devices/me/attributes/request/<request_id> 或者 v1/devices/me/attributes/response/+ 中会得到从平台返回的数据，如下：

1
2
3
4
5

{
  "shared": {
    "test": "1"
  }
}

对 json 进行解析，即可得到平台返回的共享属性值；

• 属性修改/变动自动推送

无论在平台侧应用，还是在平台本身，我们对共享属性进行增、删、改操作，设备都会收到平台自动推送的属性值，如下：

1. 增和改

1
2
3

{
  "test": "2"
}

2. 删

1
2
3
4
5

{
  "deleted": [
    "test"
  ]
}

• 平台侧应用获取数据

平台侧应用获取共享属性的方式和服务端属性大同小异，只是将 SERVER_SCOPE 替换为 SHARED_SCOPE 即可，如下所示,在此不过多赘述：

1

curl -X GET 'https://iot.140105.xyz/api/plugins/telemetry/DEVICE/4d453110-4e91-11f0-aa54-d1bcfb4dde7b/values/attributes/SHARED_SCOPE'   -H 'Content-Type: application/json'   -H 'X-Authorization: Bearer JWT 令牌'

• 平台侧应用设置数据

平台侧应用设置共享属性的方式和服务端属性大同小异，只是将 SERVER_SCOPE 替换为 SHARED_SCOPE 即可，如下所示,在此不过多赘述：

1
2
3

curl -v 'https://iot.140105.xyz/api/plugins/telemetry/DEVICE/4d453110-4e91-11f0-aa54-d1bcfb4dde7b/SHARED_SCOPE'   -H 'Content-Type: application/json'   -H 'X-Authorization: Bearer JWT 令牌' \
-H 'content-type: application/json' \
--data-raw '{"test":"2"}'

用此方法进行数据的更新，设备也会自动收到平台推送的数据；
如果设备离线，可能会错过重要的数据更新，所以建议在设备启动之后订阅共享属性，并且每次连接后请求属性的最新值；

除了属性，ThingsBoard 还提供了遥测（Telemetry）数据，和属性的区别是遥测多了时间序列相关的功能，可以用于长时间的数据对比分析等，展开的话内容太多，在此不过多赘述，可以在这里查看：遥测数据；

总结

本文记录了从零开始使用 Docker 快速部署 ThingsBoard 平台的全过程，并详细演示了平台与设备之间通过 MQTT 协议进行数据交互的方式，特别是客户端属性、服务端属性、共享属性三者的使用与差异；借助 ThingsBoard 丰富的功能，我们可以轻松实现设备的远程配置、状态监测与规则联动，为物联网系统的构建打下坚实基础；

如果你正在开发或运营一个嵌入式项目，或正在寻找一套支持 MQTT/HTTP/CoAP 且功能全面的物联网平台，相信 ThingsBoard 能为你提供一个清晰的起点；

后续我将继续记录更多实战经验，包括遥测数据上传与可视化、规则链自动化处理、集成邮件/钉钉/短信报警机制等内容，欢迎持续关注；

我最开始只是想记录一下技术笔记，后来发现 Markdown 写作 + Hexo 渲染这个组合用起来非常舒服：格式统一、可定制性强、部署自由（可以部署在 GitHub Pages、VPS、自建服务器等）；于是就干脆一步步搭建了一个完整的 Hexo 博客站点；

这篇文章就是整个过程的完整记录：从搭建环境、初始化项目、使用主题，到部署上线、开启 HTTPS、绑定域名等等，涵盖我实战中遇到的所有关键环节；希望能帮到你，也为自己留个备忘；

环境准备（Ubuntu 系统）

在正式搭建 Hexo 博客之前，需要先安装一些基础环境工具；由于我使用了 FRP 实现内网穿透部署 Hexo，所以本篇不涉及 GitHub Pages 或 Git 相关内容，仅保留最必要的部分；

安装 Node.js 和 npm

Ubuntu 默认的软件源中 Node.js 版本可能比较老，推荐使用官方的 NodeSource 源进行安装；这里以 Node.js LTS 版本（长期支持版）为例：

1
2
3

# 安装 Node.js LTS 版本（包含 npm）
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

验证安装是否成功：

1
2

node -v    # 输出版本号表示安装成功
npm -v

安装 Hexo 命令行工具

1

sudo npm install -g hexo-cli

验证安装是否成功：

1

hexo -v    # 输出版本号表示安装成功

可选：Git（非必须）

如果你后续打算将博客托管到 GitHub Pages，或使用 Git 做版本管理，也可以顺手安装 Git：

1

sudo apt install -y git

但如果你和我一样是用 FRP 暴露本地服务到公网，那完全可以跳过这一步；

Hexo 博客项目初始化

在完成环境安装后，就可以开始初始化 Hexo 博客项目了；Hexo 会在指定目录生成整个博客所需的目录结构，包括文章源文件、配置文件和静态资源目录等；

创建博客项目文件夹

选择一个你喜欢的目录作为博客的根目录，例如：

1
2

mkdir -p ~/my_blog
cd ~/my_blog

初始化博客项目

在项目目录中初始化 Hexo，会自动生成 scaffolds/、source/、themes/ 等基础目录：

1
2

hexo init
npm install

执行完后目录结构大致如下：

1
2
3
4
5
6
7

my_blog/
├── _config.yml        # Hexo 配置文件
├── package.json       # 项目依赖描述
├── scaffolds/         # 文章模板
├── source/            # 文章和静态资源存放目录
├── themes/            # 博客主题目录
└── node_modules/      # npm 安装的依赖包

启动本地服务器

完成初始化后，Hexo 自带的本地服务器就可以直接启动，用于查看博客内容是否正确渲染：

1

hexo server

启动成功后，浏览器访问 http://localhost:4000，即可看到博客的默认页面；

别急！别看到有端口就急着用FRP进行映射，因为hexo server 本质上只是一个轻量级本地预览服务，虽然可以通过 FRP 等工具映射到公网进行访问，但要注意以下几点：

• 它不是为长期稳定服务设计的，性能和安全性不适合生产环境；
• 它的渲染速度比生产环境要慢很多，不适合用来做性能测试；
  一旦关闭终端或重启机器，服务就会中断；
  没有缓存机制、日志控制、访问控制等功能，暴露在公网风险较高；

所以，在正式部署之前，还有一些操作要做；

使用 Hexo 生成静态博客 + Caddy 反向代理

当你完成博客内容撰写后，就可以使用 Hexo 将其生成静态页面，供 Caddy 托管：

生成静态页面

在 Hexo 项目的根目录下运行：

1

hexo clean && hexo generate

或简写为：

1

hexo clean && hexo g

这会将博客的 HTML、CSS、JS 等静态资源统一输出到 public/ 目录中；这个目录就是你最终需要部署的网页内容；

使用 Caddy 托管博客内容

假设你希望通过 https://blog.example.com 来访问这个博客，并且你的 public/ 目录路径为 /home/time/hexo-blog/public，Caddy 的配置大致如下（具体细节见我之前写的 Caddy 文章）：

1
2
3
4

blog.example.com {
    root * /home/time/hexo-blog/public
    file_server
}

保存配置后，重新加载 Caddy 即可：

1

sudo caddy reload

注意：每次修改文章或主题后，记得重新执行 hexo g 生成静态文件；

这样，就已经将博客反向代理到本机的443端口并且开启了https，绑定了域名；

使用FRP实现公网访问

在某些情况下，我们的服务器部署在家里或内网环境中，并没有公网 IP；这时可以借助 FRP（Fast Reverse Proxy）进行内网穿透，让外部用户也能访问部署在本地的 Hexo 博客；

国内有很多提供FRP的服务，如果你有自己的公网服务器，也可以自己搭建FRP服务端（但如果有公网服务器，谁会在内网部署服务呢）；

需要注意的是：我国通过自定义域名实现公网访问博客是需要备案的；根据工信部规定，域名用于网站服务必须完成 ICP 备案，否则将无法解析或被阻断；

因为 FRP 平台和服务太多了，我也没法一一列举，这里只介绍一个通用的 FRP 映射配置方式：

将本地博客服务映射到公网域名

假设你本地的 Hexo 博客是通过 Caddy 启动的（前文所述），那么监听端口就是在 443 端口，我们希望通过公网访问 https://blog.example.com；

那么配置大体如下：

1
2
3
4
5
6
7
8

[common]
server_addr = your.server.ip  # 替换成 FRP 服务端地址
server_port = 7000            # 替换成你服务端配置的端口

[hexo-blog]
type = tcp
local_port = 443
custom_domains = blog.example.com

然后将blog.example.com域名解析为 FRP 服务端地址，这样就可以实现公网的博客访问了；

总结

至此，一个完整的 Hexo 博客就搭建完成了：从安装环境、初始化项目、选择部署方式，再到通过 Caddy 提供 HTTPS 支持，最后结合 FRP 将内网服务映射到公网访问，整个过程虽然步骤不少，但每一步其实都非常清晰；而一旦搭好，后续的维护只需要写好文章、执行 hexo g，几秒钟就能上线更新，非常高效；

当然，这只是一个最基础的博客框架，还有很多可以优化的地方，比如：

• 主题定制：Hexo 主题丰富，你可以根据自己的喜好选择合适的主题，甚至自己动手定制主题；
• 文章分类：Hexo 默认没有分类功能，但可以通过插件实现；
• 评论系统：Hexo 默认没有评论功能，但可以通过插件实现；
• SEO 优化：Hexo 默认没有 SEO 优化功能，但可以通过插件实现；

博客就像是一个属于自己的技术“树洞”，写给别人看是传播，写给自己看是成长；希望你也能在这个过程中收获成就感，把更多思考沉淀为内容，持续构建自己的知识体系；

你可能搜索过相关方法，结果却一脸懵逼：

• 有人说往 /etc/rc.local 里加一行就行了；
• 有人建议写 .service 文件放进 systemd；
• 更有甚者，在 Alpine 这类轻量级系统里突然蹦出个 “OpenRC”——啥啊这是？

更糟的是，你跟着教程配置了一堆，结果脚本根本没执行，日志里还一点提示都没有；

我也踩过这些坑，什么 systemctl、runlevel、依赖顺序、文件权限……搞得人头大；

这篇博客将结合实际情况，总结 systemd 与 OpenRC 两种主流 init 系统下的开机自启方式：

• 在现代 Linux 系统中，systemd 已成为最主流的初始化系统和服务管理器，被包括 Debian、Ubuntu、Fedora、CentOS 7+、Arch Linux 在内的大多数发行版所采用；它提供了统一的服务控制方式（如 systemctl 命令）、并行启动优化、日志管理（journald）等丰富功能，适合中大型服务器、桌面系统及容器环境；
• 相比之下，OpenRC 是一个轻量级的 init 系统，广泛用于如 Alpine Linux、Gentoo 等追求极致体积与灵活性的发行版；它不依赖 systemd，使用简单的 shell 脚本管理服务，启动快速，特别适合资源受限或需要最大程度自定义的场景，如容器、嵌入式设备和自定义 Linux 构建系统；

目标是：看完后你能快速写出属于自己的启动脚本，并能“优雅地”开机自启，而不是一顿 chmod +x + debug；

systemd

systemd是主流的 init 系统，被包括 Debian、Ubuntu、Fedora、CentOS 7+、Arch Linux 在内的大多数发行版所采用；

最近整了一个成都的LXC云服务器，7块包年，配置也“感人”：128M 内存 + 1G 硬盘；不过好在有25个可分配的V4端口，并且带宽高达1Gbps，非常适合用来跑frps以及虚拟组网等服务；

所以我就打算跑一些服务，让它们后台运行并且开机自启；但可能是因为性能或者别的一些问题，我使用 nohup + & 或 screen 都不稳定，别说开机自启了，连后台稳定运行都做不到；

以下以 frps 为例，演示如何在 systemd 下实现开机自启；

创建服务文件

首先，在 /etc/systemd/system/ 目录下创建一个以 .service 结尾的文件，如 frps.service；

1

sudo vim /etc/systemd/system/frps.service

建议以后统一使用比如 emtime_xxx.service 这样的命名方式，便于识别和管理；

以下是一个最小可用服务配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

[Unit]
Description=Frp Server Service
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/frps -c /etc/frp/frps.toml
Restart=on-failure
RestartSec=5s
StandardOutput=file:/var/log/frps.log
StandardError=file:/var/log/frps-error.log

[Install]
WantedBy=multi-user.target

说明：

• After= 可根据需求改成 network-online.target，必要时加上 Requires=network-online.target，这样服务会在网络可用后启动；
• User 可根据需求改成其他用户，但要注意权限问题，比如访问低于1024的端口或者调用需要 root 权限的命令，都需要使用 root 用户；
• ExecStart 要使用绝对路径，不能写成 ./xxx.sh；
• 最后的命令不能中断或退出，否则服务会直接终止；
• Restart=always 可用于无条件重启；

启用服务

创建完服务文件后，需要启用并启动服务：

1
2
3
4
5
6
7
8

# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启动服务（frps 是服务名）
sudo systemctl start frps

# 设置开机自启
sudo systemctl enable frps

服务运行管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 查看服务状态
sudo systemctl status frps

# 查看运行输出
tail -f /var/log/frps.log
tail -f /var/log/frps-error.log

# 停止 / 重启服务
sudo systemctl stop frps
sudo systemctl restart frps

# 禁用开机自启
sudo systemctl disable frps

# 查看服务日志
sudo journalctl -u frps -f
sudo journalctl -u frps -n 50 --no-pager

# 验证服务文件语法
sudo systemd-analyze verify /etc/systemd/system/frps.service

OpenRC

OpenRC 是一个轻量级的 init 系统，广泛用于 Alpine Linux、Gentoo 等发行版；

还是以frps为例，演示如何在 OpenRC 系统（如 Alpine）中实现开机自启；

安装 OpenRC（如未预装）

1

apk add openrc --no-cache

编写启动脚本

在 OpenRC 中，服务通过位于 /etc/init.d/ 的脚本来管理；我们可以手动编写一个脚本来启动 frps：

1

sudo nano /etc/init.d/frps

内容如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

#!/sbin/openrc-run

name="frps"
description="Frp server"

command="/home/alpine/app/frp/frps"
command_args="-c /home/alpine/app/frp/frps.toml"
pidfile="/run/${RC_SVCNAME}.pid"

output_log="/var/log/frps.log"
error_log="/var/log/frps.err"

depend() {
    after sshd
    need net
}

start_pre() {
    # 确保 /run 目录存在，并可写入 PID 文件
    checkpath --directory /run --owner root:root

    # 创建或检查日志文件
    checkpath --file --mode 0644 /var/log/frps.log /var/log/frps.err
}

command_background="yes"

说明：

• command= 和 command_args= 指定要执行的命令及参数；
• pidfile= 指定 PID 文件的路径，通常建议放在 /run；
• output_log= 和 error_log= 可指定标准输出和错误输出文件路径；
• depend() 中声明依赖项，如网络（need net）和 SSH；
• start_pre() 在启动服务前执行一些准备工作，如创建所需目录或文件；
• command_background=”yes” 表示服务以后台方式运行；

添加可执行权限

OpenRC 启动脚本必须具有执行权限：

1

sudo chmod +x /etc/init.d/frps

管理服务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 启动服务
sudo rc-service frps start

# 停止服务
sudo rc-service frps stop

# 查看服务状态
sudo rc-service frps status

# 设置开机启动
sudo rc-update add frps

# 取消开机启动
sudo rc-update del frps

# 查看所有开机自启服务
sudo rc-update show

提示与建议

• 日志调试：OpenRC 本身不会自动保存日志，建议你手动查看日志文件或将日志写入 /var/log 中的文件（如上所示），确保问题可定位；
• 后台守护进程注意事项：确保你的命令不会自行退出（即不会直接跑完就结束），否则 OpenRC 会认为服务失败；
• 目录权限问题：某些系统（特别是 Alpine）在 /run 下的临时目录可能会重置，建议服务脚本中始终用 checkpath 创建并赋权；
• 写 PID 的必要性：OpenRC 通过 pidfile 判断服务状态，漏写 PID 文件可能导致服务状态判断异常；

总结

无论是主流发行版中功能强大的 systemd，还是轻量简洁、广泛用于容器的 OpenRC，它们都承担着 Linux 系统中“启动与管理服务”的关键角色；

这篇文章从两个角度出发，分别介绍了如何：

• 编写 systemd 的 .service 文件，实现服务注册、日志管理、异常重启等；
• 使用 OpenRC 编写 init 脚本，借助 checkpath 和 command_background 等机制实现后台运行和日志落地；

在实际使用中，你只需要记住：

• systemd 写的是配置文件，放在 /etc/systemd/system/；
• OpenRC 写的是可执行脚本，放在 /etc/init.d/；
• 二者都可以通过 enable 或 rc-update add 实现“开机自启”；

最后，无论你是跑一个简单的守护进程，还是想在嵌入式设备上部署自己的服务，只要搞清楚系统用的是什么 init 系统，再结合本文中的方法，一般都能跑通（别再满世界搜 /etc/rc.local 了，那已经是“老黄历”了）；

希望本文能帮你绕过“服务起不来没日志还没报错”的痛苦，优雅地把脚本跑起来；

在嵌入式开发中，如何在不影响系统实时性的前提下，高效输出调试信息，一直是让人头疼的问题；传统的串口 printf 虽然简单易用，但在输出量大、串口速率较低时，就可能严重阻塞系统主流程，甚至引发时序异常；

为了解决这些问题，SEGGER 提供了 RTT（Real-Time Transfer）机制，它是一种利用 J-Link 仿真器在目标设备与主机之间进行高速内存通信的方案；它几乎不占用 CPU 时间、无需占用串口资源，而且速度快到令人惊喜，非常适合用于日志输出、数据查看甚至远程控制；

这篇博客将围绕 SEGGER RTT 展开，介绍简单原理、使用方法、常见配置及注意事项，帮助你在项目中轻松上手 RTT 输出，彻底告别“卡顿的串口 printf”；

RTT简介

什么是RTT

RTT 是 SEGGER 提供的一种 通过调试接口进行双向通信 的机制，所有支持 J-Link 的调试器都可以使用这个功能；它的核心优势在于：

• 高速传输：输出字符速度远超 SWO 和半主机模式；
• 非阻塞：不会影响目标程序的实时执行；
• 无需额外引脚：不依赖 SWO，引脚需求低；

RTT 的传输是通过 SWD 或 JTAG 接口完成的，不需要像传统串口那样占用 UART 资源，也不需要额外的 IO；只要接好 SWDIO、SWCLK（必要时加 VCC 和 NRST），甚至用三线 JLINK-OB 也能正常使用；

多通道+双向通信

RTT 不只是一个 printf 替代品，它支持 多通道双向通信，这意味着你可以像使用多个串口终端一样，将不同类别的日志输出到不同的“虚拟终端”中；

SEGGER 官方提供的工具 RTT Viewer 支持多个终端窗口，可以将标准输出、错误信息、调试日志分流显示，条理清晰，非常适合调试复杂系统；

RTT vs SWO vs 半主机模式

官方做过一组速度测试（以 STM32F407、168MHz 为例）：

可以看出，RTT 不只是快一点，而是快了几个数量级！如果你以前用的是 SWO 或半主机，这种性能差距足以让你考虑迁移到 RTT；

RTT 与硬件兼容性

RTT 不依赖 SWO 引脚，这对大多数小型开发板非常友好；基本上只要你能用 J-Link 下载程序，就能用 RTT 输出调试信息；

而且 RTT 支持多种接口速度的 J-Link 设备；在默认的 512 字节缓冲区配置下，普通速度的 J-Link 也可以跑到 0.5MB/s，高端版甚至可以达到 1MB/s，轻松应对大体量日志输出的需求；

RTT 工作原理简单解析

核心结构

RTT 的核心在于它在目标芯片的 RAM 中创建了一个称为 RTT 控制块（RTT Control Block） 的结构；这个控制块包含：

• 一个 标识符（ID）：用于让 J-Link 调试器能快速在芯片内存中定位这个控制块；
• 多个 通道结构体：每个通道对应一个缓冲区，用来描述缓冲区地址、大小、读写指针等状态信息；

RTT 支持 多个上行通道（Up Buffers） 和 多个下行通道（Down Buffers），即从芯片上传到 PC 端，或者从 PC 发送数据到芯片；这使得 RTT 可以支持例如“标准输出”“错误日志”“调试日志”等多路并行通信；

通道数量和每个缓冲区的大小可以通过编译配置定义，也支持在运行时动态注册新的缓冲区；

数据写入策略

每个 RTT 通道可以配置为阻塞模式或非阻塞模式：

• 阻塞模式：当缓冲区满了，应用程序会等待，直到 J-Link 读出数据腾出空间；这保证了日志不会丢失，但有可能会阻塞当前任务执行；
• 非阻塞模式：当缓冲区满时，多余的数据会直接丢弃，程序继续正常执行；这种模式下，即使调试器没有连接，也不会影响系统实时行为；

缓冲区工作

每个缓冲区本质上是一个环形队列，用一对指针进行数据管理：

• 对于上行通道（芯片 → 主机）：

  • 写入指针由应用程序维护（写入数据）；
  • 读取指针由 J-Link 维护（从芯片读数据）；

• 对于下行通道（主机 → 芯片）：

  • 写入指针由 J-Link 写；
  • 读取指针由芯片读取；

当读取指针和写入指针相等时，说明缓冲区为空；

这种设计方式确保了调试器和芯片之间的同步传输，不需要中断，也不依赖外设，从而最大限度地减少对系统性能的干扰；

RTT移植

准备 RTT 组件

RTT 随 J-Link 工具链一同提供，无需单独下载安装；你可以在默认安装路径下找到 RTT 示例代码，路径如下：

1

C:\Program Files\SEGGER\JLink\Samples\RTT

你可以直接把 RTT 目录下的所有文件打包带入你的工程中；

关于 RTT 汇编加速文件（可选）

新版本 RTT 文件夹中包含一个用于优化的汇编文件（如 SEGGER_RTT_ASM_ARM.S），作用是加速字符输出（通过优化内存访问方式），在高频率大数据量输出时能提高吞吐率；

不过由于不同编译器对汇编支持略有差异，如果你暂时用不上或不清楚用法，也可以先忽略这个文件，不会影响基本使用；

缓冲区大小配置说明

RTT 的配置文件为 SEGGER_RTT_Conf.h，你需要关注三个重要参数：

1
2
3

#define BUFFER_SIZE_UP                        1024  // MCU -> PC
#define BUFFER_SIZE_DOWN                      16    // PC -> MCU
#define SEGGER_RTT_PRINTF_BUFFER_SIZE         64    // 格式化临时缓冲区

默认 BUFFER_SIZE_DOWN 是 16，不能随便改太大，否则 RTT Viewer 不一定能正常接收；

缓冲区选型建议（根据传输频率和单次数据量）：

暴力点来说，大多数项目配置 1024 字节基本是绰绰有余的，除非你是数据刷屏狂魔；

RTT 最小使用代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

#include "SEGGER_RTT.h"

uint8_t RTT_Buffer_R[16] = {0};
uint32_t RTT_Count_R = 0;

int main(void)
{
    SEGGER_RTT_ConfigUpBuffer(0, "RTTUP", NULL, 0, SEGGER_RTT_MODE_NO_BLOCK_SKIP);
    SEGGER_RTT_ConfigDownBuffer(0, "RTTDOWN", NULL, 0, SEGGER_RTT_MODE_NO_BLOCK_SKIP);

    while (1)
    {
        static int i = 0;

        // 设置当前使用的终端为 0
        SEGGER_RTT_SetTerminal(0);
        SEGGER_RTT_printf(0, RTT_CTRL_TEXT_RED"%d\r\n", i++);

        // 设置当前使用的终端为 1
        SEGGER_RTT_SetTerminal(1);
        SEGGER_RTT_printf(0, "%d\r\n", i++);

        // 从 PC 端接收数据，默认最多只能接收 16 字节
        RTT_Count_R = SEGGER_RTT_Read(0, RTT_Buffer_R, 16);
        if (RTT_Count_R)
        {
            RTT_Buffer_R[RTT_Count_R] = '\0';  // 添加字符串终止符
            SEGGER_RTT_printf(0, RTT_CTRL_TEXT_YELLOW"%s\r\n", RTT_Buffer_R);
            RTT_Count_R = 0;
        }
    }
}

说明：

• SEGGER_RTT_SetTerminal(n) 设置的是在哪个虚拟终端窗口显示；
• SEGGER_RTT_printf(0, …) 的第一个参数是 通道编号，默认为 0，固定使用；

注意：虚拟终端编号与通道编号并非一回事，通道编号决定数据流向的通道，而终端编号仅影响在 RTT Viewer 中显示的窗口；

• 接收缓冲区推荐用 16 字节，因为 RTT Viewer 默认一次只支持发送一个字符，除非启用了“Send on Enter”；

使用 J-Link RTT Viewer 工具

打开 J-Link RTT Viewer，选择如下参数：

• Interface：JTAG 或 SWD（视你的硬件连接而定）；
• Speed：建议设置为中等速度，比如 1000kHz，太高可能不稳定；
• 连接不上时：点击菜单 File -> Connect 尝试重连；
• 多终端支持：在工具右下角可以勾选多个终端进行输出区分；
• 输入设置：建议勾选 Send on Enter，这样输入多个字符后按下回车才会发送，方便处理字符串指令；

总结

SEGGER RTT 凭借其高速、非阻塞、零占用外设资源等优势，成为现代嵌入式开发中调试输出的理想方案；相比传统串口、SWO 或半主机模式，RTT 不仅性能更优，还具有更强的灵活性，支持多通道、双向通信，使日志输出更加有序高效；

通过本篇文章的介绍，我们了解了 RTT 的工作原理、配置方式、缓冲策略以及实际使用示例，并结合实际开发场景给出了配置建议；如果你在项目中苦于串口调试带来的性能瓶颈，不妨试试 RTT——它不仅能大幅提升调试效率，还能让你更专注于系统逻辑本身，而不是被调试工具“牵着鼻子走”；

此外，RTT 的下行通道支持从 PC 向目标设备发送数据，这为构建交互式调试终端提供了可能；例如，可以将 Letter Shell 的输入输出绑定到 RTT 通道上，实现无需串口、无需 IO 引脚的 Shell 控制台；配合 RTT Viewer 或自定义串口工具，你可以像操作普通终端一样通过 J-Link 实时操控设备，极大地拓展了嵌入式调试的边界；

未来在配合如 RTT Viewer、JScope、SystemView 等 SEGGER 工具时，RTT 还能拓展出更多实用功能，助力系统分析与性能评估；写代码的时候不卡壳，调试输出更清爽，从一步启用 RTT 开始；

在嵌入式开发中，USB 是一个非常重要的外设接口，它不仅可以用来调试、传输数据，还能为产品增加多样化的功能体验；而如果你希望在一个 USB 接口上同时实现多个设备功能，比如既能当串口调试工具、又能当 U 盘存储设备，甚至还能充当 HID 控制器，那你就需要掌握 USB Composite（复合设备） 的实现方式；

本篇博客将结合前文实现的 FatFS 文件系统功能，进一步介绍如何在 STM32 平台上实现 USB Composite 设备；我们将以 U盘 + 虚拟串口（CDC） 为例，完整讲解如何配置多个接口；通过这一实践，你将掌握一线多用的 USB 技巧，为你的嵌入式设备赋予更多“身份”和可能性；

本文采用了 GitHub 上一个开源项目（I-CUBE-USBD-Composite）作为基础，该项目已经实现了 USB Composite 的关键功能；我们基于它，以简单快捷的方式完成了 U 盘 + CDC 的复合设备实现；

文件下载

AL94.I-CUBE-USBD-COMPOSITE.1.0.3.pack
提取密码: zKxR3

链接中是一个 pack 文件，但是这个文件并不是给 MDK 使用的，而是给 STM32CubeMX 使用的，我们需要在 STM32CubeMX 中导入这个文件，作为组件库引入我们的工程中；

导入文件步骤如下：

工程引入

导入完成之后，我们还需要在 CubeMX 中勾选这个组件库，选择所需的功能 ，如下：

其中，Core 是必须勾选的，如果你要同时使用 CDC 和 U 盘，那么不仅 CDC_ACM 和 MSC_BOT 都需要勾选，而且还必须勾选 COMPISITE,否则 USB Composite 功能将无法正常使用；

在导入组件库之后，我们还需要在 CubeMX 中配置一下 USB 相关的配置，如下：

• 配置 USB 外设的中断，否则 USB 外设将无法正常工作

• 配置组件库

博客使用 F103 作为例子，所以还需要选择最后一项；

代码修改

配置好之后，我们直接使用 CubeMX 生成代码即可，代码中需要修改的地方不多，主要是初始化和对应 USB 功能的逻辑，如下：

引入工程

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#include "usb_device.h"
#include "usbd_cdc_acm_if.h"

int main(void)
{
    ...
    MX_USB_DEVICE_Init();
    ...

    while(1)
    {
        ...
    }
}

功能逻辑

每一个 USB 功能都对应一个文件，比如 CDC 功能对应的是 usbd_cdc_acm_if.c，我们只需要在对应的文件中添加我们需要的逻辑即可，因为在之前的博客中已经实现了 FatFS 文件系统，所以我们今天主要将重点放在 CDC 与 U 盘的处理逻辑上；

CDC 串口

CDC（Communication Device Class）是一种虚拟串口接口，库文件中已经封装好了基本的收发逻辑：发送数据时直接调用发送函数，接收到数据时则会自动调用接收回调函数；

听起来一切都很完美，但这背后其实还隐藏着一个关键问题；

答案是：理解 USB 的传输机制，特别是数据包的处理方式；

USB 在底层按“包（Packet）”传输，CDC 使用的传输类型为 Bulk（批量传输），**每个端点的最大数据包大小（Max Packet Size）**对于全速设备通常为 64 字节；因此，大于 64 字节的数据会被分为多个包发送；这意味着：

• 如果我们发送的数据长度小于等于 64 字节，可以一包发完；
• 如果发送的数据长度大于 64 字节，则需要拆分为多个数据包进行分批发送；

在发送方面，库通常已经封装好了自动拆包的逻辑；我们调用发送函数时，只需要传入需要发送的缓冲区和长度，不必关心包的边界或分段细节；

接收就没那么轻松了；

虽然 USB 主机会自动将数据拆分为多个包发送，但在设备端的接收回调函数中，我们每次只能获取一包数据，这意味着：如果一条完整的数据大于 64 字节，必须手动将这些数据包拼接起来，然后再统一处理；

那么，我们该如何判断数据是否接收完毕？

我的做法是引入了一个“接收超时判断”机制；每当接收到一包数据时，就刷新一次超时计时器；如果在某个预设时间内没有再接收到新的数据包，就说明数据应该已经接收完毕，可以进行处理了（算是串口空闲的简单实现思路）；

这种方法简单实用，特别适合一些非实时、包长度不确定的串口协议；

如果你希望更稳妥地判断数据边界，也可以考虑使用协议头尾、长度字段等方式进行辅助判断；但在简单应用中，“超时判断法”是一个很实用的起点；

头文件 usbd_cdc_acm_if.h 中需要添加以下内容：

1
2
3
4
5
6
7

// 相关宏定义
#define CDC_RX_BUF_SIZE    512   // 缓冲区大小，根据实际需求调整
#define CDC_TIMEOUT_MS     6     // 超过 6ms 没数据，认为一帧结束，结合实际一包发送的时间调整

// 相关函数声明
void process_usb_frame(uint8_t* data, uint16_t len);  // 处理接收到的 USB 数据帧
void check_usb_timeout(void);                         // 检测 USB 接收超时，超时后调用 process_usb_frame

源文件 usbd_cdc_acm_if.c 中需要添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

// 相关变量定义
uint8_t cdc_rx_buffer[CDC_RX_BUF_SIZE];
uint16_t cdc_rx_index = 0;
uint32_t cdc_last_recv_tick = 0;
uint8_t  cdc_receiving = 0;

// 修改 CDC_Receive 函数
static int8_t CDC_Receive(uint8_t cdc_ch, uint8_t *Buf, uint32_t *Len)
{
  /* USER CODE BEGIN 6 */
  // 拼接到总缓冲区
  if(cdc_rx_index + *Len < CDC_RX_BUF_SIZE)
  {
      memcpy(&cdc_rx_buffer[cdc_rx_index], Buf, *Len);
      cdc_rx_index += *Len;
      cdc_last_recv_tick = HAL_GetTick(); // 更新时间戳
      cdc_receiving = 1;
  }
  else
  {
      // 缓冲区溢出，复位
      cdc_rx_index = 0;
      cdc_receiving = 0;
  }

  USBD_CDC_SetRxBuffer(cdc_ch, &hUsbDevice, &Buf[0]);
  USBD_CDC_ReceivePacket(cdc_ch, &hUsbDevice);
  return (USBD_OK);
  /* USER CODE END 6 */
}

// 处理 USB 数据帧
void process_usb_frame(uint8_t* data, uint16_t len)
{
    // 举例：打印字符串帧
    data[len] = '\0'; // 保证以 \0 结尾
    CDC_Transmit(0, data, len);  // 回显
}

// 检测 USB 接收超时
void check_usb_timeout(void)
{
    if(cdc_receiving)
    {
        if(HAL_GetTick() - cdc_last_recv_tick > CDC_TIMEOUT_MS)
        {
            // 超时，处理一帧数据
            process_usb_frame(cdc_rx_buffer, cdc_rx_index);
            cdc_rx_index = 0;
            cdc_receiving = 0;
        }
    }
}

在 main.c 的 while 循环中添加 check_usb_timeout 函数即可；

注意：

• 这套库中的用户代码部分是没有作用的，你每次使用 CubeMX 生成代码都会覆盖掉你写的代码，无论你写在注释部分或者非注释部分，重新生成之后都会消失，所以可以找到 CubeMX 存储的位置，找到库文件，手动修改库文件，这样每次生成的代码都会是有处理逻辑的代码；
  我的存储位置如下，在 C:\Users\EMTime\STM32Cube\Repository\Packs\AL94\I-CUBE-USBD-COMPOSITE\1.0.3\Middlewares\Third_Party\COMPOSITE\App 中即可找到对应的文件，打开进行修改即可；
  放心，USB 的逻辑部分不像别的代码一样需要频繁修改，你写好之后，大部分情况可以直接使用；

注意：虽然虚拟串口数量可以在 CubeMX 中配置，但由于 I-CUBE-USBD-COMPOSITE 库在生成代码时会覆盖相关配置，这项设置在实际工程中并不会生效；真正起作用的是头文件 AL94.I-CUBE-USBD-COMPOSITE_conf.h 中的 _USBD_CDC_ACM_COUNT 宏定义，该值才是决定虚拟串口个数的关键参数；

MSC U盘

因为之前已经实现了 FatFS 文件系统，所以关于文件系统的部分不过多赘述，USB 模拟 U 盘仅需实现 usbd_msc_if.c 中下面几个函数即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

int8_t STORAGE_GetCapacity(uint8_t lun, uint32_t *block_num, uint16_t *block_size)
{
  /* USER CODE BEGIN 3 */

  // 如果使用我之前博客中提供的代码，则这里可以不用自己计算扇区数和扇区大小，和我写一样的即可

  // 总扇区数，和存储容量有关，扇区数 = 总容量 / 每个扇区大小，比如 16MB SPI Flash 的扇区数 = 16M / 4096 = 16 * 1024 * 1024 / 4096 = 4096，那么这里就是4096
  *block_num  = Flash_Sector_Count;

  // 每个扇区大小，和存储类型有关，如果是 SPI FLash，则是 4096，如果是内部 FLash 或者 SD 卡，则是 512
  *block_size = Flash_Sector_Size;

  return (USBD_OK);
  /* USER CODE END 3 */
}

int8_t STORAGE_Read(uint8_t lun, uint8_t *buf, uint32_t blk_addr, uint16_t blk_len)
{
  /* USER CODE BEGIN 6 */

  // 我之前博客中提供的读取函数如下所示，改成你自己的即可
  FLASH_RD_Block_Start(blk_addr * 4096);
  FLASH_RD_Block(buf, blk_len * 4096);
  FLASH_RD_Block_End();

  return (USBD_OK);
  /* USER CODE END 6 */
}

int8_t STORAGE_Write(uint8_t lun, uint8_t *buf, uint32_t blk_addr, uint16_t blk_len)
{
  /* USER CODE BEGIN 7 */

  for (uint16_t i = 0; i < blk_len; i++)
  {
    FLASH_Erase_Sector((blk_addr + i) * 4096);
  }

  W25XXX_WR_Block((uint8_t*)buf, blk_addr * 4096, blk_len * 4096);

  return (USBD_OK);
  /* USER CODE END 7 */
}

注意：除了和前面一样的，需要自己手动去修改库文件之外，最好把 uint8_t MSC_Storage[321024]; 这个变量也删除掉，因为默认库中分配了 uint8_t MSC_Storage[321024]; 作为虚拟存储使用，但我们使用了外部存储器（如 SPI Flash），该数组将不再使用，建议释放该部分内存资源；

至此，我们已经成功实现了一个包含 CDC 和 USB 存储的复合设备功能；如果你掌握了这部分内容，就可以自由组合 HID、Audio、WebUSB 等模块，为你的嵌入式项目打造更加丰富的功能形态；

总结

这篇文章带你一步步实现了一个“多合一”的 USB 设备，让一个 USB 接口同时具备虚拟串口（CDC）和 U 盘（MSC）的功能；我们从组件库的导入、CubeMX 的配置，到代码逻辑的修改与实现，完整搭建了一个 USB Composite 设备的基础框架；

在过程中，你了解了 USB 是如何以数据包方式传输信息的，也学到了接收多包数据时如何“拼接”数据，以及如何判断一帧数据是否接收完成；通过简单的“超时判断”方法，我们就能实现比较可靠的数据处理逻辑；

另外，我们还结合了之前写好的 FatFS 文件系统，让 MCU 成功模拟出一个能读写的 U 盘，这对实际项目开发很有帮助；

掌握了这些内容之后，你就可以继续添加更多 USB 功能，比如 HID 键盘、音频设备，甚至是 WebUSB，让你的设备功能更加丰富；

如果你是第一次接触 USB Composite，这篇文章可以作为一个很好的起点；希望这次的实践能帮你打下基础，也欢迎你把这些经验应用到自己的项目中，做出更多好玩的嵌入式设备！

当你用单片机做项目，代码调试靠串口、数据记录靠看屏幕、文件读写靠想象，久而久之，你会发现：没有文件系统，生活就像裸奔，哪都能跑，就是不太方便；

尤其是在一些需要长时间运行、持续采集数据的应用场景中，比如环境监测、设备日志记录、传感器数据采集等，如果没有一个可靠的文件系统来进行数据持久化存储，不仅开发调试麻烦，维护和升级也会变得困难重重；你总不能每次都靠串口打印几十KB甚至几MB的数据吧？

这时候你可能听说了一个神器：FatFS，一个轻量级的 FAT 文件系统，专为嵌入式系统设计，小巧灵活，支持 SD 卡、SPI Flash，甚至 RAMDisk；不论你用的是 STM32、GD32，还是别的 MCU 平台，都能把它“嫁接”过去；

有了文件系统，不仅可以更方便地与电脑共享数据（比如通过 U 盘或 SD 卡读取设备日志），还能按时间归档、分类管理信息，甚至在设备意外断电或异常重启时保留关键数据，提升项目的健壮性和专业程度；

那么，这篇文章就是来讲一讲：如何在你的单片机上，成功移植 FatFS，让你的 MCU 拥有读写文件的能力；

FatFS 移植流程概览

FatFS 的移植主要包括以下几个步骤：

1. 准备底层存储驱动（如 SPI Flash 驱动）
2. 实现 FatFS 所需的 diskio.c 接口函数
3. 配置 ffconf.h 以满足你的文件系统需求
4. 在主函数中初始化 FatFS，挂载文件系统
5. 实现文件的读写操作测试

接下来，我们从第一步开始，移植 SPI Flash 驱动；

FatFS 文件系统移植到 SPI Flash

要让 FatFS 在单片机上正常工作，首先你得有一个“存储设备”能读能写；虽然 SD 卡是最常见的选择，但很多时候，SPI Flash 是更方便的一种方式：不需要外接卡座、不怕接触不良，容量也够用；

对应的驱动文件如下，将文件添加到你的工程中，驱动文件来自沁恒例程，做了一点点的补充与修改：

W25Qxx.c

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398