v1.0.0 • MIT 许可证

velxio-updater

CLI 工具，从本地 diagram.json 和 sketch.ino 文件更新 velxio 项目

自动读取、转换 Wokwi 格式、一键上传至 velxio API。配置灵活，使用简单。

立即安装 GitHub 仓库
自动读取文件
格式转换
一键上传

核心特性

简单、高效、可靠。让 velxio 项目更新变得前所未有的便捷。

自动文件读取

自动从项目目录读取 diagram.json 和 sketch.ino 文件，无需手动指定路径。

智能格式转换

自动将 Wokwi 图表格式转换为 velxio 格式，保持数据完整性和兼容性。

一键上传

单条命令即可将更新上传至 velxio API，支持详细输出和干运行模式。

灵活配置

支持环境变量、.env 文件和命令行参数三种配置方式，满足不同场景需求。

安全可靠

支持 .env 文件配置敏感信息，自动忽略 .gitignore，确保凭据安全。

快速高效

优化的执行流程，支持详细输出模式，帮助快速定位和解决问题。

工作原理

三步完成项目更新，简单直观

1

准备项目文件

确保项目目录包含 diagram.json 和 sketch.ino 文件

2

配置连接信息

设置环境变量或创建 .env 文件，配置 BASE_URL、PROJECT_ID 和 ACCESS_TOKEN

3

执行更新命令

运行 vup 命令，自动完成文件读取、格式转换和上传

安装配置

从 PyPI 安装最新稳定版本

从 PyPI 安装（推荐）

pip install velxio-updater
自动获取最新稳定版本，支持所有 Python 版本

配置方式

方式 1：环境变量（推荐）

Linux/macOS：

export VELXIO_BASE_URL="http://localhost:3080"
export VELXIO_PROJECT_ID="182883dc-xxxx-xxxx-xxxx-6143cbed1b92"
export VELXIO_ACCESS_TOKEN="your-access-token-here"

Windows (PowerShell)：

$env:VELXIO_BASE_URL="http://localhost:3080"
$env:VELXIO_PROJECT_ID="182883dc-xxxx-xxxx-xxxx-6143cbed1b92"
$env:VELXIO_ACCESS_TOKEN="your-access-token-here"

方式 2：.env 文件

创建 .env 文件：

# .env file
VELXIO_BASE_URL=http://localhost:3080
VELXIO_PROJECT_ID=182883dc-xxxx-xxxx-xxxx-6143cbed1b92
VELXIO_ACCESS_TOKEN=your-access-token-here
记得将 .env 添加到 .gitignore

方式 3：命令行参数

vup --base-url http://localhost:3080 \
--project-id 182883dc-xxxx-xxxx-xxxx-6143cbed1b92 \
--access-token your-access-token-here

使用示例

快速上手，简单易用

基础使用

进入包含 diagram.json 和 sketch.ino 的项目目录并运行：

vup

详细输出

查看详细进度信息：

vup -v

自定义文件路径

指定文件路径：

vup --diagram /path/to/diagram.json --sketch /path/to/sketch.ino

干运行模式

验证配置而不实际更新：

vup --dry-run

常见问题

快速解答您可能遇到的问题

如何获取 Project ID？

Project ID 是您 velxio 项目的 UUID，可以在项目 URL 中找到：

http://localhost:3080/project/182883dc-xxxx-xxxx-xxxx-6143cbed1b92
如何获取 Access Token？

Access Token 是用于身份验证的 JWT 令牌，按以下步骤获取：

  1. 1 在浏览器中打开 velxio 实例并登录
  2. 2 打开开发者工具（F12）
  3. 3 转到 Application/Storage > Cookies
  4. 4 找到 access_token cookie
支持哪些 Python 版本？

velxio-updater 支持 Python 3.7+ 版本。建议使用最新的 Python 3.x 版本以获得最佳性能和兼容性。

如何为不同项目配置不同设置？

可以在不同项目目录中使用不同的 .env 文件：

# 项目 A
cd ~/projects/project-a
echo "VELXIO_PROJECT_ID=project-a-id" > .env
vup

# 项目 B
cd ~/projects/project-b
echo "VELXIO_PROJECT_ID=project-b-id" > .env
vup
遇到错误怎么办？

缺少必需配置

确保设置了所有必需的环境变量或通过命令行参数提供。

文件未找到

确保 diagram.json 和 sketch.ino 存在于项目目录中，或使用 --diagram 和 --sketch 参数指定路径。

请求失败

验证 velxio 服务器正在运行并可访问，检查访问令牌是否有效且未过期，确保项目 ID 正确。