Difference between revisions of "Refactor"

From iagent
Jump to: navigation, search
(→‎Booting Recore from USB, load from Linux from USB drive)
(→‎Upgrading Refactor from the command line)
 
(155 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
The latest images for Recore and Replicape are available from github: https://github.com/intelligent-agent/Refactor
+
<div class="res-img">
 +
[[File:Refactor header 2.png]]
 +
</div>
  
−
==== ReFactor is the next generation of controller board software stack installation. ====
+
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.  
  
−
It is meant to simplify the lives of new users when they begin using a Thing-Printer controller board. Pre-built images of ReFactor are available for users who want to get up and running quickly with Replicape or Recore.
+
These instructions are for version v3.2. For older versions of Refactor:
 +
* [[Refactor_v3.1.3]]
 +
* [[Refactor_v3.0.3]]
  
−
ReFactor is available for Replicape and Recore, with updates being propagated simultaneously for both platforms.
+
=Installing an image=
 +
For instructions on making a flasher image, have a look at [[Reflash]]
 +
<div class="alert alert-warning">
 +
===='''Note'''====
 +
In order to install Refactor v3.2.x, you need to use Reflash v0.1.2 or newer.
 +
</div>
  
−
ReFactor uses [https://www.ansible.com/ Ansible] as the underlying framework to describe the desired system state.
+
=Latest images=
−
There are many reasons for this:
+
The latest images for Recore and Replicape are available from github: https://github.com/intelligent-agent/Refactor/releases
−
 
 
−
# 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.
 
  
−
== Why? ==
+
=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.12.0-13-g795ce490) 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
  
−
The ultimate goal is to have multiple decliations of ReFactor, providing the user the ability to choose which firmware/software stack to run on their hardware. The following pre-build declinations are planned:
+
==Recore OctoPrint==
−
* '''OctoPrint, Klipper, Replicape'''
+
* OctoPrint (1.9.3) https://github.com/OctoPrint/OctoPrint
−
* '''OctoPrint, Klipper, Recore'''
+
** Octoprint Klipper (0.3.9.5) https://github.com/thelastWallE/OctoprintKlipperPlugin
−
* OctoPrint, Klipper, Toggle, Replicape
+
** Octoprint Refactor (main) https://github.com/intelligent-agent/octoprint_refactor
−
* OctoPrint, Klipper, Toggle, Recore
+
** OctoPrint Toggle (master) https://github.com/intelligent-agent/octoprint_toggle
−
* Duet Web Control, Klipper, Replicape
+
** OctoPrint Top Temp (master) https://github.com/LazeMSS/OctoPrint-TopTemp.git
−
* Duet Web Control, Klipper, Recore
+
* Toggle (v1.4.1) https://github.com/intelligent-agent/toggle
−
* OctoPrint, Klipper, Raspberry Pi [1-3]
 
−
* OctoPrint, Klipper, Raspberry Pi 4 (arm64 edition)
 
  
 +
==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
  
−
'''''Only the options in bold''''' have been implemented so far, while the others are undergoing various steps in development in the order shown in this list.
+
=Getting started=
−
The ReFactor images with OctoPrint are meant to provide drop-in replacements for the previous Umikaze images, including all the extra goodies that were present in Umikaze, like mjpg-streamer, SMB server, and usbreset for the main ones.
+
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.  
  
−
The default login is ''root'' with password ''kamikaze''. The system will prompt for an immediate password change, to prevent a massive IoT exploitation through the web. Wouldn't want your printer sending out spam or starting to print unauthorized objects, now would we?
+
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
  
−
== So how do I use it? ==
+
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.
  
−
ReFactor will be usable differently depending on what platform you're running it from.
+
On the MainSail image, there should not need to be any configuration necessary. Verify that the web interface comes up and that Klipper is running as expected.
  
−
=== Replicape ===
+
== 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.
  
−
The Replicape images will be meant to run from the micro SD you flash it to. You cannot boot the Replicape from a USB key at this time.
+
After the Klipper configuration is complete, do a test print to make sure everything is working.  
−
By default, ReFactor images do not flash to the eMMC the way Umikaze used to. Part of this is historical - the early betas of ReFactor did not fit on the eMMC, but there's another advantage as well: it allows you to test out ReFactor on an SD card while keeping your working Redeem config on the eMMC.
+
<div class="alert alert-warning">
 +
===='''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.  
 +
</div>
  
−
==== Booting Refactor from USB ====
+
=== Recore booting ===
−
If you want to boot Refactor from a USB stick, you need to stop u-boot by pressing space during boot.  
+
Recore comes with Refactor pre-installed.  
−
You must run these commands:
 
−
<pre>
 
−
setenv bootpart 0:1; setenv oldroot /dev/sda1; setenv devnum 0; run usb_boot
 
  
−
load ${devtype} ${bootpart} ${loadaddr} /boot/uEnv.txt; env import -t ${loadaddr} ${filesize}
 
−
 
−
run uname_boot
 
−
</pre>
 
−
 
−
=== Recore ===
 
 
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.  
 
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.  
  
Line 64: Line 80:
 
# Linux will load the rootfs from eMMC.
 
# Linux will load the rootfs from eMMC.
  
−
===Booting Recore from eMMC, but load rootfs from USB===
+
===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  
 
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):
 
Refactor version you can let the rootfs be loaded from a USB drive (mass storage device):
Line 70: Line 86:
 
# Insert the USB drive in the board.  
 
# Insert the USB drive in the board.  
 
# Boot the board normally
 
# Boot the board normally
−
# Edit the commandline:
+
## Open the Refactor tab in OctoPrint.
−
## nano /boot/armbianEnv.txt
+
## Select '''run from USB'''
−
## Add this line:
+
#:or
−
<pre>
+
## Use SSH to log into the board: '''ssh root@recore.local'''
−
extraargs=root=/dev/sda1
+
## Run the command '''set-boot-media usb'''
−
</pre>
 
 
# Reboot
 
# Reboot
−
The board should now be have the rootfs from teh USB drive.  
+
The board should now be have the rootfs from the USB drive.
  
−
===Booting Recore from USB, load from Linux from 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.  
 
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  
 
There is a 4 pin header on Recore marked '''DBG''', where UART 0 is routed. All u-boot and kernel  
−
messages will appear here.
+
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  
 
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:   
 
load the boot script from a USB drive, stop u-boot by pressing a key and then write:   
Line 90: Line 105:
 
# When the boot process gets to u-boot, you will see: '''Hit any key to stop autoboot:  '''
 
# When the boot process gets to u-boot, you will see: '''Hit any key to stop autoboot:  '''
 
# Hit the Any key.  
 
# Hit the Any key.  
−
# Then:
+
# 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 [[Recore_A6#USB_connectors_not_discovered_when_powered_by_USB_device|in the "known errors" section of Recore A6]]
 +
 
 +
===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. This is handled automatically by apt in this version:  
 
<pre>
 
<pre>
−
run bootcmd_usb0
+
sudo apt update
 +
sudo apt upgrade
 
</pre>
 
</pre>
  
−
===Boot Recore from a USB stick, eMMC is blank===
+
===Upgrading Refactor from OctoPrint===
−
Recore should come pre-flashed with Refactor image on the eMMC. If the eMMC has been wiped for some reason
+
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.
−
and you need to do everything from scratch, here are the instructions:
+
<div class="res-img">
−
# Flash the ReFactor Linux distro to a USB drive.  
+
[[File:Refactor-tab.png|center]]
−
# Insert the USB drive in the Recore board.
+
</div>
−
# Insert the Recore board in a host computer with the USB-C connector.  
+
 
−
# If the eMMC is blank or the "FEL" button is pressed, the board will go into bootloader mode.  
+
There is a separate image used for upgrading Refactor. Take a look at [[Reflash]]
−
# Upload SPL, EL3 and u-boot through the USB port:
+
 
−
## Download the Recore repository https://github.com/intelligent-agent/Recore
+
===Upgrading Refactor from the command line===
−
## Install the sunxi-tools program
+
To reboot into a USB drive:
−
## Run '''make fel'''
+
<pre>
−
# The board will boot using the USB drive.
+
set-boot-media usb
−
# Copy the contents of the USB drive into the eMMC/Internal flash.
+
reboot
 +
</pre>
  
−
===AR100 firmware===
+
'''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.
−
The ar100 has a binary file that is loaded on startup by klipper.service
 
−
The binary file comes pre-compiled in Refactor, but can be recompiled on Recore (or on a host computer).
 
  
−
====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/
+
=== Enable host mode on the USB-C connector ===
 +
<pre>
 +
sudo mount -o remount,rw /boot
 +
sudo armbian-add-overlay /boot/overlay-user/sun50i-a64-usb-host.dts
 +
sudo mount -o remount,ro /boot
 +
</pre>
  
−
The toolchain has been built with 
+
==Using Moonraker and Mainsail==
 +
<div class="res-img">
 +
[[File:Mainsail.png]]
  
−
https://github.com/richfelker/musl-cross-make
+
==Using KlipperScreen==
 +
KlipperScreen is running on X, so a new config should allow rotating the screen.
 +
<pre>
 +
sudo nano /usr/share/X11/xorg.conf.d/90-monitor.conf
 +
</pre>
 +
Add the following:
 +
<pre>
 +
Section "Monitor"
 +
    Identifier "HDMI-1"
 +
    Option "Rotate" "left"
 +
EndSection
 +
</pre>
 +
After that, KlipperScreen can be restarted.
 +
<pre>
 +
sudo systemctl restart KlipperScreen
 +
</pre>
  
−
====Cross compilation toolchain for x86_64====
+
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.
−
The toolchain used during automatic testing and is the same used for the CRUST firmware project:
+
<pre>
 +
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
  
−
https://github.com/crust-firmware/crust#building-the-firmware
+
EndSection
 +
</pre>
  
−
====Compiling the ar100 binary====
+
==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
 
<pre>
 
<pre>
−
cd /opt
+
dd if=u-boot-sunxi-with-spl.bin of=/dev/mmcblk0 bs=1024 seek=8 conv=notrunc
−
wget http://feeds.iagent.no/toolchains/or1k-linux-musl.tar.xz
 
−
tar xf or1k-linux-musl.tar.xz
 
−
export PATH=$PATH:/opt/output/bin
 
 
</pre>
 
</pre>
  
 +
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:
 
To configure klipper for AR100 and build the binary:
 
<pre>
 
<pre>
Line 143: Line 221:
 
</pre>
 
</pre>
  
−
This will produce a bin file located in out/ar100.bin.
+
This will produce a bin file located in out/ar100.bin, so it should be moved to /opt/firmware
−
The file can be "flashed" (really loaded into SRAM) by writing
 
 
<pre>
 
<pre>
−
make flash
+
mv out/ar100.bin /opt/firmware/
 
</pre>
 
</pre>
−
This is the same operation that happens from the klipper.service script, so it can also be done by running
+
Once the AR100 binary has been updated, klipper.service can be restarted which then loads the new AR100 binary.
 
<pre>
 
<pre>
 
systemctl restart klipper
 
systemctl restart klipper
 
</pre>
 
</pre>
  
−
====STM32 firmware====
+
====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===
 +
 
 
The firmware for the stm32f031 mcu that is responsible for ADC  
 
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.  
 
conversions and PWM for heaters and fans comes pre-installed in the flash of the MCU.  
Line 159: Line 254:
 
<pre>
 
<pre>
 
cd /home/debian/klipper
 
cd /home/debian/klipper
−
cp test/configs/stm32f0.config .config
+
cp test/configs/stm32f031.config .config
 
make menuconfig
 
make menuconfig
 
-> Enable extra low-level configuration options
 
-> Enable extra low-level configuration options
−
-> Clock Reference internal
+
-> Processor model (STM32F031)
 +
-> Bootloader offset (No bootloader)
 +
-> Clock Reference (Internal clock)
 +
-> (16) Internal clock trim override
 
-> Communication interface (Serial (on USART2 PA15/PA14))
 
-> Communication interface (Serial (on USART2 PA15/PA14))
−
-> Baud rate for serial port: 38400
+
-> Baud rate for serial port: 250000
 
make
 
make
−
systemctl stop klipper
 
−
make recoreflash FLASH_DEVICE=/dev/ttyS4
 
−
systemctl start klipper
 
 
</pre>
 
</pre>
  
−
===Flashing ReFactor from a USB drive===
+
====Flashing STM32 firmware====
−
Get the latest ReFactor image from here: https://github.com/intelligent-agent/ReFactor/releases
+
To flash the STM32 firmware:
−
for example:
 
−
<pre>
 
−
wget https://github.com/intelligent-agent/Refactor/releases/download/v3.0.0/Refactor-recore-v3.0.0-2021-08-06.img.xz
 
−
</pre>
 
−
Assuming you have managed to boot Recore from a USB flash drive and you have the ReFactor image available in the same folder, you can
 
−
use dd to do a direct transfer of the image from the USB drive to eMMC. On Replicape / BeagleBone this will be /dev/mmcblk1
 
 
<pre>
 
<pre>
−
xz -v -d -c Refactor-recore-v3.0.0-2021-08-06.img.xz  | dd of=/dev/mmcblk0
+
cp out/klipper.bin /opt/firmware/stm32.bin
 +
sudo flash-stm32
 
</pre>
 
</pre>
  
 
===Running Klipper===
 
===Running Klipper===
−
While details are ironed out there is a script that can be used to restart Klipper that will handle
+
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.  
−
resetting things and setting up the steppers etc.  
 
 
<pre>
 
<pre>
 
systemctl restart klipper
 
systemctl restart klipper
 
</pre>
 
</pre>
  
−
===Running OctoPrint===
+
The log for Klipper is located in /tmp. It can be viewed as:
−
OctoPrint should start and run on boot, but if there is a need to restart the daemon, use this command
 
 
<pre>
 
<pre>
−
systemctl restart octoprint
+
tail -f /tmk/klippy.log
 
</pre>
 
</pre>
  
−
== Building a runnable image for Replicape ==
+
Klipper can also be restarted from the OctoPrint interface. On the "Klipper" tab, press "Firmware" to restart the Klipper firmware.
 +
<div class="res-img">
 +
[[File:Klipper-firmware-press.png]]
 +
</div>
  
−
The [[Replicape_Rev_B | Replicape]] runs on a Beaglebone black (or green, without video output), which has a single core ARM processor running at 1GHz with 512MB of RAM. While impressive for an embedded application, it's rather weak when trying to build a system, which can take a lot of time.
+
===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.
  
−
There's a significant time gain when building the image from a more powerful host system, then flashing it to memory from an SD card.
+
Toggle is running on Weston, so a new config should allow rotating the screen.
 +
<pre>
 +
sudo nano /etc/xdg/weston/weston.ini
 +
</pre>
 +
Edit the section about rotation:
 +
<pre>
 +
[output]
 +
name=HDMI-A-1
 +
transform=rotate-90
 +
</pre>
 +
After that, Weston can be restarted.  
 +
<pre>
 +
sudo systemctl restart weston
 +
</pre>
  
−
The host system can be any ARM v7 or above architecture machine. In this example, the Raspberry Pi 4 will be used as an example, as it has a quad-core arm64 1.5GHz processor with 1 to 4GB of RAM. Any standard linux platform will do, but you will need a build storage space of at least 5GB for the build to succeed. Using a fast SD or a USB3 flash drive can provide higher disk speeds, reducing build time significantly.
+
See the Ubuntu documentation for valid rotations: [https://manpages.ubuntu.com/manpages/jammy/man5/weston.ini.5.html weston.ini]
  
−
To build an image from ReFactor for the Replicape, follow these steps:
+
===Running OctoPrint===
−
# Browse to a folder on the pi where you wish to run the build
+
OctoPrint is stated on boot. If there is a need to restart the daemon, use this command
−
# Clone the [https://github.com/goeland86/ReFactor git repository] for ReFactor
+
<pre>
−
# In the ReFactor folder, run the build-image-in-chroot-end-to-end.sh script. It may take some time, so you may want to consider using a screen or byobu session to protect against network drops if you're doing so through SSH.
+
systemctl restart octoprint
−
# If the build completes successfully, you should be left with a file 'Umikaze-console.img.xz'
+
</pre>
−
# Use etcher to write the .img.xz file to a micro SD card, insert it into the Beaglebone, power it up and wait for it to power down.
 
−
# Start using the ReFactor image on your printer
 
  
−
== Installing a custom software stack with ReFactor from a base Debian image ==
+
= Refactor build system=
  
−
At the moment ReFactor only supports using a debian-based distribution as a basis. Further down the line it will be refactored so that many more packaging systems are supported - this is not an Ansible limitation, but rather simply a developer time limitation.
+
Refactor uses [https://www.ansible.com/ Ansible] as the underlying framework to describe the desired system state.  
 +
There are many reasons for this:
  
−
The goal for ReFactor is to allow the end-user to choose a custom software stack, while making installation of those packages easier. In this case, the user will want to learn how to write a simple Ansible playbook - there are multiple examples available in the ReFactor base folder (build_full_klipper_octoprint.yml, install_klipper.yml, any yml file really).
+
# 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.
−
The files starting with "build_full_" are meant to be used for the image building described in the previous section. The files starting with "install_" are designed to be run on a printer platform exclusively - not on a host system.
+
# 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.
−
 
 
−
Each install_ file will install a specific component with its required dependencies. For instance, if you with install toggle, it will also install the Beaglebone's graphics drivers, required for video output, along with a number of libraries that Toggle is reliant on (such as a custom-built libclutter using the framebuffer output instead of the X11 driver).
 
−
 
 
−
To install a specific component, make sure that you have installed ansible. Alternatively you can just run the prep_ubuntu.sh script - the only thing it does is make sure that Ansible is ready to execute any further tasks required.
 
−
 
 
−
Once Ansible is installed, just run "ansible-playbook install_klipper.yml" for example. Let it run and it will go through to make sure everything is available upon the next reboot.
 
−
 
 
−
After all packages have been installed as desired, reboot the system. A reboot is necessary, as depending on the software installed, kernel modules may be enabled / disabled, kernel versions may have changed etc. These are unfortunately not changes that can be done without a reboot.
 

Latest revision as of 13:45, 15 December 2023

Refactor header 2.png

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:

Installing an image

For instructions on making a flasher image, have a look at Reflash

Note

In order to install Refactor v3.2.x, you need to use Reflash v0.1.2 or newer.

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.

Recore OctoPrint

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.

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 web interface comes up and that Klipper is running as expected.

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)

  1. Turn on power
  2. The BROM will load u-boot SPL from eMMC
  3. The u-boot SPL will load u-boot
  4. u-boot will load Linux
  5. 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):

  1. Download Refactor and flash it to a USB drive
  2. Insert the USB drive in the board.
  3. Boot the board normally
    1. Open the Refactor tab in OctoPrint.
    2. Select run from USB
    or
    1. Use SSH to log into the board: ssh root@recore.local
    2. Run the command set-boot-media usb
  4. 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:

  1. Download Refactor and flash it to a USB drive
  2. Insert the USB drive in the board and apply power
  3. When the boot process gets to u-boot, you will see: Hit any key to stop autoboot:
  4. Hit the Any key.
  5. 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:

  1. Flash the Reflash Linux distro to a USB drive.
  2. Insert the USB drive in the Recore board in one of the two host connectors close to the HDMI.
  3. Hold down the FEL button while applying power to the board via the USB-C connector.
  4. Download the Recore repository https://github.com/intelligent-agent/Recore
  5. Install the sunxi-tools program
  6. 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 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. This is handled automatically by apt in this version: 

sudo apt update
sudo apt upgrade

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.

Refactor-tab.png

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.


Enable host mode on the USB-C connector

sudo mount -o remount,rw /boot
sudo armbian-add-overlay /boot/overlay-user/sun50i-a64-usb-host.dts
sudo mount -o remount,ro /boot

Using Moonraker and Mainsail

Mainsail.png

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

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.

Klipper-firmware-press.png

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:

  1. 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...)
  2. 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.
  3. 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.
Retrieved from "https://wiki.iagent.no/mediawiki/index.php?title=Refactor&oldid=1040"