DEV Community: Orion Jiang

Build a Linear Actuator Cycle-Time Calculator in Python

Orion Jiang — Mon, 10 Aug 2026 10:19:11 +0000

When estimating the output of an automated machine, actuator speed alone does not tell the whole story.

A reciprocating axis normally needs to:

Move from home to the working position
Wait while an operation is performed
Return to home
Wait for the next cycle

These small delays can have a surprisingly large effect on hourly throughput.

Let’s build a simple Python calculator for estimating cycle time, motion duty cycle, and theoretical cycles per hour.

The Calculation

For a basic reciprocating axis:

outbound time = stroke / outbound speed
return time = stroke / return speed

motion time = outbound time + return time
cycle time = motion time + dwell times

The following script turns those calculations into a reusable class.

from dataclasses import dataclass

@dataclass(frozen=True)
class LinearAxisCycle:
stroke_mm: float
outbound_speed_mm_s: float
return_speed_mm_s: float
dwell_at_end_s: float = 0.0
dwell_at_home_s: float = 0.0

def calculate(self) -> dict[str, float]:
    if self.stroke_mm <= 0:
        raise ValueError("Stroke must be greater than zero.")

    if self.outbound_speed_mm_s <= 0:
        raise ValueError("Outbound speed must be greater than zero.")

    if self.return_speed_mm_s <= 0:
        raise ValueError("Return speed must be greater than zero.")

    if self.dwell_at_end_s < 0 or self.dwell_at_home_s < 0:
        raise ValueError("Dwell times cannot be negative.")

    outbound_time_s = (
        self.stroke_mm / self.outbound_speed_mm_s
    )

    return_time_s = (
        self.stroke_mm / self.return_speed_mm_s
    )

    motion_time_s = outbound_time_s + return_time_s

    cycle_time_s = (
        motion_time_s
        + self.dwell_at_end_s
        + self.dwell_at_home_s
    )

    motion_duty_cycle_pct = (
        motion_time_s / cycle_time_s
    ) * 100

    cycles_per_hour = 3600 / cycle_time_s

    return {
        "outbound_time_s": outbound_time_s,
        "return_time_s": return_time_s,
        "motion_time_s": motion_time_s,
        "cycle_time_s": cycle_time_s,
        "motion_duty_cycle_pct": motion_duty_cycle_pct,
        "cycles_per_hour": cycles_per_hour,
    }

cycle = LinearAxisCycle(
stroke_mm=300,
outbound_speed_mm_s=250,
return_speed_mm_s=400,
dwell_at_end_s=0.4,
dwell_at_home_s=0.2,
)

results = cycle.calculate()

for name, value in results.items():
print(f"{name}: {value:.2f}")

The output is:

outbound_time_s: 1.20
return_time_s: 0.75
motion_time_s: 1.95
cycle_time_s: 2.55
motion_duty_cycle_pct: 76.47
cycles_per_hour: 1411.76
What This Number Does Not Include

This is an ideal constant-speed estimate. A real axis also requires time for acceleration, deceleration, controller communication, sensor confirmation, mechanical settling, and safety interlocks.

The result should therefore be treated as an early engineering estimate—not a guaranteed production rate.

The calculated motion duty cycle is also different from the manufacturer’s thermal duty-cycle rating. Powered holding, motor current, load, orientation, acceleration, and ambient temperature can all affect thermal performance.

From Timing to Hardware Selection

Once the required cycle time is understood, the next step is selecting suitable hardware.

Stroke length and nominal speed are only the beginning. Load, screw lead, repeatability, mounting orientation, motor interface, environmental protection, and allowable moments also matter.

These single-axis linear actuator configurations show examples of different module sizes and motor-mounting arrangements that can be compared during early design work.

A ten-line calculation will not select the entire motion system, but it can quickly expose unrealistic throughput assumptions—before they become expensive hardware decisions.

Filter a Chattering Proximity Sensor in Python Without Blocking the Control Loop

Orion Jiang — Wed, 05 Aug 2026 10:25:22 +0000

A proximity sensor near its switching threshold may change state several times before settling.

The cause might be vibration, target movement, electrical interference or an incorrectly selected sensing distance. Software filtering cannot repair bad hardware, but it can prevent brief transitions from being treated as valid machine events.

Here is a non-blocking Python state filter that can run inside an existing control loop.

Why sleep() Is Usually the Wrong Filter

A simple approach might look like this:

if read_sensor():
time.sleep(0.05)

if read_sensor():
    handle_detection()

It works in a tiny demonstration, but it pauses the entire loop.

During that pause, the program may delay:

Other input checks
Communication updates
Motion commands
Alarm handling
User-interface refreshes
Data logging

A timestamp-based filter lets the rest of the program continue running.

A Non-Blocking State Filter
from dataclasses import dataclass
from typing import Optional

@dataclass
class StableDigitalInput:
on_delay_s: float = 0.03
off_delay_s: float = 0.03
state: bool = False
candidate: bool = False
candidate_since: Optional[float] = None

def update(
    self,
    raw_state: bool,
    now_s: float,
) -> bool:
    # The input returned to the accepted state.
    if raw_state == self.state:
        self.candidate = raw_state
        self.candidate_since = None
        return self.state

    # A new possible state has appeared.
    if raw_state != self.candidate:
        self.candidate = raw_state
        self.candidate_since = now_s
        return self.state

    delay_s = (
        self.on_delay_s
        if raw_state
        else self.off_delay_s
    )

    # Accept the state only after it remains stable.
    if (
        self.candidate_since is not None
        and now_s - self.candidate_since >= delay_s
    ):
        self.state = raw_state
        self.candidate_since = None

    return self.state

Using It in a Control Loop
import time

sensor_filter = StableDigitalInput(
on_delay_s=0.03,
off_delay_s=0.05,
)

previous_state = False

while True:
raw_state = read_sensor_input()

stable_state = sensor_filter.update(
    raw_state=raw_state,
    now_s=time.monotonic(),
)

if stable_state and not previous_state:
    print("Object detected")

if not stable_state and previous_state:
    print("Object cleared")

previous_state = stable_state

update_other_tasks()

read_sensor_input() and update_other_tasks() are placeholders. They can be replaced with GPIO, PLC, fieldbus or simulation functions appropriate for the system.

time.monotonic() is used because it only moves forward and is not affected by changes to the computer’s clock.

Separate ON and OFF Delays

The example uses different qualification times:

ON delay: 30 ms
OFF delay: 50 ms

Separate values can be useful when detecting an object should happen quickly but confirming that it has left requires slightly more stability.

The correct delays depend on the machine. A fast counting application may need much shorter values, while a slowly moving fixture can tolerate longer filtering.

Filtering should never be longer than the process can safely accept.

Hardware Selection Still Matters

Before adjusting software, verify:

Target material
Required sensing distance
Inductive or capacitive sensing method
NPN or PNP output
Normally open or normally closed operation
Supply voltage
Response frequency
Shielded or unshielded installation
Nearby metal and sensor spacing
Cable routing and electrical noise

This proximity sensor selection provides examples of inductive, capacitive, cylindrical, rectangular, NPN and PNP configurations.

Industrial sensors must also be connected through an interface compatible with their voltage and output type. A 24 V sensor output should not be connected directly to a low-voltage GPIO input unless an appropriate interface, level conversion or isolation circuit is provided.

Do Not Hide a Mechanical Problem

If the filter requires hundreds of milliseconds to produce a stable result, investigate the application.

Possible causes include:

Target positioned at the edge of the sensing range
Loose sensor bracket
Excessive machine vibration
Incorrect sensor technology
Electrical interference
Unstable target geometry
Metal buildup on the sensing face

Software filtering is useful for rejecting brief disturbances. It should not be used to make an unsuitable installation appear reliable.

A good control system filters noise—and keeps enough evidence to notice when the noise is trying to tell you something.

Build a Timing Belt Ratio and Linear Speed Calculator in Python

Orion Jiang — Thu, 30 Jul 2026 09:38:29 +0000

Timing belt calculations often begin with two questions:

How fast will the driven pulley rotate?
How fast is the belt moving?

Both can be estimated from four basic inputs: driver teeth, driven teeth, belt pitch and motor speed.

Let’s turn the calculation into a small Python utility.

The Basic Equations

The driven-pulley speed is:

Driven RPM =
Motor RPM × Driver Teeth ÷ Driven Teeth

The reduction ratio is:

Reduction Ratio =
Driven Teeth ÷ Driver Teeth

The approximate belt speed at the pitch line is:

Belt Speed =
Driver Teeth × Belt Pitch × Motor RPM

When pitch is entered in millimeters and speed is required in meters per second, the result is divided by 60,000.

Python Calculator

from dataclasses import dataclass

@dataclass(frozen=True)
class TimingBeltDrive:
driver_teeth: int
driven_teeth: int
pitch_mm: float
motor_rpm: float

def validate(self) -> None:
    values = {
        "driver_teeth": self.driver_teeth,
        "driven_teeth": self.driven_teeth,
        "pitch_mm": self.pitch_mm,
        "motor_rpm": self.motor_rpm,
    }

    for name, value in values.items():
        if value <= 0:
            raise ValueError(
                f"{name} must be greater than zero"
            )

def reduction_ratio(self) -> float:
    self.validate()
    return self.driven_teeth / self.driver_teeth

def output_rpm(self) -> float:
    self.validate()
    return (
        self.motor_rpm
        * self.driver_teeth
        / self.driven_teeth
    )

def belt_speed_m_s(self) -> float:
    self.validate()

    travel_per_driver_rev_mm = (
        self.driver_teeth * self.pitch_mm
    )

    return (
        travel_per_driver_rev_mm
        * self.motor_rpm
        / 60_000
    )

drive = TimingBeltDrive(
driver_teeth=20,
driven_teeth=60,
pitch_mm=5,
motor_rpm=1500,
)

print(
f"Reduction ratio: "
f"{drive.reduction_ratio():.2f}:1"
)

print(
f"Driven speed: "
f"{drive.output_rpm():.1f} RPM"
)

print(
f"Belt speed: "
f"{drive.belt_speed_m_s():.2f} m/s"
)

The result is:

Reduction ratio: 3.00:1
Driven speed: 500.0 RPM
Belt speed: 2.50 m/s

Why Tooth Count Controls the Ratio

A 20-tooth driver pulley moves 20 belt teeth during each revolution. A 60-tooth driven pulley needs three times that belt movement to complete one revolution.

The driven pulley therefore rotates once for every three motor revolutions:

60 ÷ 20 = 3:1 reduction

This reduces speed and increases the ideal torque available at the driven shaft. Actual output torque will be lower than the theoretical value because bearings, belt flex and other system losses reduce efficiency.

Why Belt Pitch Matters

A 5 mm pitch belt advances approximately 5 mm for each pulley tooth passing the pitch line.

For the 20-tooth driver:

20 × 5 mm = 100 mm per revolution

At 1,500 RPM:

100 × 1500 = 150,000 mm/min

That is:

2.5 m/s

The calculation uses the belt pitch line—not the pulley’s outside diameter.

Moving From Code to Hardware

The ratio alone is not enough to select a pulley. The belt and both pulleys must use a compatible tooth profile and pitch. Two products with the same nominal pitch are not automatically compatible if their tooth geometries belong to different standards or series.

When reviewing hardware, compare tooth profile, pitch, tooth count, belt width, bore, flange arrangement and shaft-mounting method. This timing belt pulley selection includes trapezoidal, curved-tooth, set-screw and keyless-bushing configurations.

What This Calculator Does Not Check

The script provides a useful first estimate, but it does not calculate:

Required belt length
Center distance
Belt tension
Tooth engagement
Allowable pulley speed
Acceleration loads
Shaft and bearing loads
Motor torque requirements
Belt service life

Those checks still require the selected belt and pulley manufacturer’s engineering data.

The code answers the first questions quickly. The mechanical design still gets the final vote.

Build a Stepper Motor Steps-per-Millimeter Calculator in JavaScript

Orion Jiang — Wed, 29 Jul 2026 09:09:23 +0000

When a stepper-driven axis moves 80 mm after being commanded to move 100 mm, the problem is often not mysterious. The controller may simply be using the wrong steps-per-millimeter value.

Instead of recalculating it manually every time, we can turn the formula into a small JavaScript utility.

The Basic Formula

For a lead-screw-driven axis:

Steps per mm =
(full steps per revolution × microsteps × gear ratio)
÷ travel per revolution

A 1.8-degree stepper motor has:

360 ÷ 1.8 = 200 full steps per revolution

With 16× microstepping and an 8 mm lead screw:

200 × 16 ÷ 8 = 400 steps per mm

JavaScript Calculator

function calculateStepsPerMm({
stepAngleDeg,
microsteps,
travelPerRevMm,
motorRevsPerOutputRev = 1,
}) {
const values = [
stepAngleDeg,
microsteps,
travelPerRevMm,
motorRevsPerOutputRev,
];

if (values.some(value => value <= 0)) {
throw new Error("All inputs must be greater than zero.");
}

const fullStepsPerRev = 360 / stepAngleDeg;

const stepsPerMm =
(
fullStepsPerRev *
microsteps *
motorRevsPerOutputRev
) / travelPerRevMm;

return {
fullStepsPerRev,
stepsPerMm,
theoreticalDistancePerStepMm: 1 / stepsPerMm,
};
}

const axis = calculateStepsPerMm({
stepAngleDeg: 1.8,
microsteps: 16,
travelPerRevMm: 8,
});

console.log(
Full steps/rev: ${axis.fullStepsPerRev}
);

console.log(
Steps/mm: ${axis.stepsPerMm.toFixed(2)}
);

console.log(
Theoretical distance/step: ${ axis.theoreticalDistancePerStepMm.toFixed(6) } mm
);

The result is:

Full steps/rev: 200
Steps/mm: 400.00
Theoretical distance/step: 0.002500 mm

Lead Screw and Belt Drive Inputs

For a lead screw, travelPerRevMm is the screw lead—not necessarily its thread pitch.

A multi-start lead screw can travel several millimeters during one revolution. Using pitch instead of lead is a common reason for incorrect axis movement.

For a timing-belt axis, calculate travel per revolution as:

Pulley teeth × belt pitch

For example, a 20-tooth pulley with a 2 mm pitch belt travels:

20 × 2 = 40 mm per revolution

Check the Required Step Frequency

Steps per millimeter also affect the pulse frequency required from the controller.

function calculateStepFrequency(
speedMmPerSecond,
stepsPerMm
) {
return speedMmPerSecond * stepsPerMm;
}

const frequency = calculateStepFrequency(
50,
axis.stepsPerMm
);

console.log(${frequency} steps per second);

At 50 mm/s and 400 steps/mm, the controller must generate:

20000 steps per second

This matters because very high microstepping or mechanical reduction can push the required pulse rate beyond the controller’s practical limit.

From Calculation to Motor Selection

Steps per millimeter determine the command scale, but they do not determine whether the motor has enough torque.

Motor selection must also consider load, acceleration, supply voltage, driver current, operating speed and mechanical efficiency. When comparing frame sizes and control options, this stepper motor selection provides examples of NEMA-format, open-loop, closed-loop and integrated configurations.

One Important Reality Check

The calculated distance per microstep is a theoretical command resolution. It is not automatically the same as mechanical accuracy.

Real positioning performance is affected by:

Lead-screw pitch error
Backlash
Belt stretch
Frame deflection
Motor torque
Microstep linearity
Load variation
Missed steps

The calculator establishes a correct starting value. Calibration with an actual distance measurement should still be the final step.

Estimate Pneumatic Cylinder Air Consumption With Python

Orion Jiang — Tue, 28 Jul 2026 09:03:42 +0000

Compressed-air consumption is useful when estimating compressor capacity, operating cost or whether an existing air supply can support another actuator.

Here is a small Python function for estimating the free-air consumption of a double-acting pneumatic cylinder.

from math import pi

def cylinder_air_consumption(
bore_mm,
rod_mm,
stroke_mm,
gauge_pressure_bar,
cycles_per_min,
dead_volume_factor=1.10,
atmospheric_bar=1.01325,
):
bore_area_mm2 = pi * bore_mm*2 / 4
rod_area_mm2 = pi * rod_mm*2 / 4

extension_volume_l = (
    bore_area_mm2 * stroke_mm / 1_000_000
)

retraction_volume_l = (
    (bore_area_mm2 - rod_area_mm2)
    * stroke_mm
    / 1_000_000
)

pressure_ratio = (
    gauge_pressure_bar + atmospheric_bar
) / atmospheric_bar

free_air_per_cycle_l = (
    extension_volume_l + retraction_volume_l
) * pressure_ratio * dead_volume_factor

free_air_per_minute_l = (
    free_air_per_cycle_l * cycles_per_min
)

return {
    "extension_chamber_l": extension_volume_l,
    "retraction_chamber_l": retraction_volume_l,
    "free_air_per_cycle_l": free_air_per_cycle_l,
    "estimated_free_air_l_min": free_air_per_minute_l,
}

result = cylinder_air_consumption(
bore_mm=32,
rod_mm=12,
stroke_mm=100,
gauge_pressure_bar=6,
cycles_per_min=20,
)

for key, value in result.items():
print(f"{key}: {value:.3f}")

For this example, the estimated consumption is approximately:

free_air_per_cycle_l: 1.139
estimated_free_air_l_min: 22.8
How the Calculation Works

A double-acting cylinder consumes air during both extension and retraction.

The extension chamber uses the full bore area:

A = π × D² / 4

The retraction chamber contains the piston rod, so its effective area is smaller:

A = π × (D² - d²) / 4

The code calculates both chamber volumes and converts the compressed volume to an approximate free-air volume using the absolute-pressure ratio.

The dead_volume_factor adds a simple 10% allowance for unmodeled space. It can be adjusted when better system data is available.

From Calculation to Component Selection

Bore diameter has a major effect on both output force and air consumption because piston area increases with the square of the diameter.

When comparing the calculated result with real hardware, it helps to review different pneumatic cylinder types and bore options, including standard, compact, guided and miniature configurations.

Important Limitations

This script is intended for preliminary estimation. A complete system calculation may also need to consider:

Valve and tube volume
Leakage
Cushioning chambers
Pressure losses
Temperature
Actual cycle timing
Simultaneous actuator operation
Compressor duty cycle

The result is expressed as approximate free-air liters per minute. It should not be labeled as normalized liters per minute unless a reference temperature and pressure have also been defined.

Still, this small calculation is useful for comparing cylinder sizes before moving to detailed pneumatic-system sizing.

Convert Linear Travel Into Motor RPM and Step Pulses With Python

Orion Jiang — Sat, 25 Jul 2026 08:35:46 +0000

When controlling a screw-driven linear axis, the motion command usually begins in millimeters, but the motor operates in revolutions and step pulses.

A small conversion function can help answer three useful questions:

How many motor revolutions are required?
What motor speed is needed?
How many step pulses should the controller generate?
The Basic Relationship

For a screw with a lead of 10 mm per revolution:

10 mm of travel = 1 screw revolution

A 120 mm move therefore requires 12 revolutions.

Motor speed depends on both the desired linear speed and the screw lead.

Python Function
def calculate_axis_motion(
distance_mm,
speed_mm_s,
screw_lead_mm_rev,
motor_steps_rev=200,
microsteps=16
):
revolutions = distance_mm / screw_lead_mm_rev

motor_rpm = (
    speed_mm_s * 60 / screw_lead_mm_rev
)

step_pulses = (
    revolutions
    * motor_steps_rev
    * microsteps
)

pulse_frequency_hz = (
    motor_rpm
    / 60
    * motor_steps_rev
    * microsteps
)

return {
    "revolutions": revolutions,
    "motor_rpm": motor_rpm,
    "step_pulses": step_pulses,
    "pulse_frequency_hz": pulse_frequency_hz
}

result = calculate_axis_motion(
distance_mm=120,
speed_mm_s=80,
screw_lead_mm_rev=10
)

for key, value in result.items():
print(f"{key}: {value:.2f}")

Expected output:

revolutions: 12.00
motor_rpm: 480.00
step_pulses: 38400.00
pulse_frequency_hz: 25600.00

If you are unfamiliar with the mechanical components behind this conversion, this ball screw actuator working guide explains how the motor, coupling, screw, ball nut, carriage, and support structure work together.

Important Limitations

This calculation assumes:

Direct motor-to-screw transmission
No gearbox or belt reduction
Constant screw lead
No lost motion
The selected microstepping setting remains fixed

It also does not confirm whether the motor can produce enough torque at the calculated RPM. Acceleration, load inertia, friction, screw efficiency, critical speed, and controller pulse limits must still be checked.

The calculation tells the controller how far and how fast to command the axis. It does not guarantee that the mechanics can follow.

Still, it is a useful first bridge between a CAD dimension and an actual motion-control command.

A Tiny OpenSCAD Test Coupon Can Save Your Heat-Set Inserts

Orion Jiang — Fri, 24 Jul 2026 10:10:52 +0000

This post was created with AI assistance. Please review the code and technical details before publication.

Heat-set inserts are an excellent way to add reusable metal threads to 3D-printed enclosures, sensor brackets, and robot parts.

The difficult part is often not the insert. It is the hole.

A hole that measures 4.2 mm in CAD may print smaller or less circular because of extrusion width, shrinkage, filament behavior, layer settings, and printer calibration. Using one “recommended” diameter for every printer can produce loose inserts, cracked bosses, or a brass insert that slowly leans sideways during installation.

Instead of testing the final enclosure, print a small calibration coupon first.

A Simple OpenSCAD Coupon

The following model creates four holes with slightly different diameters:

hole_diameters = [4.0, 4.1, 4.2, 4.3];
spacing = 12;
coupon_height = 6;

difference() {
cube([
len(hole_diameters) * spacing,
12,
coupon_height
]);

for (i = [0 : len(hole_diameters) - 1]) {
    translate([
        i * spacing + 6,
        6,
        -1
    ])
    cylinder(
        h = coupon_height + 2,
        d = hole_diameters[i],
        $fn = 48
    );
}

}

Change the diameter values to match the insert you are testing.

Print It Under Real Conditions

The coupon should use the same:

Filament
Layer height
Wall count
Print orientation
Nozzle
Temperature settings

After printing, install one insert in each hole and compare:

How much pressure is required?
Does the plastic flow around the knurl?
Does the insert remain straight?
Does the boss crack or bulge?
Does the insert rotate when the screw is tightened?

The best hole is not necessarily the tightest one. Excessive interference can damage the surrounding plastic, while insufficient interference may allow the insert to rotate or pull out.

Hole diameter is only one part of the design. Boss diameter, wall thickness, installation depth, plastic type, load direction, and print orientation also affect the final joint. This design guide for threaded inserts in plastic provides a broader checklist for evaluating those variables.

A ten-minute calibration print is much cheaper than discovering the wrong hole size after a six-hour enclosure print.

Small coupon, fewer surprises.

Three Mechanical Checks Before Blaming Your PID Loop

Orion Jiang — Thu, 23 Jul 2026 10:22:32 +0000

When a linear axis vibrates, overshoots, or produces inconsistent positioning, the controller is usually the first suspect.

Sometimes the PID values are wrong. Sometimes the mechanism is simply asking the controller to perform magic.

Before spending another hour tuning gains, I like to check three mechanical conditions.

Check for binding

Move the axis slowly through its complete stroke and record:

timestamp
command_position
actual_position
motor_current
travel_direction

A current spike that repeatedly appears at the same position may indicate misalignment, rail binding, contamination, or an uneven mounting surface.

If the spike only appears in one travel direction, friction or preload deserves attention before the control loop does.

Check the sensor mount

A sensor can be accurate while its bracket is not.

With the axis stationary, monitor the feedback signal and lightly disturb the cable or surrounding structure. If the reading changes, check:

Bracket stiffness
Fastener tightness
Cable strain
Sensor-to-target distance
Nearby vibration sources

Filtering unstable feedback may hide the symptom, but it does not make the measurement more trustworthy.

Check the coupling and drive alignment

Misalignment between a motor, coupling, and lead screw can create periodic load changes. At low speed, watch for motor-current peaks that repeat once per revolution.

That pattern is usually more informative than random vibration. It points toward eccentricity, angular misalignment, a bent shaft, or poor support alignment.

A useful debugging order

When an axis behaves badly, try this sequence:

Mechanical freedom
→ Sensor stability
→ Drive alignment
→ Electrical noise
→ Control tuning

PID tuning works best when the mechanism is predictable. Otherwise, the controller is only being tuned around a moving target.

What mechanical problem has wasted the most control-tuning time in one of your projects?