Quick start guide for Myxa v0.1


(Pavel Kirienko) #1

This post is a tentative quick start guide for Myxa motor controllers. It assumes that the user has a GNU/Linux enabled PC; support for Windows is going to be added pretty soon as well. If you have any questions or concerns, please send us an email to info@zubax.com, or post right here in the comments.

The user is advised to have a basic understanding of the field-oriented motor control theory.

Overall, the setup procedure is as follows:

  1. Configure the USB connection.
  2. Download the Kucher GUI tool.
  3. Connect the motor to Myxa (if you need to reverse the direction of rotation later, swap any two phases). The motor should be disconnected from any mechanical load (propellers, thrusters, gearboxes, etc), otherwise, the automatic motor identification procedure may return suboptimal results. You must not touch the motor while identification is in progress for the same reason.
  4. Connect Myxa to a power supply, and then to your PC via USB.
  5. Launch Kucher, specify the number of poles and the rated current of the motor. Launch the motor ID procedure.

That’s it. Should be pretty straightforward to get started. Please see the following video for a more hands-on guidance:

Geometry and connectors

The images below document the placement and pinout of on-board connectors:

Bare board geometry:

Aluminum enclosure geometry:

(Pavel Kirienko) #2

Okay, continuing with the quick start guide here.

Motor control modes

Myxa implements an advanced field-oriented motor control algorithm that features high efficiency and fast response, provided that the controller is configured properly. Myxa supports the following three major motor control modes:

  • Voltage control mode – in this mode, the controller modulates the specified quadrature axis voltage Uq, ignoring the quadrature axis current Iq, while maintaining the direct axis current Id close to zero. This mode imitates the behavior of a typical BLDC ESC. Its use is generally discouraged since it does not permit the drive to maintain stability under certain operating conditions.

  • Current (torque) control mode – in this mode, the controller modulates the specified quadrature axis current Iq, while maintaining the direct axis current Id close to zero. Since the torque of an electric motor is linearly dependent on the magnitude of the torque-generating current (i.e. the quadrature axis current Iq), this mode allows the controller to achieve constant torque irrespective of the angular velocity of the rotor (until the voltage modulator is saturated). This, in turn, can be used to modulate a nearly-constant thrust if the controller is used to drive a propeller or some other thruster.

  • Velocity control mode – in this mode, the controller runs an angular velocity control loop (which is based on a simple PI controller) on top of the current control loop described earlier. The controller maintains the requested velocity by regulating the torque. This control mode is typically used for variable pitch drives or multirotor UAV drives. This control mode is selected by default.

Some theory on motor control in the context of simple BLDC drives can be found in the Sapog Reference Manual.

Communication interfaces

The following interfaces are supported:

  • Single or doubly-redundant CAN busUAVCAN. The UAVCAN GUI Tool might come in handy. The implementation of UAVCAN in Myxa is largely equivalent to that in Sapog, so please refer to the Sapog Reference Manual for an in-depth description. The only major difference is that Myxa does not support automated ESC index assignment - it has to be configured manually.
  • Proprietary binary serial protocol over USB and UART. The protocol is built on top of Popcop; it features a strong data integrity protection and resilience to packet losses. This protocol is leveraged by the Kucher GUI tool; as Kucher is open source, you are encouraged to use it as an example and reference for building your own applications that interact with Myxa.
  • The industry-standard RCPWM, sometimes referred to as RC PWM or even RC PPM. This interface is flawed in many ways, so we generally discourage its use. Shall you choose to use it, you will need an adapter cable (shown below) that connects the pin GPIO1 of the Aux connector on Myxa to an RCPWM-compatible header as shown below.

(Pavel Kirienko) #3

Integration instructions for Myxa are not yet written; however, we have them for Sapog, and seeing as Myxa’s communication interfaces are largely similar to those in Sapog, we suggest our early customers to refer to the following guides, keeping in mind the differences in configuration parameters, which we’re going to review here next: https://kb.zubax.com/x/cYAh.

Configuration parameters

In this section, we’re going to walk through some of the most important configuration parameters available in Myxa. Most configuration parameters take effect virtually immediately or at the next use, so in most cases, it is not necessary to restart Myxa.

Common abbreviations:

  • eangvel - electrical angular velocity; always in electrical radian/second.
  • ctl - control.
  • ttl - time-to-live - the amount of time between the last command received from the given interface until the motor is stopped automatically.

Motor control

Motor control parameters are contained in the section m; for example, m.max_current. Some of the parameters in this section are deduced by Myxa automatically if they are not provided by the user. It is, therefore, necessary to reset all of the parameters in the group if you’re switching Myxa to a different motor; otherwise, the auto-deduced parameters will keep their old values.

All parameters in this group take effect when the motor is started or re-started. Restarting the whole device is not necessary.

  • m.num_poles - the number of magnetic poles on the rotor; equals the number of magnets on the rotor; always an even number.
  • m.max_current - rated phase current of the motor, in amperes (more on this later).
  • m.min_current - minimum current at which sufficiently stable operation of the drive is guaranteed. Deduced automatically from the previous parameter; can be changed by the user if necessary. You should lower this value if your application requires low-speed operation.
  • m.phi_milliweber - magnetic flux linkage in milliweber; measured automatically.
  • m.rs_ohm - phase resistance in ohm; measured automatically.
  • m.ld_microhenry - direct axis phase inductance in microhenry; measured automatically.
  • m.lq_microhenry - quadrature axis phase inductance in microhenry; measured automatically.
  • m.min_eangvel - minimum electrical angular velocity, in electrical radian/second, at which sufficiently stable operation of the drive is guaranteed. You should lower this value if your application requires low-speed operation.
  • m.max_eangvel - maximum rated electrical angular velocity, in electrical radian/second. Raise this value if the motor does not reach required speed levels in the RPM control mode.
  • m.current_ramp - the maximum rate of change of the quadrature current setpoint (Iq), in amperes per second.
  • m.eangvel_rampup - the maximum permitted acceleration, in electrical radian per second per second. It is likely that this value will need to be increased for multirotor drives.
  • m.eangvel_rampdn - the maximum permitted deceleration, in electrical radian per second per second. It is likely that this value will need to be increased for multirotor drives. Do not exceed 5000 radian/second^2.
  • m.eangvel_ctl_kp - P gain of the RPM PID controller. Units: ampere*second/electrical_radian.
  • m.eangvel_ctl_ki - I gain of the RPM PID controller. Units: ampere/electrical_radian.
  • m.current_ctl_bw - the bandwidth multiplier of the current control loop; unitless.


There is only one parameter in this group; it is valid only for Myxa B: bec.can_pwr_on. It defines whether the BEC (battery elimination circuit) power output is enabled or not. The parameters takes effect immediately.


All parameters in this group take effect after a reboot.

  • uavcan.node_id - the UAVCAN node ID. If set to zero, which is the default, Myxa will attempt dynamic node ID allocation.
  • uavcan.esc_index - the index of this ESC on the vehicle. Set to zero by default; must be configured manually.
  • uavcan.esc_ttl - deadman switch timeout, in seconds.
  • uavcan.esc_rcm - RCM stands for “ratiometric control mode”. This setting defines which control mode to use when interpreting the message uavcan.equipment.esc.RawCommand:
    • 0 - current control mode
    • 1 - RPM control mode
    • 2 - voltage control mode (not recommended)

Beware that Myxa does not support automated ESC index assignment. The parameter uavcan.esc_index must be configured manually.


All parameters in this group take effect when the RCPWM signal is connected, i.e. in order to apply new parameters, disconnect the RCPWM cable from the device and then connect it back at least 0.1 seconds later. An exception is rcpwm.enable - out of safety considerations, this parameter takes effect only after reboot.

The basics of RCPWM are explained in the relevant section of the Sapog reference manual, and some useful information is also provided on Wikipedia.

  • rcpwm.enable - whether to enable the RCPWM interface. Requires reboot.
  • rcpwm.pulse.bot - minimum duration of the RCPWM pulse, in seconds.
  • rcpwm.pulse.mid - duration of the RCPWM pulse that is treated as a zero setpoint, in seconds; i.e. the motor will be stopped.
  • rcpwm.pulse.top - the maximum duration of the RCPWM pulse, in seconds.
  • rcpwm.ttl - deadman switch timeout, in seconds.
  • rcpwm.ctl_mode - which control mode to use with RCPWM:
    • 0 - current control mode
    • 1 - RPM control mode
    • 2 - voltage control mode (not recommended)

By default, the range parameters are set up as follows:

  • rcpwm.pulse.bot - 1 ms
  • rcpwm.pulse.mid - 1.5 ms
  • rcpwm.pulse.top - 2 ms

Which implies that the motor will be stopped when the pulse is 1.5 ms long; run forward if the pulse is longer than that, and reversed if the pulse is shorter than that. In order to configure unidirectional operation, set rcpwm.pulse.mid to 1 ms.

(Dmitry Ramensky) #4

Advanced tuning

In certain scenarios, with some motors, manual tuning of the control system may be required in order to achieve optimal performance.

  1. Run the motor with a load attached in the current control mode. Increase the current setpoint until the motor stops accelerating. Decrease the current setpoint a bit and ensure that the drive operates stably. If the motor speed is not stable or if the motor is restarting repeatedly, decrease the parameter m.phi_milliweber in 0.01–0.1 mWb steps. If it doesn’t help, decrease m.current_ctl_bw in 0.001 steps until a stable and smooth operation in all range of current setpoints is achieved.
  2. Run the motor with a load attached in the speed control mode. Apply different setpoints. If a faster speed response is desired, increase the parameters m.eangvel_ctl_kp and m.eangvel_ctl_ki, following the conventional PID tuning procedure.

(Rick) #5

Is it recommended to perform the motor identification for every motor, or can the parameters be reused for motors of the same type? Assuming the motor manufacturer has reasonably good quality control.

(Pavel Kirienko) #6

@Anubis it is not necessary to perform motor identification per every motor if motor parameter variations do not exceed the following limits:

Parameter Deviation
Flux linkage 0.3%
Inductance 1%
Resistance 1%

Some decent motors may not require identification at all (e.g. Maxon, Anaheim), you can just copy-paste the motor parameters from the datasheet provided by the vendor. Low-cost motors and motors with poor repeatability (e.g. T-Motor, Tarot, KDE, Scorpion, and so on) always require identification for every motor.

(Pavel Kirienko) #7

Using Myxa in multirotor aircraft

By default, Myxa’s control loops use fairly conservative settings which result in slow speed response characteristics. These settings are optimized for applications where fast response is not required by design (e.g. electric aircraft and submarines). Other applications, such as multirotor aircraft, may require faster step response, in which case Myxa’s settings will require adjustments.

In order to improve the step response characteristics of the speed control loop, perform the following adjustments:

  • Set the acceleration rate to 10 000 ~ 15 000 electrical radian per second per second, depending on the needs of your application.
  • Set the deceleration rate close to 10 000 electrical radian per second per second or lower (higher values should be avoided).
  • Set the maximum current to 1.5 times of the maximum continuous current of the motor, but not higher than 40 A.
  • Increase the P gain of the speed controller (more info below).
  • Increase the I gain of the speed controller (more info below).

The relationship between electrical angular velocity and mechanical RPM is defined as follows:

  • RPMM - mechanical RPM,
  • ωE - electrical angular velocity, in radian per second,
  • P - number of rotor poles.

The transfer function of the speed PID controller can be approximated as follows:


  • A - current setpoint [ampere]
  • Kp - proportional gain [ampere*second/electrical_radian]
  • Ki - integral gain [ampere/electrical_radian]
  • Kd - integral gain; always zero in firmware v0.1 (available in later versions)
  • n - sample index
  • ωE - electrical angular velocity [radian/second]
  • ΩE - electrical angular velocity setpoint [radian/second]
  • TPWM - PWM period [second]

The standard PID tuning principles apply. Generally, the proportional gain should be increased until a satisfactory short-term performance of the controller is achieved. After that, the integral gain should be increased until the convergence is satisfactory yet the system doesn’t trigger self-induced oscillations. The response of a generic PID controller to Kp and Ki is shown on the images below, respectively.


(Pavel Kirienko) #8

Spinup tuning

Starting the motor from standstill is challenging for any sensorless drive, Myxa is no exception.

When commanded to start the motor, Myxa activates the current control mode first, regardless of the commanded control mode - Myxa will switch to the desired mode once the motor is started. The initial current setpoint is set to the value of m.spup_current_l, in amperes, where l stands for “low”. Once the spinup process is initiated, Myxa will slowly ramp the current towards the second ramp endpoint defined by the parameter m.spup_current_h. The duration of the ramp is defined by the parameter ctl.spinup_durat, in seconds; however, Myxa can abandon the ramp early and switch to the normal operating mode if it deems so appropriate. The ramp is illustrated in the following figure:

The ramp can be negative as well:

Myxa will abandon spinup and restart from scratch if the motor did not reach stable operation by the end of the ramp.

Observe also that if the motor is already spinning when the ramp is activated, Myxa will detect that, and skip the ramp, switching to the normal operating mode immediately. This behavior ensures that the motor can be restarted quickly and reliably if the rotor is already spinning in the correct direction. However, high settings of the initial current setpoint can somewhat interfere with this behavior.

In the firmware v0.1, the default values are set as follows (the defaults are likely to change in future releases):

  • ctl.spinup_durat = 1.5
  • m.spup_current_l = 2 × m.min_current = 0.05 × m.max_current
  • m.spup_current_h = 0.5 × m.max_current

If the motor does not spin up sufficiently quickly, or if the rotor freezes for a few seconds before starting, it is recommended to alter the configuration parameters as follows:

  • ctl.spinup_durat = 0.5
  • m.spup_current_l = 0.5 × m.max_current
  • m.spup_current_h = 0.05 × m.max_current

The proposed configuration defines a reverse (negative) current ramp. If the motor overshoots to a high speed after spinup and it is considered unacceptable, the initial current value m.spup_current_l can be reduced as necessary. Usage of constant current ramps (i.e. when both endpoints are equal) is likely to lead to substandard performance and therefore not recommended, because the rotor state observer requires some current gradient in order to deduce the initial position of the rotor.

Note that the following constraints must be met, otherwise Myxa will reject the configuration as invalid:

  • m.spup_current_lm.max_current
  • m.spup_current_hm.max_current
  • m.min_current < m.max_current
  • 0.1 ≤ ctl.spinup_durat ≤ 60

(Pavel Kirienko) #9

Power balance explained

A popular source of confusion when using Telega (or vector control drives in general) is the complicated relationship between the DC link current (the current that flows between the battery and the motor controller) and the phase current (between the controller and the motor).

Reviewing the system in terms of power conversions helps to eliminate the confusion.

The DC input power PDC is simply the product of DC voltage and DC current:


The active power delivered to the motor can be expressed in terms of the rotating DQ system quantities (simplified, ideal conditions assumed):

PM = ⅔ UQ IQ ⇔ ID = 0

The reactive power is not of interest in this case, so it can be ignored safely.

In general, assuming negligible losses, the following holds true:

PDC ≈ PM ⇔ Ploss ≪ PM


UDC IDC ≈ ⅔ UQ IQ ⇔ Ploss ≪ PM, ID = 0

It is also helpful to mentally picture the motor controller as a step-down DC-DC converter on steroids; for a DC-DC converter the following is valid:

Uin Iin ≈ Uout Iout

Notice the similarity with the above equations.