StartProportionalToAngularPosition

class StartProportionalToAngularPosition(encoder: AbsoluteRotaryEncoder, powertrain: Powertrain, target_angular_position: AngularPosition, pwm_min_multiplier: float | int, pwm_min: float | None = None)

Bases: RuleBase

StartProportionalToAngularPosition object.

It can be used to make a gradual start of the powertrain’s motion, in order to avoid a peak in the powertrain’s DC motor absorbed electric current.

It computes a pwm to apply to the powertrain’s DC motor which increases linearly with the encoder’s target rotating object’s angular_position. The computed pwm starts from a minimum value, based on powertrain’s elements properties and pwm_min_multiplier or solely on pwm_min parameter. The computed pwm increases up to 1 when the encoder’s target’s angular_position equals target_angular_position.

Methods

apply()

It computes the pwm to apply to the powertrain motor, proportional to the encoder’s target angular_position until it reaches the target_angular_position.

Raises

TypeError

• If encoder is not an instance of AbsoluteRotaryEncoder,

• if powertrain is not an instance of Powertrain,

• if the first element in powertrain is not an instance of MotorBase,

• if an element of powertrain is not an instance of RotatingObject,

• if target_angular_position is not an instance of AngularPosition,

• if pwm_min_multiplier is not a float or an int,

• if pwm_min is defined and it is not a float or an int.

ValueError

• If powertrain.elements is an empty tuple,

• if the powertrain motor cannot compute electric_current property (DCMotor.electric_current),

• if pwm_min_multiplier is less than or equal to 1,

• if pwm_min is defined and it is negative or null.

See Also

DCMotor.pwm

apply() → None | float | int

It computes the pwm to apply to the powertrain motor, proportional to the encoder’s target angular_position until it reaches the target_angular_position.

Returns

float or int or None

PWM value to apply to the motor, proportional to the encoder’s target angular_position.

Notes

The powertrain’s motor has a minimum pwm which, as is, cannot be used to control the motor, since at this value the motor will remain still. So, in order to properly control the motor motion, it is required to apply a pwm greater than the minimum pwm, therefore the motor minimum pwm is multiplied by pwm_min_multiplier to get a starting pwm to be applied to the motor.

If the motor’s minimum pwm is null, then it is useless to multiply this value by pwm_min_multiplier in order to get a starting pwm; therefore, only in this case, pwm_min is directly used as starting pwm.

First of all, the rule computes a candidate minimum applicable pwm as:

\[D_{min}^c \left( T_l \right) = \frac{1}{\eta_t} \, \frac{T_l}{T_{max}} \, \frac{i_{max} - i_0}{i_{max}} + \frac{i_0}{i_{max}}\]

where:

• \(D_{min}^c\) is the candidate minimum applicable pwm,

• \(T_l\) is the load torque on the powertrain DCMotor.load_torque,

• \(T_{max}\) is the maximum torque developed by the powertrain DC motor (DCMotor.maximum_torque),

• \(i_{max}\) is the maximum electric current absorbed by the powertrain DC motor (DCMotor.maximum_electric_current),

• \(i_0\) is the no load electric current absorbed by the powertrain DC motor (DCMotor.no_load_electric_current),

• \(\eta_t\) is the powertrain overall efficiency, computed as:

\[\eta_t = \prod_{i = 1}^N \eta_i\]

where:

• \(\eta_i\) is the mechanical mating efficiency of the mating between two gears (SpurGear.master_gear_efficiency or HelicalGear.master_gear_efficiency or WormGear.master_gear_efficiency or WormWheel.master_gear_efficiency),

• \(N\) is the total number of gear matings in the powertrain.

If both the load torque on the powertrain DC motor \(T_l\) and the motor no load electric current \(i_0\) are null, then also the computed candidate minimum applicable pwm \(D_{min}^c\) is null. Only in this case, the computed candidate minimum applicable pwm is discarded and it is taken into account the pwm_min parameter, which must have been set (don’t used otherwise):

\[D_{min} = D_{min}^p\]

where:

• \(D_{min}\) is the minimum applicable pwm,

• \(D_{min}^p\) is the pwm_min parameter.

Otherwise, the candidate \(D_{min}\) is multiplied by the pwm_min_multiplier parameter.

\[D_{min} = D_{min}^c \, g\]

where \(g\) is the pwm_min_multiplier parameter.

Then it checks the applicability condition, defined as:

\[\theta \le \theta_t\]

where:

• \(\theta\) is the encoder’s target angular_position,

• \(\theta_t\) is the target_angular_position.

If the applicability condition is not met, then it returns None, otherwise it computes the pwm as:

\[D \left( \theta \right) = \left( 1 - D_{min} \right) \frac{\theta}{\theta_t} + D_{min}\]