Update Jan 11th: Open Source and How to Contribute

HI Everyone,

This week we’re going to be talking about open source, why it matters to you, how it’s already making your machine better, and how you can contribute. (I know this week's update is a little wordy, but bear with us we'll be back with a project based update next week)

I am sure you have heard by now that Maslow is an “open source” project, but what does that mean for you? As an open source project, Maslow is fundamentally different from something you can buy at the store. Maslow is a project with the goal of making CNC accessible to more people, and the community is the most important part.

Maslow is built for and by the community. We saw in last week's update how community feedback shaped the design of the main controller board. The community said adding a 3rd axis and more auxiliary ports were important so we prioritized them and now they are part of the design. Having direct community feedback made the design better.

This week we are going to be talking about taking it a step further. Because Maslow is open source you can literally edit the PCB layouts, CAD models, and code yourself to make Maslow better if you are so inclined. This is important because at over 1,200 strong already our community has members with tremendous talents. By harnessing that talent we all get a better machine. The process is curated by the community of course to ensure that all the changes are really improvements.

We saw a great example of this process in action this week when community member Keith Selbo rewrote the mathematics which define the machine's motions to correct for the tilt of the sled. I had mentioned in a forum post that it was an important unfinished part of the software and Keith took it upon himself to solve what turns out to be quite a difficult mathematical problem in an elegant way.

The effect of of Keith's solution is that as the router sled tilts, the spindle remains perfectly positioned. As nearly as I can measure this means that a line cut from one side of the eight foot plywood to the other is perfectly straight.

You can see the new math in action in the video below.

I couldn't have solved the kinematics as elegantly as Keith did and I can't wait to see the other improvements everyone makes. If you've got an idea for how to improve something, next we're going to talk about how to add it to the design.

How to contribute:

You may have noticed that we keep all of our source files on a website called GitHub. GitHub is more than just a place to keep your files, it’s what’s called a “revision control system”. GitHub uses a revision control software called Git. Git not only keeps our files, it also keeps track of every version of each file and who has made each change to each file. Git was created by Linus Torvolds (the creator of Linux) as a way to help the thousands of people around the world who collaborate on Linux to work together. Git allows multiple to edit the same software at the same time without stepping on each others toes.

The easiest way to explain how this works is to walk through an example. To encourage you to try this at home, I’ve created a file in the firmware repository called “guestbook.txt”. The guest book is a place to sign your name, or leave a message which will stay with the project. When you contribute, it also drives up the number of contributors on our page which makes us look cooler to other open source projects, so give it a go!

Until very recently Git was a command line tool which meant there was no user interface, but we’re going to be using the more user friendly GitHub Desktop application.

First, you will need to make an account on GitHub if you don’t already have one. To create an account, navigate to https://github.com/ and pick a user name and password.

Next, choose the free option. The company GitHub supports open source projects by offering all of their services free to the open source community. How cool is that?

Now you can claim a copy of the source code to be your own. This process is called “forking” because the software branches out like the tines on a fork. Your fork of the software is your space to experiment with it, change things, and hopefully make them better. Because this is your copy, you are free to experiment with the software in any way you want.

To create your fork, navigate to https://github.com/MaslowCNC/Firmware and click the “Fork” button in the upper right hand corner.

And that’s all there is to it you now have your very own version of the firmware, but it doesn’t do you much good when it’s only online.

To download the files to your computer we’re going to use a program called GitHub Desktop which you can download for free from https://desktop.github.com/. The GitHub Desktop software allows you to work on files locally on your computer and then synchronize them with the GitHub website. Think of it like Dropbox, but with more control over when files are uploaded and downloaded.

Once you have installed the GitHub software click the “+” button in the upper left hand corner. Then click on “firmware”, then click on “Clone Firmware”. This will download a copy of the firmware to your computer to work on.

We’re going to edit the text file “guestbook.txt”, but the process will be the same for editing the Sketchup CAD files for the frame, the Eagle files for the PCBs or the text files for the software.

I use notepad++ as my text editor so I’m going to open the text file there and add my message.

As soon as that file is saved, the changes appear in the GitHub Desktop application. To upload those changes to the GitHub website make a note about what was changed in the lower left, click the “Commit” button in the lower left and then click “Sync” in the upper right.

This will upload your changes as a “commit”. Think of commits as save points. You can always go back to an earlier commit, so it’s helpful to commit often, but not so often that it is hard to tell your commits apart.

You repeat this process of editing files and committing changes for as long as you need to. When your changes are complete and you are ready to request that they be merged into the main version of the software click the “Pull Request” in the upper right hand corner and enter a description for the changes you have made.

The project will then receive a notification that a request has been made, and the changes can be merged in.

For a simple change like adding an entry into the guest book, this process is unnecessarily complicated, but when you have multiple people working on something as complex as a piece of software, revision control is crucial to that process going smoothly.

Git offers many many more features and benefits than we have room to cover here, but the best way to learn is by doing. As always, if you have any questions or we’ve missed anything, let us know in the forums.

Have a great week!

-Bar, Hannah, and Tom