Refactor
Refactor is a complete Linux image for Recore 3D printer controller boards. It comes with Klipper installed and the choice of either MainSail or OctoPrint.
These instructions are for version v3.2. For older versions of Refactor:
Contents
- 1 Installing an image
- 2 Latest images
- 3 Installed software
- 4 Getting started
- 5 Refactor build system
Installing an image
For instructions on making a flasher image, have a look at Reflash
Latest images
The latest images for Recore and Replicape are available from github: https://github.com/intelligent-agent/Refactor/releases
Installed software
The Recore version is based on Armbian, Debian Buster. On top of that, Refactor comes preinstalled with a stack of programs to simplify setting up a new controller board.
- Klipper (v0.11.0-173-ga8b1b0ef) https://github.com/Klipper3d/klipper
- Ustreamer (master) https://github.com/pikvm/ustreamer
- Linux (5.15.113-sunxi64) https://github.com/armbian/build
- u-boot (2022.10) https://github.com/armbian/build
Recore OctoPrint
- OctoPrint (1.7.3) https://github.com/OctoPrint/OctoPrint
- Octoprint Klipper (master) https://github.com/thelastWallE/OctoprintKlipperPlugin
- Octoprint Refactor (main) https://github.com/intelligent-agent/octoprint_refactor
- OctoPrint Toggle (master) https://github.com/intelligent-agent/octoprint_toggle
- OctoPrint Top Temp (master) https://github.com/LazeMSS/OctoPrint-TopTemp.git
- Toggle (v1.4.1) https://github.com/intelligent-agent/toggle
Recore Mainsail
The Recore version is based on Armbian, Debian Buster. On top of that, Refactor comes preinstalled with a stack of programs to simplify setting up a new controller board.
- Mainsail (v2.6.0) https://github.com/intelligent-agent/mainsail
- Moonraker (v0.8.0) https://github.com/Arksine/moonraker
- KlipperScreen (v0.3.2-22) https://github.com/intelligent-agent/KlipperScreen
Getting started
It can be a good idea to test the board on the bench before installing it in the printer. Use the USB-C connector to power the board.
Once the board is powered up, use a computer to access the web interface provided by OctoPrint. In order to get access to OctoPrint, a network cable must be connected to the board and to a network switch. It is also possible to use a wifi dongle. If a network cable is used, the board should respond to the address: http://recore.local
Once the OctoPrint interface is visible, run through the wizard to set up a new printer. After the wizard is done, go to the Klipper tab in OctoPrint and edit the Klipper config file. This is where the bulk of the work will happen.
On the MainSail image, there should not need to be any configuration necessary.Verify that the
Klipper configuration
There is a standard klipper configuration file that comes with Refactor. The configuration file is set up to work out of the box without anything connected. The default Klipper config can be used as a starting point for building a custom config file for the printer at hand.
After the Klipper configuration is complete, do a test print to make sure everything is working.
Note
On Refactor 3.2.x, all hardware revisions communicate with the MCU (STM32) on UART /dev/ttyS2. This was different on previous versions of Refactor.
Recore booting
Recore comes with Refactor pre-installed.
The Recore images will need to be flashed to a USB flash drive, as there is no SD slot on the board. Recore's uboot is designed to attempt to boot from a USB drive if there is no OS on the eMMC.
There are several stages to booting Recore, and depending on which media is installed, the boot process will try and boot either from eMMC, USB host or USB device.
Booting Recore from eMMC (the normal way)
- Turn on power
- The BROM will load u-boot SPL from eMMC
- The u-boot SPL will load u-boot
- u-boot will load Linux
- Linux will load the rootfs from eMMC.
Loading u-boot from eMMC but load kernel and rootfs from USB
If the board is working normally and you are able to log in through ssh, but want to try out a new Refactor version you can let the rootfs be loaded from a USB drive (mass storage device):
- Download Refactor and flash it to a USB drive
- Insert the USB drive in the board.
- Boot the board normally
- Open the Refactor tab in OctoPrint.
- Select run from USB
- or
- Use SSH to log into the board: ssh root@recore.local
- Run the command set-boot-media usb
- Reboot
The board should now be have the rootfs from the USB drive.
Booting Recore from USB, load Linux kernel from USB drive
This method requires a UART to USB adapter that can plug into a host computer. There is a 4 pin header on Recore marked DBG, where UART 0 is routed. All u-boot and kernel messages will appear here. The baud rate is 115200. If the eMMC is partitioned and has an OS, u-boot will launch right into that. In order to override that and load the boot script from a USB drive, stop u-boot by pressing a key and then write:
- Download Refactor and flash it to a USB drive
- Insert the USB drive in the board and apply power
- When the boot process gets to u-boot, you will see: Hit any key to stop autoboot:
- Hit the Any key.
- Then write run bootcmd_usb0
This will load the U-boot script from the USB drive and use the USB drive as the rootfs.
Boot Recore from a USB stick using the FEL button
If u-boot should be loaded from a host computer and kernel and rootfs is loaded from a USB drive:
- Flash the Reflash Linux distro to a USB drive.
- Insert the USB drive in the Recore board in one of the two host connectors close to the HDMI.
- Hold down the FEL button while applying power to the board via the USB-C connector.
- Download the Recore repository https://github.com/intelligent-agent/Recore
- Install the sunxi-tools program
- Run the fel command (make fel) from the host computer. All the necessary binarys are in the Recore repository:
You can read more about the steps needed to boot aboard in FEL mode on the Sunxi wiki: https://linux-sunxi.org/FEL
Note: Depending on what linux platform you're running from, sunxi-tools will require the following dependencies to compile properly:
- libftd-dev
- libusbx-dev
- libudev-dev
(These are Debian/ubuntu names. For Fedora, change -dev to -devel)
This should upload u-boot from the host computer to the board via the USB cable. u-boot will then boot from the connected USB drive. Please note that in some instances, the USB drive is not detected as a mass storage device without also having the VIN power connector inserted. See more in in the "known errors" section of Recore A6
Upgrading Refactor
Reflash will create a symlink to the device tree for the hardware version of the board. You can check that the loaded device tree matches the revision of hardware.
cat /sys/firmware/devicetree/base/model
It's also worth noting that the klipper configuration is a bit different between the A5 and A6 revisions. The A6 is the now the default configuration, but A5 is also present for use. It can be found on github or on the board.
cat /home/debian/klipper/config/generic-recore-a5.cfg
Upgrading Debian via apt upgrade
The /boot partition of Refactor is mounted Read Only, so it will have to be remounted as Read Write before running an upgrade:
sudo mount -o remount,rw /boot
Upgrading Refactor from OctoPrint
The only way to upgrade Refactor is by flashing a new version. In OctoPrint there is a "Refactor" plugin that can aid with this. If Refactor is run from a USB stick, a new version of can be downloaded and flashed on the eMMC.
There is a separate image used for upgrading Refactor. Take a look at Reflash
Upgrading Refactor from the command line
To reboot into a USB drive:
set-boot-media usb reboot
Note: Reflash may not show up with the same IP as your previous ReFactor instance did. It will depend on your router's DHCP, so be sure to check if the IP has changed, even if the MAC has not.
Using Moonraker and Mainsail
Using KlipperScreen
KlipperScreen is running on X, so a new config should allow rotating the screen.
sudo nano /usr/share/X11/xorg.conf.d/90-monitor.conf
Add the following:
Section "Monitor" Identifier "HDMI-1" Option "Rotate" "left" EndSection
After that, KlipperScreen can be restarted.
sudo systemctl restart KlipperScreen
If it is necessary to rotate the touch panel as well, here is a useful section that can be added to the bottom of that same file. Uncomment the rotation that matches your setup.
Section "InputClass" Identifier "Coordinate Transformation Matrix" MatchIsTouchscreen "on" MatchDevicePath "/dev/input/event*" MatchDriver "libinput" Option "CalibrationMatrix" "1 0 0 0 1 0 0 0 1" # 0 degrees #Option "CalibrationMatrix" "0 1 0 -1 0 1 0 0 1" # 90 degrees #Option "CalibrationMatrix" "-1 0 1 0 -1 1 0 0 1" # 180 degrees #Option "CalibrationMatrix" "0 -1 1 1 0 0 0 0 1" # 270 degrees EndSection
Recompiling and installing binaries
Update u-boot on Recore
This is not something the regular user would need to do, but documented here for convenience. Place u-boot-sunxi-with-spl.bin in sector 15 (8KB offset) Flash the binary
dd if=u-boot-sunxi-with-spl.bin of=/dev/mmcblk0 bs=1024 seek=8 conv=notrunc
Note: U-boot needs to be patched in order to use the eMMC as the first (and only) boot device. The changes can be done in "spl_mmc_get_device_index" where dev_num should be 0 instead of 1.
AR100 firmware
The AR100 CPU needs a binary file that is loaded on startup by the systemd file klipper.service The AR100 binary file comes pre-compiled in Refactor, so most users should not have to re-compile it. For experiments the AR100 binary can be recompiled on Recore (architecture aarch64) or on a host computer (amd64 or similar).
Compiling the ar100 binary
To configure klipper for AR100 and build the binary:
cd /home/debian/klipper/ cp test/configs/ar100.config .config make olddefconfig make
This will produce a bin file located in out/ar100.bin, so it should be moved to /opt/firmware
mv out/ar100.bin /opt/firmware/
Once the AR100 binary has been updated, klipper.service can be restarted which then loads the new AR100 binary.
systemctl restart klipper
Cross compilation toolchain for ARM64
The AR100 needs a cross compilation toolchain. For ARM64, it can be downloaded from feeds.iagent.no:
http://feeds.iagent.no/toolchains/
The toolchain has been built with
https://github.com/richfelker/musl-cross-make
GCC version: 11.2.0
Cross compilation toolchain for x86_64
The toolchain used during automatic testing and is the same used for the CRUST firmware project:
https://github.com/crust-firmware/crust#building-the-firmware
STM32 firmware
Note
The latest Refactor now does automatic flashing of the STM32 firmware on first boot after a fresh install. This was merged with PR#199 in Refactor on Github.
The firmware for the stm32f031 mcu that is responsible for ADC conversions and PWM for heaters and fans comes pre-installed in the flash of the MCU. It can be recreated on the board using the Klipper build system.
cd /home/debian/klipper cp test/configs/stm32f031.config .config make menuconfig -> Enable extra low-level configuration options -> Processor model (STM32F031) -> Bootloader offset (No bootloader) -> Clock Reference (Internal clock) -> (16) Internal clock trim override -> Communication interface (Serial (on USART2 PA15/PA14)) -> Baud rate for serial port: 250000 make
Flashing STM32 firmware
To flash the STM32 firmware:
cp out/klipper.bin /opt/firmware/stm32.bin sudo flash-stm32
Running Klipper
Klipper is run as a systemd service. It should not normally need to be restarted from the command line, but during development it can be necessary.
systemctl restart klipper
The log for Klipper is located in /tmp. It can be viewed as:
tail -f /tmk/klippy.log
Klipper can also be restarted from the OctoPrint interface. On the "Klipper" tab, press "Firmware" to restart the Klipper firmware.
Running Toggle
Toggle is started automatically by the systemd service toggle.service. A user is created for Toggle on first boot, but the credentials are not set until a user is created in OctoPrint. Once the wizard has been completed, the Toggle user is active, but the credentials will not be valid until OctoPrint is restarted. Therefore, if Toggle is needed, restart OctoPrint after the wizard is complete.
Toggle is running on Weston, so a new config should allow rotating the screen.
sudo nano /etc/xdg/weston/weston.ini
Edit the section about rotation:
[output] name=HDMI-A-1 transform=rotate-90
After that, Weston can be restarted.
sudo systemctl restart weston
See the Ubuntu documentation for valid rotations: weston.ini
Running OctoPrint
OctoPrint is stated on boot. If there is a need to restart the daemon, use this command
systemctl restart octoprint
Refactor build system
Refactor uses Ansible as the underlying framework to describe the desired system state. There are many reasons for this:
- Ansible describes the system's end state, not individual actions to perform, so it is relatively easy to port across platforms (i.e. debian, arch, BSD...)
- The Refactor repository can be updated from the git repository and Ansible will only change what has been updated from the previous version, not needing a complete reinstallation of the system for upgrades.
- Description of components is modular, making it easy to pick and choose different components for the end goal desired, while keeping each component's setup independent and reliable, and independently updatable.