PROS Simulator

Run PROS robot code without the need for real VEX V5 hardware.

Installation

cargo add pros-simulator

Or, as an executable JSON-based server:

cargo install pros-simulator-server

Overview

This Rust crate is a WebAssembly-based runtime for simulating VEX V5 robot code, without the need for any special hardware. It's the best way to program from home, debug misbehaving programs, and quickly iterate code design.

This runtime implements a portion of the PROS C interface, allowing pre-existing PROS-based programs to function in the simulator without the need for invasive modification. Support for pros-simulator is built directly into the pros crate, so programs using it will be compatible with this simulator without extra work.

Usage

PROS Simulator is available in library form, and also as a JSON-based server that's inspired by the LSP protocol and ideal for integrating into other programs (see releases page for ready made binaries). This project contains the core of the simulator, which handles loading and running user-generated robot code, and requires a custom interface (like a GUI or TUI) to be useful. There are a few example interfaces provided, like the TUI-based one below.

TUI Interface

To build the example simulator program, you'll need a nightly Rust toolchain and the was32-unknown-unknown target installed. In the example directory, run the following command to build:

cargo pros build -s

Then, in the project root, run the following command to start the TUI:

cargo run --example tui ./example/target/wasm32-unknown-unknown/debug/example.wasm

The simulator (and its TUI interface) support the use of breakpoints in robot code! Try opening this project in VS Code and pressing F5 to start debugging the example program.

Feature Overview

• Concurrent multitasking: Spawn tasks and manage them.
• LLEMU: Print messages to V5 LCD display.
• Serial connection: Print messages to debug terminal.
• Mutexes: Synchronize tasks.
• Task-local storage: Manage global variables that are specific to each task.
• Timings: Sleep program and get elapsed time.
• Abort messages: Get stack trace & error message on any panic or abort (including segfaults).
• Controllers: Control simulated robot using any SDL-compatible wired or bluetooth controller.
• Competition Status: Control autonomous/opcontrol/disabled status of simulated robot.
• Motors: Simulate VEX Smart Motors
• Sensors: Simulate V5-compatible sensors
• Physics: Physics simulation and graphical representation of simulated robot

Robot Code API Reference

See PROS docs for signatures and documentation. API is 1:1 except where mentioned otherwise.

• LLEMU (Legacy LCD Emulator) C API

  • lcd_clear
  • lcd_clear_line
  • lcd_initialize
  • lcd_is_initialized
  • lcd_print
  • lcd_read_buttons
  • lcd_register_btn0_cb
  • lcd_register_btn1_cb
  • lcd_register_btn2_cb
  • lcd_set_text
  • lcd_shutdown
  • lcd_set_background_color
  • lcd_set_text_color

• Miscellaneous C API

  • battery_get_capacity
  • battery_get_current
  • battery_get_temperature
  • battery_get_voltage
  • competition_get_status
  • competition_is_autonomous
  • competition_is_connected
  • competition_is_disabled
  • controller_clear
  • controller_clear_line
  • controller_get_analog
  • controller_get_battery_capacity
  • controller_get_battery_level (Return value always equal to capacity)
  • controller_get_digital
  • controller_get_digital_new_press
  • controller_is_connected
  • controller_print
  • controller_rumble
  • controller_set_text
  • usd_is_installed

• RTOS Facilities C API

  • delay
  • millis
  • micros
  • mutex_create
  • mutex_delete
  • mutex_give
  • mutex_take
  • task_create
  • task_delay
  • task_delay_until
  • task_delete
  • task_get_by_name
  • task_get_count
  • task_get_current
  • task_get_name
  • task_get_priority
  • task_get_state
  • task_notify
  • task_notify_clear
  • task_notify_ext
  • task_notify_take
  • task_join
  • task_resume
  • task_set_priority
  • task_suspend
  • rtos_suspend_all
  • rtos_resume_all
  • pvTaskGetThreadLocalStoragePointer
  • vTaskSetThreadLocalStoragePointer
  • xTaskAbortDelay

• Generic I/O API

  Undocumented/internal PROS functions that are required to support miscellaneous IO like errno, the debug terminal, and panicking.

  • _errno: Returns a mutable pointer to the errno value of the current task.
  • sim_abort(*const char) -> !: Simulator-only API for aborting with an error message.
  • sim_log_backtrace() -> (): Simulator-specific function that will print a backtrace to the debug terminal.
  • puts: Write to the debug terminal (pros terminal command from official PROS CLI)
  • exit: Cleanly shutdown