Maslow Home Maslow Community Garden

The Firmware Realm : From GCode to PID or the (left,right,z) and (x,y,z) alternate worlds


Keeping the pace about this overview of the MaslowCNC firmware, let’s look at the main building blocks of the firmware.

Going through the Forum discussions about improving the Maslow cutting accuracy, move speed, and “burning the shield” :astonished:, you might have been mesmerized by some techy language like “Inverse or Forward Kinematics, PID control, PWM and H-Bridge”… to name a few.

All this actually relates to some core components of Arduino work steps involved in moving motors. And moving motors is the MaslowCNC robotic dance making the router bit follow your GCode routing paths to make real your next amazing thing :-).

So this post is about the robotic dance steps of the firmware.
Rock n Roll, Reggae or Cha cha cha :dancer::man_dancing:?
You tell me…

Here is the diagram we’ll follow. Starting at blue 0, ending at blue 12. You might want to open it in a separate window to follow more easily.


Step 0:

At power up, the Arduino looks at the motor encoders counts memorized in the eeprom then starts cumulating any change afterward. The next question is Where on the workspace is the sled and where above is the bit tip?

While the Z axis move is just a matter of scaling the encoder count, finding the sled position is more challenging.

  • Left and right motors move chains, and the Z axis. So this is the left chain, right chain, and Z screw rotation (l, r, z) position. Not the (x,y,z) position.
  • To find out the (x,y,z) when having in hand the (l, r, z) is actually a trial and error guess work. It is called the Forward kinematics (another topic)

Once the (x,y,z) is found, the arduino will mainly work the other way around: calculating then setting chain lengths to meet the (x, y, z) coordinates commanded by GCode commands. And that is called Reverse Kinematics. So let’s go to…

Step 1.

Ground Control sends various control codes to the arduino, and the arduino feeds back status information to Ground Control. Let’s consider the case where a G1 command is received. So Let’s go to…

Step 2

The firmware decodes the G1 command and remembers the previous ones because GCode may just point out changes from step to step. So the GCode command is sorted out, and eventually a X position, a Y position, a Z position and a speed (which in this case is called a (F)eed rate because G1 is about moving the router bit through the material). With these (X, Y, Z, F) details in hand , let’s go to …

Step 3

To execute a G1 command, there are two possible meanings to the X, Y and Z values. The first is the exact bit position “B” on and into the workspace. This is abolute position mode. The other interpretation is to use the X, Y, Z to change the last position “A” on and into the workspace by adding to “A” the X, Y, Z values. The later is the relative position mode.

For a G1 move, going from point A to point B is always done in straight line, where X, Y and Z will change gradually together to make it happen. Some numbers are then calculated because a steady paced action is about to start into…


Step 4

Now is the time to hash the action is a series of time slices called the “TIME LOOP INTERVAL”. The arduino will then change the x, y, z sled and router bit position in a series of small intermediate steps. Each step to be executed into exactly one “TIME LOOP INTERVAL” period.

Now remember that motors don’t do (x, y, z.) moves in the MaslowCNC: They do (l, r, z). That is why we need…

Step 5

So at every “TIME LOOP INTERVAL” period, the (x,y,z) target slice is converted into an (l, r, z) target slice with a little computation involving all the delicate physical details of the chain lenght calculations. And this is nicely called Reverse Kinematics

Into the arduino, the computations are split in two blocks:

  • block one is the one we have described up to now in the “TIME LOOP INTERVAL”. It finds the target (l, r, z) slice then waits to be asked for the next slice.
  • block two works much faster to control the motor dynamics, and that brings us to …

Step 6

The current motor shaft rotation angle relates to an ideal chain length, and that is compared to the Forward Kinematics (l, r, z) position to be met.

That is compared a thousand times per second.

The observed difference is called the “error”. Now the next step is going to deal with the “error”.

Step 7

The error is a very interesting beast: It may be changing slowly, or fast, may be small or large, may be stalled and require some kicking to go away. And that depends partly on the motor physics, and partly on where the sled is on the workspace, how much force it has to pull to get the routing bit pass through the wood. Motors might have it easy when giving chain to let the sled go down, or tough when pulling up center that brick loaded sled.

So here a PID rule is applied to decide how to kick the motor. It is actually a position and speed combined PID rule. To keep things simple, let’s point out what PID means.
+P says “scale the error value” that much and send for this amount of error as much power to the motor.
+I says “the error is stalled since a while.” Scale this “amount of time” and send that much power to the motor.
+D says “the error is changing that fast”. Scale this rate of change and pull back that much on the power demand to prevent motor position overshoot.

And now let’s code this “amount of power” in …


Step 8

There is a maximum amount of power that the arduino shield can feed to the each motor. That is “100%” value. The shield can feed motors a whole range of power steps from full forward (100%) or full backward (-100%) power. And this includes zero power (0%).

The direction and power ratio are communicated to a power amplifier in the form of a “pulse width modulated” on/off signal. Really just that: full on or full off. But time matters.

  • The turn on step is steadily hapening at a steady frequency. On the stock Maslow Firmware that is 490 Hz, which is a pretty obvious buzzer sound familiar to Maslownians.
  • The off step is the interesting part: the amount on time before it occurs can range from one turn on step to the next turn on step. And that is a code expressing 0 to 100% duty cycle.

The duty cycle controls…

Step 9

The H bridge power amplifier. This is the arduino shield power circuit. It is a fast power switch modulated by the Duty Cycle signal. And because the H-Bridge electric power changes much faster than the motor moves, this reduces H-Bridge heating because the Bridge is either OFF where no electric current flows (no power) or ON where almost all power goes to the motor (few power loss in H-BRIDGE). This is all due to the wise use of on/off PWM. So that power goes to…

Step 10

The motors…
Motors produce machanical torque in response to the average power (ON/OFF ratio) they get. When the shaft turns, a special circuit detects the rotation angle position and direction: the encoder. (see step 12). Simultaneously the mechanical shaft moves some mechanics in …


Step 11

As you can see on the Maslow gear boxes, motor shaft rotation is reduced and a sprocket move chains, and or a screw move the Router along depth (Z). This movement is somewhat blind though: If anything unusual happens to the sled or router, the firmware can’t detect it. So you must be careful to monitor the mechanical behavior of the sled and router to take action and prevent problems. For xample, clearing obstacles around the sled, making sure the Z axis does not bump on maximum screw moves, and ensuring the workspace angle is correct, etc. Because the only thing the Arduino sees is…

Step 12

The encoder counts. These are cumulated, recorded in the EEPROM to keep track of chains positions between power off states. And are the basic Maslow CNC position expressed in the (l, r, z) dimensions. Ready to be compared 1000 times a second to the position slice target (Step 6), or eventually transformed into (x, y, z) with the very clever Formward Kinematics (Step 0).

So be carefull, because altough the MaslowCNC moves slowly, It really dances solo: It won’t listen much to the world around it. So it is a safety practice to keep at hand a power off button to idle the motors.

This concludes the 12 steps robotic dance of the MaslowCNC firmware. Of course, there is more than what meets the eye. So you are welcome to dive into the code :slight_smile:

Accurate MaslowCNC manual calibration, how to

I have been curious about how this works. Based on this comment, each incremental change in the motor position is detected by a pulse coming from the encoder. A missed pulse results in an inaccuracy that carries forever forward, until the machine is re-calibrated.
I had assumed the encoders were absolute, such that the location was read based on more than pulses, such that this accumulation of error wouldn’t happen. Could someone clarify?

I was able to find the answer to my question here (How does the Motor's encoder work?)
The answer is the sled position is determined by counting pulses. If one pulse is missed, the sled position is off from that point forward.

I actually think this bit me a while back. I could hear the motor hesitating, periodically. After a while, it started failing the “Sled not keeping up” check. After that, I wiggled the wire connection, and I had no problem after that. Of course, this was happening during the calibration process, so I don’t understand its long-term impact.


Maybe we could brainstorm on some encoder troubleshooting features to embed in the firmware… to check for electrical integrity,

Here is the thinking:

Encoders are located at the back end of motors, just besides the motor’s elctrical connector.
Encoder pulse counting is on the Arduino shield.

Once electrical connections are in good shape, and as long as

  • :point_right:motor power wires / router power wires are not inducing electrical noise across the encoder signals,
  • the firmware is the only one to operate motors.

then encoders counts should be good.

Also chain lengths will match encoders counts as long as chains move without slip over sprockets teeth.


Thanks for the response.

I found the place where the encoder pulses are managed, here (

There is a map which describes pin-state changes to position changes on lines 159 through 183. I found it concerning that there are 4 states which respond to both pins changing at the same time. During these events, the firmware assumes a direction that is fixed for each transition. This is not a very good assumption, because a simultaneous change in both pins can happen in either direction. A better assumption is that the motor direction is the same as the previous iteration’s direction.

This could be a source for a diagnostics feature. The firmware could increment a counter every time two pins change state simultaneously. If this happens X number of times, that implies Y uncertainty in chain length. Once this goes above a certain number, say 1 mm, you need to reset the chain lengths.


the encoders are made in such a way that no matter what direction they are moving, only one signal changes at a time. At any position, which one changes next indicates not just that motion happened, but which direction it happened in.

If you sit right on the edge of a pulse, you can get the signal bouncing, and the step count will end up going back and forth.



I would like to rephrase that.

the encoders are made in such a way that no matter what direction they are moving, if everything is working correctly, only one signal changes at a time