README.md

Machinekit-HAL

Universal framework for machine control.

Website | Docs | About

Machinekit-HAL is a powerful software for real-time control of machinery based on Hardware Abstraction Layer principle. With tools and libraries making development of new components and drivers easy. Integrators can choose to control industrial robotic arm, single purpose machine or CNC mill or lathe with additional software package.

Supporting RT PREEMPT and Xenomai 2 real-time Linux kernel patches. APT packages available for Debian 11 Bullseye, Ubuntu 18.04 Bionic LTS, Ubuntu 20.04 Focal LTS and Ubuntu 21.04 Hirsute.

Getting started

The easiest way how to get Machinekit-HAL running is to install Debian package. Packages can be obtained by triggering Github Actions workflow and downloading build artifacts on your own fork. Packages build from every push to master branch on official Machinekit/Machinekit-HAL repository are also distributed through Machinekit-HAL repository (Dependencies) kindly hosted by Cloudsmith.

Available packages constituting the Machinekit-HAL are:

• libmachinekit-hal: Main shared libraries needed for the core functionality

• libmachinekit-hal-dev: Development files (headers, CMake export scripts and STATIC libraries) for the libmachinekit-hal package

• modmachinekit-hal-components: Managed modules (components) for dynamic loading into HAL

• modmachinekit-hal-drivers: Managed modules (drivers) for dynamic loading into HAL

• modmachinekit-hal-drivers-dev: Development files (headers, CMake export scripts and STATIC libraries) for the modmachinekit-hal-drivers package

• machinekit-hal-unmanaged-components: Unmanaged modules (components) for dynamic loading into HAL

• machinekit-hal-unmanaged-drivers: Unmanaged modules (drivers) for dynamic loading into HAL

• machinekit-hal-testsuite-runtests: Machinekit-HAL runtest suite of tests

• machinekit-hal: Main executables of the Machinekit-HAL project

• python3-machinekit-hal: Python3 specific executables of the Machinekit-HAL project

• python3-libmachinekit-hal: Python3 specific modules and packages of the Machinekit-HAL project

• python3-modmachinekit-hal-unmanaged-components: Machinekit-HAL unmanaged modules (components) implemented in a Python3

• python3-modmachinekit-hal-unmanaged-drivers: Machinekit-HAL unmanaged modules (drivers) implemented in a Python3

To access the Cloudsmith repositories you will need to add it to your keyring and sources.list:

curl -1sLf 'https://dl.cloudsmith.io/public/machinekit/machinekit-hal/cfg/gpg/gpg.D35981AB4276AC36.key' | sudo apt-key --keyring /etc/apt/trusted.gpg.d/cloudsmith-apt-key.gpg add

touch /etc/apt/sources.list.d/machinekit.list

sudo sh -c "echo 'deb https://dl.cloudsmith.io/public/machinekit/machinekit-hal/deb/debian bullseye main' >> /etc/apt/sources.list.d/machinekit.list"

sudo sh -c "echo 'deb-src https://dl.cloudsmith.io/public/machinekit/machinekit-hal/deb/debian bullseye main' >> /etc/apt/sources.list.d/machinekit.list"

In most cases, all packages will be installed (with maybe the exception of machinekit-hal-testsuite-runtests).

sudo apt install -y libmachinekit-hal libmachinekit-hal-dev modmachinekit-hal-components modmachinekit-hal-drivers modmachinekit-hal-drivers-dev machinekit-hal-unmanaged-components machinekit-hal-unmanaged-drivers machinekit-hal-testsuite-runtests machinekit-hal python3-machinekit-hal python3-libmachinekit-hal python3-modmachinekit-hal-unmanaged-components python3-modmachinekit-hal-unmanaged-drivers

Dependencies and Tools

You can use a standard Debian tools to download and install most of the dependencies (with the exception of build tools):

git clone https://github.com/machinekit/machinekit-hal.git
cd machinekit-hal
debian/bootstrap
mk-build-deps -irs sudo

To get a functioning filesystem capable of building Machinekit-HAL, consult the machinekit-builder Docker images. You can build them via the debian/buildcontainerimage.py script from Dockerfile in the debian/buildsystem directory.

If you have trouble, please try installing the dependancies by hand:

sudo apt install python3-build cython3 libczmq-dev python3-avahi \
  avahi-daemon avahi-discover avahi-utils libnss-mdns mdns-scan git \
  gcc g++ python pkg-config libssl-dev libdbus-1-dev \
  libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
  python3-pip unzip libgirepository1.0-dev libcairo2-dev \
  libjansson-dev libgtk2.0-dev python3-protobuf libprotobuf-dev \
  libck-dev libcgroup-dev libcmocka-dev yapps2 libreadline-dev \
  libmodbus-dev libusb-dev libusb-1.0-0-dev nanopb libboost-dev \
  libck-dev libcgroup-dev libcmocka-dev yapps2 libreadline-dev \
  libwebsockets-dev

Building from Source:

Machinekit-HAL uses a CMake based buildsystem and supports generation and usage of both makefiles and ninjafiles for GNU make and Ninja Multi-Config centered workflows.

Building requires a Linux installation with build tools installed (functioning C and C++ compiler, linker, pkg-config, sysroot etc) and the latest stable CMake executables as specified on download page. (Main target for Machinekit-HAL are Debian based distribution, others not tested so far.)

Generally, for Ninja Multi-Config build-tool, the sequence of commands will be (for run from a build binary tree in CMake nomenclature):

git clone https://github.com/machinekit/machinekit-hal.git
cd machinekit-hal
mkdir build
cmake -S . -B ./build -G"Ninja Multi-Config"
cmake --build ./build --config Debug
sudo cmake --build ./build --config Debug --target setuid
cmake --build ./build --config Debug --target binary_tree_venv
cd build
direnv allow
halrun

For GNU Make then:

git clone https://github.com/machinekit/machinekit-hal.git
cd machinekit-hal
mkdir build
cmake -S . -B ./build
cmake --build ./build
sudo cmake --build ./build --target setuid
cmake --build ./build --target binary_tree_venv
cd build
direnv allow
halrun

More information about building can be glanced from documentation.

	Be advised that currently there is no support for Linux distributions other than Debian derivatives.

History

Machinekit-HAL was created by separating the core functionality from now deprecated Machinekit repository into own repository.

It all started in the early nineties when NIST created the Enhanced Machine Controller Architecture in Public Domain as a vendor-neutral software implementation for numerical control of machining operations. From that in 2003 open community of developers created a project called EMC2 or Enhanced Machine Controller 2. (Or on the side of commercial software, EMC was developed into popular software Mach3 for Microsoft Windows.) EMC2 was renamed in 2011 as a LinuxCNC. In 2014, Machinekit was forked from LinuxCNC to facilitate deeper changes in low level functionality. In 2020, the original Machinekit repository was archived and development is fully continuing in the Machinekit-HAL repository.

	The CNC part of original repository was separated into the Machinekit-CNC repository in the same move.

Frequently asked questions

	What is the Hardware Abstraction Layer?
	HAL represents one of the fundamental elements of Machinekit-HAL. One could imagine HAL as a electronics breadboard into which semiconductors, passives or connectors (in HAL componets and drivers) are inserted and connected by wires (in HAL signals). This all happens in-memory and the execution stage runs in Linux scheduled thread.

	Is Machinekit-HAL LinuxCNC?
	No. In the current state of development, we can say that both Machinekit-HAL and LinuxCNC 2.8 have a common ancestor. However, Machinekit-HAL doesn't include the CNC functionality like LinuxCNC, the configuration is different and the supported platforms are different also.

	What's the difference between Machinekit-HAL and Machinekit?
	Machinekit-HAL is continuation of Machinekit. Work on the original Machinekit repository was stopped and the only new development will happen on Machinekit-HAL. Machinekit-HAL exports only the core functionality to better serve the needs of machine integrators and provide leaner experience for everybody. The CNC functionality was exported into Machinekit-CNC repository.

	How can I determine if .deb package is from official distribution?
	Every package should be signed by dpkg-sig tool. Packages built by Machinekit from official repository Machinekit/Machinekit are signed by the 4A374E9D7CA79FA717293B98D2EFAE426CDDB0FE sub-key. Forks will use different key or will not sign the packages.

Getting involved

Machinekit-HAL like all projects in the Machinekit organization is volunteer based governed by the Collective Code Construction Contract , generally known as a C4 originally from the ZeroMQ project.

The source code is hosted publicly on GitHUB, where majority of programming discussion about further development happens. In lower measures, Machinekit-HAL is also discussed on Machinekit forum and in Machinekit Matrix Room, which are used more to the point of support platforms and for general chat.

For a change to be eligible for merge, all automatic tests need to run to successful conclusion. This includes the building and x86_64 and arm64, running the runtests acceptance test suite, the pytest test suite and the pre-commit driven formatting and linking checkers.

For developer's convenience, the Machinekit-HAL source-tree includes a pre-commit configuration, and it is strongly suggested to install the manager and run the hooks during git operations to automatically format and lint the changed files. (Of course, only the end result is important, and you can use whatever tool you please to archive it.)

Installing the pre-commit into virtual environment:

python3 -m venv development/pcvenv
source development/pcvenv/bin/activate
pip install pre-commit
pre-commit install

Or you can consult the installation step in the official Documentation.

	It's always encouraged to create a new issue in GitHub tracker first. Discuss the proposed changes there and then based on the output implement the changes and create a new pull request.

Licence

This software is released under the GPLv2, with some parts under the LGPL. See the file COPYING for more details.

	For more detailed information consult specific files with source code implementing given functionality. There should be explicit licensing.