拓冰网站定制 
Velxio开发者教程如何为模拟器添加一个新电子元件从元数据生成到引脚映射的完整指南【免费下载链接】velxioEmulate Arduino, ESP32 Raspberry Pi. in your browser. Write code, compile, and run on 19 real boards — Arduino Uno, ESP32, ESP32-C3, Raspberry Pi Pico, Raspberry Pi 3, and more. No hardware, no cloud, no limits.. Discord: https://discord.gg/3mARjJrh4E项目地址: https://gitcode.com/gh_mirrors/ve/velxioVelxio 是一款运行在浏览器中的开源嵌入式开发模拟器无需硬件、无需云服务即可编写、编译并运行 Arduino Uno、ESP32、树莓派 Pico 等 19 块真实开发板上的代码。本教程面向刚参与 Velxio 贡献的开发者手把手讲解如何为这款电子元件模拟器新增一个元件——从元数据生成流程到组件引脚Pin映射与仿真行为注册全程只需修改少量文件并执行一条命令。一、先看懂 Velxio 组件元数据流水线在动手之前理解元数据metadata从哪里来、到哪里去是避免踩坑的前提。Velxio 中每个元件要出现在画布、组件选择器和属性对话框里都依赖一份统一的元数据文件 components-metadata.json它包含元件的属性、分类、引脚数量和控件类型。这份文件不是手写的而是由生成脚本自动产出wokwi-elements 元件源码 / Velxio 原生元件声明 │ ▼ scripts/generate-component-metadata.ts ← 扫描源码 合并覆盖配置 │ ▼ frontend/public/components-metadata.json整个流程有三个关键文件文件作用scripts/generate-component-metadata.ts生成器脚本扫描元件源码并写入元数据 JSONscripts/component-overrides.json覆盖配置文件存放自定义属性和 Velxio 原生元件重新生成时不会丢失frontend/public/components-metadata.json最终产物前端运行时读取⚠️重要规则直接手改components-metadata.json是无效劳动——下次运行生成器会被整个覆盖。所有自定义都应写进component-overrides.json。完整流程说明见 组件元数据生成器文档。二、为新电子元件选择哪条接入路径Velxio 的元件库有 150 个组件新增元件分两条路wokwi-elements 元件如果你的元件已存在于 wokwi-elements 上游库只需重新运行生成器它会被自动发现零代码改动。Velxio 原生元件目录里没有的新元件如逻辑门、仪器、驱动芯片 A4988需要走下面的 5 步流程。下面以添加一个全新元件为目标讲解完整流程。第 1 步实现元件的 Web ComponentpinInfo 是引脚映射的核心Velxio 的画布、布线系统、仿真层都依赖一个约定元件必须是一个真正的 Web Component并暴露pinInfogetter 来声明引脚。你可以参考现成模板比如 velxio-junction 接线点元件readonly pinInfo: ElementPin[] [{ name: J, x: 5, y: 5, signals: [] }]; constructor() { super(); const root this.attachShadow({ mode: open }); root.innerHTML svg…你的元件图形…/svg; }pinInfo里每一项的name引脚名、x/y引脚在元件上的坐标就是后面引脚映射的锚点——画布上的导线就是根据这个信息吸附到元件引脚的。硬性规则开发板和任何需要连线的组件必须是 Web Component不能用 React SVG 实现。因为布线系统直接读取 DOM 元素的pinInfoReact SVG 没有引脚信息导线会吸附到坐标 (0, 0)。新元件放在 velxio-elements 目录下命名风格为xxx-element.ts。第 2 步注册自定义元素在文件末尾执行一次全局注册标签名建议带velxio-前缀以免与上游元件冲突customElements.define(velxio-my-part, MyPartElement);第 3 步在 component-overrides.json 中声明元件元数据打开 component-overrides.json在_customComponents数组里追加一条声明。以仓库中已有的 A4988 步进电机驱动为例字段结构如下{ id: my-part, tagName: velxio-my-part, name: My Part, category: motors, description: 一句话描述这个元件的用途, properties: [], defaultValues: {}, pinCount: 4, tags: [my-part, motor] }字段说明id元数据 ID后续注册仿真逻辑时就用它tagName与第 2 步注册的标签名一致pinCount引脚总数必须与pinInfo数量吻合tags搜索标签决定用户在组件选择器里能否搜到它properties如需在属性对话框中提供下拉、滑杆等控件可在此声明生成器会把number类型推断为滑杆、boolean推断为开关其余为文本框第 4 步在 PartSimulationRegistry 注册仿真行为元数据只解决看得见、摆得上要让新元件真正响应引脚电平变化输出类元件或触发事件输入类元件还需要在仿真注册表中登记行为。入口在 PartSimulationRegistry.ts按功能分文件存放基础元件在 BasicParts.ts传感器在 SensorParts.ts 等。以输出类元件为例结构非常直观PartSimulationRegistry.register(my-part, { onPinStateChange: (pinName, state, element) { // state 为 true 表示引脚变高电平 (element as any).value state; }, });两个关键回调回调适用场景onPinStateChange(pinName, state, element)输出类元件某数字引脚电平变化时被调用LED、蜂鸣器attachEvents(element, simulator, …)输入/复杂元件仿真启动时挂载事件、读取属性返回值是清理函数第 5 步一键重新生成元数据所有修改完成后只需在frontend/目录运行npm run generate:metadata生成器会重新扫描源码、合并component-overrides.json中的覆盖项重写元数据 JSON。若你的覆盖项生效终端会打印类似 Applied overrides for my-part的日志。三、深入理解引脚映射pinInfo 是如何变成连线的这一步是元数据与引脚映射的交汇点值得单独展开。当你在画布上点击元件引脚开始布线时前端会读取该元件 DOM 上的pinInfo数组根据x/y坐标渲染出可点击的引脚点连线完成后引脚名pinName会被写入项目的连线记录。仿真运行时引脚信号通过 PinResolver 统一解析它屏蔽了底层信号源是数字引脚管理器还是 SPICE 求解的节点电压你的attachEvents回调只需调用getPinResolver(pinName)就能拿到任意引脚的实时逻辑状态。对于简单的数字输出元件直接用onPinStateChange回调即可。如果你的新元件需要与 I2C、SPI、UART 总线对话或者需要接收属性对话框中的传感器滑杆值建议阅读 总线类元件编写指南 和 组件交互模型文档。后者的指针白名单机制尤其关键如果你的元件内部有旋钮、按钮等自己的指针交互必须把标签名加入 DynamicComponent.tsx 中的白名单否则画布会拦截指针事件旋钮转不动、按钮按不下。四、新元件上线前的检查清单✅元数据检查在生成的 components-metadata.json 中搜索你的id确认pinCount、tags、控件类型都正确。✅连线检查元件能否被正常布线若导线吸附到 (0, 0)说明你用了 React SVG 而不是 Web Component。✅仿真检查运行仿真用示波器或万用表探针确认引脚电平能正确驱动元件纯数字元件由PartSimulationRegistry驱动模拟元件由 ngspice 引擎每帧求解。✅交互检查点击元件能否打开属性对话框若被吞掉检查是否误加入了指针白名单。✅上游元件检查如果元件来自 wokwi-elements确认重新生成后被自动收录无需额外声明。五、延伸阅读更多元件扩展方向想要纯模拟仪器电压表、示波器、函数发生器它们在 component-overrides.json 的_customComponents中声明即可接线后数值实时更新甚至不需要写仿真代码详见 组件参考手册。想要自定义芯片用 C 语言写逻辑、编译到 WebAssemblyVelxio 提供了完整的自定义芯片 SDKCustom Chips 开发者指南 和 API 参考 覆盖了从建模到引脚网络的每一步。想深入了解元数据生成器的 AST 解析细节与覆盖项合并规则读 元数据生成器 Wiki。掌握Web Component 元数据声明 仿真行为注册这三件套你就具备了为 Velxio 浏览器电子元件模拟器扩展任何新元件的能力——从 150 个组件起步下一个目录里的元件也许就由你来添加。【免费下载链接】velxioEmulate Arduino, ESP32 Raspberry Pi. in your browser. Write code, compile, and run on 19 real boards — Arduino Uno, ESP32, ESP32-C3, Raspberry Pi Pico, Raspberry Pi 3, and more. No hardware, no cloud, no limits.. Discord: https://discord.gg/3mARjJrh4E项目地址: https://gitcode.com/gh_mirrors/ve/velxio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Velxio开发者教程：如何为模拟器添加一个新电子元件（从元数据生成到引脚映射的完整指南）
Velxio开发者教程如何为模拟器添加一个新电子元件从元数据生成到引脚映射的完整指南【免费下载链接】velxioEmulate Arduino, ESP32 Raspberry Pi. in your browser. Write code, compile, and run on 19 real boards — Arduino Uno, ESP32, ESP32-C3, Raspberry Pi Pico, Raspberry Pi 3, and more. No hardware, no cloud, no limits.. Discord: https://discord.gg/3mARjJrh4E项目地址: https://gitcode.com/gh_mirrors/ve/velxioVelxio 是一款运行在浏览器中的开源嵌入式开发模拟器无需硬件、无需云服务即可编写、编译并运行 Arduino Uno、ESP32、树莓派 Pico 等 19 块真实开发板上的代码。本教程面向刚参与 Velxio 贡献的开发者手把手讲解如何为这款电子元件模拟器新增一个元件——从元数据生成流程到组件引脚Pin映射与仿真行为注册全程只需修改少量文件并执行一条命令。一、先看懂 Velxio 组件元数据流水线在动手之前理解元数据metadata从哪里来、到哪里去是避免踩坑的前提。Velxio 中每个元件要出现在画布、组件选择器和属性对话框里都依赖一份统一的元数据文件 components-metadata.json它包含元件的属性、分类、引脚数量和控件类型。这份文件不是手写的而是由生成脚本自动产出wokwi-elements 元件源码 / Velxio 原生元件声明 │ ▼ scripts/generate-component-metadata.ts ← 扫描源码 合并覆盖配置 │ ▼ frontend/public/components-metadata.json整个流程有三个关键文件文件作用scripts/generate-component-metadata.ts生成器脚本扫描元件源码并写入元数据 JSONscripts/component-overrides.json覆盖配置文件存放自定义属性和 Velxio 原生元件重新生成时不会丢失frontend/public/components-metadata.json最终产物前端运行时读取⚠️重要规则直接手改components-metadata.json是无效劳动——下次运行生成器会被整个覆盖。所有自定义都应写进component-overrides.json。完整流程说明见 组件元数据生成器文档。二、为新电子元件选择哪条接入路径Velxio 的元件库有 150 个组件新增元件分两条路wokwi-elements 元件如果你的元件已存在于 wokwi-elements 上游库只需重新运行生成器它会被自动发现零代码改动。Velxio 原生元件目录里没有的新元件如逻辑门、仪器、驱动芯片 A4988需要走下面的 5 步流程。下面以添加一个全新元件为目标讲解完整流程。第 1 步实现元件的 Web ComponentpinInfo 是引脚映射的核心Velxio 的画布、布线系统、仿真层都依赖一个约定元件必须是一个真正的 Web Component并暴露pinInfogetter 来声明引脚。你可以参考现成模板比如 velxio-junction 接线点元件readonly pinInfo: ElementPin[] [{ name: J, x: 5, y: 5, signals: [] }]; constructor() { super(); const root this.attachShadow({ mode: open }); root.innerHTML svg…你的元件图形…/svg; }pinInfo里每一项的name引脚名、x/y引脚在元件上的坐标就是后面引脚映射的锚点——画布上的导线就是根据这个信息吸附到元件引脚的。硬性规则开发板和任何需要连线的组件必须是 Web Component不能用 React SVG 实现。因为布线系统直接读取 DOM 元素的pinInfoReact SVG 没有引脚信息导线会吸附到坐标 (0, 0)。新元件放在 velxio-elements 目录下命名风格为xxx-element.ts。第 2 步注册自定义元素在文件末尾执行一次全局注册标签名建议带velxio-前缀以免与上游元件冲突customElements.define(velxio-my-part, MyPartElement);第 3 步在 component-overrides.json 中声明元件元数据打开 component-overrides.json在_customComponents数组里追加一条声明。以仓库中已有的 A4988 步进电机驱动为例字段结构如下{ id: my-part, tagName: velxio-my-part, name: My Part, category: motors, description: 一句话描述这个元件的用途, properties: [], defaultValues: {}, pinCount: 4, tags: [my-part, motor] }字段说明id元数据 ID后续注册仿真逻辑时就用它tagName与第 2 步注册的标签名一致pinCount引脚总数必须与pinInfo数量吻合tags搜索标签决定用户在组件选择器里能否搜到它properties如需在属性对话框中提供下拉、滑杆等控件可在此声明生成器会把number类型推断为滑杆、boolean推断为开关其余为文本框第 4 步在 PartSimulationRegistry 注册仿真行为元数据只解决看得见、摆得上要让新元件真正响应引脚电平变化输出类元件或触发事件输入类元件还需要在仿真注册表中登记行为。入口在 PartSimulationRegistry.ts按功能分文件存放基础元件在 BasicParts.ts传感器在 SensorParts.ts 等。以输出类元件为例结构非常直观PartSimulationRegistry.register(my-part, { onPinStateChange: (pinName, state, element) { // state 为 true 表示引脚变高电平 (element as any).value state; }, });两个关键回调回调适用场景onPinStateChange(pinName, state, element)输出类元件某数字引脚电平变化时被调用LED、蜂鸣器attachEvents(element, simulator, …)输入/复杂元件仿真启动时挂载事件、读取属性返回值是清理函数第 5 步一键重新生成元数据所有修改完成后只需在frontend/目录运行npm run generate:metadata生成器会重新扫描源码、合并component-overrides.json中的覆盖项重写元数据 JSON。若你的覆盖项生效终端会打印类似 Applied overrides for my-part的日志。三、深入理解引脚映射pinInfo 是如何变成连线的这一步是元数据与引脚映射的交汇点值得单独展开。当你在画布上点击元件引脚开始布线时前端会读取该元件 DOM 上的pinInfo数组根据x/y坐标渲染出可点击的引脚点连线完成后引脚名pinName会被写入项目的连线记录。仿真运行时引脚信号通过 PinResolver 统一解析它屏蔽了底层信号源是数字引脚管理器还是 SPICE 求解的节点电压你的attachEvents回调只需调用getPinResolver(pinName)就能拿到任意引脚的实时逻辑状态。对于简单的数字输出元件直接用onPinStateChange回调即可。如果你的新元件需要与 I2C、SPI、UART 总线对话或者需要接收属性对话框中的传感器滑杆值建议阅读 总线类元件编写指南 和 组件交互模型文档。后者的指针白名单机制尤其关键如果你的元件内部有旋钮、按钮等自己的指针交互必须把标签名加入 DynamicComponent.tsx 中的白名单否则画布会拦截指针事件旋钮转不动、按钮按不下。四、新元件上线前的检查清单✅元数据检查在生成的 components-metadata.json 中搜索你的id确认pinCount、tags、控件类型都正确。✅连线检查元件能否被正常布线若导线吸附到 (0, 0)说明你用了 React SVG 而不是 Web Component。✅仿真检查运行仿真用示波器或万用表探针确认引脚电平能正确驱动元件纯数字元件由PartSimulationRegistry驱动模拟元件由 ngspice 引擎每帧求解。✅交互检查点击元件能否打开属性对话框若被吞掉检查是否误加入了指针白名单。✅上游元件检查如果元件来自 wokwi-elements确认重新生成后被自动收录无需额外声明。五、延伸阅读更多元件扩展方向想要纯模拟仪器电压表、示波器、函数发生器它们在 component-overrides.json 的_customComponents中声明即可接线后数值实时更新甚至不需要写仿真代码详见 组件参考手册。想要自定义芯片用 C 语言写逻辑、编译到 WebAssemblyVelxio 提供了完整的自定义芯片 SDKCustom Chips 开发者指南 和 API 参考 覆盖了从建模到引脚网络的每一步。想深入了解元数据生成器的 AST 解析细节与覆盖项合并规则读 元数据生成器 Wiki。掌握Web Component 元数据声明 仿真行为注册这三件套你就具备了为 Velxio 浏览器电子元件模拟器扩展任何新元件的能力——从 150 个组件起步下一个目录里的元件也许就由你来添加。【免费下载链接】velxioEmulate Arduino, ESP32 Raspberry Pi. in your browser. Write code, compile, and run on 19 real boards — Arduino Uno, ESP32, ESP32-C3, Raspberry Pi Pico, Raspberry Pi 3, and more. No hardware, no cloud, no limits.. Discord: https://discord.gg/3mARjJrh4E项目地址: https://gitcode.com/gh_mirrors/ve/velxio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考