Telega v0 quick-start guide

[pavel-kirienko]

Introduction

This is a quick-start guide for motor controllers and motor control modules running the Telega v0 firmware. Zubax Robotics is committed to providing long-term support for Telega v0; however, new applications are recommended to use the next-generation firmware titled Telega v1 instead, as it comes with improved motor control algorithms based on Zubax Dyshlo — the most advanced motor control software library from Zubax Robotics (also available as a separate product). The documentation for Telega v1 is hosted on a separate website at telega.zubax.com.

Aside from utilizing the older (tried-and-true) motor control software, Telega v0 also lacks support for Cyphal — a modern network protocol that replaces its predecessors known as UAVCAN/DroneCAN. The differences between Cyphal and the prior art are outlined in the article “Cyphal vs. DroneCAN”.

To migrate from v0 to v1 or back, simply install the required firmware version using the standard firmware update procedure (the bootloader supports USB, UART, DroneCAN, and Cyphal with automatic protocol version detection). Beware that migration between v0⟷v1 or between any v0.x versions may cause the device configuration to be reset back to the factory defaults.

This document is valid for Telega v0.6+. The firmware binaries can be downloaded from https://files.zubax.com/products/com.zubax.telega/firmware/v0; the file extension is .application.bin.

Initial configuration

Telega v0 relies on a different configuration and diagnostic toolset than Telega v1. The recommended software is:

• Kucher for use with USB or UART interfaces.
• DroneCAN GUI Tool for use with the CAN bus interface.

To configure a Telega v0-based controller, one will need either a USB cable (if USB is available in the device), a UART cable (if UART is available), or a USB-CAN adapter like Zubax Babel.

Irrespective of the interface used, the configuration process amounts to the following steps:

1. Download your preferred software depending on the interface used as described above.
2. Connect the communication interface between your PC and the device.
3. Connect the motor controller to the power supply and to the motor (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.
4. Run the motor identification procedure.
5. If necessary, perform additional tuning as explained below — e.g., enable RCPWM, speed controller, etc.

Step 4 depends on which software is used. In the case of Kucher (USB or UART connection), please follow the instructions in the video:

In the case of the DroneCAN GUI Tool (or any other DroneCAN interface), the motor identification process is triggered by setting the parameter exec_aux_command to 1002:

Before starting the motor identification process, be sure to assign at least the following motor parameters:

• m.num_poles – the number of rotor poles (not pairs).
• m.max_current — maximum phase current amplitude [amperes].

Once the motor identification, it should be possible to spin the motor in the current or voltage control modes. Further configuration may be needed to achieve adequate performance or to enable the velocity control mode.

Motor control modes

Telega v0 features high efficiency and fast response, provided that the controller is configured properly. It supports the following three major motor control modes:

• Voltage control mode – in this mode, the controller modulates the specified quadrature axis voltage u_q, ignoring i_q. This mode imitates the behavior of a typical BLDC ESC.

• Current (torque) control mode – in this mode, the controller modulates the specified i_q. Since the torque of an electric motor is dependent (almost linearly) on the magnitude of the torque-generating current, this mode allows the controller to achieve nearly 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 with optional feed-forward terms) on top of the current control loop described earlier. This control mode is typically used for variable pitch drives or multirotor UAV drives.

Communication interfaces

The following interfaces are supported:

• Single or doubly-redundant CAN bus – UAVCAN aka DroneCAN. The DroneCAN GUI Tool might come in handy. Telega v0 supports automatic CAN bitrate detection and plug-and-play node-ID allocation. Automated ESC index assignment is not supported, it has to be set manually via uavcan.esc_index.

• Proprietary binary serial protocol over USB (CDC ACM) and UART. The protocol is built on top of Popcop; it features 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 Telega v0 via serial port.

• The industry-standard RCPWM, sometimes referred to as RC PWM or even RC PPM. Shall you choose to use it, you may need an adapter cable (shown below) that connects the GPIO pin of the Aux connector to an RCPWM-compatible header, as shown below.
  

  

Configuration parameters

In this section, we’re going to walk through some of the most important configuration parameters available in Telega v0. Most configuration parameters take effect virtually immediately or at the next use, so in most cases, it is not necessary to restart the device. Changes are committed to the non-volatile memory automatically within a few seconds after modification.

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 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 the controller 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 restarted. Restarting the 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.
• 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.flux_linkage - magnetic flux linkage in weber; measured automatically.
• m.resistance - phase resistance in ohm; measured automatically.
• m.induct_direct - direct axis phase inductance in henry; measured automatically.
• m.induct_quad - quadrature axis phase inductance in henry; 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.voltage_ramp - the maximum rate of change of the quadrature voltage setpoint (Uq), in volts per second. Generally, values above 10 V/s require a higher setting of m.current_ctl_bw, otherwise the stability can be compromised.
• m.eangvel_accel - 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_decel - 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 10000 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.eangvel_ctl_kd - D gain of the RPM PID controller. Units: ampere*second^2/electrical_radian.
• load.linear_coef, load.square_coef - linear and quadratic feed-forward terms of the PID+FF velocity controller; more on this later.
• m.current_ctl_bw - the bandwidth multiplier of the current control loop; unitless. At very high ramp settings, especially in the voltage control mode, this parameter should be increased in steps of 0.02. Generally, values up to 0.1 are safe.
• m.spup_curr_begn, m.spup_curr_end - spinup current, more on this later.

BEC

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

UAVCAN (DroneCAN)

All parameters in this group take effect after a reboot.

• uavcan.node_id - the node-ID. If set to zero, which is the default, Telega 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

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

RCPWM

All parameters in this group take effect when the RCPWM signal is connected, i.e. 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 (default)

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

This 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.

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, or if the motor phase currents or DC current are too high:
   1.1. decrease the parameter m.flux_linkage in 0.00001–0.0001 Wb steps;
   1.2. decrease observer parameters towards o.ekf.q_id = 10000 and o.ekf.q_iq = 30000 until a stable and smooth operation in all range of current setpoints is achieved.

2. If uncommanded speed variations or a general instability are observed, do the following:
   2.1 set the parameter o.ekf.q_eangvel to 3000000;
   2.2 if the previous operation didn’t help, decrease the parameters m.voltage_ramp and m.current_ctl_bw.

3. If you need to improve the step response characteristic in the voltage control mode, increase the parameters m.voltage_ramp up to 50 V/s and m.current_ctl_bw up to 0.1 in small steps.

4. If you need to tune Telega in the speed control mode, first of all, set the maximum speed for your application. Apply the minimal battery voltage to the ESC. Spin the motor up to maximum speed by sending a 100% setpoint in the Ratiometric Voltage Control mode or Ratiometric Current Control mode. Read the value of the parameter motor.electrical_angular_velocity and assign this value to the parameter m.max_eangvel. This change will ensure that the speed controller will never reach saturation in your application and the speed will be always controllable. After that, you should tune the speed controller.

Using Telega v0 in multirotor aircraft

By default, Telega’s control loops use fairly conservative settings, which may result in poor speed response characteristics. These settings are optimized for applications where fast response is not required by design (e.g. fixed-wing UAV or AUV). Other applications, such as multirotor aircraft, may require a faster response, in which case these settings will require adjustments.

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

• Set the acceleration rate to 15 000 ~ 100 000 electrical radian per second per second, depending on the needs of your application.
• Set the deceleration rate close to 10 000 ~ 50 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 (or whatever is the maximum peak phase current for your controller).
• Set the current ramp m.current_ramp to at least 2000 A/s or higher.
• Set the P and I gains of the PID controller (m.eangvel_ctl_kp, m.eangvel_ctl_ki) as described below; set the D gain (m.eangvel_ctl_kd) to zero.
• Set the linear feedforward coefficient load.linear_coef to zero, set the quadratic feedforward coefficient load.square_coef as described below.

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

where:

• RPM_M - 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:

where:

• A - current setpoint [ampere]
• K_p - proportional gain [ampere*second/electrical_radian]
• K_i - integral gain [ampere/electrical_radian]
• K_d - integral gain [ampere*second²/electrical_radian]
• n - sample index
• ω_E - electrical angular velocity [radian/second]
• Ω_E - electrical angular velocity setpoint [radian/second]
• T_PWM - PWM period [second]

The feedforward torque is computed as follows:

\tau_\text{ff} = \omega^2 c_2 + \omega c_1

Where \omega is the mechanical angular velocity in radian/second, c_1 is load.linear_coef, c_2 is load.square_coef.

The tuning amounts to setting three parameters: m.eangvel_ctl_kp, m.eangvel_ctl_ki, and load.square_coef. Initially, the I-gain should be set to zero and the P-gain should be increased until high-frequency oscillations have appeared. After that, the I-gain should be increased to achieve the first approximation of the desired response. This will allow the P-gain to be increased further; afterward, the feed-forward term should be introduced. The process then repeats iteratively until satisfactory response is achieved. There is a helpful spreadsheet that provides a decent starting point for choosing the settings (make a copy and edit that):

Telega v0.x velocity controller parameters calculator (not applicable to Telega...

Enter the required numbers and adjust the performance by changing the damping factor δ if necessary (if unsure, leave the default value). If you require any further guidance or if your propeller is not listed in the spreadsheet, please, reach out to us either via this forum or via support@zubax.com.

Using field weakening

Follow the instructions below to tune the field weakening controller.

1. Set the value of weakening current m.max_id_current = 20…40% of m.max_current.

2. Set the maximum allowable electrical angular velocity of the motor. For example, if you want to set the max speed to 6000 rpm, set m.max_eangvel = 6000/60 * m.num_poles * pi. In the field weakening mode, the ratiometric RPM control mode is used. The setpoint value is normalized to m.max_eangvel.

3. Enable the field weakening feature: ctl.field_weaken = true The field weakening mode will be automatically activated when the motor voltage is close to the operating voltage limit.

4. Tune the BEMF controller if there is poor response in the field weakening mode. Increase m.fw_bemf_ctl_ki and m.fw_bemf_ctl_kp.

5. If you are using the voltage control mode (uavcan.esc_rcm = 2 or rcpwm.ctl_mode = 2), there may be abrupt speed (thrust) variations at values close to the maximum speed when the field weakening mode is activated. If these variations are significant, it is recommended to use the ratiometric RPM control mode (uavcan.esc_rcm = 1 or rcpwm.ctl_mode = 1).

Spinup tuning

Starting the motor from a standstill is challenging for any sensorless drive; Telega is no exception.

When commanded to start the motor, Telega v0 activates the current control mode first, regardless of the commanded control mode - it will switch to the desired mode once the motor is started. The initial current setpoint is set to the value of m.spup_curr_begn, in amperes. Once the spinup process is initiated, Telega will ramp the current towards the second ramp endpoint defined by the parameter m.spup_curr_end. The duration of the ramp is defined by the parameter ctl.spinup_durat, in seconds; however, Telega 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 current ramp can be negative as well:

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

If the motor is already spinning when the ramp is activated, Telega 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 values of the initial current setpoint may, to some extent, interfere with this behavior.

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_curr_begn = 0.5 × m.max_current
• m.spup_curr_end = 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_curr_begn can be reduced as necessary. Usage of constant current ramps (i.e., when the endpoints are equal) is likely to lead to substandard performance and, therefore, not recommended because the rotor state observer requires some current gradient to deduce the initial position of the rotor.

Note that the following constraints must be met; otherwise, Telega may reject the configuration as invalid:

• m.spup_curr_begn ≤ m.max_current
• m.spup_curr_end ≤ m.max_current
• m.min_current < m.max_current
• 0.1 ≤ ctl.spinup_durat ≤ 60

Power balance explained

One possible source of confusion 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 P_DC is simply the product of DC voltage and DC current:

P_DC = U_DC I_DC

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

P_M = 3/2 U_Q I_Q ⇔ I_D = 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:

P_DC ≈ P_M ⇔ P_loss ≪ P_M

Therefore:

U_DC I_DC ≈ 3/2 U_Q I_Q ⇔ P_loss ≪ P_M, I_D = 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:

U_in I_in ≈ U_out I_out

Notice the similarity with the above equations.