Skip to main content
This guide helps you diagnose and fix the most common issues with your OSSM. Start by identifying your symptom, then follow the troubleshooting steps.

​
Clicking noise during homing

If your OSSM makes a loud clicking or ratcheting noise when it reaches each end of the rail during homing, the belt is likely not tensioned enough and is skipping.
1

Check belt movement manually

With the OSSM unplugged, manually move the rail back and forth along its full range. The belt should move smoothly without slipping or making noise.
2

Verify belt clamp and tensioner position

Check these components:
  • Front belt clamp bolt: Ensure it is adequately tightened so the belt is firmly secured
  • End tensioner piece: Verify it is pushed fully onto the rail
  • M5 tensioner screw: Confirm it has not been tightened all the way down (it needs room for adjustment)
3

Adjust the tensioner screw

Slowly turn the M5 tensioner screw clockwise until you feel a bit of resistance. Do not screw it in all the way—you’re adding tension incrementally.
4

Test with power

Plug your OSSM in and let it home. Listen for any clicking noise as it reaches each end of the rail.
5

Increase tension if needed

If you still hear clicking, power off and gently tighten the tensioner screw a bit more. Then power cycle and test again. Repeat until the clicking stops.
6

Verify under load

As a final check, set the rail in an upward position and apply some downward force with your hand. The belt should not skip. If it does, add more tension and power cycle to re-home.
Proper belt tension prevents skipping during direction changes at the stroke endpoints. The belt should be tight enough to transfer motor force without slipping, but not so tight that it strains the motor or bearings.

Belt Tension Guide

Complete belt tension adjustment, lubrication, and inspection guide.

​
Motor sounds louder or seems weaker than before

If your OSSM motor seems to be struggling, sounds louder than usual, or feels like it’s lost power compared to when you first set it up, the issue is typically belt tension, rail lubrication, or power supply.
The most common cause of a motor that sounds louder or seems to struggle is belt tension loosening over time. When the belt is too loose, the motor works harder to overcome slippage, which creates more noise and reduces effective power transfer.Signs of loose belt tension:
  • Motor sounds louder or more strained during operation
  • Reduced thrust force compared to initial setup
  • Clicking or ratcheting sounds at stroke endpoints
  • Belt visibly deflects more than 5mm when pressed
Solution: Follow the belt tension guide to verify and adjust your belt tension. Even small amounts of slack can significantly affect performance.
Over time, the linear rail’s factory lubrication can dry out or collect debris, increasing friction. This makes the motor work harder and can produce louder operation.Signs of rail lubrication issues:
  • Scratchy or grinding sensation when moving the carriage by hand
  • Motor sounds more strained even at lower speeds
  • Inconsistent movement (stuttering or binding)
See the belt tension guide for lubrication instructions.
An aging or failing power supply may deliver less voltage or current than rated, causing the motor to struggle under load.Signs of power supply issues:
  • Motor sounds strained only under load (during strokes, not at idle)
  • Performance degrades as the session continues (power supply heating up)
  • Visible dimming of motor LED during operation
Solution:
  1. If you have a multimeter, measure the voltage at the power input terminals while the OSSM is operating—a healthy 24V supply should deliver close to 24V under load
  2. Try a different power supply if available
  3. Ensure you’re using a supply rated for at least 5A
See insufficient power supply for more details.

​
Homing is too slow

If your OSSM homes very slowly or stalls during the homing sequence, the motor may need to be programmed.
1

Check motor programming

The motor requires specific parameters to operate correctly with OSSM. If you assembled the motor yourself or it was reset, you may need to flash the motor firmware.See the motor programming guide for detailed instructions.
2

Verify motor parameters

After programming, the motor should home at a reasonable speed. If problems persist, double-check that all parameters were applied correctly.

​
Controller powers on but actuator does not move

When the controller turns on but the actuator remains stationary, the issue is typically related to power delivery, wiring, or belt tension.
Symptoms:
  • Green light on motor is dim or flickering
  • Motor light is visible but actuator doesn’t respond
  • Actuator moves weakly or stalls under load
Solution: Ensure you’re using a power supply that meets the minimum requirements:
  • Voltage: 24V DC
  • Current: At least 5A
Using an underpowered supply can damage components over time. Always use a supply rated for your motor’s requirements.
Symptoms:
  • Motor light is completely off
  • No response from motor when commands are sent
  • Visible loose or disconnected wires
Diagnosis:
  1. Inspect the wiring between the controller and motor
  2. Check that all connectors are fully seated
  3. Look for damaged or frayed wires
Solution: Reconnect any loose wiring following the wiring guide. If wires are damaged, replace them before operating.
Symptoms:
  • Motor spins but actuator doesn’t move
  • Belt slips or makes noise during operation
  • Inconsistent or jerky movement
Solution: Adjust the belt tension following the tension adjustment guide. The belt should be tight enough to prevent slipping but not so tight that it strains the motor.
A properly tensioned belt should deflect slightly when pressed but return to position immediately.

​
Wired remote does not power on

If the wired remote display stays dark when connected, the issue is usually connection timing or a loose cable.
The wired remote draws power from the control board. If you connect the remote before the board is powered, it may not initialize correctly.Solution:
  1. Disconnect the RJ45 cable from the control board
  2. Power on the OSSM using the 24V supply
  3. Wait for the control board to fully boot (LED indicators stabilize)
  4. Connect the wired remote’s RJ45 cable firmly until it clicks
If the remote still doesn’t light up, disconnect the 24V power, wait a few seconds, then reconnect and repeat the steps above.
A loose or partially seated cable can prevent power from reaching the remote.Solution:
  1. Disconnect the RJ45 cable from both ends
  2. Inspect the connectors for bent pins, debris, or damage
  3. Reconnect firmly at both the control board and the remote until you hear/feel a click
  4. Try a different RJ45 cable if available
If the remote worked previously but stopped, a simple power cycle often resolves the issue.Solution:
  1. Disconnect the 24V power supply from the control board
  2. Wait 5–10 seconds
  3. Reconnect the 24V power supply
  4. Allow the board to boot, then check if the remote display activates
If the remote powers on after cycling, no further action is needed. Intermittent issues may indicate a marginal cable connection—try reseating or replacing the RJ45 cable.

​
Wired remote lights up but speed control does not respond

If the wired remote display illuminates but the left knob (speed potentiometer) has no effect, the potentiometer component may be faulty.
Symptoms:
  • Remote display turns on and shows the menu
  • Right knob (encoder) works normally for menu navigation
  • Left knob (speed control) produces no change regardless of position
  • No visible damage to the knob or circuit board
Diagnosis:
  1. Power on OSSM and confirm the remote display activates
  2. Navigate menus with the right knob to confirm it responds
  3. Turn the left knob fully counterclockwise to clockwise—if speed never changes, the potentiometer is likely defective
Before concluding the potentiometer is faulty:
  1. Power off and reseat the RJ45 cable at both ends until it clicks
  2. Try a different RJ45 cable if available
  3. Inspect the cable connectors for bent pins or debris
  4. Power on and test again
If the right knob still works but the left knob doesn’t respond, the issue is the potentiometer rather than the connection.
A non-responsive potentiometer indicates a hardware fault that cannot be fixed through software or settings. Contact support to request a replacement wired remote under warranty.Self-repair option: If your remote is out of warranty or you prefer to repair it yourself, the potentiometer part number is:
  • Potentiometer: ALPSALPINE RK09D1130C3C
This component is available from electronics suppliers such as Digikey, Mouser, or AliExpress.
If you have a RADR wireless remote, you can continue using your OSSM while waiting for the replacement. The RADR provides full speed and stroke control.

​
Right encoder skips clicks or rotations

If the right encoder on the wired remote only registers every second or third click when navigating menus or adjusting parameters, the encoder component may be faulty.
Symptoms:
  • Remote display turns on and shows the menu
  • Left knob (speed control) works normally
  • Right encoder responds inconsistently—only some clicks or rotations are registered
  • Turning the encoder requires multiple clicks to move through menu items
  • Solder joints on the remote board appear intact
Diagnosis:
  1. Power on OSSM and navigate to any menu
  2. Slowly turn the right encoder one click at a time
  3. Count how many physical clicks it takes to move one menu position
  4. If it consistently takes 2–3 clicks to register a single movement, the encoder is defective
Before concluding the encoder is faulty:
  1. Power off and reseat the RJ45 cable at both ends until it clicks
  2. Try a different RJ45 cable if available
  3. Inspect the cable connectors for bent pins or debris
  4. Power on and test again
If the issue persists after checking the cable, the encoder itself is defective.
A partially responsive encoder indicates a hardware fault that cannot be fixed through software or settings. Some batches of encoder components have been found to have this defect. Contact support to request a replacement wired remote under warranty.Self-repair option: If your remote is out of warranty or you prefer to repair it yourself, the encoder part number is:
  • Encoder: ALPSALPINE EC11E18244AU
This component is available from electronics suppliers such as Digikey, Mouser, or AliExpress.
If you have a RADR wireless remote, you can continue using your OSSM while waiting for the replacement. The RADR provides full control without relying on a wired connection.
If selecting certain menu options—such as Get Help, WiFi Setup, or Update—causes the display to go blank or show no response, the issue is usually related to your firmware version or WiFi configuration.
These menu options are implemented in current firmware:
  • Get Help — Displays a QR code linking to documentation
  • WiFi Setup — Opens the WiFi configuration portal
  • Update — Checks for over-the-air firmware updates
If you see a blank screen instead, your firmware may be outdated. Update using the Web Flasher to get the latest version.
If the display goes blank when selecting these options, press the encoder button to return to the menu.
WiFi Setup and Update require the OSSM to connect to a WiFi network. If WiFi has not been configured, these options may not function as expected.You can configure WiFi using the Web BLE Controller in a browser without relying on the wired remote’s WiFi Setup menu. See WiFi Setup for instructions.To ensure you have the latest features, update your firmware using the Web Flasher.
If the wired remote’s menu options aren’t working for you, these browser-based tools provide the same functionality:
  1. Use the Web BLE Controller to configure WiFi from your browser
  2. Use the Web Flasher to update firmware directly via USB

​
Boot loops or display artifacts

If your OSSM repeatedly restarts (boot loops) or shows corrupted characters, flickering, or visual glitches on the wired remote display, there may be a hardware fault with the wired remote board or the main control board.
Symptoms:
  • Device restarts repeatedly without completing the homing sequence
  • Display shows garbled text, flickering, or visual artifacts
  • Crashes or reboots occur when using the right knob (encoder)
  • Random, uninstructed changes to speed, depth, or stroke parameters
  • Motor attempts to exceed position limits (violent movement, belt skipping)
  • Problems persist after trying different firmware versions
What to rule out first: Before suspecting a hardware fault, try:
  1. Different RJ45 cable — A damaged cable can cause intermittent faults
  2. Different power supply — Voltage fluctuations can cause instability (use a quality 24V supply rated for at least 5A)
  3. Reflash firmware — Corrupted firmware can cause unexpected behavior. Use the Web Flasher to install the latest stable version.
If basic troubleshooting doesn’t help, verify the control board is receiving power correctly:
  1. Check the 3.3V LED — The control board has a small blue LED near the ESP32 chip. If this LED is on, the board is receiving power and the voltage regulator is working.
  2. Check 24V at the input terminals — Use a multimeter to verify 24V DC at the power input terminals on the control board. A healthy supply should read close to 24V.
  3. Check voltage at motor terminals — Measure voltage at the motor output terminals to confirm power is reaching the motor driver.
If the 3.3V LED is off or dim, or if voltage readings are incorrect, the issue may be with your power supply or the control board itself.
Isolate whether the wired remote is causing the issue:
  1. Power off the OSSM completely
  2. Disconnect the wired remote’s RJ45 cable from the control board
  3. Power on the OSSM
  4. Observe the serial output via USB (optional) or listen for motor movement
Interpreting results:
  • If the OSSM boots normally and homes without the remote connected, the wired remote board is likely faulty.
  • If the OSSM still fails to boot or crashes without the remote connected, the main control board may be faulty.
If you have a RADR wireless remote, connect via RADR after disconnecting the wired remote to test normal operation.
Boot loops, display corruption, or erratic parameter changes that persist after troubleshooting indicate a hardware fault. Depending on test results:
  • Wired remote at fault — Contact support to request a replacement wired remote board under warranty.
  • Control board at fault — Contact support to request a replacement control board under warranty.
While waiting for a replacement, you can continue using your OSSM with a RADR wireless remote if you have one available (assuming the main control board is functional).

​
Reset button and flashing firmware

The OSSM control board has a small reset button near the blue LED. Understanding what this button does—and what it does not do—can help avoid confusion when troubleshooting or updating firmware.
The reset button on the OSSM control board performs a power cycle reset. Pressing it restarts the ESP32 microcontroller, similar to unplugging and reconnecting power.What it does:
  • Restarts the ESP32 and reinitializes the firmware
  • Clears any temporary runtime state
  • Can help recover from a frozen or unresponsive state
What it does not do:
  • It does not erase stored settings or calibration data
  • It does not wipe the flash memory
  • It does not perform a factory reset or clear WiFi credentials
  • It does not trigger a new homing sequence automatically (homing occurs on boot as part of normal startup)
If your OSSM becomes unresponsive, try pressing the reset button once. You do not need to hold it down—a single press is sufficient.
The standard OSSM firmware does not include a built-in factory reset function. To completely clear settings and return to defaults:
  1. Reflash the firmware using the Web Flasher. This overwrites the existing firmware but may not clear all stored data in flash memory.
  2. For a complete flash wipe, you need to use development tools like PlatformIO or esptool to erase the flash before reflashing. See PlatformIO setup for details.
Most users do not need to perform a full flash wipe. Standard reflashing via the Web Flasher is sufficient for firmware updates and resolving most issues.
Some community members develop alternative firmware for specialized use cases. If you want to install community firmware:
Community firmware is not officially supported by Research and Desire. Use at your own risk. Some community projects may be experimental or deprecated.
Before installing community firmware:
  • Back up any settings you want to preserve
  • Note your current firmware version in case you need to revert
  • Read the community project’s documentation carefully
If the community firmware requires a clean flash: The reset button does not wipe flash memory. To fully erase flash before installing community firmware, you typically need to:
  1. Use PlatformIO with the Erase Flash command
  2. Or use esptool.py erase_flash from the command line
Contact the community firmware developer (often via Discord) for specific installation instructions, as requirements vary between projects.
To return to official firmware after experimenting with community builds, use the Web Flasher to reinstall the latest stable release.

​
Signs of control board failure

If your OSSM control board isn’t responding to any troubleshooting steps, the board itself may be defective. Hardware failures are rare but can occur, particularly if there was a manufacturing defect or a short circuit event.
Symptoms:
  • The ESP32 chip on the control board becomes uncomfortably hot to touch within seconds of applying power
  • Overheating occurs whether powered via the 24V supply or via USB-C connection
  • The board may have worked briefly before, or never worked at all
What this indicates:The ESP32 should be warm during operation but never hot enough to be uncomfortable. Excessive heat indicates a hardware fault—typically a short circuit or damaged component on the board.
If the ESP32 is too hot to touch comfortably, disconnect power immediately. Continued operation with a damaged board can cause further damage or safety hazards.
Resolution:An overheating ESP32 indicates a hardware defect that cannot be fixed through firmware updates or configuration changes. Contact support to request a replacement control board.
Symptoms:
  • The board is detected on a COM/serial port, but flashing always fails
  • Both the Web Flasher and PlatformIO fail to communicate with the board
  • Error messages indicate “unable to connect” or “failed to sync” despite the board being detected
  • You’ve already tried: different USB cables, different USB ports, different computers, installing drivers, closing other serial applications
What this indicates:If the board appears on a COM port but cannot be flashed after exhausting all standard troubleshooting, the ESP32 or its flash memory may be damaged. This can occur from:
  • Electrostatic discharge during handling
  • A short circuit event
  • A manufacturing defect
Before concluding the board is defective, ensure you’ve completed all steps in the Web Flasher troubleshooting. Some connection issues are caused by driver conflicts or USB cable quality.
Resolution:If you’ve exhausted all troubleshooting steps and still cannot flash the board, contact support with details of what you’ve tried. A replacement board may be needed.
Symptoms:
  • Motor does not move at all when powered on—no homing attempt, no sound, no vibration
  • The 3.3V LED on the board may illuminate, but no other activity occurs
  • No purple LED breathing pattern during homing
  • Motor’s green power LED is on (indicating motor is receiving power)
  • ESP32 chip may be abnormally hot
Distinguishing board failure from motor failure:
ObservationLikely Cause
Motor LED off, board LEDs onMotor wiring or motor issue
Motor LED on, no homing movement, ESP32 hotBoard failure
Motor LED on, slow/stuttering movementMotor programming issue
Motor LED on, normal homing, then stopsPossible firmware or motor issue
Resolution:If the motor shows power (green LED) but the board shows no activity beyond the 3.3V LED, and especially if the ESP32 is overheating, the control board is likely defective. Contact support to arrange a replacement.
Symptoms:
  • Unusual sounds on first startup—clicking, buzzing, or electronic tones (not mechanical belt noise)
  • 3.3V LED may flash in sync with the sounds
  • Sounds stop after a while and the board becomes unresponsive
  • Different from the normal homing movement sounds
What this indicates:Electronic noises accompanied by LED flashing (not the normal purple breathing pattern) can indicate the board is in a fault state or experiencing a hardware issue. If the board subsequently becomes unresponsive or won’t flash, the initial noise may have been a symptom of component failure.
Normal OSSM operation produces quiet mechanical sounds from the motor and belt during homing. Electronic buzzing, beeping, or “8-bit” tones from the board itself are not normal.
Resolution:If your board made unusual electronic noises on first power-up and is now unresponsive to flashing attempts, contact support with a description of what you observed. This helps identify potential batch issues.

​
Power supply connection sparks or disconnects

If you see sparks when connecting the power supply or the barrel jack connection is loose and disconnects with small movements, the cable may not be secured properly.
The PCB mount includes a strain reliever on the side to secure the power cable and prevent movement at the barrel jack connection.Solution:
  1. Route the power cable through the strain relief slot on the side of the PCB mount
  2. Secure the cable so the barrel jack connector cannot move or wiggle during use
  3. Ensure the barrel jack is fully seated before securing the cable
A properly secured power cable should have no slack at the barrel jack. The strain reliever takes mechanical stress off the connector, preventing intermittent connections and arcing.
Symptoms:
  • Sparks when plugging or unplugging the power supply
  • Power cuts out when the cable moves
  • Intermittent power during operation
Solution:
  1. Unplug the power supply from the wall before disconnecting from the board
  2. Inspect the barrel jack connector for damage, bent pins, or debris
  3. Ensure the barrel jack is fully inserted until it clicks or seats firmly
  4. Use the strain reliever to prevent cable movement during use
Repeatedly connecting and disconnecting a loose barrel jack can cause arcing, which damages the connector over time. If you see visible damage to the barrel jack or PCB connector, contact support for replacement options.
Ensure your power supply matches the PCB requirements:
  • Barrel jack size: 5.5mm outer diameter × 2.1mm inner diameter
  • Polarity: Center-positive
  • Voltage: 24V DC (or USB-C PD if using that input)
An incorrectly sized barrel jack may not seat properly, causing loose connections. If using a third-party power supply, verify the connector matches these specifications.

​
Still having issues?

If you’ve worked through these troubleshooting steps and still have problems:

Report an issue

Found a bug or design problem? Submit a detailed issue on GitHub.
Get real-time help from experienced builders on Discord: