Thursday, February 7, 2019

Using Machinekit on the BBB - a hands on log of how I did it, by Malte Scmidt

When setting up my machine  I realized that, while all needed information was available somewhere, the information was somewhat scattered around and it took some time to figure out what was relevant and what was not.
I therefore collected some notes and thought about posting this somewhere (blog) to help others. I have some background in Linux and Linuxcnc (PC) as user and did therefore not note down line for line but rather tried to capture the overall process of getting machinekit to work on a BBB. 


(This document was written in December 2018/January 2019)

The challenge:
    Automate a lathe with 2 steppers, limit switches
    Allow for manual turning using encoder input for x, z
    Provide glass scales input for manual turning (this may be considered gold plating but my initial plan was to use this lathe in CNC or manual mode)
    Obviously have spindle feedback and control the lathe motor
    Ideally controlled via touchscreen.

My leanings:

I considered the following approaches:
    With the amount of inputs required a 
    - parallel port solution would only be feasible if multiple parallel ports are used. -> decided against it
    - MESA card solution requires two cards -> expensive, decided against it
    - A beagle bone based solution with GPIO and PRUs -> my tentatively selected approach. Downside of this is the poor graphic performance

Linux on the Beagle Bone Black:
    Three different options exist for Realtime in the Linux Kernel
    - RTAI
    - Xenomai

    All are patches to the vanilla Linux kernel. 
    - RTAI is old and seems to be superseded by...
    - RT_PREEMPT which will be adapted by main Linux kernel
    - Xenomai is commercial

    My takeaway is that RT_PREEMPT would be ideal but Xenomai is a possible option.
    Two different Debian Linux distributions have been considered:
    - Stretch
    - Jessie

    To get a Debian distribution and one of the realtime kernels on the beagle board three approaches have been explored:
    1) Putting it together by hand (
    2) Getting Stretch + RT_PREEMPT from eLinux ( and
    3) Getting Jessie + Xenomai from eLinux (see links above)

    - Current RT_PREEMPT + Stretch combinations 1) and 2) above have long boot times of 2-4 minutes.
    - The blog post in 1) is a good read in any case to perform some steps to get the system up to date and further improve boot times
    - I was not able to flash using the procedures described in most online places. I booted from SD and than used the approach outlined (
        cd /opt/scripts/tools/eMMC/
        sudo ./

    I'm currently using Jessie and Preempt_RT because I'm lazy. There is some background here on the boot time issue which will hopefully be resolved in the future:!topic/machinekit/sOWj5I7fVpo
Cape support
    - No commercially available cape was suitable to be used with my requirements. So I decided to go with a Sparkfun prototype cape and wire up things from there.
    The name of the board coded in the EEPROM will tell which device tree overlay file to load. The device tree overlay file declares the pins we can use with this cape.
    With different Linux versions different approaches exist how this is achieved.
    Linux 3.8 / Xenomai + Jessie uses cape-manager
    Linux 4.4 / Preempt_RT + Stretch uses U-boot overlays

    Most resources in the internet are about capemanager.
    We need two things for loading the cape during boot:
    -- EEPROM
    -- Device Tree overlay file

    - The easiest way to get through this is using existing device tree overlay files. (
    - This means that the eeprom needs to be coded such that those are loaded. 
      Use to write e.g. cape-universal in both the board name and revision field (I don't know which field is actually used)
    - For the Sparkfun Prototype cape it may be good to know that the sparkfun prototype cape addr is 0x57
    Checking if cape is recognized  
        - Check that the cape is recognized (e.g.
        U-Boot overlays
        - Check that cat /proc/cmdline shows overlay file handed over to kernel
    - Also worth to note:!topic/machinekit/SF9xA8sdpB0 and
  My board stopped booting from eMMC at this point when the cape was connected. It's unclear why 

Machinekit setups
    Get this tool: (
    To create a BBIO file that actually contains the pins and settings you intend to use
    Get and modify from one of the different configurations (e.g. from
    I created a "standard" Axis UI configuration (i.e. the selection that comes up when starting machinekit) and copied the .ini file from there. I also copied GUI related stuff (postgui.hal and xml files)
    I used the cramps hal file as starting point for my specific stuff:

    My takeaways
      - Make sure to understand the constraints:
        - Pin usage and dependencies are error prone. The same output may be routed to different pins
        - You can use only one PRU (machinekit driver restriction)
Adding hardware inputs and outputs to my custom cape
    A fairly straightforward thing. I used HW-399 Optocoupler Modules to isolate all inputs. They are based on a TLP-281 chip. All powered from the beagle board.
    The outputs are generated by a 4 channel (BiDirectional - although this is not used) logic level converter module. There are integrated and discrete solutions for this on the market.
    I used a discrete version here to provide the required current (afaik <15mAh) for the optocouplers in the stepper drivers. The integrated drivers available in the market are not as capable in this regard.

    Overall 16 inputs and 4 outputs are generated this way.
    The hardware design is not as nice but good enough for me. I mounted the logic lvel converter and one optocoupler on the proto cape.
    The other parts are mounted on 3D printed holder together with the BBB
The "real" User interface
    As stated in the beginning it was clear that the BBB would not deliver a good graphics performance and I looked into different options how to deal with this

    a) Axis with remote X server
    This was too slow. And also not did not meet the desire to use a touchscreen. I also did not see a way to work around this.

    b) QtQuickVCP with Cetus or a to be developed UI (for touch)
    This seems to be somewhat work in progress. The UI responsiveness was good but there were two things that I considered as downsides. The main thing was that
    the UI requires a number of user interactions to actually load. The development effort for a touch UI was another downside.
    c) Machinetalk with Browser based UI (WebVCP)
    This would have been a possible option to work around the different user interactions with QtQuickVCP. But I did not get this to work within reasonable time
    The development effort was also clearly a downside here
    d) Touchy
    Touchy delivered a reasonable graphics performance when using this with a remote X server. I therefore investigated this further and realized that this is actually fast enough with X running on the BBB itself. I assume this is because touchy will not create a preview. Since I'm running a lathe which is 2D only this is actually good enough.
    My learnings:
        - Touchy is what I will be evaluate / use further. If my requirements would have included a working preview I would have continued with QtQuickVCP.

X Display system + touchsceen.
    - I'm using a waveshare 7" touchsceen. My first attempts to get this to work failed (touch was not working). 
    It started to work after I installed lxdm but likely this was because some tools got installed in this process. I did not figure out the details here.
    follow these steps to automatically log to the terminal:
    and add startx [] to your .bashrc


  1. so how has it gone since Jan 2019?

  2. It's now August 2023 and like so many LinuxCNC or in this case MachineKit projects once again we're left hanging. No schematic. No HAL or INI files. No photos of completed lathe or LCD display with BBB.

    1. Cannot agree more, we have here a powerful tool to manage any machine, and nobody is able to use it because documentation is so messy and installation so hardware specific...
      Everybody give up at some point.