First, if you haven’t already, check out these introductory posts:

• Part 1: Motivation
• Part 2: Auxiliary Port Configuration
• Part 3: Source Configuration
• Part 4: Sink Configuration

Second, this article is available in video form:

Third, the official reference documentation can be read here. This describes in detail all of the possible configuration values.

With those niceties out of the way, lets get into the examples!

1: Onboard AS5047P

This configuration is the default for moteus, and uses the onboard absolute AS5047P magnetic encoder for all positioning.

• Torque: Yes
• Velocity: Good
• Position: Good

Configuration: This is the default for moteus, so no configuration is required.

Discussion: This configuration provides a decent all-around compromise between complexity and performance. Torque control is available and velocity control is good outside of ultra-slow regimes. The position is absolutely known to within one rotation of the rotor, across power cycles.

2: Hall effects / hoverboard

Here, the built-in hall effect sensors from a brushless motor are connected to three pins on the ENC port (aux1). Hall effect sensors are sometimes the only sensored commutation method practical to integrate into a motor system, and are the most common means of providing commutation signals for things like hoverboard motors.

• Torque: Yes
• Velocity: OK
• Position: Incremental Only

Hardware: First, for moteus r4.8/11, either a Pico-SPOX 6 connector (TE 5-1775444-6) must be soldered onto the blank ENC pads of a moteus board or a cable must be soldered directly on to the pads. Then a matching cable harness must be constructed to mate the motor’s hall effect sensors to the Pico-SPOX connector (Housing: Molex 0874390601, Terminal: Molex 0874210100). If the sensors require 5V, then a boost regulator and level translators will be required. Otherwise, the 3.3V output of the ENC port can provide up to 100mA of power to the sensors, and their outputs should be connected to the C, K, and O pins (4, 5, and 6 on the connector).

Configuration: This example requires both configuration and alternate options specified duration calibration.

conf set aux1.spi.mode 1      # disabled
conf set aux1.pins.1.mode 6   # hall
conf set aux1.pins.1.pull 1   # pull-up
conf set aux1.pins.2.mode 6   # hall
conf set aux1.pins.2.pull 1   # pull-up
conf set aux1.pins.3.mode 6   # hall
conf set aux1.pins.3.pull 1   # pull-up

conf set aux1.hall.enabled 1  # enabled

conf set motor_position.sources.0.type 4   # hall

To calibrate, two additional options must be passed:

--cal-hall              # Instruct moteus_tool to use hall effects
--call-motor-poles 30   # How many motor pole pairs are present

Discussion: Performance-wise, this is a relatively poor option. Torque control is available, which is mostly what is used in hoverboard applications. Since the effective encoder resolution is very coarse, velocity control only works well at moderate to high speeds (say 0.3 Hz or higher). Position control is *not* absolutely referenced (i.e. it starts from 0 every time you power on) and it is only good to around 4 degrees for 30 pole pair hoverboard motors. With the current moteus configuration options, there is often jitter when stopped when using velocity or position control.

3: External AS5047P

This configuration can be used when the performance of the onboard AS5047P would be adequate, but for whatever reason, the moteus controller cannot be positioned immediately behind the sense magnet.

• Torque: Yes
• Velocity: Good
• Position: Good

Hardware: Like with the hall effect example, for moteus r4.8/11, this requires that a Pico-SPOX connector be populated on the ENC blank pads (TE 5-1775444-6) or that a cable be directly soldered to the pads. A cable must then be constructed to attach the external AS5047P to the mating Pico-SPOX connector (Housing: Molex 0874390601, Terminal: Molex 0874210100). All of the pins are required:

• G: Ground
• 3: 3.3V
• C: SPI chip select
• K: SPI clock
• I: SPI CIPO/MISO
• O: SPI COPI/MOSI

As the SPI lines are high frequency, they must be relatively short (<20cm), and mounted in such a way to avoid electrical interference. That may require shielding around the cable, or around portions of the mechanical assembly.

Configuration: The following configuration changes are necessary from a default setup:

conf set aux1.pins.0.mode 2   # spi_cs
conf set aux1.pins.1.mode 1   # spi
conf set aux1.pins.2.mode 1   # spi
conf set aux1.pins.3.mode 1   # spi
conf set aux1.spi.mode 2      # ext_as5047

Discussion: After the hardware has been constructed and the above configuration changes made, use and performance is identical to the onboard AS5047P configuration.

4: Sine / Cosine

Some absolute encoders emit their output in the form of two analog signals, the “sine” and “cosine”. For a given angle, each signal emits an analog voltage biased about a non-zero operating point based on its namespace. If the sine and cosine are 3.3V level, or can be downshifted using a resistive divider to fit within that range, then they can be used with moteus.

Hardware: Like with the hall effect example, for moteus r4.8/11, this requires that a Pico-SPOX connector be populated on the ENC blank pads (TE 5-1775444-6) or that a cable be directly soldered to the pads. A cable must then be constructed to attach the encoder to the mating Pico-SPOX connector (Housing: Molex 0874390601, Terminal: Molex 0874210100). The sine and cosine channels must be connected to one of:

• ENC pin 4 / K / aux1 pin 1
• ENC pin 5 / I / aux1 pin 2
• ENC pin 6 / O / aux1 pin 3

Any two of those may be used. The ground signal should be connected, and the 3.3V signal can be used to provide up to 100mA of power to the target encoder.

Configuration: The following configuration changes are required from a default setup:

conf set aux1.pins.1.mode 8           # sine
conf set aux1.pins.2.mode 9           # cosine
conf set aux1.spi.mode 1              # disabled
conf set aux1.sine_cosine.enabled 1   # enabled

The next value must be calibrated. The raw values of the sine and cosine channel can be observed in telemetry as the encoder rotates through several revolutions. Take the midpoint, and use it below:

conf set aux1.sine_cosine.common 1692  # from hand-calibration

Calibration requires no special options.

Discussion: As a sine/cosine encoder is just an alternate way of connecting a rotor absolute position sensor, the basic properties are the same as for the onboard AS5047P encoder. However, the analog signal has less effective resolution, and more noise than a digital encoder. Thus, the audible noise may be greater for a given selected encoder bandwidth, and the control performance may be worse.

5: Quadrature / Index (ABI)

A lowest common denominator of absolute encoders is the quadrature and index interface. Here, two digital signal lines step through a quadrature relationship as ticks on the encoder pass, and a separate “index” line becomes positive at the 0 point of the encoder. This does provide absolute positioning, but requires that the motor possibly spin through an entire rotation at power on in order to discover what that absolute position is.

• Torque: Yes
• Velocity: Good
• Position: OK

Hardware: Like with the hall effect example, for moteus r4.8/11, this requires that a Pico-SPOX connector be populated on the ENC blank pads (TE 5-1775444-6) or that a cable be directly soldered to the pads. A cable must then be constructed to attach the encoder to the mating Pico-SPOX connector (Housing: Molex 0874390601, Terminal: Molex 0874210100). The three signals can be connected to any of the following pins:

• ENC pin 2 / C / aux1 pin 0
• ENC pin 4 / K / aux1 pin 1
• ENC pin 5 / I / aux1 pin 2
• ENC pin 6 / O / aux1 pin 3

The ground signal should be connected, and the 3.3V pin may be used to provide up to 100mA of power to the target encoder.

Configuration: The following must be changed from default (assuming that the I pin is connected to K/ aux1 pin 1, and the two quadrature lines are connected to I / aux1 pin 2, and O / aux1 pin 3.

conf set aux1.pins.1.mode 7         # index
conf set aux1.pins.2.mode 4         # quad_sw
conf set aux1.pins.3.mode 4         # quad_sw

conf set aux1.spi.mode 1            # disabled
conf set aux1.quadrature.enabled 1  # enabled

Quadrature encoders have a rated cycles per revolution or counts per revolution. The counts per revolution is 4x the cycles per revolution, and is what moteus requires. The following configuration is suitable for a 1000 cycle per revolution or 4000 counts per revolution encoder.

conf set aux1.quadrature.cpr 20000
conf set motor_position.sources.0.type 3    # quadrature
conf set motor_position.sources.0.cpr 4000

Calibration requires no special options.

Discussion: This option can provide nominally the same performance as the onboard encoder with two caveats.

First, a “homing” step must be performed before control can begin. This means that actuating the motor must be possible without damage from the turn-on state, and not incompatible with the end application.

Second, it is possible for counts to be “missed” because of electrical interference. This can result in decreased performance or loss of control depending upon the severity. Proper routing and shielding of quadrature lines are essential to robust performance. The aux1.quadrature.error diagnostic field can be used to monitor for events that are consistent with electrical interference (it is normal to start at 1 at turn-on).

6: I2C Disambiguator

Often a motor controlled by moteus drives a gear reducer before eventually driving the output. In such cases, the onboard moteus encoder is not able to uniquely determine which sector the reducer output is located. One means of resolving that ambiguity is to place a low-rate absolute I2C based encoder on the output shaft.

Hardware: The only pins that support I2C on moteus r4.3/5/8/11 are the two data pins on the ABS port (a JST ZH-4 connector). A harness must be constructed to connect those two signal lines. On an unmodified board, 3.3V resistive pullups are hard-wired onto the board. If a 5V sensor is desired, either a boost regulator will be required to operate it from the ABS port power, or a separate 5V regulator will be necessary to power it.

• ABS pin 1 – 3.3V
• ABS pin 2 / aux2 pin 0 – SCL
• ABS pin 3 / aux2 pin 1 – SDA
• ABS pin 4 – GND

Configuration: Assuming an AS5048B encoder is attached, the following configuration changes are required:

conf set aux2.pins.0.mode 13        # i2c
conf set aux2.pins.1.mode 13        # i2c
conf set aux2.spi.mode 1            # disabled
conf set aux2.i2c.devices.0.type 1  # as5048

conf set motor_position.sources.1.aux_number 2
conf set motor_position.sources.1.type.i2c 7     # i2c
conf set motor_position.sources.1.i2c_device 0
conf set motor_position.sources.1.cpr 65536      # for the as5048
conf set motor_position.sources.1.reference 1    # output

Since two encoders must be correlated, the sign and offsets should be manually calibrated. Set them such that motor_position.sources.0.compensated_value in the diagnostics pane increases in the same direction for both and that it is 0 for both at the same position. Additionally, the gear box reduction ration needs to be set.

conf set motor_position.sources.1.sign 1           # hand-calibrated
conf set motor_position.sources.1.offset 0         # hand-calibrated
conf set motor_position.sources.0.offset 0         # hand-calibrated
conf set motor_position.rotor_to_output_ratio 0.5  # reduction ratio

Discussion: The control performance of this example is identical to that of the primary encoder in use, which here would be the onboard AS5047P. The advantage is that the absolute position of the output shaft is known exactly at power on, even with the reducing stage.

7: Onboard + Quadrature Output

For this example, a high resolution quadrature encoder is used in combination with the onboard encoder to improve the velocity and position tracking performance of the controller.

• Torque: Yes
• Velocity: Excellent
• Position: Excellent

Hardware: Since the onboard encoder is being used, the quadrature encoder must be connected to the 2 pins on the ABS port (aux2) using a JST ZH-4 connector.

• ABS pin 1 – 3.3V
• ABS pin 2 / aux2 pin 0 – Quadrature A
• ABS pin 3 / aux2 pin 1 – Quadrature B
• ABS pin 4 – GND

Configuration: This configuration assumes that a 5000 cycle per revolution / 20000 count per revolution encoder is being used. For that, the following changes must be made:

conf set aux2.spi.mode 1             # disabled
conf set aux2.pins.0.mode 4          # quad_sw
conf set aux2.pins.1.mode 4          # quad_sw
conf set aux2.quadrature.enabled 1   # enabled
conf set aux2.quadrature.cpr 20000

conf set motor_position.sources.1.aux_number 2
conf set motor_position.sources.1.quadrature 3    # quadrature
conf set motor_position.sources.1.cpr 20000

Since multiple encoders are being correlated, we need to manually inspect the motor_position.sources telemetry view to identify if both sources increase as the output is moved in the same direction. If not, then the sign of the quadrature source should be -1.

conf set motor_position.sources.1.sign -1

Finally, the output position is configured to be derived from the quadrature signal, with a reference source from the onboard encoder so that it starts at the correct absolution position.

conf set motor_position.output.source 1
conf set motor_position.reference_source 0

Discussion: For this example, a quadrature encoder of much higher resolution than the onboard encoder was selected. Thus the resulting control performance has improved control at very low speeds, and improved position stiffness at any speed. The relative performance gain is directly proportional to the increase in effective resolution.

8: RLS AksIM-2

The RLS AksIM-2 is an encoder that reads a ring with magnetic tracks encoded on it to produce high resolution absolute position. It can be used when a hollow shaft is desired, or when high performance velocity control or high stiffness position control is required.

• Torque: Yes
• Velocity: Excellent
• Position: Excellent

Hardware: moteus only supports the RS-422 asynchronous serial configuration of the RLS AksIM-2. The exact part numbers used in this demonstration are:

• MB049SFF17BDNT00 – encoder
• MRA049BG034DSN00 – magnetic ring
• ACC049 – development cable

It requires the two data pins on the ABS port of moteus r4.3/5/8/11. To use it, a RS-422 level transceiver is required. One option which has been demonstrated to work is the MAX3490. Additionally, the AksIM-2 requires 5V power, this can be provided via a boost regulator driven from the ABS port or a separate 5V regulator.

• ABS pin 1 – 3.3V
• ABS pin 2 / aux2 pin 0 – RX
• ABS pin 3 / aux2 pin 1 – TX
• ABS pin 4 – GND

Configuration: The required configuration is straightforward. This example will leave the onboard encoder configured, but it could also be disabled if not used. It also assumes that the AksIM-2 has been configured ahead of time (either at the factory or using RLS tools) to 1000000 baud.

conf set aux2.pins.0.mode 3   # uart
conf set aux2.pins.1.mode 3   # uart
conf set aux2.spi.mode 1      # disabled
conf set aux2.uart.mode 1     # aksim2
conf set aux2.uart.baud_rate 1000000

conf set motor_position.sources.1.aux_number 2
conf set motor_position.sources.1.type 2        # uart
conf set motor_position.sources.1.cpr 4194304   # 22 bits (for any AskIM-2)

conf set motor_position.commutation_source 1
conf set motor_position.output.source 1

Discussion: This example provides excellent control performance both at very low speeds, high position stiffness, and gives a hollow shaft capability. The primary downsides are complexity and cost. An active adapter is required, and in single unit quantities, the AksIM-2 and an encoder ring is more than twice as expensive than a moteus itself.

9: iC-Haus iC-PZ

The iC-Haus iC-PZ is a reflective optical encoder that reads a marked code ring. It is high resolution and accuracy and supports a number of communication interfaces. The only one that moteus supports currently is the SPI protocol.

• Torque: Yes
• Velocity: Excellent
• Position: Excellent

Hardware: Like with the hall effect example, for moteus r4.8/11, this requires that a Pico-SPOX connector be populated on the ENC blank pads (TE 5-1775444-6) or that a cable be directly soldered to the pads. A cable must then be constructed to attach the external AS5047P to the mating Pico-SPOX connector (Housing: Molex 0874390601, Terminal: Molex 0874210100).

Additionally, while the iC-PZ can provide 3.3V compatible I/O pins, and thus no SPI level translation is required, it also requires a 5V supply. Thus either a boost regulator is required to use the ENC port provided 3.3V power, or a separate 5V supply is needed.

All of the pins are required:

• G: Ground
• 3: 3.3V
• C: SPI chip select
• K: SPI clock
• I: SPI CIPO/MISO
• O: SPI COPI/MOSI

Configuration: The iC-PZ requires a moderate amount of provisioning before it will produce usable values. While it is possible to do so using only diagnostic mode commands with moteus, the process is involved enough that it is not recommended. Instead, this configuration assumes that the encoder has been provisioned using the iC-Haus tools first.

conf set aux1.pins.0.mode 2  # spi_cs
conf set aux1.pins.1.mode 1  # spi
conf set aux1.pins.2.mode 1  # spi
conf set aux1.pins.3.mode 1  # spi

conf set aux1.spi.rate_hz 6000000
conf set aux1.spi.mode 3           # ic_pz

conf set motor_position.sources.0.cpr 16777216   # 24 bits

Discussion: The iC-PZ provides the same benefits as the RLS AksIM-2 above in terms of improved control performance and hollow shaft capability. It still requires adapter hardware with moteus, although the required hardware is slightly less complex than with the AksIM-2. Also, it is lower cost, but does require a more complex provisioning stage and optical cleanliness.

10: Fixed Voltage

Sometimes you can’t fit an encoder into a design, but you still want low speed operation. For those cases, moteus can be configured to drive a brushless motor as if it were a stepper motor with micro-steps. This means that there is no velocity or position feedback, and the motor will constantly dissipate a roughly fixed power, even when stationary or unloaded.

• Torque: No
• Velocity: Poor
• Position: Poor / Incremental Only

Hardware: No additional hardware is required.

Configuration: Auto-calibration is not possible in this mode, but the required configuration is minimal. The number of pole-pairs must be entered manually if the output is to be scaled correctly, and the fixed control voltage must be specified by the designer. A larger fixed voltage will dissipate more power but provide more holding torque.

conf set motor.poles 14   # the number of pole-pairs for the motor

conf servo.fixed_voltage_mode 1         # enabled
conf servo.fixed_voltage_control_V 0.3  # selected by the designer

Discussion: In most cases where you want to drive a motor in a stepper like manner, a dedicated stepper driver is more appropriate. However, if you already have multiple moteus controllers in your system, or you want to use the advanced trajectory controls, this might be a valid design choice.

11: GPIO

Any of the pins on any connector can be used for 3.3V digital input or output. Some pins can be used for 3.3V analog input, and some can be used for 5V digital input. A dedicated “function” on the aux port is not required, so any pins which are not otherwise needed for a function can be so configured.

Hardware: moteus does not require any specific hardware, although if you want to use a given digital input or output to do something, you will likely need to construct at a minimum a harness to connect it to one of the ENC or ABS ports.

Configuration: Each pin can be configured independently:

conf set aux2.pins.0.mode 14    # digital input
conf set aux2.pins.1.mode 15    # digital output
conf set aux1.pins.2.mode 16    # analog input

Discussion: Once configured, the digital readings from each pin are accessible in the auxN.pins diagnostic mode tree and by using the 0x05e or 0x05f register mode registers as 7 bit integer bitfields.

Writing to the digital outputs can be conducted with the diagnostic protocol as follows

aux1 out 33   # a decimal bitfield

or by using register mode registers 0x05c / 0x05d.

Finally, analog inputs can be read in the diagnostic tree at aux1.analog_inputs, and in register mode at registers 0x060 – 0x06c.

Conclusion

While the flexible I/O subsystem already enables a lot of new configurations for moteus, keep on the lookout as it makes even more things feasible in the future!