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
If things are not going as expected, there are several ways for investigation. The typical reason why DSF fails to start is because there is an SD card present in the Duet.
In SBC mode the SD card must not be present in the Duet. If it is, remove it and reset the board.
SPI connection reset
This issue may occur when the link between Duet and SBC is interrupted. Possible causes include:
- Poor wiring between the boards (intermittent connections)
- Inproper grounding
- Cable too long
- Cable picking up noise from adjacent electronic components
Disable WiFi Power Saving on the Raspberry Pi
In addition to those reasons, there have been been reports that power saving of the integrated Raspberry Pi WiFi adapter may cause problems with the SPI connection (see here and here). So unless you are using a recent DuetPi build (after 06/07/2022), it is recommended to disable it by running the following from a Linux shell (e.g. via SSH):
echo "# Disable power saving of the built-in WiFi adapter to avoid SPI connection problems" | sudo tee -a /etc/network/interfaces
echo "allow-hotplug wlan0" | sudo tee -a /etc/network/interfaces
echo "iface wlan0 inet manual" | sudo tee -a /etc/network/interfaces
echo "post-up iw dev wlan0 set power_save off" | sudo tee -a /etc/network/interfaces
sudo iw dev wlan0 set power_save off
Failed to connect to Duet (DCS not started)
If you get this message, it means that the main service communicating with RepRapFirmware failed to start. This usually means that the connection between the Duet and SBC has been interrupted.
To acquire further details about this message, access the service logs from this particular unit by running journalctl -u duetcontrolserver -e.
This will output the latest logs and it will - if applicable - report why DCS failed to start.
Timeout while waiting for transfer ready pin
This error message means the service attempted to wait for a signal on the transfer ready pin (pin 22 on the expansion header) but it timed out while doing so.
Board is not available (no header)
When DSF gets a signal over the transfer ready pin, it attempts to exchange data over SPI. If the received data is completely empty, this error message is generated. This error message indicates a problem with the SPI peripheral either on the Duet or on the SBC. Check the continuity between the SPI pins on the Duet and SBC sides.
Trivial checks
If you get communication issues between the Duet and SBC, perform the following steps first:
- Make sure there is no SD card present in the Duet
- Make sure both the Duet and SBC are powered properly
- Confirm that the red "DIAG" LED flashes in regular intervals
- Try reseating the SBC cable between the Duet and SBC
- Disable all third-party plugins (only v3.3 and newer)
In case these steps haven't improved the situation, you can proceed with the following checks.
Measure continuity of the ribbon cable
Disconnect the power source from your SBC and Duet. Then take a multimeter and check if there is continuity between the Duet and SBC of the following pins
| Pin Number | Description |
|---|---|
| 17 | +3.3V |
| 19 | MOSI |
| 20 | GND |
| 21 | MISO |
| 22 | TfrRdy |
| 23 | SCLK |
| 24 | CS0 |
If there is no or bad continuity between any of the pins, consider replacing the cable.
Note that pin 17 is required to turn on the TfrRdy and MISO pins unless you are using a Duet 3 MB6HC v1.0 or older.
Testing GPIO capability of the SBC
This type of check is recommended if you get "Timeout while waiting for transfer ready pin"
Power down the Duet as well as the SBC and disconnect the cable between the Duet and SBC.
When done, take a jumper cable and connect the +3.3V line of your SBC to the TfrRdy pin.
Be careful and do not mix up the +5V pins with the +3.3V pin, else you will damage your SBC!
When you are done, power up the SBC again. When it has finished booting, open a terminal and stop the DCS service via sudo systemctl stop duetcontrolserver first.
Then run gpioget gpiochip0 25. It should output 1 to indicate that the GPIO pin reads the correct signal.
After this, pull off the jumper cable and run the command again. This time it should output 0.
Note that the gpio chip name and the pin number may vary if you are not using a Raspberry Pi.
If the expected results do not match the command outputs, it is likely that the GPIO peripheral of your SBC is damaged. In this case it is a good idea to replace the affected SBC.
Check SPI data lines in loopback mode
This type of check is recommended if you get "Board is not available"
Power down the Duet as well as the SBC and disconnect the cable between the Duet and SBC.
When done, take a jumper cable and bridge the MOSI and MISO pins (pins 19 and 21 on the Raspberry Pi).
After this power up the SBC again and open a terminal. Then run the following commands:
wget https://raw.githubusercontent.com/raspberrypi/linux/rpi-3.10.y/Documentation/spi/spidev_test.c
gcc -o spidev_test spidev_test.c
./spidev_test -D /dev/spidev0.0
spi mode: 0
bits per word: 8
max speed: 500000 Hz (500 KHz)
FF FF FF FF FF FF
40 00 00 00 00 95
FF FF FF FF FF FF
FF FF FF FF FF FF
FF FF FF FF FF FF
DE AD BE EF BA AD
F0 0D
Note the last section of the output above (FF FF ...) should match.
If you get only 00 or FF there, it is likely that the SPI peripheral of your SBC is broken.
Web interface not updating
If the web interface appears to be frozen but still reacts to incoming commands, it is very likely that you are trying to run an unsupported firmware version.
To resolve this problem, the easiest solution is to send M997 over the web interface or code console.
In case this method does not resolve this problem, open a terminal and run journalctl -u duetcontrolserver -f.
This will show you the log including new messages being written. If you see any kind of exception there, please file a new issue on GitHub and share the console output plus the output of M122.
Increasing log level
To obtain more data for potential debugging it is possible to adjust the log level of the DCS service.
This can be done by changing LogLevel in /opt/dsf/conf/config.json from info to debug.
Once this change has been made, restart the DCS service to apply it (sudo systemctl restart duetcontrolserver).
After that you can follow potential debug messages in a terminal by running journalctl -u duetcontrolserver -f.
If you want to share a log of the events from today, the command journalctl -u duetcontrolserver --no-pager --since today may be useful.
This command dumps the log content directly to the console so it can be easily copied from your terminal and pasted in a text file.
Don't forget to change back the log level from debug to info when you are done, else you may get a lot more IO on your SD card over time.
Further troubleshooting
If none of the described steps helped, please open a new thread on the forum. Note that support requests on GitHub will be closed immediately.