I followed this advice:

The easiest way to fetch all the machinekit runtime packages is to install a current package, and then delete it

but ./configure told me that some packages are still missing beginning with Protobuf compiler.

So I had to install missing packages one by one until ./configure did not complain any more.
Those were:

  sudo apt-get install -y  libprotobuf-dev protobuf-compiler python-protobuf libprotoc-dev
  sudo apt-get install -y  libtool liburiparser-dev
  sudo apt-get install -y  libssl-dev  openssl
  sudo apt-get install -y  uuid-dev
  sudo apt-get install -y  libavahi-client-dev
  sudo apt-get install -y  libmodbus-dev
  sudo apt-get install -y  libusb-1.0-0-dev
  sudo apt-get install -y  libreadline-gplv2-dev 
  sudo apt-get install -y  libglib2.0-dev
  sudo apt-get install -y  libgtk2.0-dev tcl8.6-dev tk8.6-dev
  sudo apt-get install -y  libxaw7-dev
  sudo apt-get install -y  libboost-python-dev
  sudo apt-get install -y  libglu1-mesa-dev

The order of installtion may be important.

I did then

sudo apt-get remove --purge machinekit

after make run.

libreadline-gplv2-dev got me into dependency hell. It should have been libreadline6-dev from the very beginning.

I discovered preview and production builds were broken for over a week, see also discussuion at #193

I think I patched it up, but frankly I do not understand the causality; factoids are:

• I used ssh://[email protected]/machinekit-ci/machinekit-ci.github.io to pull and force-push to the HTML storage repo
• this stopped working, I had to change the URI to use ssh://[email protected]/machinekit-ci/machinekit-ci.github.io (it uses the machinekit-ci SSH key pair though), and change the credential to use 'git' instead of 'machinekit-ci' - works now
• the git subtree pull of the machinetalk-protobuf repo stopped working with 'Working tree has modifications' (the rsync'd asciidoc files)

changing this to

# update the machinetalk-protobuf subtree

git stash
git subtree pull --message="machinetalk-protobuf subtree merge" --prefix machinetalk-protobuf machinetalk-protobuf master --squash
git stash pop

fixed it for now (both here and here)

very weird

For information regarding (py)machinetalk/haltalk I would need to dig thru the code. We should have (minimal is OK) documentation of it's design (minimal is ok) and how to use it.

There's still work to get static HTML or PDF documentation. Generating packages that go together with the Machinekit packages. IMO no rush, but let's not forget this.

I think this means building against a PR to the machinekit-docs

this is an anchor issue about the web mechanics perspective:

• which style/fonts/layout/css etc should we use?
• which source highlighting style is best
• do we need an epub format of the website?

we need a bit of a style guide for writing documents and man pages!

Just got my first ever machinekit up and running. One part I didn't find in the documentation was how to resolve resource confllcts between capes.
It manifested itself as

Loading cape-universal overlay
bash: line 0: echo: write error: File exists

It isn't all that easy to understand what the problem is. dmesg gives the right clues though.

From what I understand this is a well known issue (now when I have googled it).

The solution is to load/unload HDMI/HDMIN cape.
I think a description of this topic would be a great fourth point under the BeagelBone Black / jessie installation.
Ref: https://groups.google.com/forum/#!topic/machinekit/AjBFY6aMSeQ

It would be wise to have some preferred way of making headers so it's easy to have the second pair of C4 eyes looking at a PR like me merging #10 while @zultron had some remarks.

I noticed when prepping a new BBB image for development that instructions to install packages are here:
http://www.machinekit.io/docs/developing/machinekit-developing/#install-development-packages
specifically:

sudo apt-get install libczmq-dev python-zmq libjansson-dev pkg-config \
  libwebsockets-dev libxenomai-dev python-pyftpdlib cython bwidget lsb-release

now when getting to the section:
http://www.machinekit.io/docs/developing/machinekit-developing/#get-source-and-build
in the step sudo mk-build-deps -ir it pulls in a lot of packages.

2 questions:

1. Can't the packages above be pulled in in the same way via sudo mk-build-deps -ir?
2. Am I right that the package machinekit-dev is missing in above instructions ( I get the impression that this is needed for the sudo mk-build-deps -ir step?

Someone should craft a glowing blog post about the new documentation changes. I will do so if necessary, but I'd rather it come from one of the group who actually did a good chunk of the work. I was barely able to keep up with the issue emails you were all working so fast! :)

...and GREAT JOB EVERYONE! It's super exciting to see all the changes!

@luminize pointed out that some of the commits silencing build warnings in machinekit/machinekit#327 now apply to this repo.

Just saw this link appear on the list.
http://wiki.linuxcnc.org/cgi-bin/wiki.pl?BeagleboneDevsetup

In due time we should pick these instructions and put them into the docs at the appropriate place.

do we still need this?

conjecture: can be removed

Some documents are generic and of standalone worth.

Some are Linuxcnc specific and need weeding.

Others are valid topics for Machinekit, but need to be made specific to take account of changes made.

Your lists please

@mhaberler @Strahlex @RunningLight @luminize @cdsteinkuehler et al.

Currently, there is no place where all project maintainers are publically listed. I suggest adding a new section on the Machinekit.io website containing the project maintainers.

Currently, the only place to find a list of project maintainers is here:
https://github.com/orgs/machinekit/people
However, even on this page, many people are marked private.

Referrering to http://www.machinekit.io/docs/packages-debian/ .

Just tried to install machinekit-xenomai on an identical machine as I did it two months ago:

~$ uname -a
Linux debian-slave 3.8-1-xenomai.x86-amd64 #1 SMP Debian 3.8.13-12~1wheezy~1da x86_64 GNU/Linux
~$ halrun
msgd:0 stopped
rtapi:0 stopped
halcmd: hal_init() failed: -22
NOTE: 'rtapi' module must be loaded
halcmd: hal_init() failed: -22
NOTE: 'rtapi' module must be loaded
halcmd: hal_init() failed: -22
NOTE: 'rtapi' module must be loaded
halcmd: hal_init() failed: -22
NOTE: 'rtapi' module must be loaded

So rtapi.so cannot be found somehow...

~$ sudo find / -iname rtapi.so
/usr/lib/pyshared/python2.7/machinekit/rtapi.so
/usr/lib/linuxcnc/posix/rtapi.so
/usr/lib/linuxcnc/xenomai/rtapi.so
/usr/lib/python2.7/dist-packages/machinekit/rtapi.so

But the same on the other machine (same hardware) yields:

~$  sudo find / -iname rtapi.so
/usr/lib/rtapi.so
/usr/lib/linuxcnc/xenomai/rtapi.so
/usr/lib/linuxcnc/posix/rtapi.so
/usr/lib/pyshared/python2.7/machinekit/rtapi.so
/usr/lib/python2.7/dist-packages/machinekit/rtapi.so

So the older installtion has /usr/lib/rtapi.so .
This older machinekit-xenomai installation is of 1st Nov 2015.

The legacy documentation was set up as 6 manuals. (Paper/PDF)

With the Jekyll site we should change towards a situation where:
Buildup from explanations of What machinekit is and does, towards getting started (terminal), making configurations, examples, increasing the level of knowledge towards the more "developers" and api stuff.

I've got no idea if this is technically do-able, but how about explaining all parts in correct order, and showing/hiding/collapsing (button, checkmark in the site) some more advanced stuff for those who need it?

Hello,
I have no picture on my browser 'Seamonkey 2.33.1' ?
Kind regards

Referring to https://github.com/machinekit/machinekit-docs/blob/master/machinekit-documentation/developing/machinekit-developing.asciidoc

$ sudo apt-get install libzmq3-dev
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following package was automatically installed and is no longer required:
  libzmq1
Use 'apt-get autoremove' to remove it.
The following extra packages will be installed:
  libzmq3
The following NEW packages will be installed:
  libzmq3 libzmq3-dev
0 upgraded, 2 newly installed, 0 to remove and 17 not upgraded.
Need to get 0 B/876 kB of archives.
After this operation, 1,914 kB of additional disk space will be used.
Do you want to continue [Y/n]? Y
(Reading database ... 184756 files and directories currently installed.)
Unpacking libzmq3:amd64 (from .../libzmq3_3.2.3+dfsg-2~bpo70+1_amd64.deb) ...
dpkg: error processing /var/cache/apt/archives/libzmq3_3.2.3+dfsg-2~bpo70+1_amd64.deb (--unpack):
 trying to overwrite '/usr/lib/x86_64-linux-gnu/libzmq.so.3', which is also in package libzmq4:amd64 4.0.4-2~1da~wheezy1
Selecting previously unselected package libzmq3-dev:amd64.
Unpacking libzmq3-dev:amd64 (from .../libzmq3-dev_3.2.3+dfsg-2~bpo70+1_amd64.deb) ...
dpkg: error processing /var/cache/apt/archives/libzmq3-dev_3.2.3+dfsg-2~bpo70+1_amd64.deb (--unpack):
 trying to overwrite '/usr/lib/x86_64-linux-gnu/libzmq.a', which is also in package libzmq4-dev:amd64 4.0.4-2~1da~wheezy1
dpkg-deb: error: subprocess paste was killed by signal (Broken pipe)
Errors were encountered while processing:
 /var/cache/apt/archives/libzmq3_3.2.3+dfsg-2~bpo70+1_amd64.deb
 /var/cache/apt/archives/libzmq3-dev_3.2.3+dfsg-2~bpo70+1_amd64.deb
E: Sub-process /usr/bin/dpkg returned an error code (1)

but:

$ sudo apt-get install libzmq4-dev
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages were automatically installed and are no longer required:
  libpgm-5.1-0 libzmq1
Use 'apt-get autoremove' to remove them.
The following NEW packages will be installed:
  libzmq4-dev
0 upgraded, 1 newly installed, 0 to remove and 17 not upgraded.
Need to get 878 kB of archives.
After this operation, 2,164 kB of additional disk space will be used.
Get:1 http://deb.dovetail-automata.com/ wheezy/main libzmq4-dev amd64 4.0.4-2~1da~wheezy1 [878 kB]
Fetched 878 kB in 0s (1,299 kB/s)
Selecting previously unselected package libzmq4-dev:amd64.
(Reading database ... 184695 files and directories currently installed.)
Unpacking libzmq4-dev:amd64 (from .../libzmq4-dev_4.0.4-2~1da~wheezy1_amd64.deb) ...
Processing triggers for man-db ...
Setting up libzmq4-dev:amd64 (4.0.4-2~1da~wheezy1) ...

works.

https://github.com/machinekit/machinekit-docs/blob/master/src/remap/structure.asciidoc
Possible remaps list is wrong. Should include M100-M999 instead of M199-M999.

There should be a section about how to use Machinekit for 3D printing. The FDM standard should also move into the docs: https://github.com/strahlex/Machinekit-FDM-Standard

I'll sign up for a piece on how to submit new issues by making use of the "edit this page" button. Including screen shots

People think that machinekit is a beaglebone or a 3D printer project.
The landing page therefore is not clear enough.

http://blog.machinekit.io/2015/11/summary-of-open-discussion-at-nov-2015.html?m=1

Gives a good summary.
The landing page should better explain the project

• reusable stack to build applications on top
• multi platform
• HAL
• realtime
• remote UI

The builds of the website have not worked since February 9th 2017.

The first problem, is the changes to machinekit-protobuf since this commit
machinekit/machinetalk-protobuf@e84a6e5

cp "python/setup.py" "build/python/setup.py"
make[1]: *** No rule to make target 'build/python/machinetalk/__init__.py', needed by 'Makefile'.  Stop.

This did not arise immediately, because only when a complete rebuild is triggered will the protobuf docs be rebuilt from scratch.

@machinekoder can you see if you can get this working again.
As soon as the repo will build in isolation, the docs will get past that point

Further back in time there was another error, which appeared to be from a corrupt git SHA

+ cd /var/lib/jenkins/workspace/website-production/output
+ git config user.email [email protected]
+ [ -d .git ]
+ git add .
+ git commit --amend -m Force updated by Jenkins build 1469
error: object file .git/objects/ee/30f70e7ace4c41a3d901a014acfe09d80ba58c is empty
error: object file .git/objects/ee/30f70e7ace4c41a3d901a014acfe09d80ba58c is empty
fatal: loose object ee30f70e7ace4c41a3d901a014acfe09d80ba58c (stored in .git/objects/ee/30f70e7ace4c41a3d901a014acfe09d80ba58c) is corrupt
Build step 'Conditional step (single)' marked build as failure
Stopping Docker container after build completion

but until the first error is fixed, cannot get far enough into the build to diagnose that one.

Also despite all the changes to instcomps since Jan 17th, a new build of machinekit-manual-pages package has not been triggered since 21st Dec 2016
http://deb.machinekit.io/debian/pool/main/m/machinekit-manual-pages/machinekit-manual-pages_1.10292_all.deb

I will look at that, as I set the build up (if I can remember how 😄)

takeover of https://github.com/machinekit/machinekit.github.io/issues/32

@Strahlex wrote:
It would be possible to provide a nicer integration of Charles blog into the Machinekit website by migrating it to Jekyll. Jekyll seems to provide some tools for that http://jekyllrb.com/docs/migrations/

In this thread are some considerations on what we need to figure out what to do with the documentation. This issue (and this comment) gathers info on that and provides a more focused discussion.
This issue supersedes issue machinekit/machinekit#844 because this is a better place.

Goal of this thread:

• decision on which actions to take
• clear specs on how to actually get there
• an educated guess on the tasks and effort
• decide on how to go forward with API documentation

issues that relate to this:

• #7
• machinekit/machinekit#840

Experiments:

• what do we need for easy navigation of the documentation. Result: having readthedocs build the documentation from the github repo as per this comment has yielded a marvelous result. Next to that one can always get the same result by using mkdocs.org from the local clone.
• investigate on the effort that goes with possible converting the documentation. Result: Bob has shown that this is just 1 line of code for a conversion to .md
• test out the above by writing down the recent build and CI changes. as per issue machinekit/machinekit#840.
• integration of manually and generated comp manpages into the machinekit-docs. the machinekit-man concept is not working
• find out which documentation needs to be reworked like in this issue #33
• find out how we MAKE and GET get API documentation into machinekit-docs (similar to 3). With that I mean that we must find a way to get for example in-code generated comments into the documentation. Like Doxygen or a similar solution ???.
• Since mkdocs.org generates static pages, we can investigate what it takes to build the docs for github pages, travis-CI pushing to machinekit-docs.github.io ?
• experiment on getting docs in PDF/Epub format

With the points above we could work towards steps to these specs (pending discussion):

• a solution MUST NOT be dependant on 1 cloud/build service
• ANY cloud/build solution MUST have Github integration
• ALL documentation (docs, Machinekit API and Components manpages) must be visible from ONE location. This means NO fragmentation of information.
• a tutorial on contributing MUST be made
• we MUST know how current links break during conversion, and how to correct this
• ...

so, leave you remarks below and discuss so we can update the above!

This is an anchor issue for information which should not have to be explained by the Machinekit project, but is meaningful to know about.

Following the discussion in this PR #216 as well as the points #117 and #103 I think we should define what we expect people to know when they start with Machinekit.

If we only say "this is not a linux course" then we'll never get traction in for example a more industrialised/manufacturing setting, where practically everything that engineers/service people do runs on Windows. And it is this environment which is so suited for Machinekit.

I think we should point to sources that are suited to read up to first, before getting into the cold and murky water (from a non-linux perspective).

After all, if we want to have a re-usable realtime motion system, there need to be users, and hopefully this project continues to grow.

[1]
We have the "user" who just wants to set up a machine. This can be a standard machine, like mill-xyz or 3D-printer-type-a. These users have certain hardware and a certain machine, so they will typically need to choose and start with a config, and change things like homing parameters, speeds etc. But also there needs to be able to use haltalk, when a remote GUI is needed.

[2]
There's a "user" who will want to make a custom hal configuration because of a custom (mechanical/electronical) hardware design. Meaning understanding of HAL components, netting etc. is needed. Building a HAL configuration from scratch. Do we think these people will want to use the python bindings to do so? These people will probably want to make custom UI's.

[3]
When [1] and [2] are not enough, and one of these users needs things that are available, this means programming. Writing components, etc

[4]
Programmers

What should be the prerequisits/tips so that we can point to and don't have to explain "scp" or "git" or "dmesg" but instead can point to other sources that will explain what's going on when that command is invoked.
Please add to this thread.

This is just an aide-memoir should the same problem occur again

See machinekit/machinetalk-protobuf#80

I am having problems reading the default textboxes rendered on the website. The black on dark-gray and turquoise on dark gray have very little contrast. Is this what it looks like for everyone else?

For Travis-ci, the jenkins build, building packages, building website etc we should have diagrams which depict the flow so mere mortals can understand.

please add points and references:

• machinekit CI documentation see: machinekit/machinekit#840
• ...

The Gtkmm website has a page called commercial support where people can list themselves if they are interested in providing commercial services evolving around the project.

Since people are already using Machinekit in commercial products, I suggest adding a similar page to the Machinekit website.

There are a diverse slides and YouTube videos on various topics, but they have no real place on the site.
We should find them a place and link to these for reference in different topics.

note to self to properly document this thread
https://groups.google.com/forum/?nomobile=true#!topic/machinekit/x4eID_2IqPA

the use and setup of QtQuickVCP is not mentioned in the docs. Cetus and Machineface for example could be added to (future separate) section of GUI's. But general instructions on making a custom UI, setting up the Machinekit SDK or vagrant would lower barrier of use

If the top-level README were interpreted by GitHub as asciidoc, or else renamed to README.md and converted to markdown, then a link to the main index could be visible directly from https://github.com/machinekit/machinekit-docs (right now, I have to remember to look in the machinekit-documentation folder and then take a stab at which file is the best index).

Takeover of this issue https://github.com/machinekit/machinekit.github.io/issues/61

@Strahlex wrote
In my opinion the Machinekit website has to many sub-pages (e.g. http://www.machinekit.io/community/home/) I need to click 2 times to get the relevant information -> the link to the Google Groups page. Most websites these days have a flat structure without many sub-pages. Just to reference a few:
https://developers.google.com/protocol-buffers/docs/faq
http://docs.getchip.com/chip.html#installing-c-h-i-p-sdk
https://facebook.github.io/react/support.html

This design makes it possible to use the browser search to find the information + works a lot better on phones and tablets.

@Strahlex is this still a relevant issue? If not, would you then close this?

anchor issue for all documentation content needing overhaul.

Report documentation bugs here!

this is an anchor issue about the overall website structure - what I am thinking about is:

• how do we best encourage users to contribute?
• which types of contents would we like to add - and make easy to add while at it?
• examples: application reports, reference material, a bibliography, videos ("CNC p0rn") a 'news column', status updates, a tag cloud?
• should we integrate the blog into the website? (I think yes, and it should become open for all users to blog there; I also think it should generalize focus from BB issues)
• toplevel categories: do they make sense?
• does the navigation means make sense? how do we improve it (eg deeper structured topic bars on the right hand side)

This issue is more general in scope than #103 - which focuses on the documentation proper (manuals, man pages) - therefore documentation-specific themes should go to #103

In the developer documentation, could you add a brief overview of the folders in the machinekit source? For example, I was looking at the source to find the code for the GCode interpreter as shown in the architecture overview diagram, but I'm not sure where to start. Or what is the purpose of the nc_files folder?

Diagrams that work should have an example page describing the syntax needed, with a link to further explanation to that package (like to http://blockdiag.com/en/ ) we've already got one but it needs a bit of revamp. I'll sign up for this one

For beginners to try out Machinekit without risking anything. Would be useful for tutorials and workshops
See https://github.com/strahlex/machinekit-vagrant

I would like to point out one possible omission in the instructions to setup rt-preempt linux image on RPi2/RPi3 (http://www.machinekit.io/docs/getting-started/install-rt-kernel-RPi2/).

By default Raspbian (at least current jessie) disables cpuset cgroup subsystem and therefore you will not be able to mount cpuset filesystem. I would suggest adding cgroup_enable=cpuset to /boot/cmdline.txt

Regards,
F. Moya

We need instructions and examples on how to use the Cython bindings.

When all is mature enough for Machinekit to be supported on Debian Jessie, the installation instructions should be updated.

reference machinekit issue : machinekit/machinekit#598

Including mkwrapper-sim and anddemo.

https://github.com/strahlex/mkwrapper-sim
https://github.com/strahlex/anddemo

Needs also documentation of client-side bindings.

Why do we need this libczmq package on Jessie? https://github.com/machinekit/machinekit-docs/blob/master/machinekit-documentation/getting-started/APT-packages-jessie.asciidoc#add-the-sid-repository-to-you-debian-sources-list-and-update

Please see https://evil32.com/ (note: site will not damage your computer :-P) for why it is important to begin using key IDs bigger than 32 bits.

I notice that in documentation such as docs/getting-started/APT-packages-raspbian.asciidoc 32-bit key IDs are being used.

As far as I understand it, gpg and apt-key adv will both know how to use 64-bit key IDs, but I haven't verified this.

While I'm asking, is this the proper key?

pub   2048R/31B5958F43DDF224 2016-02-28
uid                          Machinekit Signer <[email protected]>
sub   2048R/9AF25B185CFD4136 2016-02-28
sub   2048D/F81BD2B7499BE968 2016-02-29

instead of an obscure question from a user developers frequently need more info, like a pastebin of linuxcnc.log, info about the system, platform etcetera.

We need to document this and point to this when the info provided is inadequate. So then without that info the user has to follow a quick tut of list on what to provide in what form before we can continue.

GUI's are now collected in "Getting Started" and should be split off into a separate section.

Since all documentation, including the source for the site now reside in machinekit-docs, and machinekit.github.io is only used for displaying the site, should we move/close issues on machinekit.github.io to machinekit-docs, and disable the possibility of making issues on machinekit.github.io repo?

https://github.com/machinekit/machinekit.github.io/issues/60
https://github.com/machinekit/machinekit.github.io/issues/61

When you add info about source code highlighting in .asciidoc files like example below it will highlight the code on the github page. From reading point of view I would love to be able to view .hal files in the same way as we can view .ini files

[source,ini]
----
[PRUCONF]
DRIVER=hal_pru_generic
CONFIG=pru=1 num_stepgens=4 num_pwmgens=3
PRUBIN=xenomai/pru_generic.bin
----

in (this issue example) markdown it would be done in this way:

```ini

which gives:

[PRUCONF]
DRIVER=hal_pru_generic
CONFIG=pru=1 num_stepgens=4 num_pwmgens=3
PRUBIN=xenomai/pru_generic.bin