Skip to content

About

Open-source NEMA-17 integrated servomotor (motor + closed-loop driver + controller + encoder). RS-485, Python/Arduino libraries, MCP server for AI control. Hardware, firmware and software.

Topics

Resources

Stars

19 stars

Watchers

1 watching

Forks

Latest commit

 

History

583 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Gearotons M17 servomotor family: M17-60, M17-48, M17-40, M17-34

Gearotons M17 — an open-source servomotor you can talk to

The M17 is a NEMA-17 integrated servomotor: motor, closed-loop driver, motion controller and magnetic encoder in one unit. It daisy-chains over RS-485, ships with Python and Arduino libraries, and has a first-party MCP server so an AI assistant (Claude Desktop, Claude Code, Cursor, …) can drive real motors from plain English.

Hardware, firmware and software are all in this repository under the MIT license.

M17-34 M17-40 M17-48 M17-60
Length 33.5 mm 40.1 mm 48.7 mm 59.7 mm
Holding torque 0.28 N·m 0.42 N·m 0.55 N·m 0.65 N·m
Weight 210 g 285 g 360 g 470 g

All sizes: 12–24 V, up to ~1.1 A, up to 560 RPM, closed-loop 32 kHz control, RS-485 at 230400 baud, 64-bit unique ID + one-byte alias per motor, standard NEMA-17 mount. Indoor use (IP20).

Buy one: gearotons.com (from $20; ships worldwide from Shenzhen). Documentation: 9o.at/M17_1.5 · Datasheet (PDF) · Python API · Arduino API

Quick start (Python)

pip install servomotor
import time, servomotor

servomotor.open_serial_port()                      # prompts for the USB–RS-485 adapter the first time
m = servomotor.M3("X", time_unit="seconds", position_unit="shaft_rotations")
m.enable_mosfets()
m.trapezoid_move(1.0, 1.0)                         # one full turn, in one second
time.sleep(1.1)
m.disable_mosfets()
servomotor.close_serial_port()

That is python_programs/example_trapezoid_move.py. Units are yours to choose (degrees, rotations, radians, encoder counts; seconds or milliseconds) — the library converts. No STEP/DIR timing, no microstep configuration.

Quick start (Arduino / ESP32)

Install the Servomotor library by Gearotons from the Arduino Library Manager, or from Arduino_library/. Wire the board's UART to an RS-485 transceiver, then:

#include <Servomotor.h>

void setup() {
  Servomotor motor('X', Serial1);                  // alias 'X'; the port opens on first use
  motor.setPositionUnit(PositionUnit::SHAFT_ROTATIONS);
  motor.setTimeUnit(TimeUnit::SECONDS);
  motor.enableMosfets();
  motor.trapezoidMove(2.0f, 3.0f);                 // two rotations over three seconds
  delay(4000);
  Serial.println(motor.getPosition());             // commanded position; getHallSensorPosition() reads measured position
}
void loop() {}

That is a trimmed Arduino_library/example_one_move.cpp (the full file adds the ESP32 RS-485 pin definitions).

Quick start (talk to it)

uvx --from servomotor-mcp servomotor-mcp        # runs with a simulated motor if no hardware is attached

Add it to Claude Desktop or run claude mcp add gearotons-motor -- uvx --from servomotor-mcp servomotor-mcp, then ask: "Find my motors, then move the one on the bench to 90 degrees and tell me where it ended up." Details and the full tool list: Gearotons/servomotor-mcp.

Claude Code driving a real M17 over MCP: find the motor, turn it two rotations, back, read the encoder

▶ 50-second video: the real motor and this session side by side (recorded 2026-09-09 on a bench M17).

Wiring: computer, USB to RS-485 adapter, two daisy-chained M17 motors, 12–24 V supply

What is in this repository

Folder Contents
firmware/ Motor firmware (STM32G0), plus bootloader_STM32G030/ and bootloader_STM32G031/
PCB/ Schematics, board layouts and 3D (STEP) models of the controller board
python_programs/ The servomotor Python library source, examples, test and characterisation scripts
Arduino_library/ The Arduino/ESP32 C++ library and examples
API_documentation/ Generated Python and Arduino API references (Markdown and PDF)
servomotor_datasheets/ Datasheet sources and PDFs (EN, DE, ES, FR, IT, PT), dimension drawings
production_test_system/, motor_tests/ How we test motors before they ship
marketting_page/ Source of the gearotons.com product page

The command set is data-driven: every firmware command is defined once in motor_commands.json and the Python library, the Arduino library and the MCP server are generated from it, so they always agree.

Firmware 0.17.0.0

This M17 release adds Set immediate position target (49) and Set immediate position target and get position (50). The second command returns the latest stored Hall position. Both require an empty motion queue and enabled closed-loop position control. PID readback (48) remains available.

m.set_immediate_position_target(1000)
measured = m.set_immediate_position_target_and_get_position(2000)

Updated bindings are published as Python 0.13.0 and Arduino 0.11.0. See the client-library release handoff for validation, release receipts and remaining indexing/publishing follow-ups. The release image targets M17 hardware 1.5, software compatibility code 3. Version 0.17.0.0 promotes the validated 0.17.0.6 implementation; only the development-version byte changes. See the release notes for behavior, client compatibility, upgrade/rollback commands and validation. The exact stable image passed 35,148+ canary updates with zero communication errors; see release-image results. The firmware release index lists images, release notes, checksums and manifests, including the preceding 0.16.0.0 release.

Immediate targets and ServoTune

Both commands require an empty queue and enabled closed-loop position control. They retain PID history and protections. Validation runs with interrupts enabled; only the target/planner stores are masked. Command 50 reads cached Hall position atomically afterwards, without a sensor recalculation or control-tick wait. Its reply confirms reference installation, not shaft arrival.

The exact 0.17.0.0 image passed 35,148+ canary updates, both CRC modes, protection/recovery, native C++ clients and timed-move followups, with zero communication errors. Release-image results include timing limits. Updated Python/Arduino bindings and ServoTune recognize stable 0.17.0.0; ServoTune also retains the legacy 24-byte reply for development 0.17.0.2.

Try the ServoTune browser bench without a motor:

python3 servotune/serve.py

The launcher opens a clearly labelled demo with simulated data. The modified client serializes request/reply transactions and supports both new commands. The published stable firmware is 0.17.0.0. The preceding 0.16.0.0 release does not implement immediate-target commands.

Where the M17 is not the right tool

Direct-drive torque tops out at 0.65 N·m (gear it or go up a frame size for more), it is IP20 and indoor-only, and it is not a STEP/DIR drop-in for an existing 3D-printer board — it wants a serial bus and a host that sends it moves. We would rather you know that before you buy.

Community and support

Questions and builds: GitHub Discussions · email info@gearotons.com. Issues and pull requests welcome — the whole stack is here to be read, modified and improved.

Built and assembled by Gearotons in Shenzhen. MIT license — see LICENSE.

About

Open-source NEMA-17 integrated servomotor (motor + closed-loop driver + controller + encoder). RS-485, Python/Arduino libraries, MCP server for AI control. Hardware, firmware and software.

Topics

Resources

Stars

19 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages