Metadata-Version: 2.4
Name: velxio-updater
Version: 0.1.1
Summary: A CLI tool to update velxio projects from local diagram.json and sketch.ino files
Author-email: Samge0 <samge720@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Samge0/velxio-updater
Project-URL: Repository, https://github.com/Samge0/velxio-updater
Project-URL: Issues, https://github.com/Samge0/velxio-updater/issues
Keywords: velxio,arduino,cli,updater
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# velxio-updater

[![PyPI version](https://badge.fury.io/py/velxio-updater.svg)](https://pypi.org/project/velxio-updater/)
[![Python Versions](https://img.shields.io/pypi/pyversions/velxio-updater)](https://pypi.org/project/velxio-updater/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A CLI tool to update [velxio](https://github.com/davidmonterocrespo24/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)

Install the latest stable release:

```bash
pip install velxio-updater
```

[View on PyPI](https://pypi.org/project/velxio-updater/)

### From source

```bash
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:**
```bash
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):**
```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):**
```cmd
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:

```bash
# .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:

```bash
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:

```bash
vup
```

### Verbose Output

To see detailed progress information:

```bash
vup -v
```

### Custom File Paths

If your files are not in the current directory:

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

### Dry Run

Validate configuration without actually updating:

```bash
vup --dry-run
```

### Using with Command-line Override

You can override environment variables with command-line arguments:

```bash
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

```bash
cd ~/projects/my-arduino-project
vup
```

### Example 2: Update with verbose output

```bash
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:

```bash
# 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

```bash
pip install build
python -m build
```

### Installing in development mode

```bash
pip install -e ".[dev]"
```

### Running tests

```bash
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](https://github.com/Samge0/velxio-updater/issues).
