Important
This project is no longer officially supported. If possible, we advise you to use the QEMU-based simulator instead.
Execute vexide programs using a WebAssembly sandbox.
V5Wasm is a code executor for VEX V5 programs compiled to WebAssembly. By emulating the V5's jump table, it can run programs intended for the robot brain with minimal modifications. V5Wasm is not a GUI or application; instead, it's a simulator engine that could power one.
If you'd like any help getting this working, don't hesitate to ask on the Vexide Discord server linked on our website!
Prerequisites:
- A recent version of Rust
- CMake, so that Cargo can build SDL2
Apart from that, you should be able to run cargo install --git "https://github.com/vexide/v5wasm.git"
to install the engine.
You might also be able to get builds from the "Releases" tab on Github, but they could be out of date or missing.
V5Wasm expects a single argument <PROGRAM>
which is the path to the .wasm
program that you would like to run. In Rust projects,
this file is located at ./target/wasm32-unknown-unknown/debug/{crate-name}.wasm
.
Example usage:
cargo pros build -s
v5wasm ./target/wasm32-unknown-unknown/debug/vexide-template.wasm
After starting, V5Wasm will attempt to initiate a Vexide Simulator Protocol session over its standard output and standard input streams.
V5Wasm doesn't work with every .wasm
file, so you'll have to follow these instructions to make one that's compatible.
To make a vexide project compatible with the engine, ensure the following code snippet is somewhere in .cargo/config.toml
:
[target.wasm32-unknown-unknown]
rustflags = ["-Clink-arg=--export-memory", "-Clink-arg=--import-table"]
Then, compile the project with cargo pros build -s
or cargo build --target wasm32-unknown-unknown
.
You can use a debugger (such as LLDB or CodeLLDB in VS Code) to set breakpoints inside simulated robot code, as long as you built your program with debug symbols.
Check out .vscode/launch.json
and .vscode/tasks.json
for an example of what that might look like. Those files currently expect there to be a ../vexide
repo, and they compile the basic
example. If you have a symlink from ../vexide/target/..../basic.wasm
to program.wasm
, it should work correctly.
What's working:
- ALL of the serial SDK! (100%)
- The display SDK (98%)
- The controller SDK (90%)
- The competition SDK (50%)
- Some of the system and tasks SDK (25%-ish)
An incomplete list of what's missing:
- Every Device API (yeah...)
- Stdin
- Touch support for the display
If the simulator crashes with "No such file or directory", your program is probably missing.
If you get a "wasm trap: uninitialized element" error, it's possible an SDK call isn't implemented yet. For example, this error means vexBatteryCurrentGet
isn't implemented:
Error: error while executing at wasm backtrace:
0: 0x69340 - vex_sdk::battery::vexBatteryCurrentGet::hc5f5e7af7e7aca72
at /vex-sdk-0.12.3/src/lib.rs:79:21
1: 0x9452 - basic::main::{{closure}}::hfcc5ba2ee817eb06
at /basic.rs:14:9
(...more backtrace...)
10: 0x17b47 - vexide_startup::program_entry::hbc8e02734bc7e165
at /vexide-startup/src/lib.rs:117:9
11: 0xa17d - _entry
at /basic.rs:8:1
Caused by:
wasm trap: uninitialized element