Machinekit with Debian Stretch on the BeagleBone Black

Machinekit with Debian Stretch on the BeagleBone Black 4 minutes read

This is a quick and easy guide to get from an RCN Debian Linux image for the BeagleBone (Black) to a working Machinekit installation.

At the time of writing this blog post, there is no ready to use image available. However, in the future, there might be a ready to use image with everything set-up and ready. So please check the page here before you start.

If you eager to start without following the steps (although I recommend you do so) you can download the resulting image here: BBB Machinekit Image with Debian Stretch

Download and Flash Debian BBB image

First of all, start by downloading the latest Stretch console image: Console image.

Next, flash to a micro-SD card. I recommend using Etcher for the job.

Flash the image to BBB eMMC

Now it’s time to flash the files from the micro-SD card to the eMMC of the BBB.

To auto-flash the image when inserting the SD card into your BBB you can uncomment the last line in /boot/uEnv.txt on the rootfs.

In case you have an older BBB or you don’t want to modify the uEnv.txt, you will need to trigger flashing manually by holding the user button during boot until the running lights appear.

Connecting via SSH

For the next steps, we will use SSH to connect to the BBB.

Under Linux or Mac OS X just use any terminal application.

If you are using Windows, please use PuTTY.

Note: The BBB creates two network interfaces when connected. One with IP address and another one with In this guide I will refer just to, but if you are experiencing any problems feel free to use the other.

Log in and create the machinekit user

Following, we add a machinekit user and then remove the default debian user.

Log in via SSH with the username debian and password temppwd.

ssh debian@

Please verify that the BBB has booted the correct Linux/image version:

uname -a
cat /etc/dogtag

You should see the Linux kernel version and the image creation date as stated where you download the BBB images files.

Next, we need to execute the following steps:

  1. create the machinekit user
  2. remove the sudo password
  3. change the root password
sudo su
adduser machinekit

Use the password machinekit or anything else (dont’ forget it).

usermod -aG  sudo,kmem,netdev,video machinekit
echo -e "# No sudo password for machinekit user\nmachinekit ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/90-machinekit

Then log out from the SSH shell with exit.

Log in again to the BBB with the username machinekit and password machinekit (I hope you didn’t forget it).

sudo su
deluser debian
rm -rf /home/debian

Now we are back at the machinekit user shell.

Install the basics

Subsequent, I recommend installing the following packages. Feel free to add or remove packages as you need.

sudo apt update
sudo apt upgrade
sudo apt install -y avahi-daemon network-manager nano git usbutils dirmngr locales firmware-misc-nonfree \
    libnotify-bin iw dnsmasq apt-offline zip unzip \
    libprotobuf-c0-dev protobuf-c-compiler libjpeg-dev python-smbus make python-setuptools python-dev gcc python-zmq libzmq3-dev \
    libzmq3-dev libprotobuf-dev

The next step ensures that your locale is configured correctly. I choose en_US.UTF-8 for my system.

sudo dpkg-reconfigure locales

Install the RT Kernel

Now it’s time to install the PREEMPT_RT kernel on our system.

For this, we can use the prepared scripts.

cd /opt/scripts/tools/
sudo su
git pull
./ --ti-rt-channel --lts-4_4

Once the installation is complete, reboot the system and run the following command to install additional firmware packages.

sudo apt install linux-firmware-image-`uname -r`

Setup uEnv.txt

Succeeding, we need to disable all universal device tree overlay we don’t need. In my case, that’s the HDMI (video and audio) and the wireless cape.

For this purpose, we open the /boot/uEnv.txt in the text editor of your choice.

sudo nano /boot/uEnv.txt

And change the following lines.

###Disable auto loading of virtual capes (emmc/video/wireless/adc)

Improve boot performance

You don’t need to follow the next steps if you are happy with the startup performance of the BBB as is.

However, I found it useful to do the following optimizations since I noticed slower boots compared to the Debian Wheezy images.

First, disable the wait-online Systemd service.

sudo systemctl disable systemd-networkd-wait-online.service

Then, disable the eth0 interface and enable network-manager instead.

sudo nano /etc/network/interfaces
# allow-hotplug eth0
sudo nmcli con add type ethernet con-name dhcp-ethernet ifname eth0

Moreover, disable (in my opinion) for an embedded system useless services.

sudo systemctl disable ModemManager.service
sudo systemctl disable debug-shell.service
sudo systemctl disable pppd-dns.service

Since I don’t use the graphical environment of the BBB, I also disable the graphical Systemd target.

You may have noticed that we started from the console image, so this shouldn’t make any difference anyway.

sudo systemctl set-default

Install Machinekit

Now, that we have everything set up and ready it is time to install Machinekit.

I copied the following commands from the official Machinekit docs. In case you encounter problems, make sure to check for updates there.

First, set up the official Machinekit repository:

sudo apt-key adv --keyserver hkp:// --recv 43DDF224
sudo sh -c \
  "echo 'deb stretch main' > \
sudo apt-get update

Then install the Machinekit packages with the following command:

sudo apt install machinekit-rt-preempt

Test-drive Machinekit

To verify everything is set-up and ready you can run the following command:

realtime start
halcmd show pin

You should see that the HAL configuration is running and empty.

Stop it again by running:

realtime stop

If you want something quick and actionable, clone and run the anddemo.

mkdir -p repos
cd repos
git clone
cd anddemo

Additional step: Setup mklauncher

You may want to try out the QtQuickVcp remote user interfaces.

To launch remote UIs from the comfort of your desktop computer you need to install and start the mklauncher as a service.

The quickest way to achieve this is by using the script.

sudo python

Follow the steps and you should be ready to go.

Then, download the MachinekitClient and start playing.

Flash the eMMC contents back to the micro-SD card

It’s always useful to know how to create a new micro-SD card image from eMMC contents on the BBB.

Luckily, RCN created a script to make this super easy.

Insert a micro-SD into your BBB and run:

sudo /opt/scripts/tools/eMMC/


In this quick tutorial, you have learned how to create your own Machinekit image from a pristine RCN Debian image for the BeagleBone.

I hope you found this tutorial useful and if so please share it with your friends and co-workers.

Machine Koder

Spread the love

7 thoughts on “Machinekit with Debian Stretch on the BeagleBone Black”

  1. Thanks a lot for your work, I’m new to BBB capes, got Debian running and installed machinekit but can’t get a working configuration I get:

    /sys/devices/bone_capemgr.*/slots: No such file or directory

    I did a little search and read about new uBoot loading overlay before the kernel so no slots dir, hacked to not search bone_capemgr stuff but don’t know exactly what to check for in the validations, then I get:

    RuntimeError: rtapi_loadrt ‘(‘hal_pru_generic’, ‘pru=0’, ‘num_pwmgens=6’, ‘num_stepgens=6’, ‘halname=hpg’, ‘prucode=/usr/lib/linuxcnc/xenomai/pru_generic.bin’)’ failed: Operation not permitted

    Could you point me in the right direction please

    1. Hello Alejandro,

      Please follow the steps closely or download the image from the link.

      hal_pru_generic’, ‘pru=0’, ‘num_pwmgens=6’, ‘num_stepgens=6’, ‘halname=hpg’, ‘prucode=/usr/lib/linuxcnc/xenomai/pru_generic.bin

      Also, make sure to replace xenomai with rt_preempt in your HAL config.


      1. Thanks for shedding some light, changing to rt_preempt at fabrikator-mini.ini config got it working


        So now I will try to help with machinekit/issues/1310 by upgrading CRAMPS config.

          1. Hello Cyrus,

            The 3D printer CRAMPS configurations should work as is. However, there are some other CRAMPs configs which use a script for doing the pin configuration.
            The device tree overlays have changed so I suggest converting these setups scripts to .bbio files similar to the .bbio files for the 3D printers configs. How to do this is described in the linked issue.

            Machine Koder

  2. Hi,

    Great guide, but I can’t ssh into the console image like I can with the IoT image. Is there something I need to configure? Please let me know!

    I flashed the image to the eMMC just fine. But then I’m stuck…

Leave a Reply

Your email address will not be published. Required fields are marked *