Skip to main content

Usage

Here's a basic example of how to use the servomotor package:

import servomotor

# Open the intended adapter explicitly. Use a motor unique ID on shared racks.
servomotor.set_serial_port("/dev/ttyUSB0")
servomotor.open_serial_port()
motor = servomotor.M3("0123456789ABCDEF", position_unit="encoder_counts")
try:
    kp, ki, kd = motor.get_pid_constants()  # firmware 0.16.0.0 or later
    print(kp, ki, kd)
finally:
    servomotor.close_serial_port()

Firmware 0.17.0.0 adds set_immediate_position_target(targetPosition) and set_immediate_position_target_and_get_position(targetPosition). Both require closed-loop position mode, enabled MOSFETs, an empty trajectory queue and zero commanded/planned velocity. Targets must satisfy the configured position and deviation limits. These commands step the reference immediately; trajectory velocity/acceleration limits do not profile the resulting catch-up motion.

The combined method returns the latest stored measured Hall position, which may come from the preceding control tick. It does not wait for arrival or sample the ADC again. With position_unit="encoder_counts", Python integer targets and responses preserve the full signed 64-bit value. For other units, conversions use floating point. The measured position may differ from the requested target.

Broadcast calls return an empty list because motors do not reply. Use a unique ID to obtain a measured position or PID constants. Invalid keyword arguments, nonfinite numeric inputs and out-of-range integer fields raise exceptions before transmitting. Device fatal errors raise servomotor.FatalError and require a motor reset. Do not retry motion automatically after a communication failure.

For more detailed usage instructions, please refer to the documentation.

Choosing the serial port

The command line tools work out which serial port to use in this order, highest priority first:

  1. -p PORT on the command line (-P instead pops up a menu of detected ports)
  2. the SERVOMOTOR_PORT environment variable
  3. the port saved from the last successful run
  4. an interactive menu, if none of the above apply

So a port can be set once for a whole shell session:

export SERVOMOTOR_PORT=/dev/ttyUSB0        # Linux
export SERVOMOTOR_PORT=/dev/cu.usbserial-110   # macOS
set SERVOMOTOR_PORT=COM3                   # Windows (cmd)
$env:SERVOMOTOR_PORT = "COM3"              # Windows (PowerShell)

-p still overrides it for a single command, and -P always shows the menu.

After a port is opened successfully it is remembered, in a per-user location:

Platform Saved port file
Linux $XDG_CONFIG_HOME/servomotor/serial_device.txt, else ~/.config/servomotor/serial_device.txt
macOS ~/Library/Application Support/servomotor/serial_device.txt
Windows %LOCALAPPDATA%\servomotor\serial_device.txt

Delete that file to forget the remembered port.

Serial port permissions on Linux

Serial devices usually belong to the dialout group (uucp on some distributions). If you get a permission error, add yourself to it:

sudo usermod -a -G dialout $USER

then log out and back in for the change to take effect.

Features

  • Control Gearotons servomotors via serial communication
  • Easy-to-use interface for sending commands and receiving responses
  • Automatic handling of serial port selection and management

Requirements

  • Python 3.8+

That is the whole list. pyserial is BUNDLED inside this package (servomotor/vendor/serial/) and imported from there, so pip install servomotor pulls in no other dependencies and you do not need to install pyserial yourself.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENCE file for details.

Contact

Tom Rodinger - tom.rodinger@alumni.utoronto.ca

Project Link: https://gearotons.com

Metadata

Release files for servomotor 0.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for servomotor 0.13.0
File Size Uploaded Provenance Actions
servomotor-0.13.0.tar.gz 162.4 kB Without provenance Details for servomotor-0.13.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for servomotor 0.13.0
File Interpreter ABI Platform Actions
servomotor-0.13.0-py3-none-any.whl Python 3 none any Details for servomotor-0.13.0-py3-none-any.whl

Total release size: 348.3 kB

Release files / servomotor-0.13.0.tar.gz

Download URL servomotor-0.13.0.tar.gz
Size 162.4 kB
Tags Source
SHA-256 checksum
How to use checksums
28f0962c3b9be54cc9d6c6b618f8b975bf39e262e0f3801c3e1e2571e81f93e5
BLAKE2b-256 checksum
How to use checksums
72e9caddd6f8dc37a90167ebe0904e239e5a748c023c35f2d35a0a3781ca711c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / servomotor-0.13.0-py3-none-any.whl

Download URL servomotor-0.13.0-py3-none-any.whl
Size 185.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
523e6b659ab99517cb7863596b8527f8eb0e5e91db55c516c20caca5f861c2bb
BLAKE2b-256 checksum
How to use checksums
4dbf0f65b129ea5ae001202165ecb61bc8f3a17a91b2667d2f244810dd8c5a48
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for servomotor 0.13.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page