CREATOR Gateway

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

[!NOTE] 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.

esp32c3
- ESP32-C3-DevKitC-02 (includes JTAG)
- ESP32-C3-DevKitM-1 (no JTAG detected)
esp32c6
- ESP32-C6-DevKitC-1 (JTAG + port included)
- ESP32-C6-DevKitM-1 (JTAG + port included)
esp32h2
- ESP32-H2-DevKitM-1 (JTAG + port)

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.

OrangePi RV2: 8 RISC-V cores, Wi-Fi and Bluetooth conection
Nezha D1-H 64 bit RISC-V: Single-core RISC-V64. It does not offer Wi-Fi connection or a GUI

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

Install Docker Desktop
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.
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
```

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):
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"
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

Install Docker engine (or Docker Desktop)
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).

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):
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"
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:

Linux/macOS

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

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

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

Set the OPENOCD_SCRIPTS environment variable: bash export OPENOCD_SCRIPTS="/full/path/to/openocd-esp32/share/openocd/scripts"
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
```
After the container confirms that GDBGUI is up and running, access the web interface at http://localhost:5000

Windows

Install and setup Zadig
List all the devices in Options > List All Devices and select USB Jtag/serial debug unit (Interface 2)
Downgrade the driver
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
```
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.

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

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
```
Download and unzip the ESP32 gateway
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
```
Load the ESP-IDF environment variables (export.sh)
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

Install the OS following the SBC manufacturer's instructions
Create the default folder where your CREATOR projects will be saved, e.g. ~/creator

Ensure you provide the correct rights to the directory

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

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.
Check the SSH service status:
```
systemctl status ssh
```
Check your username with whoami. Typically, it's ubuntu.
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>
```
Download and unzip the SBC gateway in the SBC

Set up the gateway (inside the gateway folder):

Create a new Python virtual environment:

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

Install the dependencies:

pip3 install -r requirements.txt

[!IMPORTANT] 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

Install the RISC-V Cross-Compiler on your macOS, Linux or Windows with WSL device
Execute the gateway
```
python3 gateway.py
```

User Interface

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

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

Gateway

CREATOR Gateway

Supported devices

Espressif ESP32

Single-Board Computers

Executing the ESP32 gateway

Docker execution

Windows

Linux/macOS

Setting up the debugger

Linux/macOS

Windows

Native execution (Linux-only)

Setting up the debugger

Executing the SBC gateway

User Interface

Buttons

results matching ""

No results matching ""