Create MachineKit SD Card Without a Linux Machine

NOTE: The latest BeagleBone MachineKit releases include both a tar.xz file, and a raw image file.  If you don't have a Debian or Ubuntu Linux system handy, I suggest you use the raw image file and copy it directly to the uSD card.  Use dd if you have any Linux machine available, or one of the Windows disk imaging utilities if you only have Windows.  It is no longer recommended that you create your uSD card image using the instructions below, which remain here in the hope that they may be somewhat informative (and to avoid broken links).

If you have a BeagleBone and want to play with my MachineKit image but are stuck on Windows without a handy Linux system (other than the 'Bone itself), here's how to do it.

WARNING: These instructions are meant to be easy to follow, but are not targeted at the complete Linux novice.  If this is your first experience with the Linux command line, find a friend with a Linux machine and get them to make you an SD Card image.  If you don't have any friends with Linux machines, Google a bit to find a LUG or maker space near you, and offer to buy someone a beer if they'll burn an SD image for you.  Presto!  You now have friends with a Linux box!  :)

OK, let's get started.  First, gather up all the supplies you need:
  • Download my MachineKit image (start it now, it takes a while)
  • A 4G or larger USB Key, with at least 3G or so of free space
  • A USB SD-Card Reader
  • A 4G or larger SD card plugged into the SD-Card reader.  This is the SD card that will contain the MachineKit install when you are finished.
  • A USB Hub with a power cord.  Trying to power the hub from the BeagleBone will not work reliably.
Once the image file finished downloading, you need to extract it.  Download and install the excellent 7-Zip archiver if you don't have it already.  Find the downloaded <file>.tar.xz image file in Explorer, right-click, and select "7-Zip -> Extract Here".  You will get a much larger <file>.tar.  Right-click on the new Tar file and select "7-Zip -> Extract Files".  In the extraction dialog that pops up, change the "Extract to:" destination to point to your USB key with at least 3G of free space, and make sure you add a directory name so you can find the files.  My USB Key is drive G:, so I used "G:\MachineKit" as the extraction path.  Click OK, and wait for a while as the files are extracted to your USB key.  Eject the USB key from your Windows machine and set it aside for now.

Plug a USB hub with your USB Key and SD Card reader into your BeagleBone with the BeagleBone TURNED OFF (USB hot-plug is broken on several early versions of the AM335x kernel, so this makes sure you will be able to see your devices).

Power up and boot your BeagleBone as usual and obtain a command prompt.  You can do this stand-alone with a keyboard and HDMI monitor (Black only), tethered via USB, using a serial-port cable, via ssh, etc.  If you can't get to a command prompt on your BeagleBone stop now, go read the BeagleBone documentation, and don't come back until you can tell me how much free space is left on your root filesystem by running 'df' at a command prompt.

 So go ahead and run the df command.  Recent BeagleBone images should auto-mount the USB storage into the /media directory.  Here's what it looks like on my 'Black:
root@beaglebone:~# df
Filesystem     1K-blocks    Used Available Use% Mounted on
rootfs           1738184 1297492    350728  79% /
/dev/root        1738184 1297492    350728  79% /
devtmpfs          255216       0    255216   0% /dev
tmpfs             255320       4    255316   1% /dev/shm
tmpfs             255320     236    255084   1% /run
tmpfs             255320       0    255320   0% /sys/fs/cgroup
tmpfs             255320       4    255316   1% /tmp
/dev/mmcblk0p1     71133   55179     15955  78% /media/BEAGLEBONE
/dev/sda         3919868 2737024   1182844  70% /media/CRUZER 4G
/dev/sdb2       15116684 2892476  11449656  21% /media/rootfs
/dev/sdb1          66396       0     66396   0% /media/BOOT
Note the four lines at the bottom.  In order, they are:
  1. /dev/mmcblk0p1
    This is the BeagleBone boot partition
  2. /dev/sda
    My 4G USB Key
  3. /dev/sdb1 & /dev/sdb2 These are two existing partitions on my SD card.
To avoid the potential for confusion and data corruption, unmount the SD Card partition(s) now:
umount /dev/sdb1
umount /dev/sdb2
Now change to the directory where you extracted the image.tar.xz file.  In my case, that is "/media/CRUZER 4G/MachineKit/".  You will know you are in the right place if you see the script:
root@beaglebone:~# cd /media/CRUZER\ 4G/MachineKit/
root@beaglebone:/media/CRUZER 4G/MachineKit# ls
root@beaglebone:/media/CRUZER 4G/MachineKit# cd debian-7.0.0-machinekit-armhf-2013-06-14
3.7.10-x12-dtbs.tar.gz            uInitrd-3.2.42-psp27
3.8.13xenomai-bone20-dtbs.tar.gz  uInitrd-3.7.10-x12
armhf-rootfs-debian-wheezy.tar    uInitrd-3.8.13xenomai-bone20
hwpack                            user_password.list
initrd.img-3.2.42-psp27           vmlinuz-3.2.42-psp27
initrd.img-3.7.10-x12             vmlinuz-3.7.10-x12
initrd.img-3.8.13xenomai-bone20   vmlinuz-3.8.13xenomai-bone20
Now all you have to do is run the script with the proper options.  The --mmc device should be the base device of your SD Card (WITHOUT any trailing partition number!), and the --uboot option should always be bone_dtb, so for my setup, I run:
# bash ./ --mmc /dev/sdb --uboot bone_dtb

I see...
/sbin/fdisk -l:
Disk /dev/mmcblk0: 1920 MB, 1920991232 bytes
Disk /dev/mmcblk0boot1: 1 MB, 1048576 bytes
Disk /dev/mmcblk0boot0: 1 MB, 1048576 bytes
Disk /dev/sda: 4022 MB, 4022337024 bytes
Disk /dev/sdb: 15.9 GB, 15931539456 bytes
Review the partitions CAREFULLY and if everything looks OK, let the script continue on.  Once the script completes, you can power down and you should have an SD Card you can boot from that runs the MachineKit Debian install with LinuxCNC.


  1. Hi Charles

    I think that the line in your blog is corrupt:

    # bash ./ --mmc /dev/sdb --uboot bone_dtbhinekit-armhf-2013-06

    Is that possible, at least it did not work for me.

    Mike ( Linuxcnc fan )

  2. Yep...that was a cut-and-paste goof (fixed). Thanks for the catch!

  3. Salu Charles

    Now I'm one step further.. but now I get a new error message:

    wget: bad address ''
    error: can't connect to, retry in a few minutes.

    On my PC I can reach that adress in the web browser..

    What do I do wrong ?


  4. It sounds like your BeagleBone isn't hooked to the network. Do you have Ethernet connected to the BeagleBone and DHCP setup on your network?

  5. No, I use USB .

    And I do not realy understand what the driver is doing... W7/74 ultimate.
    At least I'm not able to use a SSH on outside of chrome.

    Will try via ethernet and hdmi and then come back.

  6. Hi Charles

    Now it's up. Definitively the machinekit as downloaded to the microssd.
    I use ethernet cable and via my Nexus 10 I can acces the BBB via ssh.

    I can see directories and read files etc. Only tty style...

    Where can I read how to start a linuxcnc applikation and how to get
    the axis screen to my Nexus?

    P.S. I'm not strong in linux, but quite used with linuxcnc (ca. 2002)

  7. If you're using ssh, as long as X11 forwarding is enabled you should be fine. Just run "linuxcnc &" at the command line and the display should appear on your Nexus. If that doesn't work, try something simple like xterm. If _that_ doesn't work, dig around in your ssh client configuration and see if you can figure out how to enable X11 forwarding (I'm not sure it works with Android, but it ought to be possible...from a bit of Googling you may have to install an X server on your Android system). If you are using a standard Linux system, you would simply "ssh -o forwardX11=yes"

    You can also use the cygwin X11 server on Windows and putty if you're short on available Linux boxes.

  8. I'm a bit confused

    Starting a ssh server on my Nexus ?

    Or, what in could understand, just I start something in my BBB


  9. Comming nearer

    I installed an APP called VXConnectBot plus the proposed

    Starting via sever I see now coloured tty.
    But running linuxcnc shows an error message:

    Applications initialisation failed
    No displayname and no $DISPLAY environement variable set......

    What did I miss?

  10. You probably don't want to be doing this with an Android tablet, especially if you're not familiar with Linux, but the "no $DISPLAY variable set" generally means you do not have X11 forwarding enabled via ssh. You will have to review your ssh client documentation to see how to enable X forwarding.

    As for starting an ssh server on the Nexus, no you do not have to do that. The ssh *server* is the BeagleBone. The ssh *client* is running on the Nexus and needs to be setup to forward X11. The BeagleBone side is already setup to allow X forwarding.

    I warn you, however, that even if you get this sort-of working (ie: you can run xterm and see a BeagleBone console on the Nexus), LinuxCNC is not likely to run as a bit of Googling shows the X servers available for Android are generally lacking all but the bare minimum of functionality. If it does work, it will likely be with one of the older interfaces (try some of the sim setups with GUI interfaces other than axis).

  11. THX Charles for your patience

    Yes, I will have to digg deeper into the x-window story..
    Had already a bit of windows in my Nexus..

    I fear it's not a profesionnal solution with stable use via a Nexus,
    but that way I can exercise a bit, and compare BBB speed versus PC.

    Keep you informed.


  12. Heureka

    I gave up (at least for a while) to connect via my Android tablet.. As you wrote , until now it's not good enough supported by android.

    I went to a PC, using W7/64Ulti. and Bitvise SSH /SFTP Client as filemanager and Xming as X11 window suporting X server.

    Was able to get the BeBoPr running and also to make my own was easy to do. Now I have to fiddle around the I/O pins.

    In my environement I have ca 1.5 sec updaterate for the axis screen. I would like to run a hdmi/VGA/ LCD native, and that as I understood needs other pin layout.

    So enough to do in the next days/weeks...

    THX again Charles. Only with your help I reached that point.


  13. This comment has been removed by the author.

  14. This comment has been removed by the author.

  15. After extracting the image to a USB key, next I need to connect a USB hub to the Beaglebone with the USB key and SDcard reader attached to the USB hub. Do I need to have an SDcard with the basic Angstrom distribution plugged directly into the Beaglebone when I boot up or leave the slot empty? Do I need to have my new empty SD card plugged into the SDcard reader?

    1. The contents of the SD card don't matter, they will be overwritten. You will be booting the Angstrom release from the 2G flash on-board the BeagleBone Black. If you have a BeagleBone White, you need the default Angstrom SD card plugged into the BeagleBone, and your 4G or larger SD card for MachineKit plugged into your SD card reader.

      Either way, it's best to have everything attached before you power up. While things are improving, several BeagleBone kernels have issues with USB hot-plug.

      Finally, you may find it easier to use the raw image file with Windows, instead of trying to run the Linux-based script to create the SD card. It takes a bit longer, but is generally less hassle.