SBC Setup Guide - Duet3D/DuetSoftwareFramework GitHub Wiki
Starting from the Duet 3 series, Duets can be operated either in standalone or in SBC mode. The latter allows the usage of mini computers (like the popular Raspberry Pi 3) to control the machine operation and to make use of third-party plugins.
Note that the commands mentioned in this guide are supposed to be executed in a Linux terminal and not in the G-code console of the web interface.
Installation
This section will cover the installation of the required components.
Raspberry Pi installation
This section covers the installation of the Duet with a Raspberry Pi. If you are using another SBC, skip to the "Other SBCs" section.
Connecting the Duet
The SBC connection of the Duet 3 series is primarily designed for easy connections to the popular Raspberry Pi 3 or newer. To begin it is necessary to connect the 26-pin plug of the supplied ribbon cable to the SBC header of the Duet. Before you continue, make sure both boards are powered off.
Connect the 40-pin plug directly to the Raspberry Pi expansion header with the red wire closest to the edge of the Pi (red line is +5V). If you are using a Duet 3 Mini 5+, it is mandatory to connect an external 5V supply to the Pi as well. This step isn't strictly required for the Duet 3 MB6HC but it is highly recommended.
Preparing the SD card
In order to start the Pi, you must install the required system files on the microSD card first. For this purpose Duet3D provides two different SD card images for the Raspberry Pi. Choose one of the two options and install it as described here.
DuetPi Full
If you have a display connected to your Raspberry Pi, the best way to get going is to install the full image. It comes with a graphical environment and it will start the web interface automatically on boot. This is the recommended image for users without much experience in Linux or Raspberry Pi administration.
DuetPi Lite
If you do not have a display for your Raspberry Pi, you can use the lite image.
This image is intended for network-only access and it does not start a GUI automatically to save resources.
Unlike the full image, this one comes with SSH enabled by default and it contains a wpa_supplicant.conf file for easy WiFi configuration.
To establish a terminal connection, use either the built-in SSH client (e.g. run ssh pi@duet3) or use PuTTY.
Other SBCs and/or distributions
Duet 3 series can be used with different SBCs and/or distributions as well. However, the SBC must provide an ARMv7-compatible CPU for the required software framework to work. For this reason, the Raspberry Pi Zero is not supported either.
Package installation
Duet3D provides precompiled DSF packages via package feeds for Debian-based distributions running on arm or arm64 platforms. The following package feeds are available:
The stable feed is suitable for production whereas Duet3D encourages users to give the unstable feed a try. It contains new and experimental features that need to be tested.
In order to use one of these feeds, create a new file /etc/apt/sources.list.d/duet3d.list and copy the file contents from one of the feeds above.
In additon, it is necessary to add a new GPG certificate for the Duet3D package feed:
wget -q https://pkg.duet3d.com/duet3d.gpg
sudo mv duet3d.gpg /etc/apt/trusted.gpg.d/
sudo chown root:root /etc/apt/trusted.gpg.d/duet3d.gpg
After that, update your apt package lists and install duetsoftwareframework:
sudo apt-get update
sudo apt-get install duetsoftwareframework
Since the software packages come with systemd services, you can enable both the duetcontrolserver and duetwebserver services if you wish to start them on boot:
sudo systemctl enable duetcontrolserver
sudo systemctl enable duetwebserver
In order to start the services without a reboot, run the following commands:
sudo systemctl start duetcontrolserver
sudo systemctl start duetwebserver
It is mandatory to have DSF installed before you can continue.
Link between the Duet and SBC
DSF and RepRapFirmware use SPI and a GPIO pin to communicate with each other. If you are using a custom SBC, it is necessary to set up the SPI device and the GPIO pin before DSF can be started.
Note that all voltage levels must be +3.3V, else you risk damaging either the Duet MCU or the SBC.
SPI setup
Most Linux configurations allow a maximum transfer size of 4KiB for a single SPI transfer.
Because DSF and RRF may exchange more than this in a single transfer, the SPI buffer size must be increased.
To do so, create a new file /etc/modprobe.d/spidev.conf with the content
options spidev bufsiz=8192
This will increase the maximum SPI transfer size to 8KiB.
On Linux, SPI device are usually exposed via /dev/spidev*.*. By default, DSF attempts to use /dev/spidev0.0 (device 0, CS line 0).
If you wish to use a different SPI device or transfer mode , further settings can be found in /opt/dsf/conf/config.json.
Finding the correct GPIO pin
RRF notifies the SBC when it is ready to exchange data. For this purpose the transfer ready pin is continuously monitored by DSF. For this purpose DSF uses the gpiochip module. However, the underlying interface is slightly different from the more common SysFS interface. Note that pins allocated by SysFS cannot be used simultaneously by the gpiochip module.
Most Linux distributions provide a toolkit for the gpiochip module in a package called gpiod.
You must have this package installed (containing the gpioinfo program) before you can continue.
In order to identify the GPIO device and pin number for DSF, run the gpioinfo command to get a list of available pins.
On a Raspberry Pi, the output will provide something like
gpiochip0 - 58 lines:
...
line 23: "GPIO23" unused input active-high
line 24: "GPIO24" unused input active-high
line 25: "GPIO25" unused input active-high
line 26: "GPIO26" unused input active-high
line 27: "GPIO27" unused input active-high
...
In this default scenario, GPIO25 corresponds to pin 22 of the expansion header on the Raspberry Pi.
That means DSF can use pin 25 from /dev/gpiochip0.
Note that the output of gpioinfo may vary and for other SBCs it may not be as verbose as seen here.
Refer to the manufacturer documentation of your SBC for further details.
When you connect +3.3V to the pin of your choice, it may help to use the gpioget utility to find the actual chip device and pin number:
pi@Duet3:~ $ gpioget gpiochip0 25
1
where 1 corresponds to a high level (+3.3V) and 0 to a low level (GND).
When you have identified the correct chip device and pin number, open /opt/dsf/conf/config.json and change the values of GpioChipDevice and TransferReadyPin accordingly.
To apply the new values, restart DCS once via sudo systemctl restart duetcontrolserver.
Third-Party plugins (only v3.3 and newer)
DSF 3.3 and later allow the installation of third-party plugins on the SBC. To prevent regular plugins from performing malicious actions, they are confined using AppArmor security profiles.
This means AppArmor support must be enabled before third-party plugins can be installed. To achieve this on a Raspberry Pi, perform the following:
- Install the
apparmorpackage - Edit the kernel command line and append
lsm=apparmorto it (for Raspberry Pi this is saved in/boot/cmdline.txt) - Reboot the machine
- Check if the AppArmor module is enabled (run
aa-statusand check the output)
Note it is also possible to disable the AppArmor requirement for Linux distributions that do not support it (like RedHat-based distros), but this is not encouraged and a potential security hazard.
If this requirement is supposed to be disabled, edit /opt/dsf/conf/plugins.json and set DisableAppArmor to true.
When the configuration steps for AppArmor are complete, enable the plugin services:
sudo systemctl enable duetpluginservice
sudo systemctl enable duetpluginservice-root
Run the following to start them right away:
sudo systemctl start duetpluginservice
sudo systemctl start duetpluginservice-root
Unstable package feed
To get access to the latest and possibly experimental software components, it is possible to change the package feed.
Upgrading to unstable packages
This step is relatively trivial. Be aware that potential downgrades can involve more work.
- Change
stabletounstablein/etc/apt/sources.list.d/duet3d.list(sudo bash -c "echo 'deb https://pkg.duet3d.com/ unstable armv7' > /etc/apt/sources.list.d/duet3d.list") - Run a system update (
sudo apt update && sudo apt dist-upgrade) - The latest unstable packages should be installed
Downgrading to stable packages
- Change back
unstabletostablein/etc/apt/sources.list.d/duet3d.list(sudo bash -c "echo 'deb https://pkg.duet3d.com/ stable armv7' > /etc/apt/sources.list.d/duet3d.list") - Refresh the package lists (
sudo apt update) - Remove potentially left-over RRF packages (
rm -f ./reprapfirmware*.deb) - Download the latest stable RepRapFirmware package (
apt download reprapfirmware/stable) - Downgrade RepRapFirmware (
sudo dpkg -i --force-depends ./reprapfirmware*.deb) - Downgrade DSF (
sudo apt install -y --allow-downgrades duetsoftwareframework/stable duetcontrolserver/stable duetwebserver/stable duetpluginservice/stable duetpimanagementplugin/stable duettools/stable duetruntime/stable duetwebcontrol/stable)
Troubleshooting
See https://docs.duet3d.com/en/User_manual/Machine_configuration/SBC_setup#h-9-troubleshooting