Skip to content

CREATOR Gateway

CREATOR supports the execution of RISC-V programs in real hardware devices.

Info

We also support our predefined RISC-V system calls.

Supported devices

CREATOR supports Espressif ESP32 development boards and RISC-V SBCs.

Espressif ESP32

Espressif's family of ESP32 MCUs.

These use the creator-gateway-esp32.

Single-Board Computers

RISC-V SBC boards with Linux that can run SSH and GDBGUI. At the moment, SBC RISC-V boards with Ubuntu 24.04.3 for RISC-V fulfill these requirements.

These use the creator-gateway-sbc.

Executing the ESP32 gateway

Docker execution

This is the recommended way of executing the gateway on Windows, Linux, or macOS.

For more information, see the IDF documentation.

Windows

  1. Install Docker Desktop
  2. Connect your device and check which port it belongs to. You can do this with the mode terminal command, or in the Device Manager. The default port is COM3.

  3. Set up the Remote Serial Port:

    1. Download and unzip esptool
    2. Run esp_ffc2217_server in the device's port (e.g. COM3): 
      esp_rfc2217_server -v -p 4000 COM3

  4. Run the container: 

    docker run --rm --name creator-gateway-esp32 -it --init -p 8080:8080 -p 5000:5000 --add-host=host.docker.internal:host-gateway creatorsim/creator-gateway-esp32:latest

    Tip

    You can also use a Docker compose file (compose.yaml):

    1. Create the following compose.yaml file: 

      services:
  creator-gateway-esp32:
    image: creatorsim/creator-gateway-esp32:latest
    ports:
      - "8080:8080" # gateway
      - "5000:5000" # gdbgui
    stdin_open: true
    tty: true
    init: true
    # for debug
    network_mode: bridge
    extra_hosts:
      - "host.docker.internal:host-gateway"

    2. Deploy the docker compose in the directory of the YAML file: 

      docker compose up

    Take into account that docker compose up is not interactive, therefore the program won't be able to read the keyboard inputs. You can run docker compose up -d and then attach to the specific container (check its name/id with docker ps) with docker attach <container>.

Linux/macOS

  1. Install Docker engine (or Docker Desktop)
  2. Connect your device and check which port it belongs to. It typically resides in /dev/, e.g. /dev/ttyUSB0. You can quickly check it with ls /dev/ttyUSB* (Linux) or ls /dev/cu.usbserial-* (macOS).

  3. Run the container: 

    docker run --rm --name creator-gateway-esp32 -it --init --device=/dev/ttyUSB0 --add-host=host.docker.internal:host-gateway -p 8080:8080 -p 5000:5000 creatorsim/creator-gateway-esp32

    Tip

    You can also use a Docker compose file (compose.yaml):

    1. Create the following compose.yaml file: 

      services:
  creator-gateway-esp32:
    image: creatorsim/creator-gateway-esp32:latest
    ports:
      - "8080:8080" # gateway
      - "5000:5000" # gdbgui
    stdin_open: true
    tty: true
    init: true
    devices:
      - /dev/ttyUSB0 # device port
    # for debug
    network_mode: bridge
    extra_hosts:
      - "host.docker.internal:host-gateway"

    2. Deploy the docker compose in the directory of the YAML file: 

      docker compose up

    Take into account that docker compose up is not interactive, therefore the program won't be able to read the keyboard inputs. You can run docker compose up -d and then attach to the specific container (check its name/id with docker ps) with docker attach <container>.

Setting up the debugger

The debugger is only available in boards with JTAG, and both USB and SERIAL ports must be connected to the computer.

Tip

For boards without the secondary port on the board, but with JTAG support, you can wire a USB-to_Dip as such:

JTAG connection

USB-to-DIP wiring for boards with JTAG support.

Linux/macOS
  1. Setup OpenOCD
  2. Download OpenOCD with ESP32 JTAG support v0.12.0-esp32-20241016 (for your OS and architecture) and unzip it

  3. Add the bin/ folder to your PATH, e.g.: 

    bash export PATH="/full/path/to/openocd-esp32/bin:$PATH"

  4. Set the OPENOCD_SCRIPTS environment variable: bash export OPENOCD_SCRIPTS="/full/path/to/openocd-esp32/share/openocd/scripts"

  5. Execute the openocd_start.sh script (inside the openocd_scripts folder in our driver) with the type of device (e.g. esp32c3) 

    ./openocd_start.sh esp32c3

  6. After the container confirms that GDBGUI is up and running, access the web interface at http://localhost:5000

Windows
  1. Install and setup Zadig

  2. List all the devices in Options > List All Devices and select USB Jtag/serial debug unit (Interface 2)

    Setting the device in Zadig

    Selecting the device in Zadig.

  3. Downgrade the driver

    Downgrading the driver

    Downgrading the device driver in Zadig.

  4. Setup OpenOCD

    1. Download OpenOCD with ESP32 JTAG support v0.12.0-esp32-20241016 (for your OS and architecture) and unzip it

    2. Add the bin\ folder to your PATH, e.g.: 

      set PATH=%PATH%;<openocd-esp32 path>\bin\

    3. Execute the openocd_start.bat script (inside the openocd_scripts folder in our driver) with the type of device (e.g. esp32c3) 

      .\openocd_start.bat esp32c3

  5. After the container confirms that GDBGUI is up and running, access the web interface at http://localhost:5000

Native execution (Linux-only)

You can run the gateway natively on your Linux device.

  1. Install Python 3.9

    • With uv: 

      uv python install 3.9

    • In Ubuntu: 

      sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.9

  2. Install the ESP-IDF framework v5.3.2

    • Follow the instructions from Espressif's documentation.
    • To ensure Python 3.9 is used for the installation, first create a virtual environment in ~/.espressif/python_env/idf5.3_py3.9_en, and activate it, before executing the install.sh script. 
      python3.9 -m venv ~/.espressif/python_env/idf5.3_py3.9_en
source ~/.espressif/python_env/idf5.3_py3.9_env/bin/activate

  3. Download and unzip the ESP32 gateway

  4. Install the python dependencies

    1. Use the install.sh script from ESP-IDF 

      /path/tp/esp-idf-v5.3.2/install.sh

    2. Install the Python dependencies with pip (move to the downloaded folder): 

      pip3 install -r requirements.txt

  5. Load the ESP-IDF environment variables (export.sh)

  6. Execute the gateway web service: 
    python3 gateway.py

Setting up the debugger

You must set up ports permissions for the JTAG. Your user must be in the plugdev and dialout groups (in Ubuntu/Debian/Fedora), or uucp (in Arch Linux).

You can add yourself to the group with usermod, e.g.:

sudo usermod -a -G dialout $USER
sudo usermod -a -G plugdev $USER

Another error might occur: gdb_exception_error -- libusb_bulk_write error: LIBUSB_ERROR_NO_DEVICE. This problem happens because the user doesn't have permission to write to the JTAG USB device, located in /dev/bus/usb/003/XXX (where XXX is a pseudo-random number).

You can check this by doing:

ls -lah /dev/bus/usb/003

total 0
drwxr-xr-x 2 root root      180 Oct  1 11:03 .
drwxr-xr-x 6 root root      120 Oct  1 10:36 ..
crw-rw-r-- 1 root root 189, 256 Oct  1 10:41 001
...
crw-rw-r-- 1 root root 189, 256 Oct  1 10:41 022

You can see the user and group are root.

To change this, we can configure udev so that, when it mounts the JTAG device it gives it the group permissions it typically gives to all other devices (uucp for Arch, dialout for Ubuntu).

Tip

To see the device's ID, run lsusb:

...
Bus 003 Device 018: ID 10c4:ea60 Silicon Labs CP210x UART Bridge
Bus 003 Device 022: ID 303a:1001 Espressif USB JTAG/serial debug unit
...

Therefore, the vendor ID for the JTAG is 303a, and the product ID is 1001, and for the UART 10c4 and ea60.

Create a new /etc/udev/rules.d/99-Espressif.rules file (with sudo!):

  • For Ubuntu/Debian/Fedora: 

    # Set default permisions when mounting Espressif USB JTAG/serial debug unit and UART

SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1001", GROUP="plugdev"
SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", GROUP="dialout", MODE="0660"

  • For Arch Linux: 

    # Set default permisions when mounting Espressif USB JTAG/serial debug unit

SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1001", GROUP="uucp"

For more information, see the JTAG documentation.

Executing the SBC gateway

Tip

Recommendations for a correct SBC setup:

  • Use the recommended power supply for your SBC
  • Use a good Ethernet Cable
  • Use a Class 10 MicroSD card from a recognizable brand from Amazon or another reliable retailer
  1. Install the OS following the SBC manufacturer's instructions
  2. Create the default folder where your CREATOR projects will be saved, e.g. ~/creator

  3. Ensure you provide the correct rights to the directory 

    sudo chown $USER:$USER ~/creator
sudo chmod u+rwx ~/creator

  4. Connect the SBC to the Internet via Ethernet or Wi-Fi if possible. !!! tip Depending on the SBC's configuration, its IP may change from time to time. Check its private IP with ip a before each use. An example IP would be 10.117.129.219.

  5. Check the SSH service status: 

    systemctl status ssh

  6. Check your username with whoami. Typically, it's ubuntu.

  7. Connect to the SBC from your computer via SSH: 

    ssh <user>@<IP>

    Tip

    Every time an SSH connection is made, the system will ask for a password. This can be overridden by copying your computer's SSH keys to the SBC.

    1. Create a new SSH key in your computer: 

      ssh-keygen -t rsa -b 4096

    2. Copy the key to the SBC 

      ssh-copy-id <user>@<IP>

  8. Download and unzip the SBC gateway in the SBC

  9. Set up the gateway (inside the gateway folder):

    1. Create a new Python virtual environment: 

      python3 -m venv .venv
source .venv/bin/activate

    2. Install the dependencies: 

      pip3 install -r requirements.txt

    Warning

    Currently, there is a small issue in GDBGUI that needs to be patched as such:

    sed -i "/extra_files=get_extra_files()/a\        allow_unsafe_werkzeug=True," .venv/lib/python3.12/site-packages/gdbgui/server/server.py

    To validate the changes, run:

    grep -n "allow_unsafe_werkzeug" .venv/lib/python3.12/site-packages/gdbgui/server/server.py

  10. Install the RISC-V Cross-Compiler on your macOS, Linux or Windows with WSL device

  11. Execute the gateway 
    python3 gateway.py

User Interface

The Target Flash menu can be accessed from Tools → Flash in the simulator view.

ESP32 Gateway User Interface

ESP32 Gateway Target Flash user interface.

First, select your device type (ESP32 or SBC) and target board.

Then, provide the target information:

  • ESP32
    • Target port: Port of the device's UART connection. The default values are:
      • Linux: /dev/ttyUSB0
      • macOS: /dev/cu.usbserial-10
      • Windows: rfc2217://host.docker.internal:4000?ign_set_control
  • SBC
    • Target user: User and IP address of the SBC (<user>@<ip>)
    • Target location: Location of the project folder (e.g. ~/creator)

Finally, provide the flash URL, the URL address of the gateway. By default, https://localhost:8080.

Buttons

  • Flash: Builds and flashes CREATOR's program into your development board.
  • Monitor: Executes development board's flashed program. It can be stopped by using the "Stop" button or the keyboard shortcuts Ctrl + ] or Ctrl + t + x.
  • Debug: If it's setup correctly, it will open another tab with an instance of GDBGUI ready to execute programs step-by-step
  • Clean: Erases gateway's copy of the program
  • Erase-flash: Erases the device's program