151 lines
6.9 KiB
Markdown
151 lines
6.9 KiB
Markdown
# Velxio Desktop App
|
|
|
|
Native desktop build of the Velxio simulator — same React frontend, wrapped in a Tauri shell, with the QEMU binaries bundled in. Targets Windows, macOS, and Linux.
|
|
|
|
> The desktop app is a **Pro** feature (30-day free trial). The OSS web build remains free at velxio.dev and via Docker self-host.
|
|
|
|
---
|
|
|
|
## What you get
|
|
|
|
- **Offline-capable** — the simulator keeps running with no internet. License is validated on launch with a grace period if the network is down.
|
|
- **Bundled QEMU** — `libqemu-xtensa`, `libqemu-riscv32`, and `qemu-system-aarch64` ship inside the app, so ESP32 and Raspberry Pi boards work without Docker.
|
|
- **Native menus and file system** — open `.vlx` projects from the filesystem, save without browser download prompts.
|
|
- **Local compile** — `arduino-cli`, ESP-IDF, and the custom-chip toolchain are managed by the app, with progress shown in a native panel.
|
|
- **Single-process** — frontend, backend, QEMU all in one Tauri runtime — no Docker, no localhost dance.
|
|
|
|
---
|
|
|
|
## Install
|
|
|
|
Download the installer for your platform from [velxio.dev/download](https://velxio.dev/download):
|
|
|
|
- **Windows** — `Velxio-Setup-{version}.exe` (signed)
|
|
- **macOS** — `Velxio-{version}.dmg` (notarized)
|
|
- **Linux** — `Velxio-{version}.AppImage` and `velxio_{version}_amd64.deb`
|
|
|
|
First launch downloads the toolchains it needs (~200 MB for AVR + RP2040, plus ~700 MB for ESP-IDF if you select ESP32 boards). All caches live under the OS app-data dir:
|
|
|
|
| Platform | Path |
|
|
|----------|------|
|
|
| Windows | `%APPDATA%\velxio\` |
|
|
| macOS | `~/Library/Application Support/velxio/` |
|
|
| Linux | `~/.local/share/velxio/` |
|
|
|
|
---
|
|
|
|
## License flow
|
|
|
|
The desktop app uses `vlx_pro_*` / `vlx_trial_*` keys issued by velxio.dev.
|
|
|
|
### Sign in (browser deep-link)
|
|
|
|
1. Launch the desktop app.
|
|
2. **Welcome screen** appears (the editor is hidden behind it until authorised).
|
|
3. Click **Sign in with Velxio**.
|
|
4. Your default browser opens `https://velxio.dev/auth/desktop`.
|
|
5. Sign in (or create an account) and click **Authorise Velxio Desktop**.
|
|
6. The page hands a license token back via the `velxio-desktop://auth?token=…` deep-link scheme.
|
|
7. Editor appears.
|
|
|
|
### Paste a license key manually
|
|
|
|
If your browser blocks the custom-URL scheme (some Linux distros, corporate proxies), click **Paste key** on the welcome screen and enter the `vlx_pro_*` or `vlx_trial_*` string from [Account → My licenses](https://velxio.dev/account/licenses).
|
|
|
|
### Offline grace period
|
|
|
|
Once authorised, the desktop app caches the validated key + entitlements on disk (encrypted via the OS keychain on Windows/macOS, plain file on Linux). On launch:
|
|
|
|
- **Online + valid** — proceeds normally.
|
|
- **Offline + cached key still in grace window** — a **GraceBanner** appears at the top reading "Working offline — re-validate by *date*". The editor stays usable.
|
|
- **Offline + grace window expired OR explicit invalidation** — welcome screen comes back; the editor stays hidden until re-validation succeeds.
|
|
|
|
Grace window length and revalidation cadence are set by the license server response (typically 14 days).
|
|
|
|
---
|
|
|
|
## ESP32 QEMU prompt
|
|
|
|
The first time you select an ESP32-family board on the canvas, a side panel asks you to confirm the bundled QEMU shared library was extracted successfully. If extraction failed (antivirus quarantine, missing VC++ redistributable on Windows), the panel offers a manual download link and a "Retry" button.
|
|
|
|
Once QEMU is in place, the prompt does not appear again unless the cached binary is removed.
|
|
|
|
---
|
|
|
|
## Storage layout
|
|
|
|
```text
|
|
%APPDATA%/velxio/ (Windows) or ~/Library/Application Support/velxio/ (macOS)
|
|
+- arduino-cli/ arduino-cli binary + index
|
|
+- arduino-data/ installed cores (avr, rp2040, esp32, ATTinyCore)
|
|
+- esp-idf/ ESP-IDF toolchain (~700 MB, optional)
|
|
+- qemu/ libqemu-xtensa, libqemu-riscv32, qemu-system-aarch64
|
|
+- ccache/ C/C++ object cache
|
|
+- build/ persistent ESP-IDF build dirs (per target)
|
|
+- vlx-files/ user-saved projects
|
|
+- license.json cached license payload + expiry
|
|
+- logs/ rotating log files (last 7 days)
|
|
```
|
|
|
|
Everything outside `vlx-files/` is regeneratable — you can delete the whole folder and reinstall; first launch will refetch.
|
|
|
|
---
|
|
|
|
## Tauri bridge
|
|
|
|
The renderer (React) talks to the native shell through `frontend/src/desktop/tauriBridge.ts`. The Tauri commands shipped:
|
|
|
|
| Command | Purpose |
|
|
|---------|---------|
|
|
| `license_get_key` | Read the cached license key from disk |
|
|
| `license_validate` | POST it to `https://velxio.dev/api/pro/license/validate` |
|
|
| `license_clear` | Wipe the cached key (Sign Out) |
|
|
| `qemu_check` | Verify the bundled libqemu binaries exist + are executable |
|
|
| `qemu_extract` | Re-extract the bundled binaries into the cache dir |
|
|
| `open_external` | `open` / `xdg-open` / `start` for the docs button |
|
|
| `pick_file` | OS file picker for `.vlx` import |
|
|
| `save_file` | OS save dialog for `.vlx` export |
|
|
|
|
The render-side mounts only when `VITE_DESKTOP` is set at build time, so the OSS web bundle never ships these symbols.
|
|
|
|
---
|
|
|
|
## Build from source
|
|
|
|
The desktop shell is not in this repo (it lives in the closed Tauri build). The renderer code at `frontend/src/desktop/` is what mounts on top of the regular SPA when `VITE_DESKTOP=true`.
|
|
|
|
If you want to build your own Tauri shell against the OSS frontend, the minimum requirements are:
|
|
|
|
1. A Tauri 2.x project that loads the production-built `frontend/dist` as its WebView source.
|
|
2. Implement the commands listed under "Tauri bridge" above.
|
|
3. Bundle `arduino-cli` and `libqemu-*` for your target platforms.
|
|
4. Set `VITE_DESKTOP=1` when running `npm run build` in `frontend/`.
|
|
|
|
The OSS license still applies to the React side. You provide your own Tauri Rust code and your own license server (the official one is gated to legitimate Pro subscriptions).
|
|
|
|
---
|
|
|
|
## Pricing
|
|
|
|
- **Free trial** — 30 days, full Pro features, no credit card.
|
|
- **Pro $15/mo** — desktop app + premium components on velxio.dev.
|
|
- **Pro Max $35/mo** — everything in Pro plus the in-app AI assistant and priority simulation queue.
|
|
|
|
Manage your subscription at [velxio.dev/billing](https://velxio.dev/billing).
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
- **Welcome screen won't close after sign-in** — the deep-link handler didn't fire. Click **Paste key** instead and use the key from [Account → My licenses](https://velxio.dev/account/licenses).
|
|
- **"libqemu missing" error on ESP32 boards** — the prompt to re-extract appears automatically. If it fails, antivirus likely quarantined the file; whitelist `%APPDATA%\velxio\qemu\` (Windows) or the equivalent on your OS.
|
|
- **Grace banner says "expired"** — connect to the internet briefly and the next launch will re-validate.
|
|
- **Logs** — `~/.local/share/velxio/logs/` (or equivalent). Attach the latest file when filing a bug report.
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
- [Getting Started](./getting-started.md) — Hosted, Docker, manual options
|
|
- [Emulator Architecture](./emulator.md) — How each CPU backend works
|