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

Comments 30

  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. Post

      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. Post

            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...

    1. Post
  3. Hello Alexander,

    Is there any prebuild image available for this already
    Or should i usw Debian Jessie better ?

    Many thanks

    1. Post
    1. Post
  4. Pingback: ROS with Debian Stretch on the BeagleBone Black/Green/Blue - Machine Koder

  5. Hi Alex,

    I am a newbie at BBB,so i flashed the prebuild image microSD/Standalone: (machinekit) Based on Debian Jessie with 3.8.x kernel to emmc,and it works.

    Now i want to compile my driver with machinekit source tree,but i am confused with how to configure the source tree or using COMP to compiling components outside the source tree .

    Could you point me in the right way to build drivers or components please.


  6. Thanks for your work, I am a newbie to use BBB.

    Now i used prebuilt image microSD/Standalone: (machinekit) Based on Debian Jessie with 3.8.x kernel to build my system ,and it is works .

    but i am confused with how to configure the machinekit source tree to compile my drivers or components. and there is not the component generator "comp" exist in my environment ,should i re-install new machinekit or do something else to solve this?

    Many thanks
    Le Roi

    1. Post

      Hello Roi,

      Unfortunately, the Jessie images contain an outdated version of Machinekit which will not receive updates anymore. However, in this version of Machinekit, it is necessary to install the `machinekit-dev` package to get the `comp` tool. Newer versions of Machinekit ship the tool per default.

      1. Hello Alex:

        Thanks for your work,can you tell where to get the `machinekit-dev` package ?

        "it is necessary to install the `machinekit-dev` package to get the `comp` tool. Newer versions of Machinekit ship the tool per default."

        1. Post
  7. Hey there! Just followed you tutorial to the letter and worked almost perfectly.
    I had a minor issue due to changes on uEnv.txt files, that apparently uses remote proc by default for PRUSS, leading to insmod error when launching my hal file.
    To resolve this, just commmented and uncommented these marked lines:
    ###pru_rproc (4.4.x-ti kernel)
    ###pru_rproc (4.14.x-ti kernel)
    ###pru_uio (4.4.x-ti, 4.14.x-ti & mainline/bone kernel)

    Thanks a bunch!

  8. Hello! thank you for all of your work in this guide. I have followed every step, and every step seems to have executed properly. I am running into some minor issues:

    1) I believe your instructions completely disable the ability to just plug a screen into the Beaglebone's HDMI port, correct? The Stretch / Machinekit image doesn't have a built-in GUI?

    2) I configured Mklauncher and Machinekit client, and when I communicate with the Beaglebone via Machinekit Client I see the And-Demo but not much else. How do I load a configuration to control a 3-axis CNC machine?

    Thank you,


    1. Post
  9. Hi,
    I have my mini mill just about mechanically finished so wanted to complete the controller. I'm afraid I'm a Linux goof but followed your blog and have, I believe, a working system. i.e. I can run the halcmd. So like the other post I have no idea what to do next (I did have it on an rpi a few years ago and could run and edit the ini's!). I did faff around and loaded lxde to give me a GUI but when I launch machinekit and pick a config it just sits there at 100% for ever. I ran your AND and that is fine too and I see your instruction to start a configuration but I don't really know how to do that. Might you have that described elsewhere or could you possibly point me in the right direction? Any help much appreciated!


  10. sudo apt-key adv --keyserver hkp:// --recv 43DDF224
    Executing: /tmp/apt-key-gpghome.TwPIWYqfS5/ --keyserver hkp:// --recv 43DDF224
    gpg: keyserver receive failed: Server indicated a failure
    I'm getting this error can you please tell me what to be done?

  11. Hello,

    I follow with steps and stuck on some problem. Can you help me ?

    halcmd loadusr io started
    Traceback (most recent call last):
    File "", line 20, in
    File "/home/machinekit/MiniKossel-CRAMPS/", line 45, in init_hardware
    File "/home/machinekit/MiniKossel-CRAMPS/config/", line 34, in usrcomp_watchdog
    watchdog = rt.loadrt('watchdog', num_inputs=count)
    File "hal/cython/machinekit/rtapi.pyx", line 223, in machinekit.rtapi.RTAPIcommand.loadrt (hal/cython/machinekit/rtapi.c:5293)
    RuntimeError: rtapi_loadrt '('watchdog', 'num_inputs=1')' failed: Operation not permitted
    Shutting down and cleaning up Machinekit...

    1. Post
  12. Hey there, I followed all the mentioned steps and I couldn't figure out how to enable the xenomai for my kernel. Also, when I flashed the contents of eMMc to the microSD card and then power up the board with the microSD card inserted, the card is flashing the image back to eMMc. How do I resolve these problems?


    1. Post
  13. Hello,

    After flashing the image you provide on my bbb i was able to ssh into it however i noticed that a few commands are missing such as connmanctl and ifconfig. I also noticed
    that my computer does not recognize my bbb. I would install the packages to get the missing commands but i cant since i have the wifi version of bbb so i
    need connmanctl which i dont have for some reason. I would have connected to the internet over usb but i cant since my pc wont recognize the device once this
    image is flashed to the emmc. Do you know of any way i can resolve my problem? Or did i do something wrong?
    Thank you.

    1. Post
  14. Hello,

    Since i am primarily interested in the creating real-time application is it possible that only installing PREEMPT_RT kernel will solve high latency issues and does it immediately replace my current kernel or is there additional setup to get it working after the install?

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.