velxio-updater 0.1.0

A CLI tool to update velxio projects from local diagram.json and sketch.ino files

velxio-updater

A CLI tool to update velxio projects from local diagram.json and sketch.ino files.

Features

• Automatically reads diagram.json and sketch.ino from your project directory
• Converts Wokwi diagram format to velxio format
• Uploads updates to velxio API with a single command
• Configuration via environment variables or command-line arguments

Installation

From PyPI (recommended once published)

pip install velxio-updater

From source

git clone https://github.com/Samge0/velxio-updater.git
cd velxio-updater
pip install -e .

Configuration

Method 1: Environment Variables (Recommended)

Set the following environment variables:

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"

Windows (Command Prompt):

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

Method 2: .env File

Create a .env file in your project directory:

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

The .env file will be automatically loaded when you run vup.

Note: Make sure to add .env to your .gitignore file to avoid committing sensitive credentials!

Method 3: Command-line Arguments

You can also pass configuration directly via command-line arguments:

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

Usage

Basic Usage

Navigate to your project directory (containing diagram.json and sketch.ino) and run:

vup

Verbose Output

To see detailed progress information:

vup -v

Custom File Paths

If your files are not in the current directory:

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

Dry Run

Validate configuration without actually updating:

vup --dry-run

Using with Command-line Override

You can override environment variables with command-line arguments:

vup --base-url http://localhost:33080 --project-id different-project-id

Getting Your Credentials

Base URL

The base URL of your velxio server, e.g., http://localhost:3080

Project ID

The UUID of your velxio project. You can find it in the project URL:

http://localhost:3080/project/182883dc-xxxx-xxxx-xxxx-6143cbed1b92

Access Token

The JWT access token for authentication. You can find it in your browser's cookies after logging into velxio:

1. Open your velxio instance in a browser
2. Open Developer Tools (F12)
3. Go to Application/Storage > Cookies
4. Find the access_token cookie

Project Structure

Your project directory should contain:

my-project/
├── diagram.json    # Circuit diagram in Wokwi format
└── sketch.ino      # Arduino sketch code

Examples

Example 1: Update from project directory

cd ~/projects/my-arduino-project
vup

Example 2: Update with verbose output

vup -v
# Output:
# Reading files from: /home/user/projects/my-arduino-project
# Board Type: arduino-uno
# Group ID: group-arduino-uno
# Updating project: 182883dc-xxxx-xxxx-xxxx-6143cbed1b92
# Sending PUT request to: http://localhost:3080/api/projects/182883dc-xxxx-xxxx-xxxx-6143cbed1b92
#
# Update successful!
# Status code: 200
# Project URL: http://localhost:3080/project/182883dc-xxxx-xxxx-xxxx-6143cbed1b92

Example 3: Different configurations for different projects

You can use .env files in different project directories:

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

# Project B
cd ~/projects/project-b
echo "VELXIO_PROJECT_ID=project-b-id" > .env
vup

Development

Building the package

pip install build
python -m build

Installing in development mode

pip install -e ".[dev]"

Running tests

pytest

Troubleshooting

Error: Missing required configuration

Make sure you have set all required environment variables or provided them via command-line arguments.

Error: File not found

Ensure that diagram.json and sketch.ino exist in your project directory, or provide custom paths using --diagram and --sketch arguments.

Error: Invalid JSON in diagram.json

Check that your diagram.json file is valid JSON format.

Error: Request failed

• Verify that your velxio server is running and accessible
• Check that your access token is valid and not expired
• Ensure the project ID is correct

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub issue tracker.