OpenScan3 Firmware: Smooth Moves

This is the a blog post in a series on the OpenScan3 firmware. Read the previous post here. Comments, questions, or suggestions are always very welcome and a great help for future work on the firmware!

tl;dr: OpenScan3’s motor controller uses a simple motion model (max speed + acceleration) instead of “delay tuning”. The result is smoother motion, more predictable behavior, and easier configuration across devices.

The first part of the post is about the rationale of the new motor contoller. If you just want to know how to tune the settings, skip right ahead to the practical guide.

Why we entirely replaced the old motor control logic

OpenScan2 motion tuning mostly boiled down to step delays and a few ramp parameters. It worked, but it was hard to reason about:

• settings didn’t map cleanly to real-world motion,
• tuning wasn’t very transferable between devices,
• small changes could have big (and sometimes surprising) effects.

If you’re coming from OpenScan2, you might be looking for the old “delay” values. In OpenScan3, you typically don’t need them anymore: max_speed and acceleration give you a much more direct handle on how the device will move.

With OpenScan3 we rebuilt the motor controller around a simple motion model: accelerate → cruise → decelerate.

Instead of tuning a timer, you tune motion.

The mental model

OpenScan3 uses a simple motion profile that should feel familiar from school physics: uniform acceleration for start/stop, and (optionally) constant velocity in between.

If we plot velocity over time, the shape is almost always one of these:

• Trapezoid: accelerate → cruise at max_speed → decelerate
• Triangle: accelerate → immediately decelerate (short move, never reaches max_speed)

Figure 1: Velocity over time (schematic)

If we plot spatial position against time, the smoothness of the motion is obvious:

Figure 2: Position over time (schematic)The “felt” result: a smooth start/stop becomes a gentle S-curve rather than abrupt changes.

Still not convinced? See here:

The two settings that matter

There are many configuration fields in OpenScan3, but for motion quality there are basically two responsible:

1. max_speed

The maximum speed the motor is allowed to reach, measured in steps per second. Higher max_speed can reduce scan time, but it can also increase noise and vibration and the risk of skipped steps especially on high loads.

2. acceleration

How quickly the motor ramps up (and ramps down) its speed, measured in steps per second².

Acceleration is what makes motion feel “snappy” vs “smooth”:

• too high → jerky, harsh sound, higher chance of skipped steps
• lower → softer starts/stops, more forgiving

Tuning guide

If motion feels too aggressive / jerky:

• reduce acceleration

If everything feels smooth but too slow overall:

• increase max_speed

If you hear rattling / the motor stalls / steps are skipped:

• reduce max_speed
• and/or reduce acceleration
• also check mechanical friction

A good workflow is:

1. Start with conservative max_speed
2. Increase acceleration until it starts feeling harsh
3. Back off a bit
4. Increase max_speed until you hit the next limiting factor (noise, vibration, skipping), then back off