How to Install Klipper on the Creality Cloud WiFi Box

The Creality Cloud WiFi Box is a fantastic concept, but a horrible product. It’s intended to rival the likes of OctoPrint and AstroBox, providing network control for 3D Printers, with a simple app interface that can slice and send files to print remotely. Unfortunately it doesn’t even meet the most basic expectations, but we can repurpose the device with Klipper firmware to unlock its full potential.

As it stands, the Creality WiFi Box is not officially supported by OpenWrt. Being the case, we will use an OpenWrt Snapshot instead. This is a customized build of the software that has been modified with all of the necessary changes.

• Download the precompiled factory.bin file to your computer
• Rename “factory.bin” to “cxsw_update.tar.bz2” so the Creality WiFi Box recognizes it
• Format a 4GB or larger microSD card as FAT32
• Place the “cxsw_update.tar.bz2” file on the microSD card

At this point, go ahead and plug in the Creality WiFi box and wait for it to boot up. When the green LED light stops flashing and goes solid, we can insert the microSD card into the side slot. The box will detect the file and start flashing the OpenWrt operating system.

With OpenWrt now installed, we can start setting it up. However, for security reasons, the WiFi feature is disabled by default. The only way to access it as-is will be hard wiring it to another device first.

Using a standard RJ45 Ethernet Cable, we can either plug the box directly into our computer (preferred) or the router. Give it a moment to establish the connection and it should become accessible over the network.

Now we should be able to connect to it over SSH (Secure Shell). Linux and Mac users are probably already familiar with this tool, where it’s built into their operating systems. For Windows users like myself though, we’ll need to download an SSH client such as PuTTY.

Enter the IP Address of the box into the Hostname field which is “192.168.1.1”. If it successfully establishes a connection, we’ll be met with a login prompt. The default username is “root” with no password.

With root access to the device, we can start configuring the Creality WiFi Box and connect it to our wireless network. Using the built-in Vi text editor, open and modify the following configuration files as per the following instructions.

/etc/config/network

Add these two lines to the end of the /etc/config/network file.

config interface 'wwan'
     option proto 'dhcp'

/etc/config/firewall

Add the config zone block below the other config zone configurations inside of /etc/config/firewall. It should be directly above the config forwarding section.

config zone
         option name             wwan
         list   network          'wwan'
         option input            ACCEPT
         option output           ACCEPT
         option forward          ACCEPT
         option masq             1
         option mtu_fix          1

/etc/config/wireless

The ‘wireless’ file is where we configure our router’s Wi-Fi details. It’s a good idea to log into your router’s admin page to ensure that the information is correct.

At the top of the ‘wireless’ file, find the config wifi-device ‘radio0’ section and change option disable ‘1’ to option disable ‘0’ as shown below.

config wifi-device 'radio0'
         option type 'mac80211'
         option channel '11'
         option hwmode '11g'
         option path 'platform/10300000.wmac'
         option htmode 'HT20'
         option disabled '0'

Add the following config wifi-iface block to the end of the ‘wireless’ file, where there should now be 3 in total.

config wifi-iface
     option network 'wwan'
     option ssid 'WIFI_SSID'
     option encryption 'psk'
     option device 'radio0'
     option mode 'sta'
     option bssid 'ROUTER_MAC_ADDRESS'
     option key 'WIFI_PASSWWORD'

There are several options here that must be set according to your own router, ssid, bssid and key.

The ssid and key are just your wireless network name and password. They are however case sensitive, so make sure to type them exactly as they appear on your network router.

The bssid is your router’s MAC address, six sets of two characters separated by a colon such as “00:1A:24:11:3A:B7”. This is usually shown on your router’s admin page or printed on the router itself.

In some cases, the encryption option will need to be changed as well. The default ‘psk’ is for WPA encryption, whereas ‘psk2’ is for WPA2 encryption. Make sure to confirm which one is used by your network.

Connect to WiFi

Once the WiFi configuration files are updated, reboot the box and unplug the ethernet cable. After a brief delay, the orange LED status light should start flashing to indicate wireless activity. If everything was done correctly, we can now reconnect via SSH over the network.

The device will be randomly assigned an available IP address, where it may be necessary to check your Router’s admin page. Look for the device called “openwrt”.

When physical resources like space or memory (RAM) are limited, a removable disk can be used to expand the capacity. In this case, we’ll look to increase both.

Storage Space (Extroot)

The Creality WiFi Box doesn’t have much onboard storage, but we’ll extend the filesystem using a microSD card and Extroot. That gives us plenty of room to install Klipper, as well as other packages like our web interface, streaming camera, etc.

Make sure the microSD card is still inserted from the previous step when we installed OpenWrt, then run the following commands.

opkg update && opkg install block-mount kmod-fs-ext4 kmod-usb-storage kmod-usb-ohci kmod-usb-uhci e2fsprogs fdisk
 DEVICE="$(sed -n -e "/\s\/overlay\s.*$/s///p" /etc/mtab)"
 uci -q delete fstab.rwm
 uci set fstab.rwm="mount"
 uci set fstab.rwm.device="${DEVICE}"
 uci set fstab.rwm.target="/rwm"
 uci commit fstab
 mkfs.ext4 /dev/mmcblk0p1
 DEVICE="/dev/mmcblk0p1"
 eval $(block info "${DEVICE}" | grep -o -e "UUID=\S*")
 uci -q delete fstab.overlay
 uci set fstab.overlay="mount"
 uci set fstab.overlay.uuid="${UUID}"
 uci set fstab.overlay.target="/overlay"
 uci commit fstab
 mount /dev/mmcblk0p1 /mnt
 cp -f -a /overlay/. /mnt
 umount /mnt
 reboot

Memory (Swap)

The Creality WiFI Box comes with 128MB of memory (RAM), more than sufficient in most cases. However, the KlipperWrt project recommends setting up Swap space on the SD card as a precautionary measure.

If the physical RAM starts running low at any point in time, the Swap partition on our SD card will be used instead. It’s much slower to read / write to a disk than the actual memory, but it can keep the device from seizing up if resource usage spikes.

opkg update && opkg install swap-utils
dd if=/dev/zero of=/overlay/swap.page bs=1M count=512
mkswap /overlay/swap.page 
swapon /overlay/swap.page
mount -o remount,size=200M /tmp 

Those commands will create the Swap, but rebooting the box right now would lose the changes. To make it persistent, we’ll activate the Swap partition at boot by adding commands to the /etc/rc.local file. Open this with a text editor and add the following lines above exit 0.

vi /etc/rc.local

swapon /overlay/swap.page
expand /tmp space
mount -o remount,size=200M /tmp

exit 0

Packages from both Python 2 and Python 3 are needed, but Python 2 is older and long since depreciated. For that reason, the existing OpenWrt distfeeds.conf file won’t be able to download everything we want. To workaround this, we’ll temporarily change the list of distribution feeds, install the Python 2 packages, and then switch it back.

cp /etc/opkg/distfeeds.conf /etc/opkg/distfeeds.original

With the original file backed up, we can temporarily modify the distfeeds.conf to include the necessary links. Open it in the Vi text editor, erase the current content and replace it with the following…

src/gz openwrt_core http://downloads.openwrt.org/releases/19.07.7/targets/ramips/mt7621/packages   
src/gz openwrt_freifunk http://downloads.openwrt.org/releases/19.07.7/packages/mipsel_24kc/freifunk  
src/gz openwrt_base http://downloads.openwrt.org/releases/19.07.7/packages/mipsel_24kc/base  
src/gz openwrt_luci http://downloads.openwrt.org/releases/19.07.7/packages/mipsel_24kc/luci  
src/gz openwrt_packages http://downloads.openwrt.org/releases/19.07.7/packages/mipsel_24kc/packages  
src/gz openwrt_routing http://downloads.openwrt.org/releases/19.07.7/packages/mipsel_24kc/routing  
src/gz openwrt_telephony http://downloads.openwrt.org/releases/19.07.7/packages/mipsel_24kc/telephony

Once the 19.07.7 distribution feeds are in place, we’ll update the Package Manager and refresh its data, then install the necessary packages.

opkg update
opkg install python python-pip python-cffi python-pyserial python-dev gcc

pip install greenlet==0.4.15 jinja2

When these have finished installing, we can delete our modified distfeeds.conf file and restore the backup. Refresh the Package Manager once more and then grab the Python 3 packages.

rm /etc/opkg/distfeeds.conf
mv /etc/opkg/distfeeds.original /etc/opkg/distfeeds.conf

opkg update
opkg install python3 python3-pyserial python3-pillow python3-tornado --force-overwrite

In addition to Python, there are a few other necessary packages like lmdb and streaming-form-data. These are precompiled and offered through the KlipperWrt project, where we can simply download and install them on our system.

cd ~
wget https://github.com/ihrapsa/KlipperWrt/raw/main/packages/python3-lmdb%2Bstreaming-form-data_packages_1.0-1_mipsel_24kc.ipk

opkg install python3-lmdb%2Bstreaming-form-data_packages_1.0-1_mipsel_24kc.ipk
opkg install nginx-ssl

With all of the dependencies now installed, it’s time to setup Klipper on the Creality WiFi Box. Start by cloning the Github repository to the root of our device.

cd ~

opkg install git-http unzip
git clone https://github.com/KevinOConnor/klipper.git

mkdir klipper_config
mkdir gcode_files

To make sure Klipper is always running in the background, we’ll also set it up as a system service. In the event the box reboots or gets disconnected, this will start the software back up automatically.

cd /etc/init.d/

wget https://raw.githubusercontent.com/ihrapsa/KlipperWrt/main/Services/klipper
chmod 755 klipper
/etc/init.d/klipper enable

Now we need to grab the Klipper configuration file that matches our 3D Printer.

After moving into the ~/klipper/config directory, run the ls command to list all of the files. Scroll through these until you find the right one, then copy it to the ~/klipper_config folder we made previously, renaming it to printer.cfg.

cd ~/klipper/config
ls

# copy the desired configuration file to our directory and rename it
cp ~/klipper/config/printer-creality-ender3-2018.cfg ~/klipper_config/printer.cfg

# open the configuration file in text editor
vi ~/klipper_config/printer.cfg

At this point we need to make a couple changes to the printer.cfg file. Scroll down until you reach the [mcu] section and set it as follows. Make sure that serial is “/dev/ttyUSB0” and add a new line for the baud rate.

[mcu]
 serial: /dev/ttyUSB0
 baud: 230400

Scroll to the end of the printer.cfg file using the Page Down key and paste the following settings at the end.

[virtual_sdcard]
# for gcode upload
path: /root/gcode_files

[display_status]
# for display messages in status panel

[pause_resume]
# for pause/resume functionality.
# Mainsail/fluidd needs gcode macros for PAUSE, RESUME and CANCEL_PRINT to make the buttons work.

[gcode_macro PAUSE]
rename_existing: BASE_PAUSE
default_parameter_X: 230    #edit to your park position
default_parameter_Y: 230    #edit to your park position
default_parameter_Z: 10     #edit to your park position
default_parameter_E: 1      #edit to your retract length
gcode:
     SAVE_GCODE_STATE NAME=PAUSE_state
     BASE_PAUSE
     G91
     G1 E-{E} F2100
     G1 Z{Z}
     G90
     G1 X{X} Y{Y} F6000

[gcode_macro RESUME]
rename_existing: BASE_RESUME
default_parameter_E: 1      #edit to your retract length
gcode:
     G91
     G1 E{E} F2100
     G90
     RESTORE_GCODE_STATE NAME=PAUSE_state MOVE=1
     BASE_RESUME

[gcode_macro CANCEL_PRINT]
rename_existing: BASE_CANCEL_PRINT
gcode:
     TURN_OFF_HEATERS
     CLEAR_PAUSE
     SDCARD_RESET_FILE
     BASE_CANCEL_PRINT

Moonraker is a Python 3 based web server that exposes various APIs in which clients are able to communicate with Klipper. In short, it takes our input on the frontend and send it to the 3D Printer on the backend. We don’t necessarily have to understand it, but we do have to install it.

Clone the Moonraker Github repository to the root of our device.

cd ~
git clone https://github.com/Arksine/moonraker.git

As we did with the Klipper service above, we’ll do the same with Moonraker to keep it running at all times.

cd /etc/init.d/

wget https://raw.githubusercontent.com/ihrapsa/KlipperWrt/main/Services/moonraker
chmod 755 moonraker
/etc/init.d/moonraker enable

Picking a web interface (commonly referred to as the ‘client’) is the fun part. This is the control panel that we will use to manage our 3D Printer remotely. They more or less share the same set of features, where it primarily comes down to the layout and which is more appealing to you.

There are several options available on the Moonraker Github page, but the most popular are Fluidd and Mainsail. Check below for a side by side comparison of the two choices.

Fluidd vs Mainsail

We’ll start by downloading the files, Fluidd or Mainsail, to our root filesystem.

Although Moonraker can only use one interface at a time, those interested in testing both can pull the Fluidd and Mainsail packages to respective ~/ directories using wget. With these copied over to our box, we’ll tell Moonraker which to use and where to find it.

The KlipperWrt repository already has configurations prepared for both clients, so we’ll grab those that are relevant and place them in the proper folders. Pick one of the following and run the commands.

Fluidd Interface

mkdir ~/fluidd
cd ~/fluidd
wget -q -O fluidd.zip https://github.com/cadriel/fluidd/releases/latest/download/fluidd.zip && unzip fluidd.zip && rm fluidd.zip

cd ~/klipper_config
wget -O moonraker.conf https://raw.githubusercontent.com/ihrapsa/KlipperWrt/main/moonraker/fluidd_moonraker.conf

cd /etc/nginx/conf.d/
wget https://raw.githubusercontent.com/ihrapsa/KlipperWrt/main/nginx/fluidd.conf

Mainsail Interface

mkdir ~/mainsail
cd ~/mainsail
wget -q -O mainsail.zip https://github.com/meteyou/mainsail/releases/latest/download/mainsail.zip && unzip mainsail.zip && rm mainsail.zip

cd ~/klipper_config
wget -O moonraker.conf https://raw.githubusercontent.com/ihrapsa/KlipperWrt/main/moonraker/mainsail_moonraker.conf

cd /etc/nginx/conf.d/
wget https://raw.githubusercontent.com/ihrapsa/KlipperWrt/main/nginx/mainsail.conf

There are two additional configurations that we need, regardless of interface. We should already be in the /etc/nginx/conf.d/ directory from the previous step, where we’ll pull the upstreams.conf and common_vars.conf files as shown below. Once done, restart the Moonraker and Nginx services.

cd /etc/nginx/conf.d/

wget https://raw.githubusercontent.com/ihrapsa/KlipperWrt/main/nginx/upstreams.conf
wget https://raw.githubusercontent.com/ihrapsa/KlipperWrt/main/nginx/common_vars.conf

service moonraker restart
service nginx restart

The Creality Cloud WiFi Box only works with the Creality webcam, but With KlipperWrt installed on the box, we’re free to use the webcam of our choosing. We just need to install the Video4Linux utilities and a few other packages.

opkg update && opkg install v4l-utils
opkg update && opkg install mjpg-streamer-input-uvc mjpg-streamer-output-http mjpg-streamer-www

Plug the webcam into the USB2 port and it should start working almost immediately. Just enable the Webcam switch via Settings -> Interface and enter the username and password. By default, they are configured as…

Username: openwrt
Password: openwrt

If you would like to change the login details, or the camera settings such as the resolution, frame rate, etc. the /etc/config/mjpg-streamer file can be customized as needed.

We’ll almost certainly forget the IP Address of the Creality WiFI Box. We could bookmark the page in our browser of course, but why not give it a friendly hostname that’s easy to remember?

Instead of accessing the Klipper control panel at a numeric address like http://192.168.1.112, we can give it a URL such as http://klipper.local instead.

Using the Vi text editor, open the system configurations file at /etc/config/system. In the top most section, change option hostname ‘OpenWrt’ to a name of your liking and save.

config system
         option hostname 'klipper'
         option timezone 'UTC'
         option ttylogin '0'
         option log_size '64'
         option urandom_seed '0'
         option compat_version '1.0'

We’ll just need to install a couple packages to make it work and a system reboot so they take effect.

opkg update
opkg install avahi-daemon-service-ssh avahi-daemon-service-http

reboot