The moteus brushless motor controller supports several concepts of operation from within its primary “position” mode, including a velocity mode. As documented in the reference, you can run in that scenario using commands equivalent to the diagnostic mode command:

d pos nan V nan

Where V is the desired velocity. However, as with most control operations, there are a number of edge cases that can be useful to handle. When operating purely in velocity mode, the normal PID constants can be interpreted slightly differently:

For the moteus brushless controller, the moteus_tool utility has long had a --dump-config command line action which will cause the entire contents of the configuration to be written to standard output.

--dump-config format

This configuration looks like this:

servo.pid_position.kp 4
servo.pid_position.kd 0.1

moteus_tool has also had a --write-config option, which is something of a misnomer, as it actually just sends any commands one at a time from a file to the controller. Notably, it requires that the file to contain actual valid diagnostic mode commands.

When commanding a moteus controller, many of the registers defined in the reference documentation give explicit semantics when the value is passed as either a floating point NaN value or the “maximally negative integer” for integer encodings. Those that do not specify a meaning for NaN are “undefined” and anything can happen. For the most part, this isn’t a problem, but in one specific case users were repeatedly caught off guard.

Three common registers often set in position mode, (also accessible by the unlabeled first three arguments to “d pos”), are 0x020 “target position”, 0x021 “target velocity”, and 0x025 “maximum torque”. Target position has a defined meaning when set to NaN: the controller assumes that the target position is the current target position, or the sampled position if the controller is not yet in position mode. Maximum torque also has a defined meaning when set to NaN: it then uses the maximum torque as defined by the maximum phase current limit. However, target velocity had no such definition, and in practice when used, resulted in the controller becoming mostly non-functional.

As of release 2023-09-26, moteus controllers can now use CUI AMT21 series encoders for any encoder source. CUI’s AMT21 series encoders are rugged, with resolution up to 14 bits, and since they use RS485 for communication can be located a significant distance from the motor driver if necessary. Setting one up is easy with the moteus-n1, which is what I’ll cover here.

Hardware

The moteus N1 has JST GH-6 connector labeled “RS422” with all the pins necessary to power and communicate with an AMT21. Since the AMT21 is RS485, not RS422, it is required to tie the A and Y pins together and the B and Z pins together. An easy option is to do so in the harness, either by crimping multiple wires into the Molex terminal for the AMT21, or by splicing wires. The desired schematic looks like:

In simple motion control applications with moteus, a common request for the python library is “run a position command until it is complete”. moteus does track when the target position reaches the desired one and reports it in the “trajectory complete flag” (register 0x00b), however until now the application needed to poll that flag on a regular basis to see when the motion is done.

As of pypi moteus 0.3.59, there is now a new method on Controller which can be used to accomplish this, along with an example script. Basic usage is about as simple as one would expect:

As of release 2023-09-26, moteus r4 and moteus-n1 now both support the MA732 as an external SPI encoder. The magnetic sensing performance of the MA732 is normally a bit worse than the AS5047P that is used as the onboard encoder with moteus, but it has two possible advantages.

The first, is that it is much smaller, using a 3mm x 3mm QFN package. The second is that it supports off-axis applications. You will need to read the datasheet, and set the 'aux?.spi.bct' configuration parameter correctly, but this can enable operation in interesting geometries, like a ring magnet with a hollow shaft, or where the coaxial placement is otherwise not feasible.

The pi3hat repository, in addition to hosting a library for sending raw CAN frames using the pi3hat, has long had example source code demonstrating how to use that to communicate with a moteus controller. Recently however, C++ bindings were officially added to the primary moteus repository, that provide a more consistent, flexible and complete interface to moteus controllers. I’ve gone ahead and updated the pi3hat library to take advantage of that new interface, so now the pi3hat can be treated as just another transport like the fdcanusb.

In the initial announcement of the new moteus C++ library, the only transport that was supported out of the box was for the mjbots fdcanusb. That has now been upgraded so that Linux socketcan devices are supported out of the box as well!

You need version mjbots/moteus e33f188b035c7 or newer and for simple cases, no changes to source code are required at all.

For a long time, moteus has had a python library, that lets most people quickly develop motion control applications. However, python is not a suitable solution in every domain. Embedded systems often either don’t have access to python, or cannot tolerate the resource or timing penalties it imposes. In some cases, managing interoperability between python asyncio and systems using legacy python IO like ROS can be challenging. For others, python is just not familiar. The new C++ client library included in the moteus repository is designed to handle all of these scenarios with a flexible, yet ergonomic approach that makes simple things simple, and complex things possible.

For a while now moteus has had the ability to configure what action takes place upon a CAN message watchdog timeout during position control mode. If configured with ['servo.default_timeout_s'](https://github.com/mjbots/moteus/blob/main/docs/reference.md#servodefault_timeout_s) moteus requires that CAN messages be sent at a regular rate. If ever a message is delayed by more than the timeout period, the mode switches in a latching manner to the “timeout” mode, where a special action is undertaken. This is configured with ’servo.timeout_mode’ in tview, and as of firmware release 2023-07-25 the available values are as follows: