详解 KiCad HTTP Library：一个“企业级”的元器件库管理功能-电子发烧友网

“您是否还在为团队成员元件库版本不一、BOM 表整理繁琐而烦恼？KiCad Http Library 功能为您提供了一个优雅的解决方案。与传统的基于 ODBC 的数据库解决方案不同， Httplib 采用 Rest API，更开放、灵活，可以快速地与企业的 ERP/PLM 等系统进行集成，共享数据。”

老生常谈的“统一”器件库问题

对于每一位硬件工程师来说，一个规整、信息全面的元件库是高效设计的基石。然而，在传统的 EDA 工作流程中，元件库的管理往往是一件令人头疼的事情：

团队协作难：每个工程师本地都有一份元件库，版本不一，常常导致设计失误和生产问题。

信息孤岛：原理图符号、PCB 封装、3D 模型、规格书、供应商信息、库存数量…… 这些关键信息散落在各处，难以统一管理和调用。

重复劳动多：每个新项目，都需要花费大量时间整理、核对元件信息，制作 BOM 表，效率低下。

传统的解决方案通常是基于 ODBC 的数据库方案，常用的有 Altium 的 DBLib、Cadence 的 CIS、KiCad 的 Database Library 等。这些都是不错的解决方案，但问题是维护成本较高：即使一个独立的 SQL 数据库也不是大部分电子工程师可以搞定的；如果需要和 PLM/PDM 集成，更是需要电子工程师（业务）和 IT 反复沟通、确认需求，即使最终落地，也很难应用起来...

Altium 是最早意识到这个问题的公司，于是才有了后面的 Altium 365，那玩意虽然很强大也很有用，但着实太贵了，不是每个人都用得起；而且 A365 是个闭源的生态，当需要与 ERP、PLM 等企业内部系统对接时，仍然非常麻烦。

现在轮到 KiCad Http Library 出场了，和 ODBC 不同，Httplib采用了更现代、更灵活的 Rest API 方式。这意味着它的后端不再局限于一个特定的数据库，而可以是任何能够提供符合 KiCad 规范的 API 接口的 Web 服务。这为与现代云服务、SaaS 应用（如 InvenTree）以及企业自研的 Web 系统集成打开了无限可能。

我们用一张表来对比一下这些解决方案：

功能对比	KiCad Http Library	Cadence Capture CIS (ODBC)	Altium DBLib	KiCad Database Library
核心架构	Rest API (Http/Https)	ODBC (开放数据库连接)	ODBC (开放数据库连接)	ODBC (开放数据库连接)
数据源	任何支持API的Web服务 (如InvenTree, ERP, 自研系统)	任何支持ODBC的数据库 (如SQL Server, Oracle, Access)	任何支持ODBC的数据库 (如SQL Server, Oracle, Access, Excel)	任何支持ODBC的数据库 (如SQLite, MySQL, PostgreSQL)
设置复杂度	中等 (需要配置服务端点和客户端文件)	复杂 (需配置ODBC数据源, ini文件, 数据库表结构)	复杂 (需配置ODBC数据源, svn/git, 数据库表结构)	较高 (需配置ODBC驱动, .kicad_dbl文件, 数据库表结构)
实时性	极高(每次访问都可从服务器获取最新数据)	较高 (依赖数据库实时连接)	较高 (依赖数据库实时连接)	较高 (依赖数据库实时连接)
跨平台性	极佳(天然跨平台, 仅需网络连接)	较差 (ODBC驱动在不同系统下配置繁琐)	较差 (ODBC驱动在不同系统下配置繁琐)	较好 (比商业软件灵活, 但仍受ODBC驱动限制)
团队协作	非常适合(天生为远程协作设计, 权限控制灵活)	适合 (需数据库服务器支持远程访问)	适合 (需数据库服务器支持远程访问)	适合 (需数据库服务器支持远程访问)
亮点	灵活性和Web集成，可与任何现代Web系统对接	可与企业PLM系统集成，需定制开发	可与企业PLM系统集成，需定制开发	为KiCad生态提供的原生开源数据库方案
典型场景	互联网团队、需要与自研系统/InvenTree集成的团队	大型企业，有严格物料管理和审批流程	使用Altium生态系统进行设计和数据管理的企业	希望在KiCad中使用结构化数据库管理元件的团队/个人

注：KiCad 的 Database Library 暂不支持连接 Access，Excel。可以看到，KiCad HTTP Library 最大的亮点是使用 Rest API 的方式与各种系统集成。简单来说，只要企业内的系统开发符合规范的查询接口，KiCad 通过 httplib 就可以直接读取分类、数据及器件细节，非常高效。这就是为什么说 httplib 是一个“企业级”的功能，且目前其他 EDA 工具没有类似的功能。下面我们就来看下 Httplib 的实现方式。

HTTP Library

HTTP 库是 KiCad 符号库的一种，它能从外部源（例如 ERP 系统）获取元器件数据。与标准的 KiCad 库不同，它们本身不包含任何符号或封装的定义。相反，它们引用的是在其他 KiCad 库中找到的符号和封装。

HTTP 库目前是只读的，但未来将支持读/写操作。目前仅支持 REST 或类 REST 的 API，但未来可以轻松添加对其他类型库的支持。

HTTP Library 配置文件

要创建 HTTP 库，您必须创建一个配置文件，其中包含 KiCad 连接到提供库 (API) 并从中检索数据所需的信息。以下是一个完整的配置文件：

{
  "meta": {
    "version": 1.0
  },
  "name": "KiCad HTTP Library",
  "description": "A KiCad library sourced from a REST API",
  "source": {
    "type": "REST_API",
    "api_version": "v1",
    "root_url": "http://localhost:8000/kicad-api",
    "token": "usertokendatastring",
    "timeout_parts_seconds": 60,
    "timeout_categories_seconds": 600
  }
}

将以上模板复制到一个新文件中，并使用.kicad_httplib文件扩展名保存。然后，应该编辑此文件，并将root_url和token值替换为您自己的值。保存后，使用“配置符号库”对话框将此文件添加到全局符号库表中，该对话框位于 “设置”→“管理符号库…” 下。

用户可以选择配置两个超时设置。timeout_parts_seconds 设置规定了元件信息的有效期，而 timeout_categories_seconds 设置决定了类别的有效期。默认值分别设置为 60 秒和 600 秒，但如果预计数据通常保持不变，可以选择更高的值。这将显著加快符号选择器的打开速度。值得注意的是，无论这些超时设置如何，KiCad 都会在首次启动时重新缓存数据。

认证 (Authentication)

认证仅通过访问令牌 (Access Token)完成；Token 通常由提供服务的应用程序颁发。此令牌将用于每个请求中，并使用以下请求头格式：'AUTHORIZATION': 'Token usertokendatastring'。

REST API 端点定义

与 ODBC 不同，REST API 提供的是已预先格式化的信息。KiCad 不需要了解任何关于表的信息，也无需了解提供方应用程序（API）的底层数据库结构。

KiCad 需要一个根 URL (root-url)和一个API 版本 (api-version)来访问库。这些信息必须通过配置文件提供。有两个端点 (endpoint) 将为 KiCad 提供所有必要的数据，它们分别是：

categories

parts

示例

比如，使用配置文件中所示的root-url和api-version，返回属于ID = 16的分类下的所有元器件：{root-url}/{api-version}/parts/category/16.json。参照示例配置文件，相当于：http://localhost:8000/kicad-api/v1/parts/category/16.json。

另一个例子是使用非整型 ID，例如Resistors：{root-url}/{api-version}/parts/category/Resistors.json。

如下文所示，KiCad 需要一个 ID（可以是数字或非数字）用于查询 API，以及一个可选的、人类可读的名称，该名称将作为元器件名称显示给用户。如果 API 没有返回可选的name键，KiCad 将使用id键作为元器件名称。

请注意，KiCad 只接受字符串。所有整数、布尔值、双精度浮点数、单精度浮点数等都必须在响应请求时转换成字符串。

端点验证 (Endpoint Validation)

KiCad 会查询根 URL{root-url}/{api-version}/，并期望它返回一个以端点为键值对的字典。

HTTP_200_OKJSON{"categories":"","parts":""}

注意：只验证键 (key)。值 (value)可以留空或设置为实际的 URL。

获取分类 (Categories)

为了获取分类，KiCad 使用标准的 GET 请求查询{root-url}/{api-version}/categories.json。KiCad 期望服务器响应一个 JSON 格式的数组，其中包含一个或多个分类。对于每个分类，它只需要id和name，并将在符号选择器 (Symbol Chooser)中将它们显示为库。属于该分类的元器件将分别显示在这些库下面。

HTTP_200_OK[  {   "id":"16",   "name":"Active Parts/Clock and Timer ICs",   "description":"A description of Active Parts/Clock and Timer ICs"  },  {   "id":"17",   "name":"Active Parts/Driver ICs",   "description":"A description of Active Parts/Driver ICs"  },  {   "id":"20",   "name":"Active Parts/Embedded Processors and Controllers",   "description":"A description of Active Parts/Embedded Processors and Controllers"  },  {   "id":"22",   "name":"Active Parts/Interfaces",   "description":"A description of Active Parts/Interfaces"  },  {   "id":"15",   "name":"Active Parts/Logic ICs",   "description":"A description of Active Parts/Logic ICs"  }]

获取元器件

为了在 KiCad 的符号选择器中某个分类下显示元器件，KiCad 会使用标准的 GET 请求查询 parts 端点：{root-url}/{api-version}/parts/category/16.json；其中 16 是特定分类的数字 ID 示例。KiCad 期望服务器响应一个包含该特定分类下一个或多个元器件的数组。

对于每个元器件，KiCad 只需要一个id。如果需要在符号选择器中显示与id不同的名称，可以使用如下所示的可选name键。此外，还可以使用description键提供元器件描述。

HTTP_200_OK[  {   "id":"69",   "name":"830050789",   "description":"CRYSTAL 32.7680KHZ 12.5PF SMD"  },  {   "id":"40",   "name":"NE555PSR",   "description":"IC OSC SINGLE TIMER 100KHZ 8SO"  },  {   "id":"238",   "name":"TLC555CPSR",   "description":"IC OSC SINGLE TIMER 2.1MHZ 8SO"  }]

提示：由于这些元器件详情仅用于在符号选择器中进行高层级的概览，因此应该只响应所需的最少数据。这将加快数据获取过程，从而提升用户体验。因此，KiCad 只期望获取显示元器件所需的最少量的信息。在此阶段，任何其他的键/值对都将被忽略。但是，如果这样更容易实现且带宽不是问题，API 也可以发送完整的详细信息。

获取详细元器件信息

当用户在符号选择器中点击一个元器件时，KiCad 将尝试使用 parts 端点和标准的 GET 请求来检索该元器件的完整详细信息：{root-url}/{api-version}/parts/16.json。KiCad 期望得到一个单一的 JSON 对象，包含如下所示的键（注意：此示例中使用了name键）。

字典fields可以包含任意数量的附加键/值对；这也可以是一个空字典！一个key代表一个在 KiCad 符号编辑器中可见的字段名称 (FIELD Name)。服务器可以根据需要提供任意多的字段，没有数量限制。

每个KiCad 字段 (FIELD)都用一个字典表示，并且必须至少包含value键。此外，API 还可以通过可选的visible键返回该字段是否可见。如果未指定此键，KiCad 将默认显示该字段。

如上所述，所有类型都必须转换为字符串。允许的布尔值字符串为："1", "0", "true", "false", "yes", "no", "y", "n"。这些字符串不区分大小写。

HTTP_200_OK{ "id":"16", "name":"R_0R0_0603_0.125W_1%", "symbolIdStr":"Device:R", "exclude_from_bom":"False", "exclude_from_board":"False", "exclude_from_sim":"True", "fields": {   "footprint": {     "value":"Resistor_SMD:R_0603_1608Metric",     "visible":"False"    },   "datasheet": {     "value":"www.kicad.org",     "visible":"False"    },   "value": {     "value":"0R0"    },   "reference": {     "value":"R"    },   "description": {     "value":"I am a resistor",     "visible":"False"    },   "keywords": {     "value":"RES passive smd",     "visible":"False"    },   "custom1": {     "value":"MyText1",     "visible":"False"    },   "custom2": {     "value":"MyText2",     "visible":"False"    },   "custom3": {     "value":"MyText3",     "visible":"False"    }  }}

符号属性 (Symbol Attributes)

如上例所示，API 提供了包含排除标志的功能。这些属性用于在 KiCad 软件中指定某些偏好设置。当前支持以下排除标志：

exclude_from_bom(从物料清单中排除)

exclude_from_board(从电路板中排除)

exclude_from_sim(从仿真中排除)

需要注意的是，如果这些排除标志中的一个或多个未被明确指定，KiCad 将假定它们未被设置为排除。换句话说，默认行为是在相关流程（BOM 生成、电路板布局和仿真）中包含所有项目和功能，除非使用这些排除标志明确指定。

服务器响应代码 (Server Response Codes)

如果 KiCad 收到的不是HTTP 200响应，它将只向用户显示一条错误消息，并完全忽略该特定请求的结果。这意味着，如果 API 不符合要求，KiCad 最终可能无法显示部分或任何分类或元器件。

如何实测？

由于需要服务端返回 Http library 约定的格式，因此实际测试不那么容易。大神可以自己起一个本地 Server 来模拟这一过程。其他同学尝试在本地部署一些开源的系统进行尝试，比如：

Part-DB：https://github.com/Part-DB/Part-DB-server

Inventree：https://inventree.org/