quick start guide?

[rockandsalt]

I am interested in using machinekit-hal. But I have no idea where to start, the documentation links in the readme file redirects to a blog as stated here.

Is there any new documentation? I am somewhat familiar with linuxcnc but I have no idea how much machinekit-hal has diverged from it.

[cerna]

Unfortunately, the documentation was never a strong suit for the Machinekit project and what is available on the https://www.machinekit.io page is in big part outdated. But, so far, it is the best what's available. Sorry.

I haven't yet wrote (updated) the documentation for the CMake based buildsystem, so the only documentation is the [https://github.com/machinekit/machinekit-hal#getting-started](Getting Started) section in README on the from page on Github. I have no idea how useful that is for someone who does not have intimate knowledge of the codebase though.

Maybe if you have some idea what you would like to read in such a Quick guide, I could splice something up real quick...?

[ebo]

I cannot speak for rockandsalt, but I would be willing to help update the quick start guide so that it actually is functional.

I see that the QSG states that in most cases we can just use:

  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

The problem is that those packages are not found anywhere, and you give no instructions on how to get them linked through the sources.list or other files in the OS to get them up and running quickly. While I found some magical curl invocations to get it a little further down the road, I am still getting unable to locate libmachinekit-hal lots of other packages. Som guidance here would be nice. I'll search more in the issues and see if this is mentioned elsewhere, but a few extra dance steps in the QSG would have saved us some pain. Once I figure out how to get it installed via the prebuilt packages I'll add it and post a pull request. I will need to have anything I write verified as I've tried so many things that it by the time I get it to run I am not sure I will know how I got here...

[rockandsalt]

@cerna, to get started I was looking for a Helloworld example either using the hal or python interface. just to get a feel of the available function and the namespace (ie where things are).

[ebo]

Here are some simple notes of all of the packages I had to add starting from a clean Bullseye install on a RPi-3B.

The getting started guide needs instructions to get the following to work:
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

The system does not find any of these. It is likely that I need to configure the machine to see the Cloudsmith repository, but there are no instructions for that, so I moved forward building by hand.

As a note, once I got through the section on configuring and building using GNU make, I see that there is a section on bootstraping. If the intent there is to install the necessary packages (included below), then it would be nice to have that section moved up in the document BEFORE the step by step build instructions.

Here are the packages I ended up installing. Some of them are likely redundent, but at least I got it to the point where it would build mostly through:

Question: is there any reason that cmake 3.22 is required? It would make more sense to use the most recent stable cmake provided -- until 3.22 becomes available -- that or build a package on Coldsmith or elsewhere.

Install the following packages (probably an over estimate):
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 libcmocka-dev yapps2 libreadline-dev
libmodbus-dev libusb-dev libusb-1.0-0-dev nanopb libboost-dev

I will dig around and look at repurposing the RPi-4 I have on had to see if it will build out of the box.

[ebo]

Here is another list of dependencies I missed in the copy-posta:
libck-dev libcgroup-dev libcmocka-dev yapps2 libreadline-dev

[ebo]

and another one that did not show up until about 18% thought the build:

  libwebsockets

[ebo]

another clue...

The original documents:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 43DDF224
sudo sh -c
"echo 'deb http://deb.machinekit.io/debian buster main' >
/etc/apt/sources.list.d/machinekit.list"

I found I needed to modify the sourcces.list and keyring by:

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

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"

A this point I was able to run:
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

[rockandsalt]

thanks everybody, I am going to check it out.

[ebo]

@rockandsalt you might also want to check my cleaned up notes at https://github.com/ebo/machinekit-hal I think I still have a couple of minor bugs in the write (like setting -march which I am testing in the background). Like I said, in a pit I will put in a PR. If you would be so kind as to take a look and review my quick start docs and changes, that would be great to get a review before submitting the PR.

[jallwine]

In case it helps anyone, I was able to get all the machinekit-hal packages built using this documentation:
http://www.machinekit.io/docs/developing/machinekit-developing/

The only change was the buildcontainerimage.py script is under the debian directory rather than the scripts directory. Also, be sure to replace the DISTRIBUTION, VERSION and ARCHITECTURE variables properly in the commands. Once I had all the packages, I installed them and their dependencies using:

sudo dpkg -i *.deb
sudo apt-get -f install

At that point, you can fire up the real time environment and start tinkering (of course, there's no G code interpreter, trajectory planner, etc. from EMCApplication or machinekit-cnc):

realtime start
halcmd newthread servo-thread fp 1000000
halcmd loadrt siggen
halcmd addf siggen.0.update servo-thread
halcmd start

This creates a single HAL component siggen.0, which can then be queried over time (or hooked up to a some kind of hardware component):

halcmd show pin siggen.0

Component Pins:
Comp   Inst Type  Dir         Value  Name                                            Epsilon Flags  linked to:
90        float IN              1  siggen.0.amplitude                      	0.000010	--l-
90        bit   OUT         FALSE  siggen.0.clock                          		--l-
90        float OUT    -0.9785809  siggen.0.cosine                         	0.000010	--l-
90        float IN              1  siggen.0.frequency                      	0.000010	--l-
90        float IN              0  siggen.0.offset                         	0.000010	--l-
90        float OUT         -0.05  siggen.0.sawtooth                       	0.000010	--l-
90        float OUT     0.1502255  siggen.0.sine                           	0.000010	--l-
90        float OUT            -1  siggen.0.square                         	0.000010	--l-
90        float OUT        -0.924  siggen.0.triangle                       	0.000010	--l-
90        s32   OUT         13500  siggen.0.update.time                    		----
90        s32   I/O         20666  siggen.0.update.tmax                    		----
90        bit   OUT         FALSE  siggen.0.update.tmax-inc                		----

[ebo]

@jallwine, thaks for this. Was this part of the section with the docker build, or the run in place?

I am wondering if we should scrape the old documentation and rework it in a docs directory? Just a thought. It will likely be a few days before I can break out more time for this.

[jallwine]

I followed the docker build instructions for getting the deb packages.