三分钟教学：手把手教你实现Arduino发布第三方库

news/2025/3/16 0:54:22/文章来源:https://www.cnblogs.com/FreakEmbedded/p/18774455

三分钟教学：手把手教你实现Arduino发布第三方库

原文链接：

手把手教你实现Arduino发布第三方库

摘要

Arduino 发布第三方库的流程包括：构建库的基本框架后将其打包并上传至 GitHub，在 GitHub 上创建 Tag 和 Release 后，提交到 Arduino 库管理器，最后在 Arduino IDE 进行验证。

关于我们更多介绍可以查看云文档：https://f1829ryac0m.feishu.cn/docx/SGvHdRW1eoxgGIxwIjacX7SVnVb?from=from_copylink
或者访问我们的wiki：https://github.com/leezisheng/Doc/wiki

往期推荐：

学嵌入式的你，还不会面向对象？？！

全网最适合入门的面向对象编程教程：00 面向对象设计方法导论

全网最适合入门的面向对象编程教程：01 面向对象编程的基本概念

全网最适合入门的面向对象编程教程：02 类和对象的 Python 实现-使用 Python 创建类

全网最适合入门的面向对象编程教程：03 类和对象的 Python 实现-为自定义类添加属性

全网最适合入门的面向对象编程教程：04 类和对象的Python实现-为自定义类添加方法

全网最适合入门的面向对象编程教程：05 类和对象的Python实现-PyCharm代码标签

全网最适合入门的面向对象编程教程：06 类和对象的Python实现-自定义类的数据封装

全网最适合入门的面向对象编程教程：07 类和对象的Python实现-类型注解

全网最适合入门的面向对象编程教程：08 类和对象的Python实现-@property装饰器

全网最适合入门的面向对象编程教程：09 类和对象的Python实现-类之间的关系

全网最适合入门的面向对象编程教程：10 类和对象的Python实现-类的继承和里氏替换原则

全网最适合入门的面向对象编程教程：11 类和对象的Python实现-子类调用父类方法

全网最适合入门的面向对象编程教程：12 类和对象的Python实现-Python使用logging模块输出程序运行日志

全网最适合入门的面向对象编程教程：13 类和对象的Python实现-可视化阅读代码神器Sourcetrail的安装使用

全网最适合入门的面向对象编程教程：全网最适合入门的面向对象编程教程：14 类和对象的Python实现-类的静态方法和类方法

全网最适合入门的面向对象编程教程：15 类和对象的 Python 实现-__slots__魔法方法

全网最适合入门的面向对象编程教程：16 类和对象的Python实现-多态、方法重写与开闭原则

全网最适合入门的面向对象编程教程：17 类和对象的Python实现-鸭子类型与“file-like object“

全网最适合入门的面向对象编程教程：18 类和对象的Python实现-多重继承与PyQtGraph串口数据绘制曲线图

全网最适合入门的面向对象编程教程：19 类和对象的 Python 实现-使用 PyCharm 自动生成文件注释和函数注释

全网最适合入门的面向对象编程教程：20 类和对象的Python实现-组合关系的实现与CSV文件保存

全网最适合入门的面向对象编程教程：21 类和对象的Python实现-多文件的组织：模块module和包package

全网最适合入门的面向对象编程教程：22 类和对象的Python实现-异常和语法错误

全网最适合入门的面向对象编程教程：23 类和对象的Python实现-抛出异常

全网最适合入门的面向对象编程教程：24 类和对象的Python实现-异常的捕获与处理

全网最适合入门的面向对象编程教程：25 类和对象的Python实现-Python判断输入数据类型

全网最适合入门的面向对象编程教程：26 类和对象的Python实现-上下文管理器和with语句

全网最适合入门的面向对象编程教程：27 类和对象的Python实现-Python中异常层级与自定义异常类的实现

全网最适合入门的面向对象编程教程：28 类和对象的Python实现-Python编程原则、哲学和规范大汇总

全网最适合入门的面向对象编程教程：29 类和对象的Python实现-断言与防御性编程和help函数的使用

全网最适合入门的面向对象编程教程：30 Python的内置数据类型-object根类

全网最适合入门的面向对象编程教程：31 Python的内置数据类型-对象Object和类型Type

全网最适合入门的面向对象编程教程：32 Python的内置数据类型-类Class和实例Instance

全网最适合入门的面向对象编程教程：33 Python的内置数据类型-对象Object和类型Type的关系

全网最适合入门的面向对象编程教程：34 Python的内置数据类型-Python常用复合数据类型：元组和命名元组

全网最适合入门的面向对象编程教程：35 Python的内置数据类型-文档字符串和__doc__属性

全网最适合入门的面向对象编程教程：36 Python的内置数据类型-字典

全网最适合入门的面向对象编程教程：37 Python常用复合数据类型-列表和列表推导式

全网最适合入门的面向对象编程教程：38 Python常用复合数据类型-使用列表实现堆栈、队列和双端队列

全网最适合入门的面向对象编程教程：39 Python常用复合数据类型-集合

全网最适合入门的面向对象编程教程：40 Python常用复合数据类型-枚举和enum模块的使用

全网最适合入门的面向对象编程教程：41 Python常用复合数据类型-队列（FIFO、LIFO、优先级队列、双端队列和环形队列）

全网最适合入门的面向对象编程教程：42 Python常用复合数据类型-collections容器数据类型

全网最适合入门的面向对象编程教程：43 Python常用复合数据类型-扩展内置数据类型

全网最适合入门的面向对象编程教程：44 Python内置函数与魔法方法-重写内置类型的魔法方法

全网最适合入门的面向对象编程教程：45 Python实现常见数据结构-链表、树、哈希表、图和堆

全网最适合入门的面向对象编程教程：46 Python函数方法与接口-函数与事件驱动框架

全网最适合入门的面向对象编程教程：47 Python函数方法与接口-回调函数Callback

全网最适合入门的面向对象编程教程：48 Python函数方法与接口-位置参数、默认参数、可变参数和关键字参数

全网最适合入门的面向对象编程教程：49 Python函数方法与接口-函数与方法的区别和lamda匿名函数

全网最适合入门的面向对象编程教程：50 Python函数方法与接口-接口和抽象基类

全网最适合入门的面向对象编程教程：51 Python函数方法与接口-使用Zope实现接口

全网最适合入门的面向对象编程教程：52 Python函数方法与接口-Protocol协议与接口

全网最适合入门的面向对象编程教程：53 Python字符串与序列化-字符串与字符编码

全网最适合入门的面向对象编程教程：54 Python字符串与序列化-字符串格式化与format方法

全网最适合入门的面向对象编程教程：55 Python字符串与序列化-字节序列类型和可变字节字符串

全网最适合入门的面向对象编程教程：56 Python字符串与序列化-正则表达式和re模块应用

全网最适合入门的面向对象编程教程：57 Python字符串与序列化-序列化与反序列化

全网最适合入门的面向对象编程教程：58 Python字符串与序列化-序列化Web对象的定义与实现

全网最适合入门的面向对象编程教程：59 Python并行与并发-并行与并发和线程与进程

0.引言

上期教程我们讲到如何发布 Python/Micropython 的库函数，那么 Arduino 第三方库应该如何发布呢？我们想要通过 Arduino IDE 中的库管理工具找到自己编写的库，又该如何操作呢？
本期教程以 Arduino 版本的串口舵机库为例，给大家进行展示，相关操作视频可以查看：

让你的代码被全世界使用！手把手教你发布Arduino 第三方库

1.库文件基本框架

一个典型的 Arduino 库目录结构有以下几个关键部分：

YourLibraryName/├── src/                         // 源代码目录（必须）│    ├── YourLibraryName.h       // 头文件│    └── YourLibraryName.cpp     // 源文件├── examples/                    // 示例代码目录（可选但推荐）│    └── one/                    // 第一个示例代码文件夹│        └── one.ino             // 示例代码1│    └── two/                    // 第二个示例代码文件夹│        └── two.ino             // 示例代码2│    └── three/                  // 第三个示例代码文件夹│        └── three.ino           // 示例代码3├── library.properties           // 库的元数据文件（必须）├── keywords.txt                 // 语法高亮关键字（可选）├── README.md                    // 文档└── LICENSE                      // 许可证

1.1 src/ `-` 源代码目录（必须）

在这个目录下，存放的是库的核心代码，主要包含。

YourLibraryName.h：头文件，声明你的库的类、函数以及其他需要公开的接口。
YourLibraryName.cpp：源文件，定义你在头文件中声明的函数和类的具体实现。

1.2 examples/ - 示例代码目录（可选但推荐）

examples 文件夹是用来存放例程的，帮助用户快速理解并使用你的库函数。

例程文件就是一个 .ino 文件，而且每一个例程放在一个文件夹中，文件夹和例程的名字需要把保持一样。

例如有三个例程，名字分别叫 one, two, three。

那么在这三个例程的文件结构应为：

── examples├── one│   └── one.ino├── two│   └── two.ino└── three└── three.ino

1.3 library.properties - 库的元数据文件（必须）

这是库的核心文件，包含关键信息，如库的名称、版本、作者、依赖关系等。

它是 Arduino IDE 正确识别和加载库所必须的，Arduino IDE 会根据它来识别库的相关信息。一个简单的 library.properties 文件如下：

name=MyLibrary
version=1.0.0
author=Your Name
maintainer=Your Email
sentence=MyLibrary is a simple library for controlling sensors.
paragraph=MyLibrary allows you to easily control sensors and devices.
category=Sensor
url=https://github.com/yourusername/MyLibrary
architectures=*

这个文件采用 INI文件格式（注意使用UTF-8****编码），该文件通常以键值对 的形式存储信息，一行一个属性，以下是它的常见字段说明：

字段	作用	示例
name	库的名称	`name=MyLibrary`
version	版本号	`version=1.2.0`
author	作者	`author=Someone`
maintainer	维护者	`maintainer=SomeoneElse`
architectures	支持的架构	`architectures=esp32`
sentence	库的简要描述	`sentence=A lightweight servo control library.`
category	库的分类	`category=Communication`
url	项目地址	url=``https://github.com/leezisheng/serial-servo
license	许可证	`license=MIT`

关于这部分的详细编写规范可以参考官方文档

1.4 keywords.txt - 语法高亮关键字（可选）

keywords.txt 文件用于定义库中的关键字（如函数、类等），以便在 Arduino IDE 中提供语法高亮显示，提升代码可读性。

该文件的语法为：

keyword[tab]KEYWORD_TOKENTYPE

每行包含一个关键字及其对应的关键字类型，二者之间使用制表符（Tab）分隔。

关键字类型决定了关键字在 Arduino IDE 中的高亮显示方式，常用的关键字类型包括：

KEYWORD1：通常用于库的类名。
KEYWORD2：通常用于库的函数名。
KEYWORD3：通常用于常量（如宏定义）。
LITERAL1 和 LITERAL2：用于字面值常量。

KEYWORD_TOKENTYPE	Use for	Theme property
`KEYWORD1`	datatypes	`editor.data_type.style`
`KEYWORD2`	functions	`editor.function.style`
`KEYWORD3`	structures	`editor.function.style`
`LITERAL1`	constants	`editor.reserved_word_2.style`
`LITERAL2`	?	`editor.function.style`

1.5 README.md - 说明文档（可参考上期）

README.md 是你库的介绍文件，通常包含：

如何安装和使用库
库的功能说明
可能的配置选项
示例代码
常见问题解答等

1.6 LICENSE - 许可证（可参考上期）

LICENSE 文件用于明确库的使用许可条款，告知用户在使用、修改和分发您的代码时的权利和限制。

1.7 `extras/` - 补充资源目录

extras 文件夹用于存放与库相关的文档或其他附加项目。Arduino IDE 不会处理 extras 文件夹中的内容，因此您可以根据需要在此文件夹中添加任何文件。

我们 README.md 文件中的图片可以放到该文件夹中

2. 将库打包

把以上文件放到一个文件夹中，确保文件夹名称与你的库名称一致。

例如，如果你的库叫 YourLibraryName，那么文件夹的名称应该是 YourLibraryName，里面包含以下文件：

YourLibraryName/├── src/                         // 源代码目录（必须）│    ├── YourLibraryName.h       // 头文件│    └── YourLibraryName.cpp     // 源文件├── examples/                    // 示例代码目录（可选但推荐）│    └── one/                    // 第一个示例代码文件夹│        └── one.ino             // 示例代码1│    └── two/                    // 第二个示例代码文件夹│        └── two.ino             // 示例代码2│    └── three/                  // 第三个示例代码文件夹│        └── three.ino           // 示例代码3├── library.properties           // 库的元数据文件（必须）├── keywords.txt                 // 语法高亮关键字（可选）├── README.md                    // 文档└── LICENSE                      // 许可证

Arduino 库的根文件夹名称必须以基本字母（A-Z 或 a-z）或数字（0-9）开头，可以使用基本字母、数字、下划线（_）、点（.）和破折号（-）。文件夹名最大长度为 63 个字符。

3.上传到 `GitHub`

将你的库上传到 GitHub，或者你可以选择其他的代码托管平台。

发布完成之后，就可以填写 url.

4.创建发布 `Release` 和标签 `Tag`

4.1 在 `GitHub` 上创建 `Tag`

点击 Tag 图标，可以看到不同版本的 Tag 记录：

4.1.1 什么是 `Tag`

Tag 是 Git 中的一种标记，用于指向某个特定的提交 commit，它通常用于标记重要的版本点（如 v1.0.0）：

类型：
- 轻量标签Lightweight Tag：只是一个指向某个提交的指针。
- 附注标签Annotated Tag：包含额外的元数据，如标签名称、作者、日期和描述信息。
用途：用于标记版本号、里程碑或重要的代码状态。

4.1.2 创建步骤

首先打开 Git Bash，创建带注释的 Tag（通常用于版本发布）：

git tag -a v1.0.0 -m "First stable release"

-a v1.0.0：指定标签名称（例如 v1.0.0）。
-m "First stable release"：为标签添加描述信息。

查看所有Tags：

git tag

创建 Tag 后，必须将其推送到 GitHub 才能让其他人看到。

推送单个 Tag：

git push origin v1.0.0

推送所有本地的 Tags：

git push origin --tags

然后就可以在 Github 仓库中，就可以看到提交的 Tag 了：

4.2 创建发布 `release`

4.2.1 什么是 `release`

Release 是 GitHub 提供的一个功能，基于 Tag 创建，用于发布软件的特定版本。

它可以包含一个 Tag、版本描述（如新特性、修复的 Bug）、附加的文件（如编译好的二进制文件、安装包）等，主要用于正式发布软件的版本，方便用户下载和使用。

注意：Release 必须基于一个 Tag。没有 Tag，就无法创建 Release。可以理解为Release 是对 Tag 的扩展，提供了更丰富的功能（如版本描述、附加文件）。

在使用场景上，Tag 适合标记内部开发中的版本或里程碑，而 Release 适合正式发布版本，供用户下载和使用。

4.2.2 发布步骤

访问你的 GitHub 仓库，在仓库的页面中，点击上方的 "Releases" 标签。

在 Releases 页面上，点击 "Draft a new release" 按钮。

选择 Tag：

在 "Tag version" 字段中，选择之前创建的 Tag（例如，v1.0.0）。如果你还没有创建 Tag，可以在这里创建新的 Tag。
如果需要，可以点击 "Create new tag" 并为其指定版本号（例如 v1.0.1）。

填写 Release 信息：

Release title：为发布版本提供一个标题（例如 Version 1.0.0 - First Stable Release）。
Description：在描述框中添加该版本的详细说明，包括新特性、已修复的 bug 或任何变更。

附加文件（可选）：

你可以上传附加的二进制文件、构建文件或源代码的压缩包。
点击 "Attach binaries by dropping them here or selecting them"，选择文件进行上传。

发布Release：

选择发布方式：
- Pre-release：如果这个版本还不稳定，可以选择勾选 "This is a pre-release" 选项，表示它是一个预发布版本。
- 如果版本已经稳定，直接点击 "Publish release" 按钮。

5.提交到 `Arduino` 库管理器

5.1Fork Arduino Library Registry

访问 Arduino 库注册页面
打开 Arduino Library Registry GitHub 页面。

Fork仓库
在页面上，你会看到 "Create a new fork" 按钮。点击该按钮，GitHub 会开始创建一个库的副本，这样你可以对其进行修改。

等待Fork完成
在 "Forking arduino/library-registry" 页面上，GitHub 会显示一个进度条，表示正在进行 Fork 操作。等到 Fork 完成后，GitHub 会自动跳转到你自己的仓库主页：

https://github.com/leezisheng/library-registry

5.2 编辑repositories.txt

访问 repositories.txt 文件
在你的 Fork 仓库主页中，找到 repositories.txt 文件。这个文件记录了所有已提交到 Library Manager 的库的仓库地址。点击这个文件名进入文件内容页面。

编辑 repositories.txt 文件
在 repositories.txt 文件页面中，点击右上角的铅笔图标（"Edit this file"）进入编辑模式。

添加你的库的 URL
在编辑器中，将你的库的 GitHub 仓库 URL 添加到列表中。你可以将 URL 添加到列表的任何位置。示例 URL 格式如下：

https://github.com/yourusername/your-library

确保这个 URL 是你库的 GitHub 仓库首页链接。

提交修改
编辑完成后，点击页面顶部的 Commit changes... 按钮。提交框会打开，你可以在这里为你的提交输入描述信息。输入描述后，点击 Commit changes 完成提交。

5.3 提交Pull Request

返回你的 Fork 仓库首页

提交更改后，你会回到 repositories.txt 文件页面。此时你会看到一个提醒，表示你在这个分支上做了修改：“This branch is 1 commit ahead of arduino:main”。

打开 Pull Request

点击页面顶部的 Contribute 按钮，然后选择 Open pull request。这会打开创建 Pull Request 的页面。

填写 Pull Request 信息

在 Pull Request 页面中，填写适当的标题和描述，说明你所做的更改。

创建 Pull Request

点击 Create pull request 按钮提交。这样，Arduino 的库管理系统将自动检查你提交的库是否符合要求。如果没有问题，Pull Request 会被合并，并且你的库将在一天内可通过 Library Manager 安装。

5.4 处理检查结果和错误

自动检查

一旦你提交了 Pull Request，Arduino 的自动检查系统将开始检查你库的合规性。检查会包括库的结构、library.properties 文件的格式、版本号、文档等。

检查失败或有问题的情况

如果 Pull Request 本身有问题，机器人会在 Pull Request 中留言，告知你需要修改的地方。你可以通过编辑你 Fork 仓库中的文件并提交更新来解决问题。

如果库本身有问题，你需要在你库的 GitHub 仓库中进行修复，更新 library.properties 文件中的版本号，并确保该库有一个有效的 Release 或 Tag（具体要求见下文）。修复后，重新创建一个 Release 或 Tag，并通知 ArduinoBot 来触发自动检查。

解决问题后重新提交

如果是 Pull Request 的问题，修改完毕后，提交新的修改，自动检查会重新运行。

如果是库本身的问题，完成修复并更新版本后，创建新的 Release 或 Tag，并通知 ArduinoBot，这样检查将重新进行。

重新提交并通过审核

只要检查通过，Pull Request 会被合并，你的库将在一天内通过 Library Manager 提供给全体用户。

https://github.com/arduino/library-registry/pull/5863