Hexo

ThingsBoard Docker 部署指南

2025-06-21T07:48:24.000Z

官网：https://thingsboard.io
参考：http://www.ithingsboard.com/docs/user-guide/attributes

应朋友的要求，写一篇关于 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

在文件中添加：

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 命令完成：

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 的登录界面；

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

角色	用户名	密码
系统管理员	sysadmin@thingsboard.org	sysadmin
租户管理员	tenant@thingsboard.org	tenant
客户用户（演示）	customer@thingsboard.org	customer

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

ThingsBoard 使用

添加设备

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

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

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

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

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

测试设备

连接平台

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

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

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

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

属性类型	来源方向	设备是否可写	平台是否可写	是否自动推送到设备	描述
客户端属性	设备 → 平台	✅ 是	✅ 可初始化（仅首次）	❌ 否	设备主动上报的信息，例如设备型号、固件版本、运行状态，平台只做查看，不会主动推送
服务端属性	平台 → 平台侧应用	❌ 否	✅ 是	❌ 否	平台保存的属性集合，设备无法获取
共享属性	平台 → 设备	❌ 否	✅ 是	✅ 是	平台设置的共享配置项，支持平台→设备自动推送，也可由设备主动请求（如目标温度、模式等）
最新属性值（概念）	双向	✅ 是	✅ 是	❌ 否（需主动查询）	并非单独属性类型，而是平台维护的当前属性快照，用于展示或通过 API 获取

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

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

服务端属性

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

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

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

获取 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 令牌，返回示例如下（返回的信息比较长，注意仔细比对）：

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

获取设备服务端属性

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

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，返回结果如下；

[
    {
        "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 工具模拟设备，向平台发布一条消息，如下：

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

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

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

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

设备从平台获取数据

设备可以主动请求平台侧的客户端属性，请求主题为 v1/devices/me/attributes/request/，其中是请求 ID，可以任意指定，订阅主题可以是 v1/devices/me/attributes/request/ 或者 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/+ 中会得到从平台返回的数据，如下：

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

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

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

平台侧应用获取数据

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

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 即可，运行之后结果如下：

[
    {
        "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/，其中是请求 ID，可以任意指定，订阅主题可以是 v1/devices/me/attributes/request/ 或者 v1/devices/me/attributes/response/+，发送的数据如下：

1
2
3

{
  "sharedKeys": "test"
}

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

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

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

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

属性修改/变动自动推送

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

增和改

1
2
3

{
  "test": "2"
}

{
  "deleted": [
    "test"
  ]
}

平台侧应用获取数据

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

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 能为你提供一个清晰的起点；

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

悲报

2025-05-17T05:51:27.000Z

硬盘坏了，数据全没了；
在慢慢恢复数据了，但是大部分应该是很难恢复了；

使用Hexo搭建个人博客

2025-02-22T01:47:18.000Z

在信息过载的时代，拥有一个属于自己的博客，不仅能整理思路、沉淀经验，还能在需要时快速复用曾经解决过的问题；而 Hexo，作为一款基于 Node.js 的轻量静态博客框架，以其部署简单、主题丰富、生成速度快的优势，成为了许多开发者的首选；

我最开始只是想记录一下技术笔记，后来发现 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

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

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 文章）：

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；

那么配置大体如下：

[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 优化功能，但可以通过插件实现；

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

通过 init 系统实现开机自启（以 systemd 和 OpenRC 为例）

2025-02-12T09:10:28.000Z

在 Linux 系统中，“开机自启” 是我们几乎绕不开的一个话题：不管是启动一个自建的服务、挂载硬盘、跑一个守护进程，还是让脚本在系统启动后自动运行，归根结底都依赖系统使用的 init 系统；

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

有人说往 /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 这样的命名方式，便于识别和管理；

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

[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 可用于无条件重启；

启用服务

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

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

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

# 设置开机自启
sudo systemctl enable frps

服务运行管理

# 查看服务状态
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

内容如下所示：

#!/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

管理服务

# 启动服务
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 了，那已经是“老黄历”了）；

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

SEGGER RTT：嵌入式调试的高效输出利器

2024-10-27T17:18:07.000Z

参考：https://www.armbbs.cn/forum.php?mod=viewthread&tid=86177

在嵌入式开发中，如何在不影响系统实时性的前提下，高效输出调试信息，一直是让人头疼的问题；传统的串口 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 为例）：

方式	输出82字符耗时
RTT	1us
SWO	120μs
半主机模式	10700μs

可以看出，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 不一定能正常接收；

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

情况	建议缓冲区大小
每秒发送 10 次 × 每次 1 字节	6 字节
每次 2 字节	11 字节
每次 5 字节	31 字节
每次 10 字节	61 字节
每次 50 字节	401 字节
每秒发送 1 次 × 每次 500 字节	501 字节

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

RTT 最小使用代码

#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 Composite 设备：在同一接口上模拟多个设备（含 FatFS U盘）

2024-10-27T01:41:19.000Z

仓库：https://github.com/alambe94/I-CUBE-USBD-Composite
参考：https://blog.csdn.net/u012936480/article/details/137411833

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

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

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

文件下载

链接: https://pan.baidu.com/s/10a2SehxSUwr8pd7I2zs45w?pwd=dbtc 提取码: dbtc

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

导入文件步骤如下：

工程引入

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

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

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

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

配置组件库

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

代码修改

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

引入工程

#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 中需要添加以下内容：

// 相关宏定义
#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 中需要添加以下内容：

// 相关变量定义
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 中下面几个函数即可：

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，这篇文章可以作为一个很好的起点；希望这次的实践能帮你打下基础，也欢迎你把这些经验应用到自己的项目中，做出更多好玩的嵌入式设备！

从 0 搭建 SPI Flash 文件系统：驱动、FatFS、读写与坑点

2024-10-26T15:15:07.000Z

FatFS官网：https://elm-chan.org/fsw/ff/00index_e.html

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

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

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

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

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

FatFS 移植流程概览

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

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

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

FatFS 文件系统移植到 SPI Flash

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

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

spi_flash.c

#include "spi_flash.h"

volatile uint8_t  Flash_Type         = 0x00; /* FLASH chip: 0: W25XXXseries */
volatile uint32_t Flash_ID           = 0x00; /* FLASH ID */
volatile uint32_t Flash_Sector_Count = 0x00; /* FLASH sector number */
volatile uint16_t Flash_Sector_Size  = 0x00; /* FLASH sector size */

/*******************************************************************************
 * Function Name  : SPI_FLASH_SendByte
 * Description    : SPI send a byte
 * Input          : byte: byte to send
 * Output         : None
 * Return         : None
 *******************************************************************************/
uint8_t SPI_FLASH_SendByte (uint8_t byte)
{
  return User_SPI1_ReadWriteByte (byte);
}

/*******************************************************************************
 * Function Name  : SPI_FLASH_ReadByte
 * Description    : SPI receive a byte
 * Input          : None
 * Output         : None
 * Return         : byte received
 *******************************************************************************/
uint8_t SPI_FLASH_ReadByte (void)
{
  return User_SPI1_ReadWriteByte (0xFF);
}

/*******************************************************************************
 * Function Name  : FLASH_ReadID
 * Description    : Read FLASH ID
 * Input          : None
 * Output         : None
 * Return         : chip id
 *******************************************************************************/
uint32_t FLASH_ReadID (void)
{
  uint32_t dat;
  PIN_FLASH_CS_LOW();
  SPI_FLASH_SendByte (CMD_FLASH_JEDEC_ID);
  dat = (uint32_t)SPI_FLASH_SendByte (DEF_DUMMY_BYTE) << 16;
  dat |= (uint32_t)SPI_FLASH_SendByte (DEF_DUMMY_BYTE) << 8;
  dat |= SPI_FLASH_SendByte (DEF_DUMMY_BYTE);
  PIN_FLASH_CS_HIGH();
  return (dat);
}

/*******************************************************************************
 * Function Name  : FLASH_WriteEnable
 * Description    : FLASH Write Enable
 * Input          : None
 * Output         : None
 * Return         : None
 *******************************************************************************/
void FLASH_WriteEnable (void)
{
  PIN_FLASH_CS_LOW();
  SPI_FLASH_SendByte (CMD_FLASH_WREN);
  PIN_FLASH_CS_HIGH();
}

/*******************************************************************************
 * Function Name  : FLASH_WriteDisable
 * Description    : FLASH Write Disable
 * Input          : None
 * Output         : None
 * Return         : None
 *******************************************************************************/
void FLASH_WriteDisable (void)
{
  PIN_FLASH_CS_LOW();
  SPI_FLASH_SendByte (CMD_FLASH_WRDI);
  PIN_FLASH_CS_HIGH();
}

/*******************************************************************************
 * Function Name  : FLASH_ReadStatusReg
 * Description    : FLASH Read Status
 * Input          : None
 * Output         : None
 * Return         : status
 *******************************************************************************/
uint8_t FLASH_ReadStatusReg (void)
{
  uint8_t status;

  PIN_FLASH_CS_LOW();
  SPI_FLASH_SendByte (CMD_FLASH_RDSR);
  status = SPI_FLASH_ReadByte();
  PIN_FLASH_CS_HIGH();
  return (status);
}

/*******************************************************************************
 * Function Name  : FLASH_Erase_Sector
 * Description    : FLASH Erase Sector
 * Input          : None
 * Output         : None
 * Return         : None
 *******************************************************************************/
void FLASH_Erase_Sector (uint32_t address)
{
  uint8_t temp;
  FLASH_WriteEnable();
  PIN_FLASH_CS_LOW();
  SPI_FLASH_SendByte (CMD_FLASH_SECTOR_ERASE);
  SPI_FLASH_SendByte ((uint8_t)(address >> 16));
  SPI_FLASH_SendByte ((uint8_t)(address >> 8));
  SPI_FLASH_SendByte ((uint8_t)address);
  PIN_FLASH_CS_HIGH();
  do
  {
    temp = FLASH_ReadStatusReg();
  } while (temp & 0x01);
}

/*******************************************************************************
 * Function Name  : FLASH_RD_Block_Start
 * Description    : FLASH start block read
 * Input          : None
 * Output         : None
 * Return         : None
 *******************************************************************************/
void FLASH_RD_Block_Start (uint32_t address)
{
  PIN_FLASH_CS_LOW();
  SPI_FLASH_SendByte (CMD_FLASH_READ);
  SPI_FLASH_SendByte ((uint8_t)(address >> 16));
  SPI_FLASH_SendByte ((uint8_t)(address >> 8));
  SPI_FLASH_SendByte ((uint8_t)address);
}

/*******************************************************************************
 * Function Name  : FLASH_RD_Block
 * Description    : FLASH read block
 * Input          : None
 * Output         : None
 * Return         : None
 *******************************************************************************/
void FLASH_RD_Block (uint8_t *pbuf, uint32_t len)
{
  while (len--)
  {
    *pbuf++ = SPI_FLASH_ReadByte();
  }
}

/*******************************************************************************
 * Function Name  : FLASH_RD_Block_End
 * Description    : FLASH end block read
 * Input          : None
 * Output         : None
 * Return         : None
 *******************************************************************************/
void FLASH_RD_Block_End (void)
{
  PIN_FLASH_CS_HIGH();
}

/*******************************************************************************
 * Function Name  : W25XXX_WR_Page
 * Description    : Flash page program
 * Input          : address
 *                  len
 *                  *pbuf
 * Output         : None
 * Return         : None
 *******************************************************************************/
void W25XXX_WR_Page (uint8_t *pbuf, uint32_t address, uint32_t len)
{
  uint8_t temp;
  FLASH_WriteEnable();
  PIN_FLASH_CS_LOW();
  SPI_FLASH_SendByte (CMD_FLASH_BYTE_PROG);
  SPI_FLASH_SendByte ((uint8_t)(address >> 16));
  SPI_FLASH_SendByte ((uint8_t)(address >> 8));
  SPI_FLASH_SendByte ((uint8_t)address);
  if (len > SPI_FLASH_PerWritePageSize)
  {
    len = SPI_FLASH_PerWritePageSize;
  }
  while (len--)
  {
    SPI_FLASH_SendByte (*pbuf++);
  }
  PIN_FLASH_CS_HIGH();
  do
  {
    temp = FLASH_ReadStatusReg();
  } while (temp & 0x01);
}

/*******************************************************************************
 * Function Name  : W25XXX_WR_Block
 * Description    : W25XXX block write
 * Input          : address
 *                  len
 *                  *pbuf
 * Output         : None
 * Return         : None
 *******************************************************************************/
void W25XXX_WR_Block (uint8_t *pbuf, uint32_t address, uint32_t len)
{
  uint8_t NumOfPage = 0, NumOfSingle = 0, Addr = 0, count = 0, temp = 0;

  Addr        = address % SPI_FLASH_PageSize;
  count       = SPI_FLASH_PageSize - Addr;
  NumOfPage   = len / SPI_FLASH_PageSize;
  NumOfSingle = len % SPI_FLASH_PageSize;

  if (Addr == 0)
  {
    if (NumOfPage == 0)
    {
      W25XXX_WR_Page (pbuf, address, len);
    }
    else
    {
      while (NumOfPage--)
      {
        W25XXX_WR_Page (pbuf, address, SPI_FLASH_PageSize);
        address += SPI_FLASH_PageSize;
        pbuf += SPI_FLASH_PageSize;
      }
      W25XXX_WR_Page (pbuf, address, NumOfSingle);
    }
  }
  else
  {
    if (NumOfPage == 0)
    {
      if (NumOfSingle > count)
      {
        temp = NumOfSingle - count;
        W25XXX_WR_Page (pbuf, address, count);
        address += count;
        pbuf += count;
        W25XXX_WR_Page (pbuf, address, temp);
      }
      else
      {
        W25XXX_WR_Page (pbuf, address, len);
      }
    }
    else
    {
      len -= count;
      NumOfPage   = len / SPI_FLASH_PageSize;
      NumOfSingle = len % SPI_FLASH_PageSize;
      W25XXX_WR_Page (pbuf, address, count);
      address += count;
      pbuf += count;
      while (NumOfPage--)
      {
        W25XXX_WR_Page (pbuf, address, SPI_FLASH_PageSize);
        address += SPI_FLASH_PageSize;
        pbuf += SPI_FLASH_PageSize;
      }
      if (NumOfSingle != 0)
      {
        W25XXX_WR_Page (pbuf, address, NumOfSingle);
      }
    }
  }
}

/*******************************************************************************
 * Function Name  : FLASH_IC_Check
 * Description    : check flash type
 * Input          : None
 * Output         : None
 * Return         : None
 *******************************************************************************/
void FLASH_IC_Check (void)
{
  uint32_t count;

  /* Read FLASH ID */
  Flash_ID = FLASH_ReadID();
//  printf ("Flash_ID: %08x\n", (uint32_t)Flash_ID);

  Flash_Type         = 0x00;
  Flash_Sector_Count = 0x00;
  Flash_Sector_Size  = 0x00;

  switch (Flash_ID)
  {
    /* W25XXX */
    case W25X10_FLASH_ID: /* 0xEF3011-----1M bit */
      count = 1;
      break;

    case W25X20_FLASH_ID: /* 0xEF3012-----2M bit */
      count = 2;
      break;

    case W25X40_FLASH_ID: /* 0xEF3013-----4M bit */
      count = 4;
      break;

    case W25X80_FLASH_ID: /* 0xEF4014-----8M bit */
      count = 8;
      break;

    case W25Q16_FLASH_ID1: /* 0xEF3015-----16M bit */
    case W25Q16_FLASH_ID2: /* 0xEF4015-----16M bit */
      count = 16;
      break;

    case W25Q32_FLASH_ID1: /* 0xEF4016-----32M bit */
    case W25Q32_FLASH_ID2: /* 0xEF6016-----32M bit */
      count = 32;
      break;

    case W25Q64_FLASH_ID1: /* 0xEF4017-----64M bit */
    case W25Q64_FLASH_ID2: /* 0xEF6017-----64M bit */
      count = 64;
      break;

    case W25Q128_FLASH_ID1: /* 0xEF4018-----128M bit */
    case W25Q128_FLASH_ID2: /* 0xEF6018-----128M bit */
      count = 128;
      break;

    case W25Q256_FLASH_ID1: /* 0xEF4019-----256M bit */
    case W25Q256_FLASH_ID2: /* 0xEF6019-----256M bit */
      count = 256;
      break;
    default:
      if ((Flash_ID != 0xFFFFFFFF) && (Flash_ID != 0x00000000))
      {
        count = 16;
      }
      else
      {
        count = 0x00;
      }
      break;
  }
  count = ((uint32_t)count * 1024) * ((uint32_t)1024 / 8);

  if (count)
  {
    // 如果是内部,那么DEF_UDISK_SECTOR_SIZE是512,如果是外部,则DEF_SECTOR_SIZE是4096
    Flash_Sector_Count = count / DEF_SECTOR_SIZE; // DEF_SECTOR_SIZE;
    Flash_Sector_Size  = DEF_SECTOR_SIZE;         // DEF_SECTOR_SIZE;
//    printf ("\r\nFlash_Sector_Count:%d\r\n", Flash_Sector_Count);
//    printf ("Flash_Sector_Size:%d\r\n", Flash_Sector_Size);
  }
  else
  {
//    printf ("External Flash not connected\r\n");
    //  while(1);
  }
}

/*******************************************************************************
 * Function Name  : FLASH_Init
 * Description    : init spi flash
 * Input          : None
 * Output         : None
 * Return         : status
 *******************************************************************************/
uint8_t FLASH_Init(void)
{
  PIN_FLASH_CS_LOW();

  SPI_FLASH_SendByte(CMD_FLASH_RESET_ENABLE);
  SPI_FLASH_SendByte(CMD_FLASH_RESET_MEMORY);

  PIN_FLASH_CS_HIGH();

  FLASH_IC_Check();

  return FLASH_ReadStatusReg();
}

spi_flash.h

#ifndef _SPI_FLASH_H_
#define _SPI_FLASH_H_

#include "spi.h"

/* SPI Pins */
#define PIN_FLASH_CS_LOW()  SPI1_CS_LOW()

#define PIN_FLASH_CS_HIGH() SPI1_CS_HIGH()

/******************************************************************************/
/* SPI Serial Flash OPERATION INSTRUCTIONS */
#define CMD_FLASH_READ 0x03         /* Read Memory at 25 MHz */
#define CMD_FLASH_SECTOR_ERASE 0x20 /* Erase 4 KByte of memory array */
#define CMD_FLASH_BYTE_PROG 0x02    /* To Program One Data Byte */
#define CMD_FLASH_RDSR 0x05         /* Read-Status-Register */
#define CMD_FLASH_EWSR 0x50         /* Enable-Write-Status-Register */
#define CMD_FLASH_WREN 0x06         /* Write-Enable */
#define CMD_FLASH_WRDI 0x04         /* Write-Disable */
#define CMD_FLASH_JEDEC_ID 0x9F     /* JEDEC ID read */

#define CMD_FLASH_RESET_ENABLE  0x66
#define CMD_FLASH_RESET_MEMORY  0x99

/******************************************************************************/
#define DEF_DUMMY_BYTE 0xFF

/******************************************************************************/
/* FLASH Parameter Definition */
#define SPI_FLASH_SectorSize 4096
#define SPI_FLASH_PageSize 256
#define SPI_FLASH_PerWritePageSize 256

/******************************************************************************/
/* SPI FLASH Type */
#define DEF_TYPE_W25XXX 0 /* W25XXX */

#define DEF_SECTOR_SIZE 4096

/* SPI FLASH STATUS */
#define SPI_FLASH_OK            ((uint8_t)0x00)
#define SPI_FLASH_ERROR         ((uint8_t)0x01)
#define SPI_FLASH_BUSY          ((uint8_t)0x02)
#define SPI_FLASH_TIMEOUT       ((uint8_t)0x03)

/******************************************************************************/
/* SPI FLASH Type Define */

/* W25XXX*/
#define W25X10_FLASH_ID 0xEF3011   /* 1M bit */
#define W25X20_FLASH_ID 0xEF3012   /* 2M bit */
#define W25X40_FLASH_ID 0xEF3013   /* 4M bit */
#define W25X80_FLASH_ID 0xEF4014   /* 8M bit */
#define W25Q16_FLASH_ID1 0xEF3015  /* 16M bit */
#define W25Q16_FLASH_ID2 0xEF4015  /* 16M bit */
#define W25Q32_FLASH_ID1 0xEF4016  /* 32M bit */
#define W25Q32_FLASH_ID2 0xEF6016  /* 32M bit */
#define W25Q64_FLASH_ID1 0xEF4017  /* 64M bit */
#define W25Q64_FLASH_ID2 0xEF6017  /* 64M bit */
#define W25Q128_FLASH_ID1 0xEF4018 /* 128M bit */
#define W25Q128_FLASH_ID2 0xEF6018 /* 128M bit */
#define W25Q256_FLASH_ID1 0xEF4019 /* 256M bit */
#define W25Q256_FLASH_ID2 0xEF6019 /* 256M bit */

/******************************************************************************/
/* Variable Definition */
extern volatile uint8_t Flash_Type;          /* FLASH chip: 0: W25XXXseries   */
extern volatile uint32_t Flash_ID;           /* FLASH ID */
extern volatile uint32_t Flash_Sector_Count; /* FLASH sector number */
extern volatile uint16_t Flash_Sector_Size;  /* FLASH sector size */

/******************************************************************************/
/* external functions */
extern uint8_t FLASH_Init(void);
extern uint8_t SPI_FLASH_SendByte (uint8_t byte);
extern uint8_t SPI_FLASH_ReadByte (void);
extern uint32_t FLASH_ReadID (void);
extern void FLASH_WriteEnable (void);
extern void FLASH_WriteDisable (void);
extern uint8_t FLASH_ReadStatusReg (void);
extern void FLASH_IC_Check (void);
extern void FLASH_Erase_Sector (uint32_t address);
extern void FLASH_RD_Block_Start (uint32_t address);
extern void FLASH_RD_Block (uint8_t *pbuf, uint32_t len);
extern void FLASH_RD_Block_End (void);
extern void W25XXX_WR_Block (uint8_t *pbuf, uint32_t address, uint32_t len);

#endif /* _SPI_FLASH_H_ */

该驱动程序在SPI1上实现了对SPI FLASH的读写操作，包括初始化、读取ID、写入使能、写入禁用、读取状态寄存器、检查IC、擦除扇区、读取块、写入块等操作；

程序中涉及的 User_SPI1_ReadWriteByte 定义如下：

uint8_t User_SPI1_ReadWriteByte(uint8_t TxData)
{
  uint8_t RxData = 0;

  HAL_SPI_TransmitReceive(&hspi1, &TxData, &RxData, 1, 0xFFFF);

  return RxData;
}

片选线的控制函数定义如下：

#define SPI1_CS_LOW() do \
{ \
  HAL_GPIO_WritePin(SPI1_CS_GPIO_Port, SPI1_CS_Pin, GPIO_PIN_RESET); \
} \
while(0)

#define SPI1_CS_HIGH() do \
{ \
  HAL_GPIO_WritePin(SPI1_CS_GPIO_Port, SPI1_CS_Pin, GPIO_PIN_SET); \
} \
while(0)

执行FLASH_IC_Check函数之后，函数会根据返回的芯片 ID，设置Flash_Type、Flash_ID、Flash_Sector_Count、Flash_Sector_Size等变量，以便后续操作使用；

移植 FatFS

实现 diskio.c 接口

主要就是需要编写 diskio.c 文件，实现以下函数（可以直接复制）：

/*-----------------------------------------------------------------------*/
/* Low level disk I/O module SKELETON for FatFs     (C)ChaN, 2019        */
/*-----------------------------------------------------------------------*/
/* If a working storage control module is available, it should be        */
/* attached to the FatFs via a glue function rather than modifying it.   */
/* This is an example of glue functions to attach various exsisting      */
/* storage control modules to the FatFs module with a defined API.       */
/*-----------------------------------------------------------------------*/

#include "ff.h"/* Obtains integer types */
#include "diskio.h"/* Declarations of disk functions */

#include "spi_flash.h"

/* Definitions of physical drive number for each drive */
//#define DEV_RAM0/* Example: Map Ramdisk to physical drive 0 */
//#define DEV_MMC1/* Example: Map MMC/SD card to physical drive 1 */
//#define DEV_USB2/* Example: Map USB MSD to physical drive 2 */
#define DEV_SPIFLASH 0

/*-----------------------------------------------------------------------*/
/* Get Drive Status                                                      */
/*-----------------------------------------------------------------------*/

DSTATUS disk_status(
  BYTE pdrv/* Physical drive nmuber to identify the drive */
)
{
  DSTATUS stat;
  uint8_t result;

  switch(pdrv)
  {
  case DEV_SPIFLASH :
    result = FLASH_ReadStatusReg();

    // translate the reslut code here
    switch(result)
    {
    case SPI_FLASH_OK:
      stat = STA_NOINIT & (~STA_NOINIT);
      break;

    case SPI_FLASH_ERROR:
      stat = STA_NOINIT;
      break;

    case SPI_FLASH_BUSY:
      stat = STA_NOINIT;
      break;

    case SPI_FLASH_TIMEOUT:
      stat = STA_NOINIT;
      break;
    }
    return stat;

  }
  return STA_NOINIT;
}



/*-----------------------------------------------------------------------*/
/* Inidialize a Drive                                                    */
/*-----------------------------------------------------------------------*/

DSTATUS disk_initialize(
  BYTE pdrv/* Physical drive nmuber to identify the drive */
)
{
  DSTATUS stat;
  uint8_t result;

  switch(pdrv)
  {
  case DEV_SPIFLASH :
    result = FLASH_Init();

    // translate the reslut code here
    switch(result)
    {
    case SPI_FLASH_OK:
      stat = STA_NOINIT & (~STA_NOINIT);
      break;

    case SPI_FLASH_ERROR:
      stat = STA_NOINIT;
      break;

    case SPI_FLASH_BUSY:
      stat = STA_NOINIT;
      break;

    case SPI_FLASH_TIMEOUT:
      stat = STA_NOINIT;
      break;
    }
    return stat;

  }
  return STA_NOINIT;
}

/*-----------------------------------------------------------------------*/
/* Read Sector(s)                                                        */
/*-----------------------------------------------------------------------*/

DRESULT disk_read(
  BYTE pdrv,/* Physical drive nmuber to identify the drive */
  BYTE* buff,/* Data buffer to store read data */
  LBA_t sector,/* Start sector in LBA */
  UINT count/* Number of sectors to read */
)
{
  DRESULT res;
  uint8_t result;

  switch(pdrv)
  {
  case DEV_SPIFLASH :
    // translate the arguments here

    FLASH_RD_Block_Start(sector * 4096);
    FLASH_RD_Block(buff, count * 4096);
    FLASH_RD_Block_End();

    result = FLASH_ReadStatusReg();

    // translate the reslut code here
    switch(result)
    {
    case SPI_FLASH_OK:
      res = RES_OK;
      break;

    case SPI_FLASH_ERROR:
      res = RES_ERROR;
      break;

    case SPI_FLASH_BUSY:
      res = RES_NOTRDY;
      break;

    case SPI_FLASH_TIMEOUT:
      res = RES_ERROR;
      break;
    }
    return res;

  }

  return RES_PARERR;
}

/*-----------------------------------------------------------------------*/
/* Write Sector(s)                                                       */
/*-----------------------------------------------------------------------*/

#if FF_FS_READONLY == 0

DRESULT disk_write(
  BYTE pdrv,/* Physical drive nmuber to identify the drive */
  const BYTE* buff,/* Data to be written */
  LBA_t sector,/* Start sector in LBA */
  UINT count/* Number of sectors to write */
)
{
  DRESULT res;
  int result;

  switch(pdrv)
  {
  case DEV_SPIFLASH :
    // translate the arguments here

    for (UINT i = 0; i < count; i++)
    {
      FLASH_Erase_Sector((sector + i) * 4096);
    }
    W25XXX_WR_Block((uint8_t*)buff, sector * 4096, count * 4096);
    result = FLASH_ReadStatusReg();

    // translate the reslut code here
    switch(result)
    {
    case SPI_FLASH_OK:
      res = RES_OK;
      break;

    case SPI_FLASH_ERROR:
      res = RES_ERROR;
      break;

    case SPI_FLASH_BUSY:
      res = RES_NOTRDY;
      break;

    case SPI_FLASH_TIMEOUT:
      res = RES_ERROR;
      break;
    }
    return res;

  }

  return RES_PARERR;
}

#endif

/*-----------------------------------------------------------------------*/
/* Miscellaneous Functions                                               */
/*-----------------------------------------------------------------------*/

DRESULT disk_ioctl(
  BYTE pdrv,/* Physical drive nmuber (0..) */
  BYTE cmd,/* Control code */
  void* buff/* Buffer to send/receive control data */
)
{
  DRESULT res = RES_OK;
//  int result;

  switch(pdrv)
  {
  case DEV_SPIFLASH :
    switch(cmd)
    {
    case GET_SECTOR_COUNT://将驱动器上可用扇区的数目返回到buff指向的DWORD变量中
    {
      /* 扇区数量：1536*4096/1024/1024=6(MB) */
      *(DWORD*)buff = Flash_Sector_Count; // 1536; //要的是DWORD类型的数据,所以给这个形参返回这样的数据
      break;
    }
    case GET_SECTOR_SIZE://将媒体的扇区大小返回到buff指向的WORD变量中
    {
      *(WORD*)buff = Flash_Sector_Size; //类型是WORD的类型,每个扇区是4096的大小,这里同时还需要修改MAX_SS的值
      break;
    }
    case GET_BLOCK_SIZE://将闪存介质的擦除块大小(以扇区为单位)返回到buff指向的DWORD变量中
    {
      *(DWORD*)buff = 1; //每次擦除的大小是1个扇区,因为单位是扇区
      break;
    }
    }
    // Process of the command for the RAM drive

    return res;

  }

  return RES_PARERR;
}

修改 ffconf.h 配置

#define FF_MAX_SS4096  // 使用的是SPI FLash,所以这个需要修改为4096

#define FF_USE_MKFS1     // 这个需要修改为1启用格式化的功能

#define FF_CODE_PAGE936   // 可以设置成936,增加对中文的支持

#define FF_FS_NORTC1     // 这个需要设置成1,就是先不搞RTC相关的日期功能

使用

main.c 文件中大体如下操作即可

#include "ff.h"

FATFS FsObject;

FIL fp;

static BYTE work_buffer[4096];

int main(void)
{
  FRESULT result;
  result=f_mount(&FsObject,"0:",1); // 这个0:就是路径,和#define FF_VOLUMES 1有关,设定为1则路径只有0:

  // 如果是13,则表明没有格式化,我们进行格式化
  // 如果是11,则表明数量对不上,需要去改设备个数,也就是FF_VOLUMES
  if(result == 13)
  {
    MKFS_PARM Format = {FM_FAT32, 0, 0, 0, 0};  // 为了兼容,可以改为FM_ANY,对16MB来说,FAT16最合适
    result = f_mkfs("0:", &Format, work_buffer, sizeof(work_buffer));

    result=f_mount(&FsObject,"0:",1);  // 再次挂载,其实还可以进行判断
  }

//  result = f_open(&fp, "0:test.txt", FA_OPEN_ALWAYS|FA_WRITE|FA_READ);

//  UINT test;
//  result = f_write(&fp,"test1234",sizeof("test1234"),&test);
//  f_close(&fp);

  
  result = f_open(&fp, "0:test.txt", FA_OPEN_ALWAYS|FA_WRITE|FA_READ);

  UINT test;
  uint8_t read[20];
  result=f_read(&fp, read, f_size(&fp), &test);

  while(1)
  {
    
  }

  return 0;
}

常见问题与调试技巧

Flash 相关问题

Q: FLASH_ReadID() 返回 0xFFFFFF 或 0x000000？
A: SPI Flash 没有接好，或者 SPI 接口初始化未正确完成；建议检查：
- SPI 时钟、模式是否与 Flash 兼容；
- Flash 供电是否稳定；
- CS 引脚是否正确拉低后开始通信；
Q: Flash 容量识别不对？
A: FLASH_IC_Check() 中只处理了常见型号，若你使用的是不在列表内的型号，请根据 datasheet 添加对应的 JEDEC ID 和容量；

挂载与格式化相关

Q: f_mount 返回 FR_NO_FILESYSTEM（13），怎么解决？
A: 说明当前设备上没有可识别的文件系统；应使用 f_mkfs 对 Flash 进行格式化，完成后再调用 f_mount 重新挂载；
Q: f_mount 返回 FR_INVALID_DRIVE（11）？
A: 说明 FatFS 的卷编号配置有问题，请检查 ffconf.h 中 FF_VOLUMES 是否 >= 你的逻辑盘号，比如 f_mount(…, “0:”, 1) 表示你至少得设置 #define FF_VOLUMES 1；

FAT 文件系统格式相关

Q: f_mkfs() 返回 FR_INVALID_PARAMETER？
A: f_mkfs 参数设置不当，建议使用如下方式初始化：

1 2	MKFS_PARM fs_param = {FM_ANY, 0, 0, 0, 0}; f_mkfs("0:", &fs_param, work_buffer, sizeof(work_buffer));

Q: 格式化完文件系统容量很小（比如识别为1MB）？
A: 可能是扇区大小未正确返回，检查 disk_ioctl() 中 GET_SECTOR_SIZE 和 GET_SECTOR_COUNT 是否准确计算，是否符合你实际 Flash 容量；

读写文件异常

Q: 文件写入后读出来的数据不对，乱码或者全 0？
A: 可能原因
- 写入之前没有正确擦除扇区；
- 写操作未对齐页写入（W25系列对页写入有要求）；
- 写入数据后未调用 f_close() 或 f_sync()，导致未刷新缓存到 Flash；
- diskio.c 中 FLASH_Erase_Sector() 和 W25XXX_WR_Block() 地址未正确计算；
Q: 写文件成功了，但再次打开文件内容变空？
A: 注意写模式是否是 FA_CREATE_ALWAYS，该模式会每次打开都清空内容；如果想保留内容，改为 FA_OPEN_ALWAYS | FA_WRITE 并调用 f_lseek(&fp, f_size(&fp)) 跳到末尾再写；

文件系统行为与配置相关

Q: 文件名太长无法识别？
A: 默认 FatFS 禁用长文件名（LFN），需在 ffconf.h 中配置：

1 2	#define FF_USE_LFN 1 #define FF_MAX_LFN 64

Q: 中文文件名乱码？
A: 请设置正确的代码页，例如：

1	#define FF_CODE_PAGE 936 // 简体中文 GBK

Q: 同一个文件写入后再读读取不到内容？
A: 若写入后未关闭文件或调用 f_sync()，FatFS 可能未刷新数据到底层 Flash，建议：

1 2	f_write(...); f_sync(&fp); // 确保数据落盘

运行异常 / 稳定性问题

Q: 写入操作中系统卡死或死循环？
A: Flash 的写入/擦除是阻塞操作，部分芯片擦除单个扇区可能耗时几十毫秒；建议你：
- 在写函数中加入 watchdog 喂狗机制；
- 考虑用非阻塞 Flash 驱动 + 文件系统缓存策略来优化；
Q: Flash 写入过程中掉电，数据损坏？
A: 推荐使用 FatFS 的事务机制，例如在写入文件时增加 f_sync()，或使用 FAT 的备用区功能（需高级配置）；另外也可以借助 CRC 校验机制保证文件有效性；

调试技巧

建议在初始化完成后先跑一个简单的读写测试函数：

f_open(&fp, "test.txt", FA_CREATE_ALWAYS | FA_WRITE);
f_write(&fp, "hello", 5, &bw);
f_close(&fp);

f_open(&fp, "test.txt", FA_READ);
f_read(&fp, buf, 5, &br);
f_close(&fp);

使用串口或者 RTT 等工具打印中间步骤结果，比如挂载结果、读写返回值、实际读出的内容，有助于快速定位问题；
调试期间建议将所有错误码都打印出来对应 FR_XXX 含义，便于对照 FatFS 源码中的错误枚举；

总结

本篇博客详细介绍了如何将 FatFS 移植到 SPI Flash，并通过 W25Q128 实现文件读写功能；从驱动实现、FatFS 配置、文件操作到问题排查，整个流程强调的是「实用」与「稳定」，希望对你的嵌入式项目有所帮助；

值得注意的是，SPI Flash 天生具备“写前擦除”“页擦除/块擦除”的特性，且写入寿命有限（一般每个扇区约 10 万次擦写）；这意味着在频繁写入场景下，Flash 容易出现写坏、性能衰减等问题；

为此，建议关注以下几点：

磨损均衡（Wear Leveling）：FatFS 本身不具备磨损均衡机制，如果使用 SPI Flash 存储频繁变更的数据（如日志、数据库），需要在应用层实现“循环覆盖”或“动态地址映射”来避免单点反复擦写；
避免频繁格式化和 f_open/f_write/f_close 操作循环，应尽可能复用文件句柄，按需 flush 写入；
设置合适的缓存机制，如启用 sector 缓冲，减少物理擦写次数；
建议定期备份重要数据，并在系统初始化时进行 Flash 健康检查（可利用空闲位、标志位判断 Flash 是否写满或擦损）；
日志/配置文件等 建议使用固定格式（如简化版 TLV）写入，便于恢复和分析；

最后，虽然 FatFS 的结构设计优雅轻量，但在用它搭配 SPI Flash 构建嵌入式文件系统时，我们仍需深入理解底层 Flash 的行为特性，并结合自身项目场景做出相应调整和优化；

下一步，我计划基于 USB Composite（复合设备） 实现 STM32 同时具备串口调试和 模拟U盘功能，通过 USB MSC 协议挂载 FatFS 文件系统，让用户能够在电脑端直接读写 SPI Flash 中的数据，这将进一步提升系统的易用性和可扩展性，敬请期待！

Docker部署MQTT服务器

2024-08-20T09:49:12.000Z

参考：

官网：https://www.emqx.com/zh

在物联网系统中，消息队列是设备通信的核心，而 MQTT 作为轻量、高效的通信协议，已经成为行业默认标准；说到 MQTT Broker，大多数人第一时间想到的就是 EMQX：一款高性能、开源且支持企业级功能的 MQTT 消息服务器；

注意：企业级功能或者商用需要付费使用；

不过 EMQX 的部署一直被人觉得“偏重”，各种配置繁琐、界面复杂，特别是初学者常常被一堆文档劝退；其实用 Docker 部署 EMQX，整个过程不仅轻量而且非常优雅；只要几条命令，就可以在本地快速跑起来，甚至连可视化管理界面都顺带搭好了；

本篇文章会一步步带你通过 Docker 部署 EMQX，适合刚接触 MQTT 或想自建消息服务的小伙伴；

顺带一提，EMQ 还提供了一个更轻量的版本： NanoMQ，专为嵌入式 Linux 设备设计，如果你后续在做边缘侧 MQTT 应用，也可以考虑这个版本；

Docker 部署 EMQX

部署方式选择的是官方提供的开源版 + 自托管 + Docker 镜像：

下载地址（可查看所有平台选项）：https://www.emqx.io/zh/downloads

直接使用如下命令完成镜像拉取与启动：

# 拉取 EMQX 开源版镜像（版本 5.7.2）,如果想看别的版本可以去docker hub查看
docker pull emqx/emqx:5.7.2

# 启动容器并映射常用端口
docker run -d --name emqx \
  -p 1883:1883 \
  -p 8883:8883 \
  -p 8083:8083 \
  -p 8084:8084 \
  -p 18083:18083 \
  emqx/emqx:5.7.2

常用端口说明

端口号	协议说明
1883	MQTT over TCP（最常用端口）
8883	MQTT over SSL/TLS（加密传输）
8083	MQTT over WebSocket
8084	MQTT over WSS（加密 WebSocket）
18083	HTTP Dashboard & REST API
4370 / 5370	集群通信端口（本次没用到）
5683	CoAP端口（本次没用到）

访问管理后台（Dashboard）

由于 EMQX 的网页管理后台需要通过 18083 端口访问，为了方便管理，我通过本地 Caddy 做了 HTTPS 反向代理，这样就可以通过我自己的域名访问了：mqtt.140105.xyz

如果你没做 Caddy 代理，直接访问宿主机的 http://localhost:18083 也是一样的；

默认账号密码是：

用户名：admin
密码：public

首次登录建议立即修改密码，避免风险；

客户端认证设置

在 EMQX 中，可以通过密码认证来控制哪些客户端可以连接；

操作路径：
Dashboard 面板 -> 访问控制 -> 客户端认证

配置流程如下：

新建一个认证方式：
- 类型选择：Password-Based
- 认证数据源：内置数据库
- 用户名类型：username
- 加密算法、加盐策略使用默认配置即可
添加用户账号：
- 用户名：emtime
- 密码：你自己的常用密码

客户端连接测试

桌面客户端推荐

建议使用官方出品的 MQTT 客户端：MQTTX

配置方式如下：

地址填写你自己的域名或本机地址，如：mqtt.140105.xyz
端口填写 1883（TCP MQTT）
用户名 / 密码填写你刚才设置的认证信息

点击连接后，右上角绿色表示连接成功，就可以自己进行订阅 / 发布测试了；

Web 客户端（可选）

你也可以用官方提供的 Web 客户端工具：https://mqttx.app/web-client

不过我个人测试的时候没连上，可能是网络或证书的问题，也可以使用 Dashboard 自带的测试功能尝试；

总结

这套部署流程非常适合个人或小型项目使用，Docker 启动简单、配置界面直观，而且支持多种认证机制，非常灵活；后续如果你有更复杂的使用场景（如 TLS 加密、集群部署、ACL 访问控制等），EMQX 都能胜任；

Docker部署Certd，实现HTTPS证书自动申请与更新

2024-08-19T14:19:47.000Z

Certd官网：https://certd.docmirror.cn

在现代网站服务中，HTTPS 已成为保障通信安全的基础组件；为了简化证书申请与更新流程，Certd 提供了自动化的证书管理能力，并支持多家主流证书颁发机构；

本文将详细介绍如何通过 Docker 快速部署 Certd，实现 HTTPS 证书的自动申请与更新；

安装并启动服务

# 创建用来存放Certd相关的
mkdir certd

cd certd

wget https://gitee.com/certd/certd/raw/v2/docker/run/docker-compose.yaml

nano docker-compose.yaml

docker conmpose up -d

# 停止并删除容器，不用怕数据，数据已经挂载到宿主机了
#docker compose down

我自己的docker-compose.yaml文件如下：

version: '3.3' # 兼容旧版docker-compose
services:
  certd:
    # 镜像                                                  #  ↓↓↓↓↓ ---- 镜像版本号，建议改成固定版本号,例如：certd:1.29.0
    image: registry.cn-shenzhen.aliyuncs.com/handsfree/certd:latest
    container_name: certd # 容器名
    restart: always # 自动重启
    volumes:
      #   ↓↓↓↓↓ -------------------------------------------------------- 数据库以及证书存储路径,默认存在宿主机的/data/certd/目录下，【您需要定时备份此目录，以保障数据容灾】
      #                                                                  只要修改冒号前面的，冒号后面的/app/data不要动
      - ./:/app/data
    ports: # 端口映射
      #  ↓↓↓↓ ---------------------------------------------------------- 如果端口有冲突，可以修改第一个7001为其他不冲突的端口号，第二个7001不要动
      - "7001:7001"
      #  ↓↓↓↓ ---------------------------------------------------------- https端口，可以根据实际情况，是否暴露该端口
      - "7002:7002"
    #↓↓↓↓ -------------------------------------------------------------- 如果出现getaddrinfo ENOTFOUND错误，可以尝试设置dns
    dns:
      - 223.5.5.5
      - 223.6.6.6
    
#    dns:
#      - 223.5.5.5      # 阿里云公共dns
#      - 223.6.6.6
#       # ↓↓↓↓ --------------------------------------------------------- 如果你服务器在腾讯云，可以用这个替换上面阿里云的公共dns
#      - 119.29.29.29  # 腾讯云公共dns
#      - 182.254.116.116
#       # ↓↓↓↓ --------------------------------------------------------- 如果你服务器部署在国外，可以用这个替换上面阿里云的公共dns
#      - 8.8.8.8       # 谷歌公共dns
#      - 8.8.4.4
#    extra_hosts:
#        # ↓↓↓↓ -------------------------------------------------------- 这里可以配置自定义hosts，外网域名可以指向本地局域网ip地址
#      - "localdomain.com:192.168.1.3"
#        #         ↓↓↓↓ ------------------------------------------------ 直接使用主机的网络，如果网络问题实在找不到原因，可以尝试打开此参数
#    network_mode: host
    labels:
      com.centurylinklabs.watchtower.enable: "true"
#    ↓↓↓↓ -------------------------------------------------------------- 启用ipv6网络，还需要把下面networks的注释放开
#    networks:
#      - ip6net
    environment:
#     设置环境变量即可自定义certd配置
#     配置项见： packages/ui/certd-server/src/config/config.default.ts
#     配置规则： certd_ + 配置项, 点号用_代替
#                                    #↓↓↓↓ ----------------------------- 如果忘记管理员密码，可以设置为true，重启之后，管理员密码将改成123456，然后请及时修改回false
      - certd_system_resetAdminPasswd=false

#     默认使用sqlite文件数据库，如果需要使用其他数据库，请设置以下环境变量
#     注意： 选定使用一种数据库之后，不支持更换数据库；
#     数据库迁移方法：1、使用新数据库重新部署一套，然后将旧数据同步过去，注意flyway_history表的数据不要同步
#                                    #↓↓↓↓ ----------------------------- 使用postgresql数据库，需要提前创建数据库
#      - certd_flyway_scriptDir=./db/migration-pg                        # 升级脚本目录
#      - certd_typeorm_dataSource_default_type=postgres                  # 数据库类型
#      - certd_typeorm_dataSource_default_host=localhost                 # 数据库地址
#      - certd_typeorm_dataSource_default_port=5433                      # 数据库端口
#      - certd_typeorm_dataSource_default_username=postgres              # 用户名
#      - certd_typeorm_dataSource_default_password=yourpasswd            # 密码
#      - certd_typeorm_dataSource_default_database=certd                 # 数据库名

#                                    #↓↓↓↓ ----------------------------- 使用mysql数据库，需要提前创建数据库 charset=utf8mb4, collation=utf8mb4_bin
#      - certd_flyway_scriptDir=./db/migration-mysql                     # 升级脚本目录
#      - certd_typeorm_dataSource_default_type=mysql                     # 数据库类型， 或者 mariadb
#      - certd_typeorm_dataSource_default_host=localhost                 # 数据库地址
#      - certd_typeorm_dataSource_default_port=3306                      # 数据库端口
#      - certd_typeorm_dataSource_default_username=root                  # 用户名
#      - certd_typeorm_dataSource_default_password=yourpasswd            # 密码
#      - certd_typeorm_dataSource_default_database=certd                 # 数据库名

#         ↓↓↓↓ ---------------------------------------------------------  自动升级，上面certd的版本号要保持为latest
#  certd-updater:  # 添加 Watchtower 服务
#    image: containrrr/watchtower:latest
#    container_name: certd-updater
#    restart: unless-stopped
#    volumes:
#      - /var/run/docker.sock:/var/run/docker.sock
#    # 配置 自动更新
#    environment:
#      - WATCHTOWER_CLEANUP=true            # 自动清理旧版本容器
#      - WATCHTOWER_INCLUDE_STOPPED=false   # 不更新已停止的容器
#      - WATCHTOWER_LABEL_ENABLE=true       # 根据容器标签进行更新
#      - WATCHTOWER_POLL_INTERVAL=600       # 每 10 分钟检查一次更新


#    ↓↓↓↓ -------------------------------------------------------------- 启用ipv6网络，还需要把上面networks的注释放开
#networks:
#  ip6net:
#    enable_ipv6: true
#    ipam:
#      config:
#        - subnet: 2001:db8::/64

访问 Certd 面板

部署完成后，可通过以下地址访问 Certd：

1 2	默认账号密码： admin/123456

首次登录后请务必修改管理员密码；

配置自动签发证书

Certd 支持多种 DNS API 接入方式（阿里云、腾讯云、Cloudflare等），根据你的域名服务商选择配置方法；详细配置方式请参考官方文档的 DNS API 配置指南；

Caddy反向代理

2024-08-19T14:19:03.000Z

Caddy官网：https://caddyserver.com

为什么我开始用 Caddy

最初接触 Caddy，是因为它在社区中被广泛推荐为一款“自动 HTTPS 一把梭”的轻量级 Web 服务器；只要你有个域名、端口没被封，Caddy 理论上能自动申请并续签 HTTPS 证书，全程无需手动操作，真正实现开箱即用；

不过，实话实说，我并没能成功实现自动 HTTPS；
我这台小水管部署在没有公网 IP 的局域网环境中，Let’s Encrypt 验证域名所有权时无法访问到我的服务器，自然无法成功签发证书；翻了一些文档后确认，这种内网场景确实不适合自动签证；

但我使用 Caddy 的真正目的其实并不是自动 HTTPS，而是简洁地实现反向代理；我的需求是把一些局域网服务（比如 Web 控制面板、API 服务、博客页面）通过统一的域名访问，而不是记一堆不同端口；

相比 Nginx 那一堆配置、手动写 location、reload 重载，Caddy 用 Caddyfile 几行就搞定，还能自动帮我处理 header、压缩、缓存等常用设置；
虽然 HTTPS 自动签发失败，但 Caddy 依然凭借其优秀的反向代理能力和极简配置体验让我留下它；

安装和基本使用

安装 Caddy（推荐官方一键脚本）

1	curl -fsSL https://get.caddyserver.com \| bash -s personal

或者使用包管理器，如在 Debian/Ubuntu 下：

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/caddy.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy.list
sudo apt update
sudo apt install caddy

编写配置文件

默认配置文件路径为 /etc/caddy/Caddyfile，也可以自己创建一个 Caddyfile 并通过命令指定；

1	sudo nano /etc/caddy/Caddyfile

启动 Caddy

编辑完配置后，使用 systemd 启动 Caddy：

1 2	sudo systemctl restart caddy sudo systemctl enable caddy

或者直接在本地调试运行：

1	caddy run --config /path/to/Caddyfile

我的 Caddy 配置详解

配置监听端口（http_port）

1
2
3

{
http_port 8080
}

因为 80 端口经常被占用（尤其内网小主机上），我将默认 HTTP 监听端口改为了 8080，更灵活些；

反代局域网里的服务

你的域名 {
    # 你的域名证书
tls cert.crt cert.key

    # 本地服务
reverse_proxy 127.0.0.1:34718
}

这个配置用于访问运行在本机 34718 端口的服务；

域名解析的是我在虚拟组网中的主机地址，因此组网内的设备都能通过域名来访问该服务；

这里的证书我是使用Certd申请的，详情见：Docker部署Certd，实现HTTPS证书自动申请与更新；

反代局域网中的https服务

你的域名 {
    reverse_proxy https://192.168.0.1:1234 {
        transport http {
            # 跳过 TLS 验证，避免证书错误导致Caddy反代失败
            tls_insecure_skip_verify
        }
    }

    # 你的证书
    tls cert.crt cert.key
}

这里反向代理的是别的设备的https服务；

Caddy 默认验证目标服务的 TLS 证书，由于我这里是自签的，就使用 tls_insecure_skip_verify 跳过了验证，避免反代失败；

本地静态页面（端口访问）

:21824 {
tls emtime.crt emtime.key
root * /home/time/doc/blog/public
file_server

handle_errors {
@404 {
expression {http.error.status_code} == 404
}
rewrite @404 /404.html
file_server
}
}

这是一个纯静态服务配置，我用来部署 Hexo 生成的博客页面；

Caddy 会监听 21824 端口，并将 /home/time/doc/blog/public 目录作为静态资源根目录；配置中还加了自定义的 404.html 页面处理逻辑；

因为没有公网 IP，这个页面更多是在局域网访问时使用；

本地静态页面（绑定域名）

blog.emtime.top {
tls emtime.crt emtime.key
root * /home/time/doc/blog/public
file_server

handle_errors {
@404 {
expression {http.error.status_code} == 404
}
rewrite @404 /404.html
file_server
}
}

这个配置和上面几乎一致，只是绑定了 blog.emtime.top 这个域名，可能正是你现在正在访问的这个博客的域名（我还有别的域名也同样部署了同样的博客）；

因为我的小水管没有公网 IP，这个域名是通过 frp 穿透暴露出来的；
这里简单说一下，我使用的是frp的方法，创建HTTPS隧道，选择本机的443端口进行映射，域名通过cname的方法解析到frp的域名即可；

为什么我最终选择了 Caddy 而不是 Nginx？

其实我也试过 Nginx，作为一个功能成熟的老牌服务器，它确实非常灵活；但对我这种轻量化内网部署场景来说，Caddy 的优势太明显了：

Nginx 配置冗长，一写就是几十行；
Caddy 的配置语言天然支持反向代理，几行就能完成；
Caddy 默认自带 TLS（即使我没成功用自动签发）；
Caddy 自带静态文件服务、自动压缩、常用 header，非常适合个人小服务；
部署只需要一个二进制，不依赖太多系统组件，非常适合局域网小主机部署；

虽然 Caddy 的自动 HTTPS 功能在我的场景下并没有成功使用，但它的反向代理能力和极低的学习成本，已经让我在日常部署中离不开它了；

总结

主要就是说了说我如何在没有公网的局域网环境下使用 Caddy 来构建统一访问入口，反代各种服务、博客页面和管理面板；

如果你也有类似的需求，不妨试试 Caddy，即使不能一把梭 HTTPS，它依然是一个非常轻便好用的反代工具；

Docker部署密码管理工具

2024-08-18T15:24:31.000Z

参考：https://ohdmire.github.io/posts/bitwarden
仓库：https://github.com/dani-garcia/vaultwarden

在数字化生活中，密码管理已经不再是“记几个数字”那么简单；各种网站、应用动辄要求复杂度极高的密码，安全意识一提升，每个账户还不能用同一个密码；这时候，一个好用的密码管理工具就显得尤为重要；

Bitwarden 是一款非常优秀的开源密码管理器，而 Vaultwarden 则是它的轻量级“克隆版”——资源占用小，部署简单，并且还有一些特有的功能，非常适合自建；更重要的是，自部署意味着你的数据真正掌握在你自己手里；

这篇文章会带你一步步部署 Vaultwarden，构建一个属于你自己的私有密码管理系统，不依赖任何第三方服务，无需高性能服务器，即便是树莓派也能轻松运行；适合注重隐私、安全、掌控感的你；

几个关键点先说清楚：

Docker 镜像不是官方的：使用的是 vaultwarden/server，优点是轻量、解锁 Bitwarden 高级功能，适合个人部署使用；
必须使用 HTTPS：Vaultwarden 不支持在 HTTP 下登录或注册，所以部署过程必须搭配 HTTPS 服务，最好申请证书；

Docker 部署过程

部署本体其实非常简单，以下是完整命令流程：

# 拉取镜像
docker pull vaultwarden/server:latest

# 准备本地挂载目录，保存 Vaultwarden 的 SQLite 数据
mkdir -p /home/time/doc/codefile/password

# 启动容器
docker run -d \
  --name password \
  -v /home/time/doc/codefile/password/:/data/ \
  --restart unless-stopped \
  -p 6468:80 \
  vaultwarden/server:latest

这个服务会监听在本地的 6468 端口，页面是能打开的，但不能登录或注册，因为没有 HTTPS；

HTTPS 配置说明

Vaultwarden 的前端强制要求 HTTPS 访问，这是很多人部署时最容易卡壳的地方；我这边采用了 Caddy 来做反向代理，部署逻辑简单、证书配置灵活，比较适合个人自部署的场景；

Caddy反向代理：我使用的是 Caddy，配置非常简洁；具体原理和部署过程可以参考我之前写的这篇博客：Caddy反向代理配置详解；
Caddy 配置示例：

你的域名 {
    # 你的域名证书
tls cert.crt cert.key

    # 反向代理到 Vaultwarden 容器所在端口
reverse_proxy 127.0.0.1:6468
}

证书来源：我没有使用 Caddy 自带的自动证书申请功能，而是通过 Certd 生成了泛域名证书，统一管理更方便；证书配置好后，Caddy 只需要加载即可；

密码导入和使用体验

Vaultwarden 兼容 Bitwarden 全套客户端，包括桌面应用、网页端和浏览器插件；首次访问你部署的网页服务后，注册一个账号并登录即可使用；

以下是浏览器插件界面截图：

初次使用时，我直接将 Chrome 导出的 .csv 密码文件导入进去，整个流程没有踩坑，页面提示也很直观；导入成功后，插件会识别你常用的网站并提供填充密码功能，体验类似 Chrome 自带的密码管理，多了主密码保护等功能；

总结

总的来说，Vaultwarden 是一个轻量、实用、易于自建的密码管理工具，适合追求数据自主和隐私保护的用户；虽然它在易用性和云同步体验上不如 1Password 或 Chrome 自带的密码管理器那么“顺手”，但它胜在部署自由、功能完整，尤其对于技术用户来说，掌控自己的数据就是最大的安心；

如果你已经有了自己的服务器资源（哪怕是树莓派），并具备基本的 Docker 和 HTTPS 配置能力，Vaultwarden 完全值得一试；配合 Caddy 做反向代理，搭配 Certd 管理泛域名证书，部署流程也没有想象中复杂；

也许它不够“傻瓜式”，但作为一名稍微动手能力强一点的用户，这种“折腾”背后的安全感和成就感，是任何云服务都给不了的；

如果你和我一样，厌倦了各种服务把账号密码握在手里，不妨给 Vaultwarden 一个机会；

Docker部署Gogs（个人GIthub）

2024-08-16T08:29:55.000Z

参考：

Gogs仓库：https://github.com/gogs/gogs

现在越来越多团队开始尝试搭建自己的 Git 服务，用于私有代码托管、版本控制以及团队协作；如果你觉得 GitLab 太重、Gitea 功能太多，那么 Gogs 这个轻量级的 Git 服务可能刚好适合你；

Gogs 的全名是「Go Git Service」，它由 Go 语言开发，体积小、部署快、占用资源极低，非常适合搭建在树莓派、低配机器或开发环境中自用；

这篇博客我就来分享下 如何用 Docker 部署 Gogs，整个流程简单高效，适合初学者和懒人党（比如我）参考；

部署Gogs

拉取 Gogs Docker 镜像

1	docker pull gogs/gogs

Gogs 提供官方维护的镜像，持续更新，推荐使用；拉取速度可能因网络而异，可考虑配置镜像加速；

创建挂载目录

为了数据持久化，我们提前创建挂载目录；这里以 /home/time/docker_mount/gogs_github 为例：

1	mkdir -p /home/time/docker_mount/gogs_github

这个目录将映射到容器的 /data 目录，Gogs 会把所有的配置、仓库文件、SSH 密钥等放在这里，重启、迁移都不影响；

启动 Gogs 容器

docker run -d \
  --name my_github \
  --restart=always \
  -p 10022:22 \
  -p 13000:3000 \
  -v /home/time/docker_mount/gogs_github:/data \
  gogs/gogs

解释一下：

-p 13000:3000：Web 界面访问端口；
-p 10022:22：Git SSH 克隆使用的端口；
-v：挂载持久化数据目录；
–name：容器名称为 my_github；

初始配置 Gogs

在浏览器中访问 http://运行服务的ip:13000，开始初始化设置；

配置项说明：

数据库类型：选择 SQLite3（默认即可）；
应用名称：如 EMTime’s Private Repo，仅用于界面展示；
SSH 端口：建议勾选“使用内置 SSH 服务器”；
应用 URL：填写 http://运行服务的ip:13000，注意不能加斜杠 /；
管理员账号：填写好用户名、密码和邮箱；
点击“立即安装” 即可完成；

安装完成后请及时记下管理员账号密码，后续登录需要用到；

修改配置（如关闭注册功能）

默认情况下，任何人都可以注册新账号；如果你希望私有使用，可以通过配置文件禁用注册功能：

1	nano /home/time/docker_mount/gogs_github/gogs/conf/app.ini

找到：

1 2	[service] DISABLE_REGISTRATION = false

修改为：

1 2	[service] DISABLE_REGISTRATION = true

保存后重启容器：

1	docker restart my_github

这样就只保留管理员创建用户的方式，更安全；

使用自定义域名（可选）

比如你使用了反代（如 Caddy、Nginx、frp 等）并绑定了你的域名，就可以修改 Gogs 的显示地址：

1 2	docker stop my_github vim /home/time/docker_mount/gogs_github/gogs/conf/app.ini

找到：

1	APP_URL = http://localhost:13000

修改为：

1	APP_URL = https://git.140105.xyz

这里用我自己的域名为例，注意不要加斜杠 /；

保存后重启容器：

1	docker restart my_github

克隆仓库报 SSL 错误的解决办法（可选）

如果你的 HTTPS 使用的是自签名证书，Git 拉取可能提示 SSL 验证失败，可以关闭 SSL 验证（注意，仅建议在局域网或受信网络使用）：

1	git config --global http.sslVerify false

如果使用 Let’s Encrypt 的证书则无需担心，Git 会自动验证；

为 Gogs 配置 SSH

在部署好 Gogs 之后，如果每次拉取和推送都输入账号密码，不仅麻烦还不安全；这时候我们可以通过 SSH 公钥认证来实现更安全、无密码的 Git 操作；

这篇文章将一步步带你完成 Gogs 的 SSH 配置过程，适用于 Linux 和 Windows（使用 MobaXterm 等终端工具）环境；

生成 SSH 密钥对

在终端中输入以下命令，按提示操作：

1	ssh-keygen -t rsa -C "git@git.140105.xyz"

这里：

-t rsa 表示使用 RSA 加密算法；
-C 根据你自己之前部署的情况进行修改，这里以我自己的域名为例；
默认会将密钥保存在 ~/.ssh/id_rsa，你也可以选择自定义，例如 id_rsa_gogs；

Gogs 同样支持 ed25519 等更现代的算法，参考其界面提示或 GitHub 教程进行生成即可；

设置权限（非常重要）

确保私钥不可被其他用户读取，防止泄露：

1 2	chmod 600 ~/.ssh/id_rsa_gogs chmod 644 ~/.ssh/id_rsa_gogs.pub

配置 SSH 连接

编辑 SSH 配置文件：

1	nano ~/.ssh/config

添加以下内容：

Host 随便取个名字
    HostName git.140105.xyz
    User git
    Port 10022
    IdentityFile ~/.ssh/id_rsa_gogs
    PreferredAuthentications publickey

解释一下这些配置：

Host 是你之后在 git clone 命令中使用的别名；
HostName 是实际的服务器地址；
User 为固定的 git，Gogs 默认就是用这个账户名；
Port 是你容器映射出来的 SSH 端口（上文我们用的是 10022）；
IdentityFile 指向你刚刚生成的私钥；
PreferredAuthentications 指定只使用公钥认证；

如果你是在 Windows 使用 MobaXterm 或类似终端，~/.ssh/config 位置在 C:\Users<用户名>.ssh\config，内容相同；

添加 SSH 公钥到 Gogs

名称随意，例如 My laptop SSH key；
内容粘贴 id_rsa_gogs.pub 中的全部内容；

这样 Gogs 就认识你的电脑了；

测试 SSH 连接

执行以下命令：

1	ssh -T git@git.emtime.top -p 10022

如果成功，会提示类似：

1	Hi EMTime! You've successfully authenticated, but Gogs does not provide shell access.

表示你已经通过公钥成功认证了！

克隆仓库的方式说明

使用 SSH 克隆仓库有两种方式：

# 推荐方式（更清晰直观）
git clone ssh://git@git.emtime.top:10022/EMTime/test.git

# 简写方式（Gogs 默认提供），这种写法虽然更短，但有些 Git 客户端或未配置 SSH 时可能会失败
git@git.emtime.top:EMTime/test.git

总结

部署一个轻量级的 Git 仓库服务其实非常简单，Gogs + Docker 就是最实用、门槛最低的选择之一：

简单易用，不依赖外部数据库；
支持 SSH、Web、组织管理；
Docker 容器化部署，迁移方便；
可与 Caddy、Frp 等无缝结合，快速公网访问；

非常适合用于自用项目托管、内网代码管理、小型团队开发协作等场景；

Docker运行OpenWRT

2024-07-25T10:26:51.000Z

在日常网络优化中，OpenWRT 作为强大灵活的软路由系统，非常适合作为旁路由运行；而使用 Docker 快速部署 OpenWRT，不仅便于管理，还能避免单独刷固件、物理接入的繁琐；本篇笔记记录了通过 Docker 安装并配置 OpenWRT 为旁路由的全过程；

参考资料：
https://www.ilovn.com/2023/02/23/deploy-openwrt-with-docker/
https://openwrt.ai/docker%E7%89%88openwrt%E6%97%81%E8%B7%AF%E7%94%B1%E5%AE%89%E8%A3%85%E8%AE%BE%E7%BD%AE%E6%95%99%E7%A8%8B/

准备工作-开启网卡混杂模式

旁路由需要 Docker 网络能桥接到主机的物理网卡，因此必须开启混杂模式（Promiscuous Mode）；

使用 ifconfig 或 ip addr 查找你的有线网卡名，比如 enp1s0，然后执行：

1	sudo ip link set enp1s0 promisc on

确认是否已开启：

1	ip link \| grep PROMISC

创建 Macvlan 网络

创建一个 Macvlan 类型的网络，供 OpenWRT 容器使用；你可以根据自己的局域网网段修改 subnet 和 gateway 参数：

docker network create -d macvlan \
  --subnet=192.168.10.0/24 \
  --gateway=192.168.10.1 \
  -o parent=enp1s0 openwrt

–subnet: 指定 OpenWRT 所在的子网；
–gateway: 原有主路由地址；
-o parent: 指定物理网卡；
openwrt: 为网络命名；

获取并导入 OpenWRT 镜像

从 https://openwrt.ai 下载适合自己设备架构的镜像，例如 x86_64 架构的 Generic 镜像；

下载后导入镜像，此命令会将镜像命名为 openwrt：

1	docker import 文件名.tar.gz openwrt

运行 OpenWRT 容器

创建容器并连接至刚才创建的网络：

docker run -d \
  --restart always \
  --name openwrt \
  --network openwrt --privileged=true \
  openwrt /sbin/init

配置 OpenWRT 网络信息

进入容器：

1	docker exec -it openwrt bash

编辑网络配置文件：

1	nano /etc/config/network

参考配置如下：

config interface 'lan'
        option device 'br-lan'
        option proto 'static'
        option ipaddr '192.168.10.2'     # OpenWRT 地址
        option netmask '255.255.255.0'
        option gateway '192.168.10.1'    # 主路由地址
        option peerdns '0'
        list dns '223.5.5.5'

配置完成后重启网络服务：

1	/etc/init.d/network restart

进入 Web 管理页面

此时你可以在浏览器访问 http://192.168.10.2 进入 OpenWRT 的 LuCI 管理界面，初始用户名密码均为 root；

进入系统后，可以通过“网络向导”配置旁路由模式，建议：

IP 地址：192.168.10.2（与前文一致）
网关与 DNS：均填写主路由地址（如 192.168.10.1）

开启 DHCP 功能（可选）

若希望 OpenWRT 自动分配 IP，则需要：

关闭主路由的 DHCP 服务；
在 OpenWRT 中开启 DHCP 功能，并配置其 IP 分配范围；

总结

部署完成后，你的 OpenWRT 容器就具备完整的旁路由能力，可以实现流量分流、广告屏蔽等高级功能；同时也得益于 Docker 的管理便利，容器化的 OpenWRT 更便于升级、迁移和备份，推荐给动手能力强的朋友们试试；

Basic OS：从任务定义到运行调度的全流程实践

2024-07-09T10:47:32.000Z

仓库：https://gitee.com/event-os/basic-os

在上一篇中，我们从架构视角出发，了解了 Basic OS 的设计理念和核心机制：共享任务栈、协作式调度、基于 PendSV 的上下文切换……这些特性让它成为资源受限设备中，极具性价比的结构化选项；

但了解原理只是第一步；

真正的价值，来自它在实际项目中的表现；这篇文章，我们将从定义任务开始，带你完整走一遍 Basic OS 的应用流程：如何写任务？如何初始化调度器？任务之间如何协作与切换？

不需要复杂的配置，也无需外部依赖；你将看到的是一个纯净、高效、清晰可控的任务调度过程，真正让你从“裸机大 while(1)”走向结构化设计的实战落地；

支持平台

当前 Basic OS 默认只适配了 Cortex-M0 和 M3 内核（比如 STM32F103 或 F030），虽然不算通用，但架构非常清晰，完全可以参考其结构来适配其他内核或平台；如果你对汇编和异常向量表比较熟悉，实现并不困难；

准备文件

使用 Basic OS 时，最基本的工作就是把它的核心源码添加到你的工程中（文件可以去开头所说的仓库中下载）；至少需要以下几个文件：

文件名	说明
basic_os.c	系统核心逻辑实现
basic_os.h	系统核心头文件
cpu.c	与平台无关的通用 CPU 支持
port_mdk.s	与平台有关的汇编端口（不同平台需对应更换）

此外，还需要你自己实现部分平台相关的钩子函数、SysTick中断等逻辑，官方示例中以 cb_basic_os.c 命名此文件；你也可以照此命名，并加入自己的实现：

#include "basic_os.h"

void bos_port_assert(uint32_t error_id)
{
    while (1)
    {
        bos_delay_ms(10);
    }
}

uint32_t count_idle = 0;
void bos_hook_idle(void)
{
    count_idle++;
}

void bos_hook_start(void)
{
    // 系统调度器启动后的钩子函数
    // 可选实现，用于调试或初始化用户资源
}

void SysTick_Handler(void)
{
    bos_tick(); // 系统时基更新
}

特别注意（针对 STM32 使用 CubeMX 的情况）
CubeMX 默认会自动生成 SysTick_Handler 和 PendSV_Handler，而这两个函数已由 Basic OS 实现；请务必在 NVIC 配置页面 → Code Generation 设置中取消勾选它们的生成，避免函数重定义冲突；

初始化 Basic OS

在你的 main.c 中，初始化 Basic OS 的代码结构非常简单：

#include "basic_os.h"

int main(void)
{
    static uint8_t stack[4096]; // 为共享栈分配空间

    bsp_init();                 // 板级初始化（LED/GPIO/UART等）
    basic_os_init(stack, 4096); // 初始化调度器

    basic_os_run();            // 启动调度器（不会返回）

    while (1)
    {
        // 实际上，这一行代码永远不会被执行到
    }
}

初始化的关键点是提供一段连续 RAM 区域作为共享任务栈，这里用了 4096 字节，具体大小依据任务栈深度和应用复杂度可调整；

注意：栈区必须是静态分配（static/global），不能是局部变量或动态分配，否则可能在函数退出后被破坏，导致调度器异常崩溃；

定义任务：结构化的多任务运行方式

在 Basic OS 中，每个任务就是一个函数 + 一个注册宏；定义任务的方式非常直观，适合嵌入式初学者理解；

以下是一个典型的多任务定义示例：

#include "basic_os.h"

uint32_t count_poll1 = 0;

void _func_poll_1(void *parameter)
{
    while (1)
    {
        count_poll1++;
        bos_delay_ms(10); // 每 10ms 执行一次
    }
}

bos_task_export(poll1, _func_poll_1, 2, NULL);

bos_task_export参数：

第一个参数：任务名称（可用于调试）
第二个参数：函数指针（真正的任务执行体）
第三个参数：任务优先级（同优先级按注册顺序轮转）
第四个参数：任务参数（通常传 NULL）

bos_task_export() 本质上是通过宏将任务描述信息放入 .bos_tasks 特定段，系统初始化时会自动扫描这段数据进行任务注册；所以bos_task_export()并不需要被调用，只需要在代码中这样导出（注册）任务即可；
Basic OS 是协作式调度器，不支持抢占式调度；只有当当前任务主动 yield 或 delay 时，调度器才会切换到其他任务；优先级高的任务在有多个可运行任务时会优先执行，但不会打断正在运行的任务；

我们可以定义多个任务，观察它们是否能按预期并发执行、互不干扰：

void _func_poll_2(void *parameter) { while (1) { count_poll2++; bos_task_yield(); } }
void _func_poll_3(void *parameter) { while (1) { count_poll3++; bos_task_yield(); } }
void _func_poll_4(void *parameter) { while (1) { count_poll4++; bos_task_yield(); } }
void _func_poll_5(void *parameter) { while (1) { count_poll5++; bos_task_yield(); } }
void _func_poll_6(void *parameter) { while (1) { count_poll6++; bos_delay_ms(10); } }

bos_task_export(poll2, _func_poll_2, 2, NULL);
bos_task_export(poll3, _func_poll_3, 2, NULL);
bos_task_export(poll4, _func_poll_4, 2, NULL);
bos_task_export(poll5, _func_poll_5, 2, NULL);
bos_task_export(poll6, _func_poll_6, 2, NULL);

你还可以添加一些控制硬件的任务，例如通过 GPIO 控制 LED 闪烁：

#include "gpio_led.h"

void _func_led1(void *parameter)
{
    while (1)
    {
        LED1_ON();
        bos_delay_ms(500);
        LED1_OFF();
        bos_delay_ms(500);
    }
}

bos_task_export(task_led1, _func_led1, 2, NULL);

软件定时器

在某些实际场景中，仅靠 bos_delay_ms() 实现任务延时是远远不够的；比如，我们希望任务可以“预约”一段时间后执行一次，或中途暂停、恢复某个定时行为，这时就需要更强大的软件定时器机制；

Basic OS 内置了轻量级的软件定时器接口，能够提供灵活、可控的定时事件触发逻辑，避免我们手动维护繁琐的计数器状态；

这一部分的使用非常简单，核心只需要掌握以下 5 个函数：

bos_timer_export(_name, _func, _oneshoot, _para)：导出（注册）一个定时器
- _name：定时器名称
- _func：定时器回调函数
- _oneshoot：是否是一次性定时器，true 表示是一次性定时器，false 表示是周期性定时器
- _para：定时器回调函数的参数

相当于给调度器声明“我有这么一个定时器”，必须在使用前调用一次，推荐在 main() 的初始化部分完成；

示例用法：

void _func_poll_7(void *para);

bos_timer_export(my_timer, _cb_timer_tick, false, NULL);

void _func_poll_7(void *para)
{

}

int16_t bos_timer_get_id(const char *name)：从软件定时器名称获取 ID，返回定时器 ID 或者错误代码
void bos_timer_start(uint16_t timer_id, uint32_t period)：启动一个定时器，period 单位是毫秒，可以和get_id配合使用
void bos_timer_stop(uint16_t timer_id)：停止一个定时器，可以和get_id配合使用
void bos_timer_reset(uint16_t timer_id, uint32_t period)：重置一个定时器，可以和get_id配合使用

总结

Basic OS 虽然定位轻量，但其设计并不简陋；从任务注册、共享栈调度，到钩子机制与软件定时器，它具备了一个结构化操作系统的核心要素；本文从创建工程出发，完整梳理了 Basic OS 的使用流程，让我们真正从裸机的 while(1) 循环中走出，迈入结构化的多任务世界；

当然，Basic OS 并非万能，它不支持抢占式调度，也没有复杂的同步机制，但也正是这种“克制”，让它在资源受限的嵌入式设备中成为一种高性价比的选择；

如果你正在开发一个不复杂但希望清晰可维护的项目，Basic OS 值得一试；下一步，我们可以探索它与外设协同、低功耗运行、任务通信等更高级的实战应用；

Basic OS：从裸机到结构化的第一步

2024-07-09T09:31:41.000Z

仓库：https://gitee.com/event-os/basic-os

在嵌入式开发中，操作系统往往是被绕开的“高级选项”；

对很多开发者而言，裸机开发已经足够：主循环、定时中断、状态机……能跑、够用、成本低；然而，项目一旦变得复杂，系统结构很容易变得混乱不堪，任务交叉、逻辑耦合、维护困难，最终演变为“能改的都不敢动”；

这时候，一套结构清晰、运行可靠、资源占用极低的轻量操作系统就显得尤为重要；

Basic OS 正是为此而生；它是一个基于事件驱动模型设计的微型嵌入式操作系统，拥有清晰的调度结构、极低的内存开销，以及良好的可读性与扩展性；哪怕在 M0 上，也能运行得游刃有余；

不追求复杂的线程抢占、不依赖高级硬件特性，Basic OS 关注的是对小型系统结构化管理的一种务实方案；

本篇文章将从整体架构出发，带你一步步了解 Basic OS 的设计理念、核心机制以及使用方法，帮助你在裸机开发和重量级 RTOS 之间，找到一个刚刚好的选择；

顺带一提，作者还有一个更完整的项目叫 Event OS，之后如果用到了，我也会写成笔记记录下来；

设计理念

为小RAM MCU而生

BasicOS 的设计出发点非常明确：针对 RAM 紧张的嵌入式系统（例如仅 8KB 的 Cortex-M0/M3）；
传统 RTOS 在每个任务上都要分配独立栈空间，这在小资源芯片上是奢侈的；而 BasicOS 采用 “共享任务栈” 的方式，实现了任务切换与栈空间复用的兼顾，极大地压缩了内存开销，为低成本 MCU 系统量身定制；

目标：让 RTOS 能在资源极度受限的 MCU 上运行自如；

极简协作式内核，不抢占也高效

BasicOS 明确定位为 协作式内核，不使用抢占调度，任务切换完全由用户控制；

协作式内核的优势在于：

无隐式中断上下文切换
更低的调试成本
避免共享资源竞争
执行流程更加可预测、逻辑更清晰

BasicOS 的设计理念认为：大多数嵌入式产品并不需要“毫秒级以下”的硬实时；对于 10ms 级别的任务响应，协作式足够胜任，而且更加稳定、易于维护；

共享栈是技术核心与突破

BasicOS 最引人注目的技术，是它引入了在 32 位 ARM 芯片中非常罕见的任务共享栈机制；

每次任务切换时，系统会将前一个任务的栈数据压缩保存，当前任务的栈重新展开；这种机制虽然带来一些上下文切换开销，但换来的，是大幅度降低的 RAM 消耗：

每个任务只占用 16 字节元数据
共享同一个运行栈
显著提高 RAM 利用率

这是 BasicOS 区别于其他 RTOS 的最大技术特征和未来持续发展的主轴；

轻学习曲线，亲民易用

相比更先进但入门门槛更高的 EventOS Nano（引入面向对象、事件驱动、控制反转等概念），BasicOS 明显更具普适性：

C语言风格直观
简单 API（例如 bos_delay_ms、bos_task_export）
明确的任务结构
清晰的调度逻辑

这降低了嵌入式初学者使用 RTOS 的门槛，也便于项目快速落地；

核心机制

PendSV_Handler

这是 Cortex-M 处理器专用于 RTOS 上下文切换的异常向量，BasicOS 也采用它来完成任务切换；

基本流程如下：

flowchart TD
    A[PendSV_Handler触发] --> B{bos_current为NULL？}
    B -- 是 --> E[跳过保存，直接恢复新任务]
    B -- 否 --> C[保存当前任务上下文
压栈r4-r11]
    C --> D[继续切换流程]
    E --> D
    D --> F{是否需要栈迁移？}
    F -- 否 --> H[跳转恢复下一个任务]
    F -- 是 --> G[进行内存块复制（栈迁移）]
    G --> H
    H --> I[从 bos_next 恢复 SP]
    I --> J[设置 bos_current = bos_next]
    J --> K[弹出 r4-r11，恢复上下文]
    K --> L[返回下一个任务继续执行]

在 BasicOS 中，任务主动让出 CPU（例如调用 bos_yield()）会触发 PendSV 异常，从而进入上下文切换流程；

关键变量作用说明（从 .s 文件可见）：

变量名	说明
bos_current	当前运行任务的控制块指针
bos_next	准备运行的下一个任务的控制块指针
addr_source	当前任务栈需要迁移的数据源地址
addr_target	下一个任务栈的目标地址（即 SP 指针新位置）
copy_size	栈数据迁移的大小（以字节计）

任务上下文保存

在当前任务退出时（即任务切换之前）：

PUSH {r4-r7}       ; 先保存低寄存器
MOV  r4, r8
MOV  r5, r9
MOV  r6, r10
MOV  r7, r11
PUSH {r4-r7}       ; 再保存高寄存器

保存的寄存器集合为：r4-r11，这是 ARM Cortex-M 在 RTOS 中典型的 callee-saved 寄存器集合；

恢复任务上下文

在新任务切换进来前：

POP {r4-r7}
MOV r8, r4
MOV r9, r5
MOV r10, r6
MOV r11, r7
POP {r4-r7}

共享栈的实现：运行时栈数据拷贝机制

这是 BasicOS 与普通 RTOS 最大的不同：

普通 RTOS 做法：每个任务独立分配一段栈空间，切换时只需切换 SP；
BasicOS 做法：所有任务共用一段物理栈空间，切换时必须将上一个任务的栈数据搬走，并将下一个任务的栈内容搬进当前栈位置；

实现方式：

判断 addr_target 和 addr_source 的关系，决定复制方向（前向或逆向）
以 word（4字节）为单位，逐字节移动任务的完整栈内容
Loop2_P：前向复制（正序）
Loop2_N：逆向复制（反向，避免内存重叠）

关键 API 实现简析

bos_critical_enter / bos_critical_exit：用于进入/退出临界区，避免任务切换导致的数据竞争；

1 2	CPSID I ; 禁用中断，进入临界区 CPSIE I ; 开启中断，退出临界区

协作式内核也需要临界保护，防止任务间修改共享数据时出现竞态；

get_sp_value：获取当前任务的栈指针，可用于调试或任务切换前的状态保存；

1	MOV r0, sp ; 读取当前任务的栈顶

总结

从裸机开发出发，BasicOS 提供了一种极具实用性的**“中间形态”**：它没有传统 RTOS 的复杂调度和庞大资源开销，也不再依赖“主循环 + 中断”这种高度耦合的代码结构，而是通过共享栈协作式调度的核心机制，在资源受限的 Cortex-M0/M3 等平台上，达到了结构清晰、可维护性强、资源使用极小的理想状态；

它的设计哲学并不激进，但足够务实：以极简的结构解决系统管理问题，以极低的门槛带来结构化开发的好处，尤其适合那些希望从裸机过渡到更系统性开发方式的项目；

如果说 FreeRTOS 等RTOS更像是一座技术体系完备的高楼大厦，那 BasicOS 则是打下基础的一块块砖石；它让我们意识到：结构化的好，不一定非要以“重量”为代价；

下一篇，我们将通过一个具体的案例，看看如何在 BasicOS 上构建一个由多个任务组成的嵌入式应用系统，真正迈出从“裸机跑代码”到“结构清晰可控”的第一步；

Docker容器访问N系显卡

2024-06-13T12:32:26.000Z

参考文章：https://www.cnblogs.com/linhaifeng/p/16108285.html

在进行深度学习、图像处理或视频编解码等计算密集型任务时，GPU 的加速能力几乎是刚需；而如果我们选择使用 Docker 部署这些应用，让容器能够直接访问宿主机的 GPU 就变得非常关键；

相比直接在物理机或虚拟环境中运行程序，通过 Docker 使用宿主机 GPU 有以下几大优势：

环境隔离：每个容器都可以拥有独立的依赖、驱动版本和运行环境，不怕“装坏”系统；
更灵活的部署：GPU 资源可以按需挂载到不同容器，便于多项目并行运行；
启动快、迁移轻：容器镜像打包后，可快速迁移到其他支持 GPU 的机器上部署；
配合 nvidia-docker 使用更丝滑：NVIDIA 官方提供的 nvidia-container-toolkit 工具链，支持零配置挂载 GPU 驱动和 CUDA 库；
可通过 Docker 的参数控制容器能使用哪一块 GPU，避免资源争用；

本篇文章将介绍如何让 Docker 容器访问宿主机的 GPU，并实际运行一个简单的测试案例验证 GPU 是否成功启用；

安装 NVIDIA Container Toolkit

如果你希望 Docker 容器也能像宿主机一样使用 GPU 进行加速计算，那么安装 NVIDIA 官方提供的 NVIDIA Container Toolkit 是关键的一步；

这个工具链可以帮助我们将宿主机的 GPU 驱动和 CUDA 库映射进容器内部，使得容器可以像“原生运行”一样调用 GPU 资源；

首先，根据你的 Linux 系统版本添加 NVIDIA 的软件源并安装工具包：

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt update && sudo apt install -y nvidia-container-toolkit
sudo systemctl restart docker

安装完成后，nvidia-container-toolkit 会自动配置 Docker，使其支持 –gpus 参数，用于将 GPU 挂载到容器中；

验证安装是否成功

要验证安装是否成功，可以通过以下命令检查 Docker 是否已识别 –gpus 参数支持：

1	docker run --help \| grep -i gpus

如果能看到类似 –gpus 的输出，说明 Toolkit 已成功生效；

你还可以运行 NVIDIA 提供的 CUDA 基准容器来确认 GPU 是否真的可用：

1	docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

输出应该类似于宿主机运行 nvidia-smi 的结果，显示当前 GPU 的使用状态、驱动版本、CUDA 版本等信息；

启动一个带 GPU 的容器

1	docker run --gpus all -itd --name 容器名镜像名 bash --privileged=true

–gpus all：将所有可用的 GPU 设备挂载到容器中；
-itd：交互式后台运行容器；
–name my-gpu-container：指定容器名称；
–privileged=true：容器具有更高权限（某些情况下处理硬件设备更稳定）；

如果你只想绑定特定编号的 GPU（比如第 0 和第 2 块），也可以这样写：

1	docker run --gpus '"device=0,2"' ...

总结

总的来说，通过 NVIDIA Container Toolkit 和 –gpus 参数，Docker 容器可以在保持环境隔离的同时，毫无障碍地访问宿主机的 GPU，这为部署 AI 模型训练、视频转码、科学计算等任务提供了极大的便利；

接下来，你可以尝试基于 GPU 的 Python 脚本、TensorFlow、PyTorch 或自定义镜像，在 Docker 容器中真正跑起来；

STM32MP157 移植笔记（一）：U-Boot 编译与启动调试

2024-04-26T14:36:11.000Z

近年来，异构多核 SoC 在嵌入式领域越来越常见，其中 STM32MP157 凭借其** Cortex-A7 + Cortex-M4 双核架构** 和良好的开源生态，成为许多开发者进行 Linux 系统移植和定制的理想平台；

相比传统的裸机 MCU 开发，STM32MP157 的启动流程更为复杂，涉及 BootROM → FSBL（如 TF-A）→ U-Boot → 内核 → 根文件系统 多个阶段，每一步都可能出现问题，每一步也都值得理解与掌控；

本系列文章将以实战为核心，记录我在 STM32MP157 平台上进行完整 Linux 移植的过程：包括 U-Boot 编译与调试、设备树配置、内核裁剪与驱动适配、根文件系统构建与挂载 等等；本篇作为第一篇，将重点放在 U-Boot 的获取、配置、编译、启动与串口调试，为后续系统启动打下基础；

本系列内容主要参考自 华清远见的嵌入式 Linux 教程，并结合我自己的实操经验进行补充、优化和归纳，力求贴近真实开发场景，便于读者实践与扩展；

如果你也在迈入 STM32MP1 系列的世界，希望本博客能帮你少走一些弯路，快速搭建起属于自己的 Linux 开发环境；

环境准备

本次移植所使用的环境基于 Ubuntu 18.04 LTS，配套的是较旧版本的 SDK 与源码（20 年），即便版本偏旧，但在 STM32MP1 系列开发中仍具代表性，适合入门与学习；

本文采用 Docker 容器方式搭建开发环境（Ubuntu 18.04 LTS），优点是可快速部署、便于还原；如果你不熟悉 Docker，也可以选择直接在虚拟机或实体机中安装 Ubuntu 18.04 环境；
容器采用 bind 挂载本地 SDK 和源码目录，便于调试与编译；建议通过 –privileged 启动容器，并开启 /dev、/proc 等挂载；

在进行 U-Boot 编译之前，请先确保以下必要工具链已安装：

1 2	sudo apt update sudo apt install -y file tar xz-utils findutils patch make gcc bc libssl-dev g++ cpio unzip device-tree-compiler python3 nano

TF 卡分区准备

为实现 TF 卡启动，我们需要手动对 TF 卡进行分区和格式化，确保各阶段引导程序能被正确识别与加载；

清除原有分区表并建立新的 MSDOS 分区表：

1	sudo parted -s /dev/sdX mklabel msdos

使用 sgdisk 对 TF 卡重建分区表（含启动及根文件系统）：

sudo sgdisk --resize-table=128 -a 1 \
-n 1:34:545     -c 1:fsbl1 \
-n 2:546:1057   -c 2:fsbl2 \
-n 3:1058:5153  -c 3:ssbl \
-n 4:5154:136225 -c 4:bootfs \
-n 5:136226     -c 5:rootfs \
-A 4:set:2 -p /dev/sdX -g

执行成功如下所示：

请将 /dev/sdX 替换为实际的 TF 卡设备名，如 /dev/sdb，确保避免误操作破坏其他磁盘数据；

SDK 与源码获取

链接: https://pan.baidu.com/s/1PS7VjeD9nnNQvaiX0QkjDA?pwd=5mw4 提取码: 5mw4

文件为 tar.xz 格式，请使用 tar -xvf 命令解压，解压之后，可进入 stm32mp1-openstlinux-5.4-dunfell-mp1-20-06-24 查看文件，其中 sdk 就是 SDK 安装文件所在文件夹，source 就是源码所在文件夹；

SDK 安装

该 SDK 是 ST 官方构建的交叉编译工具链（Toolchain），提供了用于构建 U-Boot、Linux 内核、Buildroot 系统和用户空间程序所需的编译器、头文件与库文件；
后续进行 STM32MP157 架构相关的编译工作时，均需依赖该 SDK 环境；

SDK 在解压时需要选择一个目录，作为 SDK 的安装目录，在这里我就把 sdk 文件夹改名为 sdk_installer ，然后新建一个名为 sdk 的文件夹，作为 SDK 的实际安装目录；

1	mv sdk sdk_installer && mkdir sdk

执行之后文件结构如下：

stm32mp1-openstlinux-5.4-dunfell-mp1-20-06-24/
├── sdk_installer/         # 安装器（.sh文件）
├── sdk/                   # 安装完成的 SDK 目录
└── source/                # 包含 u-boot、kernel、buildroot 等源码

进入 sdk_installer 的目录，执行名为 st-image-weston-openstlinux-weston-stm32mp1-x86_64-toolchain-3.1-openstlinux-5.4-dunfell-mp1-20-06-24.sh 的文件，接下来会提示你输入安装目录，输入我们刚刚创建的 sdk 目录，继续根据提示输入 y ，然后等待安装完成即可，整个过程提示如下：

根据提示，我们只需要执行下面的命令，就可以使用 SDK 了：

. /root/stm32mp1-openstlinux-5.4-dunfell-mp1-20-06-24/sdk/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi

# 或者可以执行
source /root/stm32mp1-openstlinux-5.4-dunfell-mp1-20-06-24/sdk/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi

每次手动执行 source 命令略显繁琐，我们可以将它加入 .bashrc 文件，让终端在启动时自动加载，提升开发效率：

1	nano ~/.bashrc

在文件末尾添加下面这条命令，然后保存退出：

1	. /root/stm32mp1-openstlinux-5.4-dunfell-mp1-20-06-24/sdk/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi

再执行 . ~/.bashrc 命令，使配置生效；

配置成功之后，执行 echo $CC 和 echo $ARCH 命令，如果输出如下，则表示 SDK 配置成功：

提示：安装 SDK 的意义不只是配置 $CC 和 $ARCH，更重要的是自动设置了交叉工具链、动态库路径、头文件路径等编译参数，使得我们可以一条命令完成 U-Boot、内核、应用程序等的 ARM 架构编译；
sdk_installer 以及 tar.xz 文件可以删除，后续编译过程中不再需要；

源码获取

进入 source 目录，可以看到里面包含多个源码文件夹，其中 u-boot、kernel、buildroot 是我们移植过程中需要用到的，其他文件夹可以忽略；

1	cd sources/arm-ostl-linux-gnueabi && ls

可以看到，u-boot、kernel、buildroot 等源码文件夹都在这里：

U-Boot 编译

源码准备

上一步看到的源码仍然是压缩包，我们进入 U-Boot 的目录，在目录下能看到 README.HOW_TO.txt 文件，里面介绍了依赖的安装和源码的解压，我们按照文件操作即可；

安装依赖

1	sudo apt install libncurses5-dev libncursesw5-dev

SDK 环境加载，这一步和之前 SDK 安装时一样，不再赘述；

源码解压与补丁

tar xfz u-boot-stm32mp-2020.01-r0.tar.gz

cd u-boot-stm32mp-2020.01

for p in `ls -1 ../*.patch`; do patch -p1 < $p; done

配置与编译

复制默认配置文件

首先，基于 ST 官方的 trusted 配置，我们复制一份作为我们板子的基础配置：

1
2
3

cp configs/stm32mp15_trusted_defconfig configs/stm32mp15_emtime_trusted_defconfig

make stm32mp15_emtime_trusted_defconfig

板级设备树修改

ST 的默认设备树不包含我们自定义的板卡信息，因此需要在 arch/arm/dts/ 中添加我们自己的设备树文件，设备树可以参考 arch/arm/dts/ 目录下的其它配置，甚至可以先直接用官方的（只要你的硬件契合），主要涉及以下几个文件（以官方文件为例）：

1
2
3

arch/arm/dts/stm32mp15xx-dkx.dtsi
arch/arm/dts/stm32mp157a-dk1.dts
arch/arm/dts/stm32mp157a-dk1-u-boot.dtsi

可以将文件复制一份，自己定义一个名字，然后修改文件，添加自己板子的硬件信息：

1
2
3

cp arch/arm/dts/stm32mp15xx-dkx.dtsi arch/arm/dts/stm32mp15xx-emtime.dtsi
cp arch/arm/dts/stm32mp157a-dk1.dts arch/arm/dts/stm32mp157a-emtime.dts
cp arch/arm/dts/stm32mp157a-dk1-u-boot.dtsi arch/arm/dts/stm32mp157a-emtime-u-boot.dtsi

修改其中的文件，修改文件引用相关的信息，如下：

将 arch/arm/dts/stm32mp157a-emtime.dts 的 #include “stm32mp15xx-dkx.dtsi” 改为 #include “stm32mp15xx-emtime.dtsi”
修改 arch/arm/dts/Makefile，在 stm32mp157 (dtb-$(CONFIG_STM32MP15x)) 中加入我们自己刚刚添加的文件，即加上 stm32mp157a-emtime.dtb \

注意：这一部分必须按照你实际情况进行修改（比如修改电源配置、增加 SD 卡支持、增加 eMMC 驱动、添加网卡驱动等），否则会导致无法正常引导或者无法正常驱动的问题；

之后有机会，我会专门写一篇关于设备树的文章，介绍如何编写设备树；
虽然我现在还没有编写这一部分的文章，但是设备树是 Linux 内核中非常重要的一部分，也是嵌入式开发中非常重要的一部分，所以建议有时间的话，一定要去学习一下；

bootcmd 修改

若要进行bootcmd的修改，则可以修改 include/configs/stm32mp1.h 文件，在 #ifdef CONFIG_BOOTCOMMAND 之后添加如下代码：

#ifdef CONFIG_BOOTCOMMAND

#undef CONFIG_BOOTCOMMAND

#endif

#define CONFIG_BOOTCOMMAND \
"if ext4ls mmc 1:2 /; then " \
"setenv bootcmd ext4load mmc 1:2 c2000000 uImage; " \
"setenv bootcmd \"${bootcmd};ext4load mmc 1:2 c4000000 stm32mp157a-emtime.dtb\"; " \
"setenv bootcmd \"${bootcmd};bootm c2000000 - c4000000\"; " \
"setenv bootargs rootwait rw console=ttySTM0,115200 root=/dev/mmcblk1p3; " \
"saveenv; run bootcmd; " \
"else run bootcmd_stm32mp; fi"

这里采用了偷懒的方法，在判断 CONFIG_BOOTCOMMAND 宏定义的地方，直接将 CONFIG_BOOTCOMMAND 宏定义取消，然后重新定义了 CONFIG_BOOTCOMMAND 宏定义，这样在编译的时候，就会使用我们重新定义的宏定义，而不会使用默认的宏定义；
为什么我要重写 bootcmd？因为他们设计的这一版板子，boot 拨码开关有问题，无论怎么拨，都会进入 USB 烧录模式，但如果是 USB 烧录的情况，那么是不会正常加载eMMC的，所以我使用了 ext4ls 命令判断 eMMC 是否正常挂载，如果正常挂载，则加载内核和设备树，然后启动，否则执行默认的 bootcmd_stm32mp 进入下载模式；

后续找到了 bootcmd 和 bootargs 的定义，在 include/env_default.h 文件下，可以自行去修改；

U-Boot 配置

执行 make menuconfig 命令，进入配置界面：

1	make menuconfig

其实大部分我们都不用修改，因为我们复制的是官方的配置，官方的配置已经包含了我们需要的配置，而且因为是 U-Boot 的配置，并不需要配置太多驱动相关的东西，这里提一嘴 bootcmd value 吧，在这里我们也可以修改 bootcmd，如果这里修改了，那么上面代码中的操作是可以省略的；

配置完之后记得保存，然后就可以退出 menuconfig 界面了；

如果修改了配置，那么记得更新配置文件：

1	cp .config configs/stm32mp15_emtime_trusted_defconfig

编译

修改上一个目录中的 Makefile 文件：

1	nano ../Makefile.sdk

对文件进行如下操作：

在UBOOT_CONFIGS中添加stm32mp15_emtime_trusted_defconfig,trusted,u-boot.stm32
在DEVICE_TREE中添加stm32mp157a-emtime

然后进行编译即可：

1
2
3

make distclean

make -f $PWD/../Makefile.sdk all UBOOT_CONFIGS=stm32mp15_emtime_trusted_defconfig,trusted,u-boot.stm32 -j$(nproc) 2> error.log

可以通过 cat error.log 查看编译错误，如果编译成功，那么会在 ../build-trusted 目录下会生成对应的文件，比如我们这里就是如下图框住的 u-boot-stm32mp157a-emtime-trusted.stm32 文件；

使用 sudo dd if=../build-trusted/u-boot-stm32mp157a-emtime-trusted.stm32 of=/dev/sdXY bs=1024 seek=8 conv=fsync,notrunc 命令将生成的文件烧录到 SD 卡中，然后就可以正常引导了；

未完待续…

Letter Shell：自定义函数参数解析

2024-02-15T02:50:19.000Z

仓库：https://github.com/NevermindZZT/letter-shell

前言

在嵌入式项目中，将函数导出为 Shell 命令是一项非常实用的能力；然而，随着调试和控制需求的增加，我们往往希望调用的函数能够接受多个参数，甚至是不同类型的复杂参数，而不仅仅是简单地触发执行；

为了解决这一需求，Letter Shell 提供了“函数签名（Function Signature）”机制；通过为函数指定参数类型，Shell 能够在命令行中自动完成字符串到对应类型的转换，从而支持整型、浮点、字符串、指针等多种参数的解析；这个机制让 Shell 不再只是“命令触发器”，而是一个支持复杂交互的真正调试接口；

本节将介绍函数签名机制的使用方式、参数类型的定义方式以及注意事项，帮助你实现更强大、更灵活的 Shell 命令调用功能；

函数签名引入

从 3.2.x 版本开始，Letter Shell 引入了 函数签名（Function Signature） 的概念；以往 Shell 调用函数时，会根据输入参数“猜测”目标类型并尝试转换；这个机制在简单命令中还能应付，但在类型较复杂或参数较多的情况下，错误率明显升高，一旦类型猜错，轻则输出异常，重则直接跑飞；

于是，现在你可以选择开启一个新的宏：

1	SHELL_USING_FUNC_SIGNATURE

开启后，Shell 会依据你提供的“函数签名”字符串，对参数进行明确且严格的类型解析，从而彻底摆脱以往“猜类型”的粗放方式；

一旦参数类型和签名不匹配，Shell 会自动停止命令执行，这也算是多了一层保护；毕竟，错误执行一个函数远比拒绝执行带来的代价大得多；

基本类型支持

函数签名是一个字符串，用来声明函数每个参数的类型；以下是当前版本支持的基本类型签名：

类型	签名
char（字符）	c
char（数字）	q
short（数字）	h
int（数字）	i
char*（字符串）	s
void*（任意指针）	p

函数的返回值不参与签名声明，仅声明参数类型即可；

1	int func(int a, char *b, char c);

对应的函数签名是：

"isc"

使用方法

在使用 SHELL_EXPORT_CMD 宏导出命令时，只需要在最后添加 .data.cmd.signature = “…” 即可，示例代码如下：

void shellFuncSignatureTest(int a, char *b, char c)
{
    printf("a = %d, b = %s, c = %c\r\n", a, b, c);
}

SHELL_EXPORT_CMD(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC),
funcSignatureTest, shellFuncSignatureTest, test function signature,
.data.cmd.signature = "isc");

就这么简单，你只需声明一次签名，Shell 便会在每次命令调用时，自动进行对应的参数解析与校验；

自定义参数类型解析

函数签名不仅支持基础类型，还支持结构体等自定义类型的解析；自定义签名格式为：

L<类型名>;

比如自定义一个结构体：

typedef struct {
    int a;
    char *b;
} TestStruct;

函数签名如下：

1	"iLTestStruct;s"

则代表函数的参数为：int、TestStruct* 和 char*；

注册解析器

要让 Shell 正确解析 TestStruct，我们需要写一个解析器函数，并通过宏注册：

int testStructParser(char *string, void **param)
{
    TestStruct *data = malloc(sizeof(TestStruct));
    data->b = malloc(16);
    if (sscanf(string, "%d %s", &(data->a), data->b) == 2)
    {
        *param = (void *)data;
        return 0;
    }
    return -1;
}

如果解析过程中涉及动态分配内存，推荐再提供一个清理函数：

int testStructCleaner(void *param)
{
    TestStruct *data = (TestStruct *)param;
    free(data->b);
    free(data);
    return 0;
}

注册方式如下：

1	SHELL_EXPORT_PARAM_PARSER(0, LTestStruct;, testStructParser, testStructCleaner);

如果不需要清理（比如结构体全是值类型），可以把最后一个参数设为 NULL；

函数导出 + 自定义参数组合示例

void shellParamParserTest(int a, TestStruct *data, char *c)
{
    uint8_t temp[100] = {0};
    Shell *shell = shellGetCurrent();

    sprintf((char *)temp, "a = %d, data->a = %d, data->b = %s, c = %s\r\n", a, data->a, data->b, c);
    shellWriteString(shell, (const char *)temp);
}

SHELL_EXPORT_CMD_SIGN(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC),
paramParserTest, shellParamParserTest, test function signature and param parser,
iLTestStruct;s);

使用示例，终端中输入命令如下：

1	paramParserTest 1 "12 2a" "apple"

解释如下：

参数1：int → 1
参数2：TestStruct* → data->a = 12, data->b = “2a”
参数3：char* → “apple”

这里用双引号包住结构体参数是为了清晰分割，但实际输入中引号可选（Shell 会智能处理）；

数组参数解析引入

从 Letter Shell 3.2.3 版本开始，函数签名机制进一步增强，新增了 数组参数 的支持，适用于如 int[]、char *[]、自定义结构体数组等情况；

启用方法

要启用数组参数解析功能，需要：

开启宏开关：SHELL_SUPPORT_ARRAY_PARAM
配置内存分配函数：确保宏 SHELL_MALLOC 和 SHELL_FREE 被定义，指向你项目中的内存分配函数（如使用 FreeRTOS，可指向 pvPortMalloc 和 vPortFree，裸机系统下可绑定 malloc / free 或其他实现）；

数组签名语法

在原有类型签名前加 [ 表示这是一个数组类型参数；例如：

类型	签名
int[]	[i
TestStruct*[]	[LTestStruct;

完整签名可组合使用，如：

1	"i[i[LTestStruct;"

表示的类型分别为：

int
int []（整型数组）
TestStruct*[]（结构体指针数组）

示例代码

int shellArrayTest(int a, int *b, TestStruct **datas)
{
    int i;
    printf("a = %d, b = %p, datas = %p\r\n", a, b, datas);
    for (i = 0; i < shellGetArrayParamSize(b); i++)
    {
        printf("b[%d] = %d\r\n", i, b[i]);
    }
    for (i = 0; i < shellGetArrayParamSize(datas); i++)
    {
        printf("datas[%d]->a = %d, datas[%d]->b = %s\r\n", i, datas[i]->a, i, datas[i]->b);
    }
    return 0;
}

SHELL_EXPORT_CMD_SIGN(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC),
arrayTest, shellArrayTest, test array param parser,
i[i[LTestStruct;);

使用示例，终端中输入命令如下：

1	arrayTest 12 [65, 89, 45] ["100 hello", "56 world"]

含义解析如下：

参数1：int → 12
参数2：int [] → {65, 89, 45}
参数3：TestStruct []（结构体数组）→
- datas[0]->a = 100, datas[0]->b = “hello”
- datas[1]->a = 56, datas[1]->b = “world”

提示：数组用中括号括起来，元素之间用英文逗号分隔；结构体数组的每个元素用双引号包裹，格式与结构体解析规则一致；

总结

通过引入函数签名机制，Letter Shell 显著提升了命令行参数解析的可靠性与灵活性，使其不仅仅是一个简单的命令触发器，更是一个具备强交互能力的调试入口；无论是基础类型、指针类型，还是结构体乃至结构体数组，用户都可以借助清晰的签名字符串和自定义解析器，实现类型安全且表达力丰富的参数传递；

此外，函数签名机制还为 Shell 使用者提供了更明确的接口约束，有效避免了因类型错误导致的崩溃或异常；配合内存管理机制、解析器注册机制和数组支持，Letter Shell 已具备构建嵌入式调试框架所需的高级能力；

对于追求高可靠性和高可维护性的嵌入式项目来说，掌握并使用好函数签名功能，将为 Shell 接口的设计与扩展带来极大的便利和安全保障；

Letter Shell：自定义命令

2024-02-15T01:22:38.000Z

仓库：https://github.com/NevermindZZT/letter-shell

前言

在完成基本交互功能和修复了一些常见问题之后，Letter Shell 已经能够稳定运行于我的嵌入式项目中；然而，项目开发中常常需要更多“定制化”的功能，比如：

注册自己的命令，快速调试；
添加快捷键，提高开发效率；
让 Shell 能调用带多个复杂参数的函数（支持自动解析参数），避免为每个测试场景重复编写包装函数；

好消息是，Letter Shell 本身就提供了完善的接口支持这些扩展；坏消息是，官方文档对这些内容略显简略，实际用起来还需要一点“摸索”；

这些扩展并非仅是“锦上添花”，而是将 Shell 从一个输入工具，变成一个真正实用的交互调试平台的关键；

Letter Shell 中，所有能被执行的“功能”：无论是你写的函数、绑定的快捷键、设置的变量，甚至是用户本身，在底层其实都被统一视为“命令项（Command）”；这些命令共享一套注册、查找与执行机制，使得 Shell 的扩展非常灵活；

不过在实际使用中，我们往往会将“自定义命令”专指 将 C 函数导出为 Shell 命令的行为，这是调试开发中最常用、最直接、最强大的手段之一；通过简单的宏定义，就可以将任意函数变成终端可调用的命令，极大提升调试效率和系统可观测性；

写在前面

Letter Shell 针对常用编译器都提供了宏支持，而为了保证导出的命令不会被优化掉，不同编译器还有一些额外的配置技巧：

Keil MDK：建议在编译选项中添加 –keep shellCommand*，防止命令结构被链接器裁剪；
GCC：需要在链接脚本（ld 文件）中显式保留命令段：

1
2
3

_shell_command_start = .;
KEEP (*(shellCommand))
_shell_command_end = .;

函数命令导出

函数导出是最常见的命令注册方式，适用于调试、信息打印、功能调用等场景；

宏定义原型：

/**
 * @brief shell 命令定义
 *
 * @param _attr 命令属性
 * @param _name 命令名
 * @param _func 命令函数
 * @param _desc 命令描述
 */
#define SHELL_EXPORT_CMD(_attr, _name, _func, _desc) \
    const char shellCmd##_name[] = #_name; \
    const char shellDesc##_name[] = #_desc; \
    SHELL_USED const ShellCommand \
    shellCommand##_name SHELL_SECTION("shellCommand") =  \
    { \
        .attr.value = _attr, \
        .data.cmd.name = shellCmd##_name, \
        .data.cmd.function = (int (*)())_func, \
        .data.cmd.desc = shellDesc##_name \
    }

这行代码中将 _func 强转为 (int (*)()) 是为了兼容不同的函数签名（不管参数多少），但这样做会掩盖类型安全，有些 IDE 可能会报警告；

这种强制类型转换方式牺牲了类型检查，适合用于调试环境，但如果对类型安全有更严格要求，也可以配合包装函数使用；

使用示例：

void myShellTask(void)
{
    Shell* shell = shellGetCurrent();
    if(shell)
    {
        shellWriteString(shell, "Shell自定义程序测试");
    }
}

SHELL_EXPORT_CMD(
    SHELL_CMD_PERMISSION(0) |
    SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC) |
    SHELL_CMD_DISABLE_RETURN,
    mytest, myShellTask, print message);

使用 mytest 命令后，将输出 “Shell自定义程序测试”；这个机制可以非常方便地快速验证某个函数逻辑；

变量导出

除了函数，也可以将变量导出到 Shell 中进行读写；支持类型包括：char、short、int、字符串、指针等；

宏定义原型：

/**
 * @brief shell 变量定义
 *
 * @param _attr 变量属性
 * @param _name 变量名
 * @param _value 变量值（地址）
 * @param _desc 变量描述
 */
#define SHELL_EXPORT_VAR(_attr, _name, _value, _desc) \
    const char shellCmd##_name[] = #_name; \
    const char shellDesc##_name[] = #_desc; \
    SHELL_USED const ShellCommand \
    shellVar##_name SHELL_SECTION("shellCommand") =  \
    { \
        .attr.value = _attr, \
        .data.var.name = shellCmd##_name, \
        .data.var.value = (void *)_value, \
        .data.var.desc = shellDesc##_name \
    }

注意：_value 必须是变量的地址，除非是字符串（数组本身即指针）；如果变量是只读的，可以加上 SHELL_CMD_READ_ONLY 属性；

使用示例：

int varInt = 0;
SHELL_EXPORT_VAR(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_VAR_INT), varInt, &varInt, test);

char str[] = "test string";
SHELL_EXPORT_VAR(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_VAR_STRING), varStr, str, test);

Log log;
SHELL_EXPORT_VAR(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_VAR_POINT), log, &log, test);

上述变量在终端中直接输入变量名（如 varInt），即可显示或修改值（除非是只读变量）；

按键定义导出

除了函数和变量，也可以绑定终端中的某些按键（如 Tab、Ctrl+C）来触发特定功能；

宏定义原型：

/**
 * @brief shell 按键定义
 *
 * @param _attr 按键属性
 * @param _value 按键键值（大端序）
 * @param _func 按键函数
 * @param _desc 描述信息
 */
#define SHELL_EXPORT_KEY(_attr, _value, _func, _desc) \
    const char shellDesc##_value[] = #_desc; \
    SHELL_USED const ShellCommand \
    shellKey##_value SHELL_SECTION("shellCommand") =  \
    { \
        .attr.value = _attr|SHELL_CMD_TYPE(SHELL_TYPE_KEY), \
        .data.key.value = _value, \
        .data.key.function = (void (*)(Shell *))_func, \
        .data.key.desc = shellDesc##_value \
    }

按键值说明，按键值为按键发送的字节序列，按 大端模式 表示；例如：

Tab 键发送 0x0B：键值为 0x0B000000
方向上箭头发送序列 0x1B 0x5B 0x41：键值为 0x1B5B4100

使用示例（绑定 Ctrl+C）：

uint8_t is_CtrlC_Pressed = 0;

static void CtrlC_Interrupt(Shell* shell)
{
    // 标记 Ctrl+C 被按下，用于其他程序中判断
    is_CtrlC_Pressed = 1;

    // 下面两行是标准行为：换行 + 触发下一轮命令解析
    extern void myshellWritePrompt(Shell *shell, unsigned char newline);
    myshellWritePrompt(shell, 1);
    
    extern void myshellExec(Shell *shell);
    myshellExec(shell);
}

SHELL_EXPORT_KEY(SHELL_CMD_PERMISSION(0), 0x03000000, CtrlC_Interrupt, Ctrl_C);

这样在终端中按下 Ctrl+C 时，即可自动执行 CtrlC_Interrupt() 中定义的行为；

提示：可以使用串口调试工具（如 SecureCRT）开启“十六进制查看模式”，按下目标键并记录其字节序列，以获取精确键值；

总结

Letter Shell 的命令导出机制设计得非常灵活统一，使用 .shellCommand 段 + 宏展开的方式，让用户可以零成本地将已有的函数、变量或按键操作暴露到终端；这一机制不仅极大提高了调试效率，也为后期维护和动态控制提供了便利；

只需根据不同平台配置保留 .shellCommand 段（如通过 –keep shellCommand* 或 KEEP(*(.shellCommand))），即可确保这些命令在最终镜像中生效；

Letter Shell：问题修复与功能扩展

2024-02-15T00:01:59.000Z

仓库：https://github.com/NevermindZZT/letter-shell

前言

在之前的文章中，我介绍了 Letter Shell 的基本使用方法；在实际使用过程中，我发现 Letter Shell 存在一些小问题，也结合项目需求对其功能进行了扩展；本文将介绍这些问题的现象与修复方法，并分享新增功能的实现过程和实际用途；

问题修复（部分修复）

现象：在 Letter Shell 中，串口输入时长按退格键或 Delete 键时，终端显示存在字符残留，虽然字符已无法继续删除，但视觉上仍未完全清除；

这背后的常见原因：

终端行为：
- 串口终端（如 SecureCRT、TeraTerm、MobaXterm 等）长按退格时会快速发出多个 0x08 字节；
- 这些字符本质是 “光标后退一格”，但 Letter Shell 要负责同步显示以及缓存处理；
Letter Shell 内部处理问题：
- Letter Shell 会维护一个输入缓存；
- 如果没有正确处理 “删到头” 的情况，可能会出现：
  - 显示没擦干净（字符残留）；
  - 缓存指针已到头，仍在处理退格；
  - 没有回显正确的光标移动和空格清除字符；

修复方法要点

判断输入缓存是否为空：在 shellHandler() 中处理退格符（0x08）时，判断光标是否已在开头，防止“负向删除”（即光标越界到输入行左边界之外）;
对于连续退格，要保证：
- Shell 缓冲区更新正确；
- 串口输出内容与终端光标同步；
- 不要超出缓存边界；

修改后的完整代码

此函数整体思路是：先调整缓存，再清空并重绘整行命令，最后将光标还原至正确位置；

void shellDeleteByte(Shell *shell, signed char direction)
{
    char offset = (direction == -1) ? 1 : 0;

    if ((shell->parser.cursor == 0 && direction == 1)
        || (shell->parser.cursor == shell->parser.length && direction == -1))
    {
        return;
    }
    if (shell->parser.cursor == shell->parser.length && direction == 1)
    {
        shell->parser.cursor--;
        shell->parser.length--;
        shell->parser.buffer[shell->parser.length] = 0;
        shellDeleteCommandLine(shell, 1);
    }
    else
    {
        for (short i = offset; i < shell->parser.length - shell->parser.cursor; i++)
        {
            shell->parser.buffer[shell->parser.cursor + i - 1] = 
                shell->parser.buffer[shell->parser.cursor + i];
        }
        shell->parser.length--;
        if (!offset)
        {
            shell->parser.cursor--;
            shellWriteByte(shell, '\b');
        }
        shell->parser.buffer[shell->parser.length] = 0;
        // 将光标移动到行首
        for (short i = 0; i < shell->parser.cursor + 1; i++)
        {
            shellWriteByte(shell, '\b');
        }
        // 重新打印整个命令行
        for (short i = 0; i < shell->parser.length; i++)
        {
            shellWriteByte(shell, shell->parser.buffer[i]);
        }
        // 打印一个空格，覆盖掉原来的最后一个字符
        shellWriteByte(shell, ' ');
        // 将光标移动到正确的位置
        for (short i = shell->parser.length; i > shell->parser.cursor; i--)
        {
            shellWriteByte(shell, '\b');
        }
    }
}

该函数通过整体刷新命令行缓冲区，并手动控制光标移动，确保删除行为与终端显示保持一致，尤其适用于字符中间删除的情形；
不过在实际使用中，仍会在某些输入场景下出现字符未被正确清除的情况，说明该方案不够完全可靠；如果你对此有更优的实现思路，欢迎联系我交流（联系方式已在主页提供）；

功能扩展

在 Linux Shell 中，如果你在终端中键入了一长串命令，但突然不想执行，也不想一个一个退格删除，只需要轻轻按下 Ctrl+C，整行输入就会被取消，重新回到提示符；这种“强制销毁当前输入”的行为，对嵌入式调试来说也非常实用；
Letter Shell 默认的 Ctrl+C 实现主要用于中断长时间运行的命令，但并不具备清除当前行的效果；接下来，我们就来实现这一功能；

实现思路

使用 SHELL_EXPORT_KEY 注册一个 Ctrl+C 快捷键；
在回调函数中：
- 将 is_CtrlC_Pressed 标记设为 1（供其他任务判断是否中断）；
- 重新输出提示符（myshellWritePrompt）；
- 清空当前行缓存（myshellExec 直接执行空行）；
由于 Letter Shell 的内部函数是 static 的，我们自行实现 myshellWritePrompt 和 myshellExec 两个版本；

Ctrl+C 注册代码（port 文件中）

/* Ctrl+C 注册，键值为 0x03 */
uint8_t is_CtrlC_Pressed = 0;

static void CtrlC_Interrupt(Shell* shell)
{
    // 设置中断标志位，可供其他长运行命令判断
    is_CtrlC_Pressed = 1;

    extern void myshellWritePrompt(Shell *shell, unsigned char newline);
    myshellWritePrompt(shell, 1); // 输出新的一行提示符

    extern void myshellExec(Shell *shell);
    myshellExec(shell); // 清除当前行输入
}

SHELL_EXPORT_KEY(SHELL_CMD_PERMISSION(0), 0x03000000, CtrlC_Interrupt, Ctrl_C);

添加 myshellWritePrompt 与 myshellExec 函数（shell.c）

由于原函数是 static，我们避免直接修改 Letter Shell 源码，而是新建两个函数：

myshellWritePrompt：打印提示符

void myshellWritePrompt(Shell *shell, unsigned char newline)
{
    if (shell->status.isChecked)
    {
        if (newline)
        {
            shellWriteString(shell, "\r\n");
        }
        shellWriteString(shell, shell->info.user->data.user.name);
        shellWriteString(shell, ":");
        shellWriteString(shell, shell->info.path ? shell->info.path : "/");
        shellWriteString(shell, "$ ");
    }
    else
    {
        shellWriteString(shell, shellText[SHELL_TEXT_PASSWORD_HINT]);
    }
}

myshellExec：清空当前命令缓冲区

void myshellExec(Shell *shell)
{
    if (shell->parser.length == 0)
    {
        return;
    }

    shell->parser.buffer[shell->parser.length] = 0;

    if (shell->status.isChecked)
    {
        // 此处不添加到历史、不调用命令，仅清空缓冲区
        shellParserParam(shell); 
        shell->parser.length = shell->parser.cursor = 0;

        if (shell->parser.paramCount == 0)
        {
            return;
        }
    }
    else
    {
        shellCheckPassword(shell);
    }
}

注意：该功能依赖串口工具正确发送 0x03（Ctrl+C）字符，建议使用支持该行为的终端，如 MobaXterm、TeraTerm 等；

扩展建议：基于 is_CtrlC_Pressed 的中断任务设计

通过 is_CtrlC_Pressed 标志，用户可以在长时间运行的命令中主动检查该变量，实现软中断功能；例如：

while (running) {
    if (is_CtrlC_Pressed) {
        break;
    }
    do_some_heavy_task();
}

注意：此中断机制适用于循环任务或长延时任务的主动中断，不适用于系统层级的任务终止；

总结

本文基于 Letter Shell 在实际嵌入式项目中的使用经验，修复了输入过程中因退格处理不完整导致的字符残留问题，并新增 Ctrl+C 清除当前输入行的功能，提升了交互体验与调试效率；

在功能扩展的同时，尽量保持对原始源码的非侵入性，便于后续升级与维护；Letter Shell 作为一款轻量级命令行工具，其灵活的可扩展性值得深入挖掘；

如果你也在使用它，欢迎交流更多改进思路；