WPrint 3D

Web-based remote control software for FDM printers via USB serial/TTY.

WPrint 3D OS | Frontend

Caution

The new frontend is here!

In order to complete the migration, please delete your .env file as it's not necessary anymore and may break some of the new services.

FAQ

Q: Why is the .env file not necessary anymore?

A: The .env file was used to store environment variables for the old frontend and backend combination, which is now gone. The new frontend uses a different approach to store its configuration, which is done through the web interface itself. The .env file is generated automatically by the new backend during the first run. You may still edit the .env file afterwards if you want to change some internal/advanced settings, but it's not necessary for the software to run.

Q: After this upgrade, the application is not starting anymore. What should I do?

A: Try running rm -rf vendor .env, then, restart your host. If the issue persists, please create a new issue so that we can follow up on it.

Compatibility information

Printer/CNC firmware

Firmware	Support
Marlin 1.x	✅
Marlin 2.x	✅
Other firmwares	❌ No support

Note

When paused from the web or from the G-code itself, M0, M1 and M600 color swaps are supported, however, these commands could time out on some printers, if that happens, resuming from the web won't work and you'll be required to click the physical printer's button (or tap the screen if it has a touchscreen).

For compatibility and reliability reasons, M600 is converted to a sequence of M0 instead (to allow for resuming through the web).

Host architecture

Architecture	Support
arm64	✅
amd64	✅
x86	✅
Other architectures	❌ No support

Note

On a Raspberry Pi 3 or any other low-memory SBC, try running a headless OS (such as Ubuntu Server) and strip out any unnecessary components, such as snapd and multipathd. If needed, add a swap partition and enable swapping.

Operating system

Operating system	Support
GNU/Linux	✅
Windows	✅* (experimental)
MacOS	❔ Untested
Other OSes	❔ Untested (may work if they can run Docker)

Note

Windows support is experimental and relies on WSL2 which requires Windows 10 or greater. If this is of your interest, read more below.

Important

MacOS users, please create a new discussion if you try to run the software!

Talk about your experience and any roadblocks you've found.

Dependencies

• Git
• Docker and Docker Compose
• GNU/Linux or Windows 10 (or greater) with WSL2 enabled (experimental)
• USBIPD-Win (Windows only)
• WPrint 3D - Frontend^*

^* The bundled frontend is downloaded automatically during the first run. If you're a developer and run the software in developer mode, the full source code will be added to the frontend directory.

System requirements

• Any dual-core CPU running at, at least, 1 GHz
• 1 GB of memory running at any speed *
• 2 GB of storage space
• A wired network card running at, at least, 10/100 Mbps mode or a wireless network card connected to a device that can provide a 54 Mbps mode (or better) for a stable live webcam feed
• Optionally, a USB camera or a real hardwired sensor, such as a Raspberry Pi camera.

Getting started

• If you're running Windows, go to the "Preparing your Windows host" section first.

• Install docker as explained in the linked guide.

• Give yourself permission to run Docker commands by following the guide linked here, this is extremely important because we'll need to set up a few privileged containers.

• Clone this repository wherever you want, just make sure you'd have write permission with the user you're currently logged in.

  git clone -b alpha https://github.com/wprint3d/wprint3d

• Change to the created directory by running cd wprint3d.

• Now, using your favorite text editor, create a new file called .env and copy the contents of .env.example into it. If you're planning on running WPrint 3D on a Raspberry Pi, consider copying .env.rpi instead as it's been specifically optimized to run faster on its hardware.

• That's it! Plug your printer in any USB port you like and turn it on! Now, run bash run.sh to get going. The first run might take a few minutes, so you'll probably want to find something else to do in the meantime.

• If you're running Windows, go to the "Next steps on your Windows host" section.

• Once it's done, type ifconfig and copy the IP address of your machine. Type that IP address into the address bar of your browser, i.e.: https://192.168.0.2

• Follow the on-screen instructions.

Preparing your Windows host

• Install WSL2 and a GNU/Linux distribution of your choice as explained in the linked article. I highly suggest going with Ubuntu as it requires way less manual work in order to get started. This guide has been tested while using said distribution.
• Open a new Terminal and get into your GNU/Linux distribution. If your distribution is named "Ubuntu-24.04", type wsl -d Ubuntu-22.04. If you're unsure, get a list of installed distributions by running wsl --list.
• Go back to the "Getting started" section and follow the remaining steps to install Docker and setup your system.

Next steps on your Windows host

Caution

Unfortunately, direct binding to USB ports has been broken for a long time in WSL2, so you'll have to re-run these steps after each connection of your printer.

The instructions will be updated whenever this gets fixed.

• From a new Terminal window or tab, install usbipd-win by running winget install usbipd. This is required to share USB devices between Windows and the virtual machine.

  Do not enter your GNU/Linux distribution yet, this step MUST be done from the host!

• Type usbipd --list to get a list of connected devices. Take note of the VID:PID field related to your printer. Mine looks like this:

    > usbipd list
    Connected:
    BUSID  VID:PID    DEVICE                                                        STATE
    ...
    1-11   2341:0042  USB Serial Device (COM4)                                      Not shared
  

• Enable binding by running usbipd bind -i 2341:0042.

• Attach the printer to WSL2 by running usbipd attach --wsl 2341:0042.

• Now, get back into your GNU/Linux distribution. If your distribution is named "Ubuntu-24.04", type wsl -d Ubuntu-22.04. If you're unsure, get a list of installed distributions by running wsl --list.

• Run hostname -I, if more than one IP address is returned, copy the first IP address from the list. Then, paste it into a new browser tab.

• That's about it!

Known bugs

• SD printing may disrupt the negotiated serial connection. The connection should come back about a minute after finishing the print job. This bug will be worked on in the near future.

License

WPrint 3D is open-sourced software licensed under the MIT license.