DOCSEARCHbyAlgolia
Submit Docs

moteus Documentation

repository·main·Indexed 22 days ago

https://github.com/mjbots/moteus

A suite of tools for brushless servo actuators, including Python and Rust client libraries for interacting with moteus controllers. It features the moteus-protocol crate for low-level, no_std compatible CAN-FD frame encoding/decoding, and the moteus-derive crate for builder-style setter macros. The libraries support various transports including fdcanusb, SocketCAN, and pi3hat, providing high-level controller abstractions and low-level protocol access.

Tokens
50.6K
Snippets
100
Records
253
Agent score
78%

What's inside moteus

  1. Overview of moteus-protocol

    main

    The moteus-protocol crate provides low-level CAN-FD protocol types for communicating with moteus brushless motor controllers. It handles the encoding and decoding of CAN-FD frames but performs no I/O itself. You must provide the CAN-FD transport layer.

    Key characteristics:

    • no_std compatible: Works on embedded systems without an allocator.
    • Transport agnostic: It builds frames for you to send and parses frames you receive.
    • High-level alternative: Most users should use the moteus crate, which provides async/blocking controllers, device discovery, and transport implementations (like fdcanusb or SocketCAN). Use moteus-protocol directly only if you are on an embedded target or implementing your own CAN-FD transport.

  2. Overview of moteus brushless motor controllers

    main

    moteus controllers are high-performance modular brushless motor controllers designed for robotics. They utilize Field Oriented Control (FOC) for 3-phase motors and include integrated magnetic encoders for precise position sensing.

    Key technical features include:

    • Communication: High-speed CAN-FD at 5Mbps.
    • Control Modes: Position, velocity, and torque control, supporting acceleration and velocity limited trajectories.
    • Performance: Fast control loops running at 15-30kHz.

  3. Overview of moteus brushless servo

    main

    moteus is a project providing full designs for brushless servo actuators, including hardware (mechanical and electrical), firmware, and client-side software.

    WARNING: The project includes designs for high-power electronics. Use with caution as there are no guarantees against hardware failure or safety hazards.

  4. Integrate moteus with software and hardware

    main

    moteus can be integrated into your system using several different methods depending on your language requirements and hardware access level:

    • Python Client: Use the high-level Python client library for rapid development and ease of use.
    • C++ Client: Use the C++ client library for high-performance applications.
    • Raw CAN-FD: Access the moteus protocol directly via CAN-FD for low-level control or custom implementations.

  5. Access moteus technical reference documentation

    main

    The moteus technical reference is organized into several key areas for hardware, software, and protocol interaction:

    Hardware & Physical Interface

    • Pinouts: Connector pinout definitions.
    • Encoders: Information on supported encoder types.
    • Hardware Specifications: Detailed hardware specs.
    • Application Limits: Operating limits for the device.

    Software & Tools

    • Client Tools: Documentation for moteus_tool and tview.
    • Python API: Reference for using the moteus Python library.
    • Flashing and Building Firmware: Instructions for firmware management.

    Protocol & Control

    • CAN Protocol: CAN-FD message format details.
    • Register Reference: The complete register map.
    • Diagnostic Protocol: Diagnostic command specifications.
    • Theory of Operation: Background on the control theory used.

  6. moteus-n1 Hardware Features and Specifications

    main

    The moteus-n1 is a high-power, high-voltage, and flexible version of the moteus brushless controller with a smaller footprint (46x46mm).

    Key Specifications:

    • Max Voltage: 51V (compared to 44V on standard moteus).
    • CAN Bus: Includes a CAN transceiver with a 58V bus fault voltage.
    • Power Output: Provides 200mA of 5V and 200mA of 3V shared between the AUX1 and AUX2 connectors.
    • RS422: Includes an RS422 transceiver and connector (utilizing two spare pins on AUX1).
    • Footprint: Designed to be smaller by removing the requirement for bottom-side connectors, though optional solder pads for power in are available for higher current capability. Variants exist with optional power/CAN connectors on the bottom for daisy chaining.

  7. Understand the role of encoders in moteus

    main

    moteus uses encoders for two primary purposes:

    1. Commutation: To determine the electrical relationship between the stator and the rotor to apply torque correctly.
    2. Output: To determine the position and velocity of the output shaft for following commanded trajectories.

    By default, the onboard magnetic encoder (AS5047P) is used for both commutation (sensing the rotor) and output (position/velocity of the output shaft, constrained by a configurable reduction ratio).

  8. Configure moteus parameters

    main

    moteus devices are configured using specific parameters. Key configuration areas include:

    • Identity: id.id for device ID.
    • Servo Limits: servo.max_power_W (maximum power), servo.default_timeout_s (command timeout), and servo.flux_brake_margin_voltage (flux braking threshold).
    • PID Tuning: servo.pid_position for position controller parameters.
    • Motion Limits: servo.position_min (minimum position limit) and servo.velocity_limit (trajectory velocity limit).
    • Motor/Encoder Mapping: motor_position.rotor_to_output_ratio (gear reduction) and motor_position.output.offset/sign (encoder offset/sign).

    Configuration can be read and written via the console using Configuration Commands.

  9. Field weakening constraints and limits

    main

    Field weakening operation is subject to several hardware and software constraints:

    • Voltage Limit: moteus restricts field weakening speed so that the back-EMF never exceeds servo.max_voltage (minus a safety margin).
    • D axis Current Limit: The maximum D axis current available for field weakening is determined by multiplying servo.max_current_A by servo.fw.max_current_ratio.
    • Stability and Noise: Some motors require a higher --cal-bw-hz during calibration to operate stably in the field weakening regime, which may increase audible noise at all speeds.

  10. Understand the two purposes of encoders in moteus

    main

    moteus utilizes encoders for two distinct functional requirements:

    1. Commutation feedback: Provides the electrical relationship between the motor's stator and rotor, which is required to apply torque correctly.
    2. Output feedback: Provides the position and velocity of the output shaft to enable following commanded trajectories.

    You can satisfy these requirements using a single encoder for both purposes, or by using separate encoders for each (e.g., one for commutation and one for output).

  11. Manage regenerative braking and overvoltage safety

    main

    When braking a load, moteus applies generated power to the DC bus. If the bus cannot absorb this energy, voltage can rise uncontrollably, potentially destroying the CAN transceiver or the FETs.

    Software Protections

    Use these configuration parameters to limit regenerative voltage rise:

    • servo.default_accel_limit (or per-command accel_limit): Controls the rate of braking torque application.
    • servo.max_regen_power_W: Limits the power allowed to flow back to the bus. Set to a small value (e.g., 10 or 0) if the supply cannot absorb energy.
    • servo.flux_brake_margin_voltage and servo.flux_brake_resistance_ohm: Controls Flux Braking, where energy is dissipated in the motor windings when bus voltage exceeds a threshold.

    Hardware Design Best Practices

    • Set servo.max_voltage: Lower this value for all devices on the bus. It should be set at least 5V above the maximum expected supply voltage.
    • Use Batteries: Batteries can sink current to mitigate transients, but only if they are not fully charged (keep charge below 75-80%).
    • Lower System Voltage: For high regenerative loads, avoid high-voltage setups (e.g., use 8S/33.6V instead of 10S/42V).
    • Two-Quadrant Supplies: Use a power supply capable of both sourcing and sinking current. Standard lab supplies that only source current are dangerous in regenerative applications.

  12. How moteus Controller interactions work

    main

    Interactions with a moteus brushless controller are mediated through the moteus.Controller object.

    When you initialize a Controller with the default argument transport=None, the library automatically attempts to find a suitable communication link on your host system, typically searching for the first available fdcanusb or socketcan bus.

    For single-controller imperative operations, you can use:

    • await Controller.set_stop()
    • await Controller.set_position()
    • await Controller.query()