HAL Components on STMBLv5 Documentation

Mon, 01 Jan 0001 00:00:00 +0000

ACIM_FLUX #

Brief #

The acim_flux component models the rotor flux of an induction motor in the rotor flux frame and gives the slip that keeps that frame oriented.

Model #

With i_mr the magnetizing current behind the rotor flux (psi_r = Lm * i_mr):

tr * d(i_mr)/dt = id - i_mr slip = iq / (tr * i_mr) [rad/s electrical] torque = 3/2 * pp * lmr * i_mr * iq lmr = Lm^2 / Lr

Mon, 01 Jan 0001 00:00:00 +0000

ACIM_FOC #

Brief #

The acim_foc component turns a torque command into d and q current commands for an induction motor in the rotor flux frame, using the flux model of acim_flux.

Behaviour #

d: id_n * scale (scale from acim_fw, 1 below the corner), reached at id_rate A/s from 0 at every enable, so the bridge never steps the full magnetizing current into one leg.
Torque is held at 0 (ready = 0, t_max = 0) until i_mr has reached 90% of the d command once; after that ready stays 1 until the next disable.
q: torque / (3/2 * pp * lmr * i_mr), limited so |i| stays within max_cur with d taking priority.
Flux boost (optional, k_boost > 0): while the flux is below the ramped d command, d gets k_boost * (d - i_mr) on top, so i_mr rises in about tr / (1 + k_boost) instead of tr: faster torque after field weakening and a shorter magnetizing at enable. Only upward; going into field weakening is not sped up, so the acim_fw loop keeps its gain. The boost only takes current q does not need: |d| <= sqrt(max_cur^2 - q^2), and with boost_max > 0 never more than boost_max * id_n on top of d (0.3 keeps the enable peak near the current limit).
t_max: torque the current limit allows at the present flux, capped by acim_fw’s t_lim when that is nonzero. Link pid0.max_torque and pid0.neg_min_torque to it.

Pins #

Name	Description
en	input, fault0.en_out
torque	input, torque command [Nm]
scale	input, flux fraction from acim_fw, 1 = rated
t_lim	input, torque limit from acim_fw [Nm], 0 = none
i_mr	input, magnetizing current from acim_flux [A]
id_n	parameter, rated magnetizing current [A peak]
id_rate	parameter, d current ramp [A/s]
max_cur	parameter, current limit [A peak]
lmr	parameter, Lm^2/Lr [H]
polecount	parameter, pole pairs
k_boost	parameter, flux boost gain, 0 = off
boost_max	parameter, largest boost as a fraction of id_n, 0 = only the current limit
d_cmd	output, to hv0.d_cmd
q_cmd	output, to hv0.q_cmd
t_max	output, available torque [Nm]
t_min	output, -t_max
ready	output, 1 = magnetized, torque allowed
boost	output, d current added by the flux boost [A]

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

ACIM_FW #

Brief #

The acim_fw component is the induction motor’s field weakening: it lowers the flux command (scale, 1 = rated flux) to hold the modulation duty at duty_setpoint, and gives a constant power torque limit t_lim.

This is acim_ttc’s regulator on its own. duty unlinked reads 0, so scale sits at 1 and there is no field weakening, which is stmbl’s default; linking acim_fw0.duty = hv0.duty is the machine builder’s choice.

Mon, 01 Jan 0001 00:00:00 +0000

ACIM_TTC #

Brief #

The acim_ttc component is responsible for controlling an AC Induction Motor (ACIM) using Torque and Flux control strategies. It reads motor parameters and control settings, calculates derived parameters, updates the control algorithm in real-time, and supports different operating modes. The component ensures that the motor operates within safe and efficient boundaries by adjusting the velocity, position, and torque limits accordingly.

Component Explanation #

The acim_ttc component is designed for controlling an AC Induction Motor (ACIM) using Torque and Flux control strategies. This component operates within a hardware abstraction layer (HAL) framework, providing real-time control and non-real-time initialization functions.

Mon, 01 Jan 0001 00:00:00 +0000

ADC #

Brief #

adc (F4 logic board) converts the raw sin/cos samples of the two feedback connectors, which the ADCs capture by DMA, into scaled sin/cos values for the feedback components, and can stream the raw samples to Servoterm as a scope. The feedback templates wire it, e.g. conf/template/res_fb0.txt (res0.sin = adc0.sin0, res0.cos = adc0.cos0, res0.quad = adc0.quad, adc0.res_mode = res0.res_mode) and conf/template/enc_fb0.txt (enc_fb0.sin = adc0.sin0l, enc_fb0.cos = adc0.cos0l, enc_fb0.amp = adc0.amp0).

Mon, 01 Jan 0001 00:00:00 +0000

AND #

Brief #

and is a four input logic AND. F4 component, used e.g. in conf/bene_sanyo.txt.

Component Explanation #

Output (rt):

out = 1 if all of in0..in3 are > 0, otherwise 0.
Unused inputs default to 0, so they must be set to 1 (e.g. and0.in3 = 1).

Pins #

Name	Description
in0	input, Logic input, true if > 0
in1	input, Logic input, true if > 0
in2	input, Logic input, true if > 0, set to 1 if unused
in3	input, Logic input, true if > 0, set to 1 if unused
out	output, 1 if all inputs are > 0

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

ANGLE #

Brief #

The angle component owns the commutation angle and the synchronous electrical speed sent to hv0 (hv0.pos, hv0.vel), for every motor type.

Sources (`src`) #

0 feedback: pos = pos_fb, vel = vel_fb. A pure pass-through, used by the PMSM templates (pos_fb = vel2.pos_out or pmsm_ttc0.pos_out, vel_fb = vel2.vel).
1 feedback plus slip: pos = pos_m * polecount + integral of slip, vel = vel_m * polecount + slip. Indirect field orientation for an induction motor on an encoder: pos_m is the mechanical rotor angle, vel_m the mechanical rotor speed, slip comes from acim_flux. The angle is built from the encoder, not from vel_m, so the lag of a speed estimate during a ramp does not show up as a lower slip.
2 observer: pos = pos_obs, vel = vel_obs.
3 open loop: vel = vel_cmd (electrical), pos integrates it. V/f and I/f.

Switching into an integrating source (1, 3) starts from the current angle, so the switch itself does not move the field. Switching into 0 or 2 takes the source’s angle as is; a sequencer that switches onto the observer is expected to do it once the observer has locked.

Mon, 01 Jan 0001 00:00:00 +0000

AVG #

Brief #

avg scales and offsets a signal and low pass filters it (first order). F4 component, typically used to turn an analog spindle speed input into a velocity command, e.g. avg0.mult = 0.1047 (rpm to rad/s), ramp0.vel_ext_cmd = avg0.out.

Component Explanation #

Output (rt):

out = LP(in * mult + offset) // first order low pass at lpf Hz

Until mult is set the output is only offset.

Pins #

Name	Description
in	input, Signal
out	output, Filtered in * mult + offset
lpf	parameter, Filter cutoff (Hz), default 100
mult	parameter, Multiplier, no default (0)
offset	parameter, Offset added after mult, default 0

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

BIQUAD #

Brief #

biquad is a second order filter for a command signal, typically a notch on the torque command at a mechanical resonance. conf/template/filters.txt loads it (opt-in, link filters after link pmsm) between pid0 and dob0, passing through (type 0) until set. The wiring, by hand or as in the template:

biquad0.in = pid0.torque_cmd
pmsm_ttc0.torque = biquad0.out (the template: dob0.in = biquad0.out)
biquad0.rt_prio = 8.3 (after pid0, before dob0 and the torque controller)

frf (conf/template/id_frf.txt) goes after biquad0 when both are loaded.

Mon, 01 Jan 0001 00:00:00 +0000

CONF #

Brief #

conf has no code: it is a set of named parameter pins that hold the motor, feedback, limit and tuning values of a drive in one place. A motor config sets them (conf/template/conf.txt shows the defaults a new config starts from, e.g. conf0.r = 1, conf0.max_ac_cur = 6), and the templates link them to the components that use them, e.g. hv0.r = conf0.r, pid0.pos_bw = conf0.pos_bw, fault0.max_dc_volt = conf0.max_dc_volt, fb_switch0.mot_offset = conf0.mot_fb_offset.

Mon, 01 Jan 0001 00:00:00 +0000

CURPID #

Brief #

curpid is the d/q current controller. From a d/q current command and the measured d/q currents it computes the d/q voltages with a PI controller plus resistance, back EMF and cross coupling feed forward and a predictor for the PWM delay. It also limits the current command to max_cur. In voltage mode it passes the command through as a voltage. It runs on the F3 (HV board) as curpid0, loaded by stm32f303/src/main.c (rt_prio 3). There all its inputs come from ls0 (the F4’s command and motor config) and dq0 (measured currents), and ud/uq go to idq0. No F4 template loads it.

Mon, 01 Jan 0001 00:00:00 +0000

DC_LIMITS #

Brief #

dc_limits is the brushed DC motor version of pmsm_limits: it estimates the armature current and torque that can be reached with the available voltage, at standstill, at the present velocity and within the next control period. It is compiled into the F4 firmware.

Component Explanation #

All work is done in rt. Inputs are clamped to lq >= 0.0001, psi >= 0.01, r >= 0.001. The back EMF is indq = vel * psi and volt = ac_volt.

Mon, 01 Jan 0001 00:00:00 +0000

DC_TTC #

Brief #

dc_ttc (torque to current) converts a torque command (Nm) into an armature current command (A) for a brushed DC motor. It runs on the F4 board and is loaded by conf/template/dc.txt: dc_ttc0.torque = pid0.torque_cmd, dc_ttc0.psi = conf0.psi, hv0.q_cmd = dc_ttc0.cur with hv0.phase_mode = 3 (DC output) and hv0.cmd_mode = 1 (current mode).

Component Explanation #

Conversion (in rt): cur = torque / psi, with psi (equal to the back EMF constant in V/(rad/s)).

Pins #

Name	Description
psi	parameter, Torque constant (Nm/A), min 0.001
torque	input, Torque command (Nm)
cur	output, Current command (A)

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

DEBOUNCE #

Brief #

debounce filters a logic signal with an integrating timer, so short pulses are ignored. F4 component, used in conf/wobl.txt (fault0.en = debounce0.out).

Component Explanation #

Timer (rt):

timer counts up by the period while in > 0 and down otherwise.
When timer exceeds debounce_time, out becomes 1 (and timer is clamped to debounce_time). When timer reaches 0, out becomes 0.
The delay is the same for both edges; short glitches only move the timer and do not change out.

Pins #

Name	Description
in	input, Logic input, true if > 0
out	output, Debounced output
debounce_time	parameter, Debounce time (s), default 0
timer	output, Debounce timer (internal state, s)

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

DMM #

Brief #

dmm reads the absolute position of a DMM servo motor encoder that streams its angle continuously over RS485 into the fb0 connector of the F4 logic board. conf/template/encdmm_fb0.txt loads it and wires fb_switch0.mot_pos = dmm0.pos, fb_switch0.mot_abs_pos = dmm0.pos, fb_switch0.mot_state = 3, fault0.mot_fb_error = dmm0.error and io0.fb0y = dmm0.error.

Component Explanation #

Receiver (hw_init):

USART6 in half-duplex mode on PC6 at 1.875 Mbaud 8N1, the fb0 transmitter (PD15) is switched off, so the drive only listens. DMA2 stream 1 writes the incoming bytes into a 15 byte circular buffer.

Frame format:

A frame has 4 bytes. Byte 0 holds the MSBs of the other three bytes (bits 0..2), 4 bits F (unused here) and a 0 in bit 7; bytes 1..3 carry 7 data bits and a 1 in bit 7.
Byte 1 + MSB = angle high byte, byte 2 + MSB = angle low byte, byte 3 + MSB = CRC-8 (polynomial x^8 + x^3 + 1) over the 16 bit angle.

Decoding (rt):

From the current DMA write position, the component looks for a valid frame starting 7, 8, 9 or 10 bytes back (the newest 3 bytes are skipped because they may belong to an incomplete frame). A frame is valid if the CRC and the four framing bits match.
On success pos = angle * 2 * pi / 65536 - pi (rad, one turn = 16 bit) and error = 0; if no valid frame is found error = 1 and pos keeps its last value.

The receive buffer is never cleared (see the TODO in rt). If the encoder stops sending, the last valid frame stays in the buffer and error stays 0 with a frozen pos, so a cable break is not detected. dmm and usart both use USART6 and DMA2 stream 1 and cannot be loaded together.

Mon, 01 Jan 0001 00:00:00 +0000

DOB #

Brief #

dob is a disturbance (load torque) observer on the torque command. It estimates the torque the rigid body model cannot explain (load, friction, cutting force, cogging) and subtracts it from the torque command, so the drive cancels the disturbance before the velocity integrator has to. conf/template/filters.txt loads it (opt-in, link filters after link pmsm) between biquad0 and the torque controller, passing through (k 0) until set; conf/fanuc_a3-3000.txt links it with k 1 and the friction feedforward off. The wiring, by hand or as in the template:

Mon, 01 Jan 0001 00:00:00 +0000

DQ #

Brief #

dq turns three phase values (normally the measured phase currents) into the stationary alpha/beta frame (Clarke transform) and then into the rotating d/q frame (Park transform) at the rotor angle pos. It runs on the F3 (HV board) as dq0, loaded by stm32f303/src/main.c (rt_prio 2): dq0.u/v/w = io0.iu/iv/iw, dq0.pos = ls0.pos, dq0.mode = ls0.phase_mode, and d/q feed curpid0 and are sent back to the F4 by ls0. si/co go to hv0 for its dead time compensation.

Mon, 01 Jan 0001 00:00:00 +0000

EMF #

Brief #

emf measures the back EMF of a coasting motor on the F3 (HV board): with the bridge off it demodulates every PWM period’s unfiltered phase voltage sample against the rotor angle and sums the flux linkage psi, its 5th and 7th harmonic back EMF, and psi per magnet pole, to tell a demagnetised magnet from a weak rotor. It is loaded by stm32f303/src/main.c as emf0 (rt_prio 7, the last in the chain). It is controlled from the F4 through config words and read back one result at a time through a state word: idpmsm’s psi test drives it (conf/template/id_pmsm.txt links hv0.emf_run/emf_sel/emf_pp to idpmsm0 and idpmsm0.emf_val = hv0.emf_val). It runs on the F3 because the F4 only sees each phase voltage every ~2 ms and through io0’s filter.

Mon, 01 Jan 0001 00:00:00 +0000

EN #

Brief #

en is an enable sequencer: after its input has been active for a while it switches on two enable outputs one after the other, and it restarts when a fault occurs. It runs on the F4 board. conf/template/en.txt uses it to enable the drive automatically after power up: en0.en_in = 1, fault0.en = en0.en_out0, en0.fault = fault0.fault, en0.time = 1. In conf/move.txt en_out1 enables the drive and homing.

Mon, 01 Jan 0001 00:00:00 +0000

ENC_CMD #

Brief #

enc_cmd reads an incremental position command (quadrature or step/dir) with an STM32 hardware timer on the F4 board and outputs it as an angle. It is loaded by conf/template/enc_cmd.txt (enc_cmd0.res = conf0.cmd_res, rev0.in = enc_cmd0.pos, fault0.cmd_error = enc_cmd0.error), so the command position goes through rev0 to build a multiturn command. It can also drive a fault/ready line back to the controller.

Component Explanation #

Connector and timer selection (remap, read once in hw_init):

remap = 0 (default): CMD connector, A = PA15, B = PB3 on TIM2 (32 bit). Fault line = CMD C (PB5), its line driver enable PB9 is switched on.
remap = 1: FB0 connector, A = PD12, B = PD13 on TIM4. Fault line = FB0 Z (PD14), enable PD15.
remap = 2: FB1 connector, A = PE9, B = PE11 on TIM1. Fault line = FB1 Z (PE13), enable PE14.
remap = 3 (“bene style”, used by conf/bene_sanyo.txt and conf/spindle_slip_uf.txt): A = PA8, B = PA9 on TIM1. Fault line = CMD D (PB8), enable PB2.
Any other value returns from hw_init without configuring anything, pos then reads a timer that was never set up.
A and B get the timer alternate function with pull-ups, the fault pin and its enable are push-pull outputs.

Signal type (mode, read once in hw_init):

mode = 0 (default): quadrature. The timer runs in X4 encoder mode (counts every edge of A and B, so 4 counts per line), auto-reload = res - 1.
mode = 1: step/dir, step on A, direction on B. mode = 2: dir/step, direction on A, step on B. Direction high counts up.
In step/dir the timer is a free running 32 bit up counter clocked by the rising edges of the step input. Each edge of the direction input captures the count in hardware (input capture), and the TIM2 interrupt (priority 1, above the rt) adds the steps since the last direction edge with the old sign. So the step at which the direction changed is exact whatever the interrupt latency; it only has to be taken before the next direction edge, else the capture overflow flag marks it as lost. The STM32 encoder modes cannot decode step/dir: they count a step pulse’s rising and falling edge with opposite signs.
mode = 3 (up/down) is not supported, and neither is step/dir on remap 1..3 (16 bit timers, their DMA belongs to the feedback components). Then error is set and the timer is not set up.
Both inputs use the digital input filter input_filter (IC1F/IC2F code), clamped, without prescaler.

Position output (rt):

Quadrature: each rt cycle the counter is read and converted:

pos = mod(counter * 2 * pi / res); // rad, wrapped to +-pi

In quadrature res is counts per revolution at X4, so lines x 4 (a 2000 line encoder is res = 8000), the same convention as enc_fb. The counter wraps once per revolution; the multiturn tracking is done downstream (e.g. rev0).
Step/dir: the rt takes a pending direction edge, reads the count and adds the steps since the last edge with the current sign, with interrupts off. The signed step count is kept modulo res, and pos = mod(steps * 2 * pi / res), so in step/dir res is steps per revolution.
res is clamped to >= 1, and in quadrature on the 16 bit timers (remap 1..3) to <= 65536. If it changes at runtime the auto-reload register is updated (quadrature only).

Error and fault output (rt):

The template links error to fault0.cmd_error, so it trips fault 1 (CMD error).
A fault of 0 drives the fault line low (e.g. enc_cmd0.fault = fault0.fault or an inverted enable signal).

Breaking change: before this version quadrature res was counts per revolution at 2 counts per line (lines x 2), with auto-reload 2 * res - 1. Configs that use quadrature enc_cmd need res (conf0.cmd_res) doubled. With an old value the drive moves twice the commanded distance, and with commutation from the command input (autophasing) the commutation angle is wrong. Step/dir is unchanged.

Mon, 01 Jan 0001 00:00:00 +0000

ENC_FB #

Brief #

enc_fb reads an incremental quadrature encoder (A/B with optional index Z, optionally with analog sin/cos tracks) on the FB0 connector of the F4 board. It is loaded by conf/template/enc_fb0.txt (and encws_fb0.txt, which disables the index), which links enc_fb0.pos, abs_pos and state to fb_switch0.mot_*, sin/cos/quad/amp to the adc0 sin0l/cos0l/quad/amp0 pins and vel to vel1.vel.

Component Explanation #

Hardware (hw_init):

FB0 A = PD12, B = PD13, Z = PD14 are connected to TIM4 (V4 board) in encoder mode (TI1 and TI2 edges, 4 counts per line, B input inverted), auto-reload = res - 1, with res clamped to >= 1.
A and B use the timer’s digital input filter at fCK_INT with N = 8 (about 95 ns at 84 MHz), so short glitches are ignored.
Channel 3 of the same timer captures the counter value on the Z (index) input.

Count and quadrant correction (rt):

The counter and the A/B port are latched together at the start of the rt interrupt (DMA2_Stream0_IRQHandler in main.c, about 4 us after the last sin/cos sample), close to the time the analog quadrant was sampled.
qdiff = quad - oquad, where quad is the quadrant computed by the ADC component from the analog sin/cos signals. If they differ by one quadrant the count is corrected by +-1 so the digital count matches the analog signals, then wrapped to 0..res-1.
pos = mod(count * 2 * pi / res). If res changes at runtime the timer auto-reload is updated.

Index and absolute position (rt):

If en_index > 0 and an index capture happened, the captured count is stored as the offset and state becomes 3.
abs_pos = minus(pos, offset). Before the first index the offset is 0.
If indexprint > 0, the nrt function prints the captured counter value (cnt = ...) once per index event.

Signal check and interpolation (rt):

If amp > min_amp or |vel| > 0.15: error = 0, state is at least 1, and the interpolated position is computed from the analog angle:

ipos = mod(pos + (int)(ires * mod(4 * atan2(sin, cos) + pi) / pi) / ires * pi / res);

i.e. the sin/cos phase adds a fine offset of +-half a count, quantised to ires steps.
Otherwise error = 1 and state = 0. For a plain digital encoder without sin/cos amp must be set to a constant above min_amp (e.g. enc_fb0.amp = 5 in conf/haas_spindle_slip_uf.txt), otherwise the encoder is reported as faulty at standstill.

The state drops back to 0 whenever the amplitude/velocity check fails, even after an index was found (the stored index offset is kept).

Mon, 01 Jan 0001 00:00:00 +0000

ENCF #

Brief #

encf reads Fanuc serial absolute encoders (tested with the Aa64 type, A860-360) on the FB0 connector of the F4 board. It is loaded by conf/template/fanuc_fb0.txt (used e.g. by conf/fanuc_a6-2000.txt), which links encf0.pos/abs_pos/state to fb_switch0.mot_* and encf0.com_pos to fb_switch0.com_pos/com_abs_pos, and sets encf0.hold = fault0.en_out.

Component Explanation #

Hardware (nrt_init):

The request pulse is generated with SPI3 (MOSI on PC12, prescaler 32, 16 bit word): every rt cycle the word req_len is written to SPI3 (see 2), which gives a request pulse of about 8.4 us. The FB0 line driver enable PD15 is switched on.

Request timing (rt):

The encoder latches its position on the request, so the request goes out at a fixed point: first in rt, the capture buffer is copied out, TIM4 and the DMA are restarted, then the request is armed. The copy is decoded after that. Sent at the end of rt, after the decode, the latch time wandered with the frame’s bit pattern (Y, 15 Oct: about 1 us rms, 0.24 rad/s of vel1 noise and 0.8 A of iq noise at 126 rad/s).
With req_sync = 1 the rt only arms the word; the frt timer interrupt (TIM5, priority 0, src/main.c) writes it to SPI3 first thing on its next update. TIM5 and the ADC that paces the rt both count TIM3, so this is always the same update, a fixed time after the timer edge. req_phase shows the TIM5 count at arming (33 of 59 on Y, about 22 us before the update). On Y this lowered vel1 noise above 200 Hz from 0.14 to 0.105 rad/s and iq noise from 0.45 to 0.37 A; pos_advance stayed the same. req_sync = 0 writes SPI3 from the rt code.
The encoder answer is received on FB0 A (PD12): TIM4 channel 1 captures every edge (both polarities) and DMA1 stream 0 (channel 2) stores up to 160 capture times.

Bit decoding (rt):

TIM4 counts at 84 MHz, so the default freq of 1.024 MHz gives 82.03 ticks per bit. A bench sweep decoded CRC-clean frames for freq from about 986k to 1060k, so the default sits in the middle.
The time between two edges is multiplied by 1 / bit_ticks and rounded to get the number of equal bits; every even-numbered interval is written as 1s. The frame is built in three 32 bit words and the write is bounded to the 80 bit frame buffer, so a noisy frame with too many bits is cut off instead of overrunning memory. Bits after the last edge up to bit 76 are set to 1 (idle line).
If fewer than 51 bits were decoded: error = 1, state = 1 and the position pins keep their last value.

Frame content and CRC (rt):

A 5 bit CRC (ITU CRC-5, from the Mesa fabsread notes) over bits 76..1, MSB first and computed four bits at a time with a nibble table, must be 0. On success crc_ok is incremented, otherwise crc_er is incremented and error = 1, state = 1 (the position pins keep their last value).
Fields: battery fail bit -> batt, un-indexed bit -> index (1 = not yet indexed), 22 bit single-turn position (6 low bits + 16 high bits), 16 bit turn counter (used for turns, see 5), 10 bit commutation track -> com_pos.
abs_pos = pos22 * 2 * pi / 2^22 and com_pos = com * 2 * pi / 1024 (rad), wrapped to [-pi, pi) by sign-extending the integer count (same result as mod() without the fmodf). According to the Mesa notes the commutation track has four 0..1023 cycles per turn and is always absolute.

Position, turns and state (rt, on every valid frame):

pos is the 22 bit count shifted by pos_offset * 64 and wrapped as a 22 bit count to [-pi, pi). The offset applies in every state; pos_offset = 0 gives pos = abs_pos.
The encoder steps its own turn count where its unsigned count wraps (abs_pos = 0), half a turn away from the +-pi wrap. encf keeps a turn count referenced to the +-pi wrap of abs_pos (the encoder’s count, + 1 on the negative half) and takes it from the encoder only while abs_pos is more than a quarter turn from 0, so a few counts of mismatch at the encoder’s own step cannot glitch it. turns is then shifted so that it steps exactly where pos wraps and equals the encoder’s count at pos = pos_offset. pos_offset = 32768 puts the wrap of pos at the encoder’s own step.
The count is taken from the encoder at once, whatever the position, after more than 10 frames without a valid frame (and at start), for 3 frames after the un-indexed bit changes, and on a jump of pos of more than 1/32 turn between two frames. This follows the encoder when it re-references its position and turns at the first index after a battery loss (it clears the un-indexed bit one frame before the count jumps).
hold > 0 (the template links fault0.en_out, so while the drive is enabled): a re-reference at the index would step pos and turns by up to a turn, and the position loop would pull the motor back by that much. Instead, a step that motion does not explain (more than 1/32 turn per frame, or during the re-take frames a change of more than 2^12 counts, 1/1024 turn, from the previous frame’s motion) is added to an offset, output on hold_off in turns, which is added to pos and turns so they stay continuous. The offset is dropped when hold goes to 0, so the new reference shows while the drive is disabled. abs_pos and com_pos are never offset and stay true for commutation.
state = 1 while the encoder reports un-indexed, during those 3 re-take frames and for the frame in which a held offset is dropped (so linrev re-takes its turns), else 3. An encoder that is indexed at power up reads 3 from the first frame; after the first index crossing state reads 3 from the frame after the re-reference, so fb_switch does not switch commutation to abs_pos from the old count.
Until then fb_switch commutates from the commutation track (com_pos + conf0.com_fb_offset, measured by id_pmsm), see fanuc_fb0.txt. For a multiturn position link linrev0.abs_rev = encf0.turns, linrev0.abs_pos = encf0.pos, linrev0.abs_state = encf0.state.

Debug output (nrt):

The raw 76 bit frame is printed as a string of 0/1.

The turn and re-take state is kept in file-static variables, so only one encf instance works. The TX enable (PD15), SPI3 and TIM4 pins are hard coded for the V4 board. The frame layout was only verified for Aa64 encoders; for Aa1000 (A860-370) the extra low resolution bits are not used.

Mon, 01 Jan 0001 00:00:00 +0000

ENCM #

Brief #

encm reads Mitsubishi serial absolute encoders (2.5 Mbit/s, byte oriented request/reply protocol) on the FB0 connector of the F4 board. It is loaded by conf/template/encm_fb0.txt (used by conf/mitsu.txt and conf/wobl.txt), which links encm0.pos to fb_switch0.mot_pos and mot_abs_pos, encm0.state to fb_switch0.mot_state and encm0.error to fault0.mot_fb_error.

Component Explanation #

Hardware (hw_init):

USART6 at 2.5 Mbaud, 8N1. TX = PC6, line driver enable = PD15.
The reply is received by DMA2 stream 1 (channel 5) into a 15 byte buffer.

Command selection (rt):

If cmd > 0 this byte is sent as request. Otherwise it depends on id:
id = 0 (unknown): request 0x92 (read encoder id), any length accepted.
id = 32: request 0x02, 7 reply bytes expected, 13 bit single-turn position.
id = 61, 65 and all others: request 0x32, 9 reply bytes expected, 17 bit single-turn position.

Reply check and decoding (rt), done on the reply to the request of the previous rt cycle:

Checksum: the XOR of all received bytes must be 0, otherwise crc_error = 1.
Fewer than 3 bytes or not the expected number: dma_error = 1.
First byte different from the sent command: cmd_error = 1.
Any of these sets error = 1, state = 0.
Reply to 0x02: ipos = (buf2 << 11) + ((buf3 & 0x1f) << 19); reply to 0x32: ipos = (buf2 & 0x80) + (buf3 << 8) + (buf4 << 16); both give state = 3.
Reply to 0x92: id = buf2, so the next cycle uses the matching position request.

pos = ipos * 2 * pi / 2^24 - pi; // rad, -pi..pi

Request (rt):

The TX enable is set, the command byte is sent and the rt function busy-waits for the USART transmit-complete flag, then the TX enable is cleared and the RX DMA is restarted.

The protocol was reverse engineered: the byte meanings in the source comments are guesses, multiturn data is not decoded, and only a plain XOR checksum is checked. After the id reply pos is set to -pi (ipos = 0) for one cycle but state stays 0. The busy-wait in rt (“irq here will cause problems”) and the hard coded USART6/PC6/PD15/DMA2 stream 1 make it V4 specific; DMA2 stream 1 is also used by encs and dmm, so these cannot be loaded together.

Mon, 01 Jan 0001 00:00:00 +0000

ENCS #

Brief #

encs reads Sanyo Denki serial absolute encoders (tested with PA035C, 2.5 Mbit/s) on the Z line of the FB0 connector of the F4 board. It is loaded by conf/template/encs_fb0.txt (used e.g. by conf/bene_sanyo.txt), which links encs0.pos to fb_switch0.mot_pos and mot_abs_pos, encs0.state to fb_switch0.mot_state and encs0.error to fault0.mot_fb_error.

Component Explanation #

Hardware (hw_init):

The half-duplex data line is FB0 Z (PD14), the line driver enable is FB0 Z TXEN (PD15).
Transmit: the request is bit-banged by DMA2 stream 1 (channel 7, TIM8 update) writing a 24 word pattern to the GPIO set/reset register. TIM8 runs with prescaler 1 and period 32, about 2.545 MHz per bit.
Receive: TIM4 channel 3 captures every edge on PD14 (both polarities), DMA1 stream 7 (channel 2) stores up to 300 capture times.
The request frame is fixed: start bit, sync, frame code, encoder address 0, command code CDF1 (“absolute lower 24 bit data request”) and a precomputed CRC.

Reply decoding (rt), done on the reply to the request of the previous rt cycle:

The time between edges is divided by 33 timer ticks per bit and rounded; every odd-numbered interval is written as 1s, the rest of the 54 bit frame is filled with 1 (idle line).
The frame consists of three 18 bit words (start bit, 16 data bits, stop bit). Only the start (0) and stop (1) bits are checked.
Position: 16 bits from word B plus the MSB (bit 16) from word C, 17 bit single turn:

pos = (pos0_15 / 65536 + pos16) * pi - pi; // rad, -pi..pi

Request (rt):

PD14 is switched to output, TX enable set, the TX DMA is started and the rt function busy-waits until it completes (about 9 us), then PD14 is switched back to the timer input, the capture timer is reset and the RX DMA is restarted.

The CRC, the alarm/status fields and the multiturn bits of the reply are not checked or used. The GPIO mode register access is hard coded for PD14 (V4 board). DMA2 stream 1 is also used by encm and dmm, and TIM8 by yaskawa, so these cannot be loaded together with encs.

Mon, 01 Jan 0001 00:00:00 +0000

ENDAT #

Brief #

endat is an experimental driver for Heidenhain EnDat 2.1 absolute encoders on the FB0 connector of the F4 board. It uses SPI3 in bidirectional single-wire mode for clock and data and the protocol helpers in shared/endat.c. No config template loads it.

Component Explanation #

Hardware (nrt_init):

SPI3 master, prescaler 32 (about 1.3 MHz clock), clock = PC10, bidirectional data = PC12.
Line driver enables: PD10 for the clock (always on), PD15 for the data line (on only while sending).

Request state machine (rt), selected by endat_state:

0: reset error; 1: select memory “state”; 2: read error register; 3: read warning register; 4: select parameter memory 0; 5: read position length; 6: read encoder type; 7: select parameter memory 1; 8: read multiturn bits; 9/10: read resolution low/high word; 11: select parameter memory 2; 12: read maximum velocity; 13: read position.
If req > 0 it overrides the command byte (e.g. 7 = read position).
After a successful reply endat_state is incremented, after a failed one it is reset to 0 (so the whole parameter sequence is read again).
In state 12 error/state follow the encoder error bit (F1): error bit set or failed reply -> error = 1, state = 0, endat_state = 0; otherwise state = 1, error = 0. In all other states state = 0.

Transfer (rt):

The mode command (2 + 6 bits, or 32 bits with address and data) is sent (bit order prepared by endat_tx()) with the data driver enabled, then the driver is switched off and bytes bytes (max 8) are clocked in.
Before receiving, a byte left in the SPI receive register from the last frame is dropped. SPI3 is disabled one SPI clock after the second to last byte, so exactly bytes bytes are clocked from the encoder. If a byte does not arrive within a polling timeout, the received data is set to 0 instead of hanging the rt function.
The received bits are shifted right by skip and then until the first 1 (start bit) is found; the total shift is shown on shift (max 32).
The reply is decoded by endat_rx(): for a position read the error bit goes to f1, the single-turn value (pos_len bits) and multiturn value (mpos_len bits) to pos/mpos, the 5 CRC bits to crc. Parameter reads fill endat_error, endat_warning, type, pos_res, max_vel, and update pos_len/mpos_len from the encoder memory.

pos = mod(pos_raw * 2 * pi / 2^pos_len); // rad, +-pi

Debug output (nrt):

If print_time > 0, timer counts up in rt and every print_time seconds the nrt function prints the last request, received raw bits, position, multiturn and CRC bits.

Experimental and incomplete. The CRC is read but never checked. The state handling looks inconsistent: the position read (13) takes the default branch, so after one successful read endat_state becomes 14, which sends nothing and falls back to 0; after the parameter sequence it then stays in state 12 (reading max velocity), so pos is no longer updated unless req is set to 7. state never reaches 3, so fb_switch will not accept it as a valid feedback. SPI3 is shared with encf.

Mon, 01 Jan 0001 00:00:00 +0000

FANUC #

Brief #

The fanuc component decodes the four digital commutation tracks C1, C2, C4 and C8 of a Fanuc pulse coder into an absolute commutation angle. It is used on the F4 board via conf/template/fanuc_io.txt, which reads the tracks from io0.C12, io0.CTX, io0.CRX and io0.C54 (with io0.cmd_remap = 1) and links fanuc0.pos to fb_switch0.com_pos / fb_switch0.com_abs_pos.

Component Explanation #

Code word (rt):

The 4-bit word is built as

t = C1 + 2 * C2 + 4 * C4 + 8 * C8;

Lookup table:

A fixed table maps the 16 possible words (a Gray-code sequence) to the sector numbers 0..15:

t: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
sector: 0 15 1 2 13 14 12 11 5 6 4 3 8 7 9 10

The output is pos = mod(sector / 16 * 2 * pi) (22.5 deg per sector). There is no error detection: every code is treated as valid.

Pins #

Name	Description
C1	input, Commutation track C1 (bit 0, high when > 0)
C2	input, Commutation track C2 (bit 1, high when > 0)
C4	input, Commutation track C4 (bit 2, high when > 0)
C8	input, Commutation track C8 (bit 3, high when > 0)
pos	output, Absolute commutation angle (rad, +-pi)

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

FAULT #

Brief #

fault is the central enable / fault state machine of the F4 board. It collects error flags, temperatures, voltages, currents and controller saturation, decides whether the drive is disabled, phasing, enabled or faulted, gates the other components with en_out, en_fb and en_pid, controls the motor brake and fans, outputs a derating factor scale, and after a stop can decelerate the motor regeneratively (rstop) or ask the F3 for short-circuit braking (sbrake). It is loaded by nearly every template (pid.txt, mpid.txt, uf.txt, the id_* templates, …). Typical links: hv0.en = fault0.en_out, fb_switch0.en = fault0.en_fb, pid0.en = fault0.en_pid, hv0.scale = fault0.scale, fault0.fb_ready = fb_switch0.state, fault0.hv_error = hv0.fault, fault0.sat = pid0.sat, io0.state = fault0.state, io0.fault = fault0.fault, and the limits from conf0. pid.txt also links hv0.sbrake = fault0.sbrake, hv0.sbrake_arm = fault0.sbrake_en, pid0.stop = fault0.rstop, fault0.vel_fb = vel1.vel; ipm.txt links fault0.ipm_temp = ipm0.temp. The commands enable and disable set fault0.en to 1 or 0.

Mon, 01 Jan 0001 00:00:00 +0000

FB_SWITCH #

Brief #

fb_switch combines up to three feedback sources (motor, commutation and joint feedback) into the position feedback for the position loop, the position used for velocity estimation and the commutation angle for the current loop. If no absolute source is available it performs autophasing. F4 component, loaded by the pid/mpid templates; e.g. fb_switch0.mot_pos = enc_fb0.ipos, fb_switch0.com_state = uvw0.state, pid0.pos_fb = fb_switch0.pos_fb, vel1.pos_in = fb_switch0.vel_fb, fault0.fb_ready = fb_switch0.state, hv0.d_cmd = fb_switch0.id.

Mon, 01 Jan 0001 00:00:00 +0000

FIELD #

Pins #

Name	Description
vele_n
velm_n
i_n
t_n
vel_boost
t_boost
vel
vel_mode
in_mode
t
iq
id
iq_max
iq_min
t_max
t_min
slip
velm
vele

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

FLUX_OBS #

Brief #

flux_obs is a hybrid rotor flux observer for an induction motor on an encoder (review item B5). It measures the rotor flux angle and magnitude from voltage and current, without tr, and can trim the current model’s slip so that the field orientation follows the measured flux at speed. Below its crossover it falls back to the current model (acim_flux), so at low speed nothing changes.

Mon, 01 Jan 0001 00:00:00 +0000

FLUXOPT #

Brief #

fluxopt reduces the flux of an induction motor at light load (acim_foc) to cut the copper loss. conf/template/acim_foc.txt loads it between the field weakening and the field oriented control with fluxopt0.torque = pid0.torque_cmd, fluxopt0.scale_in = acim_fw0.scale, fluxopt0.id_n = acim_foc0.id_n, fluxopt0.lmr = acim_flux0.lmr_act, fluxopt0.polecount = conf0.polecount and acim_foc0.scale = fluxopt0.scale. It is off there (min 1); fluxopt0.min = 0.5 in a config turns it on.

Mon, 01 Jan 0001 00:00:00 +0000

FMOVE #

Brief #

fmove implements force guided movement (admittance control): a measured force moves an axis like a virtual mass with damping and friction, and after the force is released the axis moves automatically to a target. F4 component, used in conf/move.txt with a load cell (fmove0.force_in = hx0.out0, fmove0.en = home0.en_out, home0.pos_in = fmove0.mpos).

Component Explanation #

Motion is calculated in rt, nrt prints the status. pos, vel, acc and the limits are in axis units (e.g. m), scale converts to motor angle. Default scale = 1000 / 25 * 2pi * 2.

Mon, 01 Jan 0001 00:00:00 +0000

FRF #

Brief #

frf measures the frequency response of the mechanics with the position loop running (stepped sine) and fits a two-mass model to it, mainly to find the coupling anti-resonance for conf0.j_lpf. It is loaded by conf/template/id_frf.txt, which replaces id_lpf’s ring down and is run before id_pid (j_lpf changes the plant the gains are tuned against). It sits between pid0 and the torque controller (after biquad0 if that is loaded):

Mon, 01 Jan 0001 00:00:00 +0000

GAIN #

Brief #

gain computes a velocity dependent factor between 0 and 1. F4 component; not used by any config in conf/.

Component Explanation #

Output (rt):

scale = CLAMP(|vel / MAX(max_vel, 0.1)|, 0, 1), i.e. 0 at standstill rising linearly to 1 at max_vel.

Pins #

Name	Description
vel	input, Velocity (rad/s)
max_vel	parameter, Velocity for factor 1 (rad/s), min 0.1
scale	output, Factor 0..1

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

HAL_TEST #

Brief #

hal_test is a debugging component that burns CPU time in the rt and frt threads to test HAL timing and overrun handling. F4 component; not used by any config in conf/.

Component Explanation #

Busy loops:

rt runs an empty loop rt_wait times, frt runs one frt_wait times. Both default to 0 (no load).

Pins #

Name	Description
rt_wait	parameter, Busy loop iterations per rt period
frt_wait	parameter, Busy loop iterations per frt period

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

HOME #

Brief #

home performs a homing sequence with a home switch by adding a moving offset to a position, and releases the axis with en_out when homing is done. F4 component, used in conf/move.txt: home0.pos_in = fmove0.mpos, rev0.in = home0.pos_out, home0.home_in = th0.out_not, fmove0.en = home0.en_out.

Component Explanation #

All work is done in rt. The homing velocity is limited to |home_vel| and changes by at most home_acc.

Mon, 01 Jan 0001 00:00:00 +0000

HV #

Brief #

hv runs on the F4 logic board and is its end of the UART link to the F3 power (HV) board. Every rt period it sends the current/voltage command, the commutation angle and velocity, the short brake flags and one word of current loop configuration to the F3, and unpacks the F3 reply (dq feedback, fault code and one word of state such as DC link voltage and temperatures). It also carries the hv terminal pass-through, the hv_update F3 firmware update and the hv_verify read back of the F3 flash. The F3 side of the link is the F3 ls component (stm32f303/src/comps/ls.c); the F3 bridge driver that shares this name is stm32f303/src/comps/hv.c, documented as page hv_f3.

Mon, 01 Jan 0001 00:00:00 +0000

HV_F3 #

Brief #

hv on the F3 (HV board) side: it turns the three phase voltages from idq0 into TIM8 compare values that drive the power stage. It adds a dead time compensation, then the space vector (midpoint) common mode offset, keeps every pulse above a minimum on and off time, follows the PWM period that ls0 sets to phase lock the board to the F4, and holds all low sides on while io0 short-circuit brakes. It is loaded by stm32f303/src/main.c as hv0 (rt_prio 6, after idq0) and is not configured by the user directly: its settings (drop_k, drop_knee, arr) come from the F4 through ls0. This page is the F3 component and is published as hv_f3. The F4-side counterpart, which configures the HV board and sends it the commands, is the hv component.

Mon, 01 Jan 0001 00:00:00 +0000

HX711 #

Brief #

hx (file src/comps/hx711.c) reads up to two HX711 24 bit load cell ADCs connected to the fb1 connector of the F4 logic board by bit-banging their clock and data lines, and outputs the scaled readings as out0/out1. conf/template/hx.txt loads it (hx0.gain = 100); conf/move.txt uses hx0.out0 as force input for fmove0.

Component Explanation #

Wiring (hw_init):

Clock (PD_SCK of both chips): fb1 Z line, driven as an output with the Z transmitter enabled.
Data: DOUT of chip 0 on fb1 line A, DOUT of chip 1 on fb1 line B. data_inv and clk_inv are for inverting line drivers/receivers.

Reading (rt):

timer counts up by the rt period. Once timer > time and chip 0 signals a finished conversion (data line low), the component clocks 24 bits out of both chips at the same time, MSB first, then one more clock pulse, which selects channel A with gain 128 for the next conversion. timer is then reset.
Each clock half period is a busy loop of sleep NOPs, so a read blocks rt for roughly 50 clock half periods.
Conversion to the outputs:

out = raw / 0x7fffff * gain + offset;

The value is shifted once more after the last bit, so raw is twice the HX711 reading and the sign is taken from bit 22 of the reading instead of bit 23: readings are scaled by 2 (absorbed by gain when calibrating) and wrap around beyond half of the HX711 input range. Only chip 0 is checked for data ready; chip 1 is assumed to convert in sync. There is no plausibility or saturation check (see the TODO in the code).

Mon, 01 Jan 0001 00:00:00 +0000

IDACIM #

Brief #

idacim identifies an AC induction motor. A standstill test measures the stator resistance r (with the inverter dead time voltage drop separated from it), the leakage inductance l (sigma*Ls) by injection at two frequencies around the current loop’s crossover, and the rotor time constant tr and rotor side magnetizing inductance lmr (Lm^2/Lr) by d current steps; an optional current ladder (knee) fits how tr changes with flux. From these and the motor plate it computes a vf parameter set. An optional rotating test spins the rotor open loop; with an encoder it first reads tr and the inertia from up and down speed ramps at two currents, can check tr with the rotor turning under FOC (rot_tr_vel), then sweeps the flux, each level at the ramps’ top emf and at half that speed, and fits the magnetizing curve (acim_flux0.lmr, lmr_sat, i_knee, tr_sat, i_dip, lmr_dip, tr_dip, acim_foc0.id_n). A separate pole pair test reads conf0.polecount and the direction. It runs on the F4 board, drives hv0 directly and is loaded by the id_acim template.

Mon, 01 Jan 0001 00:00:00 +0000

IDDAC #

Brief #

iddac (loaded by conf/template/id_dac.txt as id_dac) is a one shot identification on the F4 board that searches the F3 hardware overcurrent comparator threshold hv0.dac that trips at a wanted phase current cur (A peak). It drives hv0 in current mode itself, bisects the dac, and prints the hv0.dac = ... line to append to the config. Nothing is saved; for normal operation use ocdac or a fixed hv0.dac.

Mon, 01 Jan 0001 00:00:00 +0000

IDDC #

Brief #

iddc identifies a brushed DC motor: winding resistance r, inductance l and the torque/back-emf constant psi, and detects a reversed motor. It runs on the F4 board, drives hv0 on the q axis only (the template sets hv0.phase_mode = 3, 180 degree 2 phase / H-bridge) and is loaded by the id_dc template. Afterwards continue with id_mot.

Component Explanation #

Setup:

At the console, link id_dc. The template wires iddc0.en = fault0.en_out, disables pid0 and the position error fault, and connects hv0.en, cur_bw, cmd_mode, q_cmd, pos, rev, r, l to this component and hv0.uq_fb, iq_fb, pwm_volt, vel1.vel back into it.
hv0.r and hv0.l are wired to this component’s r and l, so the current loop uses the estimate as it forms. While the state is 0 the nrt function resets r 0.1 ohm, l 1 mH, psi 0.055 and out_rev 0.
Set test_cur and test_vel after enabling or before; they are not reset.

Resistance and inductance (state 1.x), rotor blocked:

When en goes high the state goes to 1.0; the nrt function prints “block the rotor” and waits in 1.1. Set iddc0.state = 1.2 to start. en low returns to 0 from any state.
1.2 (2 s): current mode, cur_bw 10, q_cmd = test_cur. r is low-passed from uq_fb / iq_fb (factor 0.01 per rt tick). At the end avg_test_volt = test_cur * r, limited to pwm_volt / 2.
1.3 (1 s): voltage mode. q_cmd alternates every rt tick between 1.5 * avg_test_volt and 0.5 * avg_test_volt; the current and voltage for both levels are low-passed into tmp0..tmp3 and

l = |tmp1 - tmp3| / |tmp0 - tmp2| * period;

1.4 (nrt): prints conf0.r and conf0.l, then goes to 2.0, which prints “unblock the rotor” and waits (in state 3.1).

Torque constant (state 2.2), rotor free:

Set iddc0.state = 2.2. For 5 s the motor runs in current mode (cur_bw 250) under a simple speed loop on |vel_fb| towards test_vel: the error is limited to test_vel / 100, integrated with ki into cur_sum, and q_cmd = vel_bw * period * error + cur_sum. q_cmd has no own limit; only the drive’s current limits apply.
While |vel_fb| > 0.1 rad/s, psi = (uq_fb - iq_fb * r) / vel_fb is low-passed with time constant pi.
At the end a negative psi is made positive and out_rev = 1 is set. State 2.3 (nrt) prints conf0.psi (Vs/rad = Nm/A) and, if reversed, conf0.out_rev = 1, then goes to 2.4 (done).

Untested per the template (no DC motor was available). The inductance test uses the per-tick dV/dI method that the idacim source documents as reading 2x to 6x high (the formula uses the full voltage swing, and the feedback delay makes the one-tick slope unpredictable), so treat l as a rough value. The 5 s speed test ramps cur_sum at no more than ki * test_vel / 100 A/s (1 A/s by default), so the motor may not reach test_vel; psi is still averaged at whatever speed it reaches. After 1.4 the nrt function moves to state 3.1 but prints iddc0.state = 2.2 as the start command, which is what you must type.

Mon, 01 Jan 0001 00:00:00 +0000

IDM #

Brief #

idm identifies the mechanical parameters of the axis: inertia, viscous damping, coulomb friction and a constant torque offset (e.g. gravity on a vertical axis). It runs on the F4 board and is loaded by the id_mot template (bare motor, results for conf0.j, conf0.d, conf0.f, conf0.o) and, through id_sys (which links id_mot and sets idm0.sys = 1), for the inertia of the coupled load (conf0.j_sys). It moves the axis back and forth through pid0, adapts the inertia (and first estimates of the others) until the feedback torque of the position/velocity loop no longer correlates with them, then fits friction, damping and offset over constant speed stretches at several speeds. A breakaway test at standstill, the torque it takes to get the axis moving in each direction (static friction and static load, see 5.), is a diagnostic: the id_brk template runs it on its own, and id_sys ends with it when brk is set to 1.

Mon, 01 Jan 0001 00:00:00 +0000

IDPMSM #

Brief #

idpmsm identifies a permanent magnet synchronous motor on the drive itself: winding resistance r together with the inverter dead time curve (hv0.drop_k, hv0.drop_knee), d and q inductance ld/lq, pole pairs pp, feedback direction out_rev, commutation offset com_offset (plus com_fb_offset for a commutation track such as encf’s) and flux linkage psi (plus a per pole back emf map from the F3’s emf0). It runs on the F4 board and is loaded by the id_pmsm config template, which takes over hv0 (enable, command mode, d/q commands, commutation angle, r, l, lq, current loop bandwidth) and prints the results as conf0.* and hv0.* lines to append to the config.

Mon, 01 Jan 0001 00:00:00 +0000

IDQ #

Brief #

idq is the inverse of dq: it turns d/q values (normally the voltages from the current controller) at the rotor angle pos into the alpha/beta frame (inverse Park) and then into three phase values (inverse Clarke). It runs on the F3 (HV board) as idq0, loaded by stm32f303/src/main.c (rt_prio 4): idq0.d/q = curpid0.ud/uq, idq0.pos = ls0.pos_v (the voltage angle), idq0.mode = ls0.phase_mode, ext_sc = 0, u/v/w go to hv0.u/v/w and si_out/co_out to hv0.si/co. The old conf/template/linkv3.txt also loads it on the F4.

Mon, 01 Jan 0001 00:00:00 +0000

IDS #

Brief #

ids tunes the gains of the pid position/velocity loop (pos_bw, vel_bw, vel_d) by moving the axis back and forth on a trapezoid profile between min_pos and max_pos and raising one gain at a time while each raise still cuts the tracking-error cost. In speed mode (pos_en = 0, a spindle) it instead tunes only vel_bw, from the speed dip under a load torque step at +-max_vel. It runs on the F4 board and is loaded by the id_pid template, normally as the last identification step after id_mot (and id_sys if a load is coupled). With lpf = 1 (template id_lpf) it instead measures the coupling resonance and computes conf0.j_lpf.

Mon, 01 Jan 0001 00:00:00 +0000

IDTUNE #

Brief #

idtune tunes the running compensations that idpmsm does not: hv0.adv, the commutation advance in seconds (hv sends pos + vel * adv), and, for the latched dead time sign (hv0.drop_knee = 0), hv0.drop_k, the dead time (drop) compensation. With drop_knee > 0 the config’s drop_k from idpmsm’s curve fit is kept. It runs on the F4 board, is loaded by the id_tune config template and prints hv0.drop_k and hv0.adv lines to append to the config.

Mon, 01 Jan 0001 00:00:00 +0000

IDX_HOME #

Brief #

idx_home implements index homing for LinuxCNC via smart serial: when LinuxCNC requests an index, it switches the feedback from the incremental motor position to the absolute motor position at the next zero crossing. F4 component, loaded by conf/template/sserial.txt: idx_home0.fb = fb_switch0.mot_fb_no_offset, idx_home0.fb_abs = fb_switch0.mot_abs_fb_no_offset, idx_home0.index_en = sserial0.index_out, sserial0.index_clear = idx_home0.index_clear, linrev0.fb_in = idx_home0.pos_out.

Component Explanation #

All work is done in rt. There is no nrt_init.

Mon, 01 Jan 0001 00:00:00 +0000

IIT #

Brief #

iit is an I2t thermal model of the motor: it estimates the motor temperature from the phase current, for motors without a temperature sensor. It runs on the F4 board and is loaded by conf/template/pid.txt, mpid.txt and uf.txt with iit0.cur = hv0.abs_cur, iit0.max_cur = conf0.max_ac_cur, iit0.high_temp = conf0.high_mot_temp, iit0.max_temp = conf0.max_mot_temp, and fault0.mot_temp = iit0.temp, so the model derates the current (fault0.scale) and finally trips a motor over temperature fault.

Mon, 01 Jan 0001 00:00:00 +0000

IO #

Brief #

io is the hardware I/O of the F3 (HV board). It reads the phase currents, phase voltages, DC link voltage and temperatures from the ADCs, calibrates the current offsets at boot, rebuilds a phase current the ADC could not sample, switches the power stage on and off, raises the HV fault codes (overcurrent, overvoltage, overtemperature, driver fault) and runs the short-circuit brake. It also drives the status LED, the brake output and the DAC reference of the overcurrent comparators. It is loaded by stm32f303/src/main.c as io0 (rt_prio 1, so it runs right after ls0 and angle0). The F3 rt runs once per PWM period, at PWM_FREQ, a build option (10, 15 or 20 kHz, default 15 kHz); tick counts below scale with it where noted.

Mon, 01 Jan 0001 00:00:00 +0000

IO4 #

Brief #

io (file src/comps/hw/io4.c) is the board I/O driver of the F4 logic board, hardware version 4: status LEDs, fan, digital output out0, PWM outputs out1/out2, the two 24 V inputs, analog reads of the feedback connectors, the raw logic levels of the command and feedback connector lines and the RJ45 LEDs. Templates load it as io0 and typically wire io0.state = fault0.state, io0.fault = fault0.fault, io0.fan = fault0.hv_fan, io0.out0 = fault0.mot_brake (brake) and the feedback templates drive io0.fb0g/io0.fb0y.

Mon, 01 Jan 0001 00:00:00 +0000

IPM #

Brief #

ipm estimates the junction temperatures of the power module (IPM) on the F4 board, so the drive can derate and trip on die temperature between the fast overcurrent trips and the slow module NTC. It adds a modelled temperature rise of each of the twelve dies (per leg: high and low IGBT, high and low diode) to the NTC reading. Loaded by conf/template/ipm.txt, which the motor templates (pid, mpid, uf and vf) link at their end, so a config does not link it again (a second link ipm loads an ipm1 nothing reads): its inputs come from hv0 (ipm0.id = hv0.id_fb, …, ipm0.case_temp = hv0.hv_temp, ipm0.pos = hv0.pos) and fault0.ipm_temp = ipm0.temp feeds the derate (conf0.high_ipm_temp) and the IPM_TEMP_ERROR trip (conf0.max_ipm_temp) in fault. The defaults are for the IKCM30F60GD fitted to v5.0 (conf/template/ipm_ikcm30f60gd.txt repeats them); link conf/template/ipm_im06b50gc1.txt after the motor template for the IM06B50GC1.

Mon, 01 Jan 0001 00:00:00 +0000

JOG #

Brief #

jog provides terminal commands to jog an axis. F4 component, used in conf/template/jog_cmd.txt together with stp (stp0.jog = jog0.jog).

Component Explanation #

Commands:

jogl sets jog to -1, jogr to 1, jogx to 0.

Timeout (rt):

If no command is received for 0.75 s, jog returns to 0, so the command has to be repeated (e.g. by holding the key in the terminal) to keep moving.
The jog state is a global variable, all instances share it.

Pins #

Name	Description
jog	output, -1 = left, 0 = stop, 1 = right

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

LINREV #

Brief #

linrev converts between machine units (e.g. mm from LinuxCNC) and the motor angle, and counts motor revolutions to turn the wrapped motor angle back into an unwrapped machine position. With a multiturn absolute encoder it can take the revolution count from the encoder instead. F4 component, loaded by conf/template/sserial.txt: linrev0.cmd_in = sserial0.pos_cmd, linrev0.fb_in = idx_home0.pos_out, sserial0.pos_fb = linrev0.fb_out, linrev0.scale = sserial0.scale, linrev0.rev_clear = sserial0.index_clear, linrev0.abs_neg = conf0.mot_fb_rev.

Mon, 01 Jan 0001 00:00:00 +0000

LS #

Brief #

ls is the F3 (HV board) end of the serial link to the F4 (3 Mbaud UART, USART3 with DMA, CRC checked packets). It receives the current or voltage command, rotor angle, velocity, enable, mode and braking flags, plus one word of configuration per packet, and puts them on pins for the current loop, ramping the d/q command between packets. It answers with the measured d/q currents, output voltages, the fault code and one word of state per packet. It also locks the F3’s PWM period to the F4’s packet timing (trimming one period per packet), carries the F3 terminal (one byte each way per packet), holds the enable off until the whole configuration has arrived, disables the bridge when packets stop and can then ask io0 for a short-circuit brake. It is loaded by stm32f303/src/main.c as ls0 (rt_prio 0.6, the first in the chain). The F4 end of the link is the hv component.

Mon, 01 Jan 0001 00:00:00 +0000

MAD #

Brief #

mad (multiply add) computes out = in * mult + add. F4 component, used e.g. in conf/spindle_slip_uf.txt to scale an analog input into a velocity command (mad0.in = io0.in1, ramp0.vel_ext_cmd = mad0.out).

Component Explanation #

Output (rt):

out = in * mult + add. All pins default to 0.

Pins #

Name	Description
in	input, Signal
mult	parameter, Multiplier
add	parameter, Offset
out	output, in * mult + add

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

MELODY #

Brief #

melody plays a tune through the motor: an audio rate current added to the d-axis command makes the stator hum the notes without torque (with the commutation offset right). It also plays a ready chime after power-up and beeps on identify, to find which drive is which. F4 component, loaded by conf/template/melody.txt (link melody after link pmsm), which inserts it between the d-axis source and hv:

Mon, 01 Jan 0001 00:00:00 +0000

MOTSIM #

Brief #

motsim is a simple software model of a PMSM with its own d/q current controller, for testing control components without hardware. It is built into the F4 firmware but no config template loads it; use load motsim and wire it by hand in place of hv0: it takes the same d_cmd/q_cmd/cmd_mode/en and commutation angle, and returns id_fb, iq_fb, ud_fb, uq_fb and a quantised rotor position pos_fb.

Mon, 01 Jan 0001 00:00:00 +0000

MOVE #

Brief #

move turns two direction bits into a signed value: out = scale * (fwd - rev). F4 component, used in conf/dual_dc_sserial.txt to drive a DC motor from smart serial outputs (move0.fwd = sserial0.out0, move0.rev = sserial0.out1, hv0.d_cmd = move0.out).

Component Explanation #

Output (rt):

With both bits set the output is 0.

Pins #

Name	Description
fwd	input, Forward, typically 0 or 1
rev	input, Reverse, typically 0 or 1
scale	input, Output magnitude
out	output, scale * (fwd - rev)

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

MPID #

Brief #

mpid is an alternative cascaded position / velocity controller for the F4 board that tracks the position error incrementally, so the error is not limited to +-pi. It outputs a torque command (Nm). It is loaded by conf/template/mpid.txt with mpid0.pos_ext_cmd = reslimit0.pos_out, mpid0.vel_ext_cmd = veltime0.vel_lp, mpid0.pos_fb = fb_switch0.pos_fb, mpid0.vel_fb = veltime1.vel_lp, mpid0.en = fault0.en_pid, and gains / limits from conf0 (pos_p, vel_p, vel_i, j, max_vel, max_acc, max_force).

Mon, 01 Jan 0001 00:00:00 +0000

MUX #

Brief #

mux selects one of eight banks of ten inputs and copies it to the ten outputs. F4 component, used in conf/spindle_slip_uf.txt to switch between parameter sets with an input (mux0.mux = io0.ind0).

Component Explanation #

Selection (rt):

The bank is mux clamped to 0..7 and truncated to an integer.
out<i> = in<bank * 10 + i> for i = 0..9, e.g. mux = 1 copies in10..in19.

Pins #

Name	Description
in0	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in1	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in2	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in3	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in4	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in5	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in6	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in7	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in8	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in9	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in10	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in11	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in12	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in13	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in14	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in15	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in16	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in17	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in18	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in19	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in20	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in21	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in22	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in23	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in24	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in25	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in26	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in27	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in28	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in29	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in30	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in31	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in32	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in33	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in34	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in35	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in36	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in37	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in38	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in39	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in40	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in41	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in42	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in43	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in44	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in45	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in46	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in47	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in48	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in49	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in50	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in51	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in52	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in53	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in54	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in55	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in56	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in57	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in58	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in59	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in60	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in61	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in62	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in63	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in64	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in65	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in66	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in67	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in68	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in69	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in70	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in71	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in72	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in73	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in74	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in75	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in76	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in77	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in78	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
in79	input, 8 banks of 10 inputs, bank n is in(10n)..in(10n+9)
out0	output, Outputs of the selected bank
out1	output, Outputs of the selected bank
out2	output, Outputs of the selected bank
out3	output, Outputs of the selected bank
out4	output, Outputs of the selected bank
out5	output, Outputs of the selected bank
out6	output, Outputs of the selected bank
out7	output, Outputs of the selected bank
out8	output, Outputs of the selected bank
out9	output, Outputs of the selected bank
mux	input, Bank select 0..7

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

NOT #

Brief #

not is a logic inverter. F4 component, e.g. used to invert an enable input (not0.in = io0.C12, fault0.en = not0.out).

Pins #

Name	Description
in	input, Logic input, true if > 0
out	output, 1 if in <= 0, else 0

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

O_FB #

Brief #

o_fb (F4 logic board, hardware v4) turns the A and B lines of the fb0 feedback connector into digital outputs, e.g. to send an encoder or step/dir style signal to another device. No template loads it.

Component Explanation #

Setup (hw_init):

Enables the fb0 A and B RS485 transmitters (FB0_A_EN, FB0_B_EN high) and configures the A and B pins as push-pull outputs. The fb0 connector can then no longer be used as a feedback input.

Output (rt):

Once per rt period, the A line is driven from a and the B line from b. The output rate is therefore limited to the rt frequency.

Pins #

Name	Description
a	input, fb0 line A output, > 0 = high
b	input, fb0 line B output, > 0 = high

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

OBS #

Brief #

The obs component estimates the flux angle and speed from voltage and current, for a PMSM and an induction motor alike. It generalises sensorless (which stays for old configs) and fixes its undamped loop.

Model #

In a frame at angle pos turning at vel, the back emf is

ed = ud - r id - ld d(id)/dt + vel lq iq eq = uq - r iq - lq d(iq)/dt - vel ld id

Mon, 01 Jan 0001 00:00:00 +0000

OCDAC #

Brief #

ocdac sets the F3 hardware overcurrent comparator threshold hv0.dac from a trip current in A peak, using a linear map fitted per board. It runs on the F4 board and is loaded by conf/template/ocdac.txt with hv0.dac = ocdac0.dac and ocdac0.cur = 20. Use iddac (id_dac template) to find the dac for one current on a given board.

Component Explanation #

Dac map (nrt):

k = MAX(k, 0.1);
dac = CLAMP(roundf(dac0 + k * MAX(cur, 0)), dac_min, dac_max);
cur_out = (dac - dac0) / k;

cur_out shows when dac_min or dac_max limited the result.

Calibration:

The comparators see the raw shunt node (2.9 mV/A, about 3.6 counts/A in theory); the measured slope and offset depend on the TIM8 break filter, because the shorter filters trip on switching ringing on top of the current.
Measured with filter 0xC (the default, periph.c), highest trip of the 60/180/300 deg angles:

Board	Map	Range
X, IKCM30F60GD, 1 Oct 2026	`dac0` 115, `k` 6.7	dac 215..255, 15..21 A
spindle, IM06B50GC1, 6 Oct 2026	`dac0` 128, `k` 6.48	dac 200..340, 11.3..32.3 A measured id, 0.12 s d pulses
Y, IKCM30F60GD, filter 0xF only	`dac0` 140, `k` 3.5

The defaults are X’s. Fit dac0 and k per board from a few trips (iddac finds the dac for one current directly) and save them in the config.

The map is a bench fit for one board and break filter setting; check it on your hardware before relying on it as overcurrent protection.

Mon, 01 Jan 0001 00:00:00 +0000

OR #

Brief #

or is a four input logic OR. F4 component.

Component Explanation #

Output (rt):

out = 1 if any of in0..in3 is > 0, otherwise 0. Unused inputs can stay at their default 0.

Pins #

Name	Description
in0	input, Logic input, true if > 0
in1	input, Logic input, true if > 0
in2	input, Logic input, true if > 0
in3	input, Logic input, true if > 0
out	output, 1 if any input is > 0

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

PE #

Brief #

pe (power and energy) computes power and energy values of the drive for display on the scope. It runs on the F4 board and is loaded by conf/template/pid.txt and mpid.txt with pe0.udc = hv0.dc_volt, pe0.id/iq = hv0.id_fb/iq_fb, pe0.torque = pid0.torque_cmd, pe0.vel = vel1.vel, pe0.r = conf0.r, pe0.j = conf0.j, pe0.cap = 0.00054. The templates set idc, ud and uq to 0. No component uses the outputs.

Mon, 01 Jan 0001 00:00:00 +0000

PID #

Brief #

pid is the standard cascaded position / velocity controller of the F4 board. It turns a position command into a torque command (Nm) using a proportional position loop, a PI velocity loop with inertia scaling, and friction / damping / inertia feedforward. It is loaded by conf/template/pid.txt (and most machine configs), where pid0.pos_ext_cmd = reslimit0.pos_out, pid0.vel_ext_cmd = vel0.vel, pid0.pos_fb = fb_switch0.pos_fb, pid0.vel_fb = vel1.vel, pid0.en = fault0.en_pid, pid0.stop = fault0.rstop, and pid0.torque_cmd feeds the torque-to-current component (pmsm_ttc, dc_ttc, …). Gains and limits are linked from conf0 (pos_bw, vel_bw, vel_d, j, max_vel, max_force, …).

Mon, 01 Jan 0001 00:00:00 +0000

PMSM_LIMITS #

Brief #

pmsm_limits estimates the current and torque a PMSM can reach with the available AC voltage: absolute limits, limits at the present operating point, and the limits reachable within the next control period. It is compiled into the F4 firmware; the outputs were meant to feed the torque limits of pid and the current controller.

Component Explanation #

All work is done in rt. Defaults (nrt_init): ld = 0.001. The inputs are clamped to lq >= 0.0001, psi >= 0.01, r >= 0.001, and polecount is truncated to an integer >= 1. With volt = ac_volt:

Mon, 01 Jan 0001 00:00:00 +0000

PMSM_TTC #

Brief #

pmsm_ttc (torque to current) converts a torque command (Nm) into a q-axis current command (peak A) for a permanent magnet synchronous motor, with optional cogging / torque ripple compensation and an experimental block commutation mode. It runs on the F4 board and is loaded by conf/template/pmsm.txt: pmsm_ttc0.torque = pid0.torque_cmd, pmsm_ttc0.pos_in = vel2.pos_out, hv0.q_cmd = pmsm_ttc0.cur, hv0.d_cmd = pmsm_ttc0.id, angle0.pos_fb = pmsm_ttc0.pos_out, with psi and polecount from conf0.

Mon, 01 Jan 0001 00:00:00 +0000

POS_FILTER #

Brief #

pos_filter smooths a position command with a critically damped second order tracking filter and outputs filtered position, velocity and acceleration. F4 component, see conf/template/pos_filter.txt: pos_in = rev0.out, vel_in = rev0.out_d, reslimit0.pos_in = pos_out, pid0.vel_ext_cmd = vel_out, pid0.acc_ext_cmd = acc_out.

Component Explanation #

All work is done in rt. bandwidth must be set (the template uses 1000).

Filter:

ki = 2 * MIN(bandwidth, 1 / period / 2);
kp = ki * ki / 4;
acc_out = kp * minus(pos_in, pos_out) + ki * (vel_in - vel_out);
vel_out += acc_out * period;
pos_out = mod(pos_out + vel_out * period);

Both poles are at bandwidth (rad/s). bandwidth is limited to 1 / (2 * period).

Enable:

With en <= 0 acc_out is 0.

Pins #

Name	Description
pos_in	input, Position (rad)
vel_in	input, Velocity (rad/s)
pos_out	output, Filtered position (rad, +-pi)
vel_out	output, Filtered velocity (rad/s)
acc_out	output, Filtered acceleration (rad/s^2)
bandwidth	parameter, Filter bandwidth (rad/s), no default
en	input, Enable filter, pass through if <= 0

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

PSI #

Brief #

psi measures the flux linkage (back EMF constant) of a motor that is turned from outside while the power stage is not driving it. It runs on the F4 board. The working wiring is in conf/experimental/psi.txt: psi0.u/v/w = hv0.u_fb/v_fb/w_fb, psi0.dc_volt = hv0.dc_volt, psi0.vel = vel1.vel, psi0.polecount = conf0.polecount, with psi0.psi and psi0.max_psi shown on the scope.

Component Explanation #

All work is done in rt.

Mon, 01 Jan 0001 00:00:00 +0000

RAMP #

Brief #

ramp is a velocity ramp generator with separate acceleration and deceleration limits and an automatic enable output, mainly for spindles in V/f mode. F4 component, used e.g. in conf/haas_spindle*.txt: ramp0.vel_ext_cmd = avg0.out, uf0.vel_cmd = ramp0.vel_cmd, ramp0.max_acc = conf0.max_acc.

Component Explanation #

All work is done in rt. max_vel and max_acc default to 0 and must be set. max_dec <= 0 uses max_acc, so the ramp always decelerates.

Mon, 01 Jan 0001 00:00:00 +0000

RES #

Brief #

res generates the resolver excitation (reference) signal on the FB0 connector of the F4 board and computes the rotor angle from the demodulated sin/cos signals delivered by the adc component. It is loaded by conf/template/res_fb0.txt, which links res0.sin/cos/quad to adc0.sin0/cos0/quad, adc0.res_mode = res0.res_mode, res0.poles = conf0.mot_fb_polecount, res0.vel = fb_switch0.mot_vel and res0.pos to fb_switch0.mot_pos/mot_abs_pos.

Component Explanation #

Reference signal (hw_init and rt):

V4 board: TIM4 is clocked by the ADC master timer trigger (TIM3, ADC_TRIGGER_FREQ = 1.2 MHz). TIM4 channel 3 toggles the reference output on FB0 Z/RES_REF (PD14); the FB0 line driver enable (PD15) is switched on.
Every rt cycle freq is rounded to a multiple of the rt frequency (5 kHz) and clamped to 5..20 kHz (the shipped configs use 5 kHz); the rounded value is written back to freq.

mult = CLAMP(freq / 5000 + 0.5, 1, 4);
ARR = 1.2e6 / 2 / (5000 * mult) - 1;
CCR3 = CLAMP(phase * ARR, 0, ARR - 1);
res_mode = ADC_GROUPS / 2 / mult; // = 12 / mult, ADC sample groups per half wave

phase must be tuned so that amp is maximal (the configs use 0.89..0.9).

Signal check (rt):

amp = sqrt(sin^2 + cos^2). If amp < min_amp: error = 1, state = 0, pos is not updated. Otherwise error = 0, state = 3.

Angle (rt):

pos_e = atan2(sin, cos) (computed with atan2_fast(), a polynomial approximation with about 3e-7 rad maximum error), plus a delay compensation of half an rt period: dpos = vel * period / 2.
poles = 1: pos = mod(pos_e + dpos).
poles > 1 (multi-speed resolver): the electrical cycle is counted by watching quad (quadrant from adc) change 2 -> 3 (+1) or 3 -> 2 (-1), wrapped to 0..poles-1, and

pos = mod((pos_e + cycle * 2 * pi) / poles + dpos); // rad, +-pi

With poles > 1 the cycle counter starts at 0 at power up, so the mechanical position is only relative (not absolute) and a missed quadrant change shifts it by one electrical cycle. The rt code uses the V4 macros RT_FREQ, ADC_TRIGGER_FREQ and ADC_GROUPS, so the component only builds for V4 (the source comment “clk = TIM_MASTER(TIM2)” is stale, TIM_MASTER is TIM3 on V4).

Mon, 01 Jan 0001 00:00:00 +0000

RESLIMIT #

Brief #

reslimit quantizes a position to a given number of steps per turn. In conf/template/pid.txt and mpid.txt it sits between the position command and the controller (reslimit0.pos_in = rev0.out, pid0.pos_ext_cmd = reslimit0.pos_out) with reslimit0.res = conf0.mot_fb_res, so the command is limited to the resolution of the motor feedback. It runs on the F4 board.

Component Explanation #

Quantization (in rt):

pos_out = (int)(pos_in * res / (2 pi) + 0.5) / res * 2 pi;

res must not be 0 (division by zero, TODO in the code). The (int) cast truncates towards zero, so rounding is wrong for negative positions and the step around 0 is twice as wide (the “offset at zerocross” TODO).

Mon, 01 Jan 0001 00:00:00 +0000

REV #

Brief #

rev optionally reverses the direction of a position and its derivative. F4 component, normally used on the command path: e.g. rev0.in = vel_int0.pos_out, rev0.rev = conf0.cmd_rev, reslimit0.pos_in = rev0.out, pid0.vel_ext_cmd = rev0.out_d, and in the sserial templates rev0.in_dd = vel_int0.acc_out, pid0.acc_ext_cmd = rev0.out_dd (acceleration feedforward from the host frames).

Component Explanation #

Reversal (rt):

If rev > 0: out = minus(0, in) (negated and wrapped to +-pi), out_d = -in_d and out_dd = -in_dd.
Otherwise the inputs are passed through unchanged.

Pins #

Name	Description
in	input, Position (rad)
out	output, Position, negated if rev > 0 (rad, +-pi)
in_d	input, Derivative of the position (rad/s)
out_d	output, Derivative, negated if rev > 0 (rad/s)
in_dd	input, Second derivative of the position (rad/s^2)
out_dd	output, Second derivative, negated if rev > 0 (rad/s^2)
rev	parameter, Reverse direction if > 0

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

RL #

Brief #

rl is a minimal resistance / inductance measurement that drives hv0 in voltage mode on the d axis. It runs on the F4 board and is loaded by the rl template. It has no nrt function and prints nothing: the results are read from the r, ld and et pins (the template puts ud_cmd, hv0.id_fb, r and ld on the scope waves). For a full motor identification use id_pmsm / idpmsm instead.

Mon, 01 Jan 0001 00:00:00 +0000

RLPSIJ #

Brief #

rlpsij is an experimental all-in-one PMSM identification: resistance, feedback offset, pole pairs, flux psi, load torque, friction, damping and inertia j in one automatic sequence. It is built into the F4 firmware but no template in conf/template loads it, so it has to be loaded and wired by hand (load rlpsij, then connect cmd_mode, d_cmd, q_cmd, com_pos, en_out to hv0, the hv0 d/q current and voltage feedback back in, and an absolute motor position to abs_pos_fb). It prints nothing; results are read from the pins. The maintained path is id_pmsm followed by id_mot.

Mon, 01 Jan 0001 00:00:00 +0000

SCALE #

Brief #

scale multiplies one signal by scale and divides another one by it. F4 component; not used by any config in conf/.

Component Explanation #

Output (rt):

out0 = in0 * scale, out1 = in1 / MAX(scale, 0.001).
There is no default, so scale is 0 until set.

Pins #

Name	Description
in0	input, Signal to multiply
out0	output, in0 * scale
in1	input, Signal to divide
out1	output, in1 / scale (scale clamped to >= 0.001)
scale	parameter, Scale factor

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

SENSORLESS #

Brief #

The sensorless component is responsible for estimating the motor’s velocity and position in real-time using electrical measurements. It applies low-pass filtering, back EMF calculation, velocity compensation, and position integration to achieve this.

Description #

Input Reading and Initialization:

l and r are ensured to be positive.
The voltage measurements ud and uq are updated using a delay line (ud2, uq2, ud1, uq1, ud, uq).
The current measurements id and iq are read from the input pins.

Gain Clamping:

The gains kb, ki, and kl are clamped to ensure they stay within valid ranges.

Low-Pass Filtering of Current Changes:

The changes in currents delta_id and delta_iq are calculated using a low-pass filter. This helps to smooth out noise in the current measurements.
The previous current values old_id and old_iq are updated to the current measurements.

Back EMF Calculation:

The back EMF (ed and eq) is estimated using the motor’s electrical equations. The back EMF is the voltage generated by the motor due to its rotation.
The equations used are:

ed = ud - r * id - PIN(delta_id) * l / period + vel * l * iq * kb;
eq = uq - r * iq - PIN(delta_iq) * l / period - vel * l * id * kb;

Velocity Compensation:

The estimated velocity vel is adjusted to compensate for the back EMF. The goal is to make the d-axis back EMF (ed) approach zero, which helps in stabilizing the control.
The compensation is done using the following equation:

vel -= SIGN2(eq, 1.0) * ed * ki * period;

Startup Boost:

If the absolute value of the estimated velocity is below a minimum threshold (min_vel), a boost is added to help the motor start up more reliably.
The boost is applied using the following equation:

vel += SIGN2(id * iq, 0.1) * PIN(vel_boost);

Velocity Limiting:

The estimated velocity is limited to ensure it does not exceed the maximum allowed value (max_vel).

Position Update:

The estimated position pos is updated by integrating the estimated velocity over time.
The position is wrapped using the mod function to ensure it stays within a valid range (e.g., 0 to 2π for angular position).

Pins #

Name	Description
r	parameter, Resistance of the motor (R)
l	parameter, Inductance of the motor (L)
ki	parameter, Integral gain for velocity compensation
kb	parameter, Back EMF gain
kl	parameter, Low-pass filter gain for current changes
min_vel	parameter, Minimum velocity threshold for startup boost
vel_boost	parameter, Velocity boost factor for startup
max_vel	parameter, Maximum allowed velocity
id	input, D-axis current
iq	input, Q-axis current
ud	input, D-axis voltage (current measurement)
uq	input, Q-axis voltage (current measurement)
ud1	internal, Delayed D-axis voltage (one sample delay)
uq1	internal, Delayed Q-axis voltage (one sample delay)
ud2	internal, Delayed D-axis voltage (two sample delays)
uq2	internal, Delayed Q-axis voltage (two sample delays)
vel	output, Estimated velocity of the motor
pos	output, Estimated position of the motor
ed	output, D-axis back EMF
eq	output, Q-axis back EMF
old_id	Previous D-axis current
old_iq	Previous Q-axis current
delta_id	output, Change in D-axis current
delta_iq	output, Change in Q-axis current

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

SIM #

Brief #

sim is a test signal generator. It outputs a sine wave, its first and second integral, a square wave and a ramp, with adjustable amplitude, frequency and offset. It is used to drive a motor or feedback test without a real command, for example conf/template/com_test.txt links hv0.pos = sim0.vel to turn the field at a fixed speed, and the pid, mpid and uf templates load it. It runs in the rt.

Mon, 01 Jan 0001 00:00:00 +0000

SISERIAL #

Brief #

The siserial component is a simple UART link that lets an external controller (for example a microcontroller or PC) send an enable word and two float values to the drive, and receive two float values back. It was adapted from the spietari/stmbl fork and is not used by any config or template in this repository.

Experimental and F4-only. It uses the same hardware as sserial and smart_torque (UART4 TX on PA0, USART1 RX on PA10, TX enable PB7 driven high, DMA1_Stream4 TX, DMA2_Stream5 RX), so only one of these components can be loaded. The link runs at 115200 baud, 8N1.

Mon, 01 Jan 0001 00:00:00 +0000

SL_SEQ #

Brief #

The sl_seq component starts a motor without an encoder and hands it to the observer (obs), for a PMSM and an induction motor alike.

States #

off: en = 0. Everything reset, obs tracks.
align: current i_f on d at a standing frame for align_time. PMSM: the rotor turns onto the d axis. Induction motor: the flux builds (about 3 tr, what align_time 0 uses).
I/f: the frame turns at f, which ramps toward vel_cmd at acc, with i_f on d. The rotor follows the rotating current. obs tracks the frame below w_hand / 2, so it starts with the right direction, then runs free.
observer: angle0 from obs (src 2), d and q from the drive (d_in, q_in, pmsm_ttc0 or acim_foc0), pid_en = 1, pid closes the speed loop on obs0.vel_m, while d goes from i_f to d_in over fade_time so the current does not step. Entered once obs is ok, |f| >= w_hand and obs ran free lock_time. Back to 2 when obs drops ok or |obs0.vel_m| < w_hand - hyst, with f seeded from obs0.vel_m.

vel_ref and acc_ref replace the command into pid: they follow f in I/f and, from the handover, ramp from the observed speed to vel_cmd at acc, so the handover is bumpless and pid gets acceleration feedforward.

Mon, 01 Jan 0001 00:00:00 +0000

SMART_TORQUE #

Brief #

The smart_torque component receives an enable word and a torque limit from an external controller over a UART link and sends one float value back. It was adapted from the spietari/stmbl fork. conf/festo.txt uses it: fault0.en = smart_torque0.enable, pid0.max_torque = smart_torque0.torque_pos, pid0.min_torque = smart_torque0.torque_neg and smart_torque0.out0 = enc_fb0.pos, so the external controller sets a symmetric torque limit and reads back the position.

Experimental and F4-only. It uses the same hardware as sserial and siserial (UART4 TX on PA0, USART1 RX on PA10, TX enable PB7 driven high, DMA1_Stream4 TX, DMA2_Stream5 RX), so only one of them can be loaded. The link runs at 115200 baud, 8N1.

Mon, 01 Jan 0001 00:00:00 +0000

SMARTABS #

Brief #

The smartabs component reads the single-turn position of a Tamagawa SmartABS style serial absolute encoder (2.5 Mbit/s half-duplex RS485). It is used on the F4 board through conf/template/smartabs_fb0.txt, which links smartabs0.pos to fb_switch0.mot_pos / mot_abs_pos, smartabs0.state to fb_switch0.mot_state and smartabs0.error to fault0.mot_fb_error.

Hardware-specific: it uses USART6 TX on PC6 in half-duplex mode, a TX enable on PD15 and DMA2_Stream1, all hard coded rather than taken from the board’s feedback definitions.

Mon, 01 Jan 0001 00:00:00 +0000

SPID #

Brief #

spid is a generic single loop PID controller with feedforward, output limits, dynamic anti windup and an output offset. It works on any unit. It is compiled into the F4 firmware but not loaded by any template or config in conf/.

Component Explanation #

All work is done in rt. There is no nrt_init, so all gains and limits start at 0.

Error:

error = cmd - fb (not wrapped), limited to +-max_error when max_error > 0.
cmd_d and error_d are the derivatives of cmd and error over one period.

Proportional / feedforward part:

output = cmd * kff0 + cmd_d * kff1 + error * kp + error_d * kd;
output = CLAMP(output, min_output - offset, max_output - offset);

Integrator (error_sum, internal):

error_sum += error * ki * period + error_d * kdi * period.
ksdi adds error_d / abs(error) * ksdi * period, only while the error is larger than 0.1 % of the output range divided by ksdi.
The integrator is clamped to the headroom left by the P output (dynamic anti windup) and then added to the output.

Enable, saturation and offset:

With en <= 0 the output and integrator are 0, but offset is still added, so the output is offset while disabled.
sat counts up by period while the output is at 99 % of min_output or max_output, and is reset to 0 immediately otherwise.
output = output + offset.

The “scaled differential” ksd term (error_d / abs(error) * ksd) is added to the integrator, not to the output, and without period, so it does not behave like a differential term. The 99 % saturation test assumes min_output < 0 < max_output. Treat ksd/ksdi as experimental.

Mon, 01 Jan 0001 00:00:00 +0000

SSERIAL #

Brief #

The sserial component makes the drive a Mesa smart serial (sserial / LBP) remote, so LinuxCNC’s hostmot2 driver can talk to it like a Mesa daughter card (card name stbl). LinuxCNC sends position and velocity commands, 4 digital outputs, enable, index enable and the linrev scale; the drive answers with position and velocity feedback, current, 4 digital inputs, fault, index enable and a fault code. On the F4 board it is loaded by conf/template/sserial.txt (and sserial_dummy.txt), which feeds sserial0.pos_cmd / pos_cmd_d through linrev0 and vel_int0 into the controller, links fault0.en = sserial0.enable, sserial0.fault_code = fault0.last_fault, linrev0.scale = sserial0.scale, sserial0.pos_fb = linrev0.fb_out, sets sserial0.pos_advance = 0.0003, sserial0.current = hv0.iq_fb and io0.clock_scale = sserial0.clock_scale.

Mon, 01 Jan 0001 00:00:00 +0000

STP #

Brief #

stp is a simple point to point trajectory planner with velocity and acceleration limits, soft limits and a jog input. F4 component, used in conf/template/jog_cmd.txt (stp0.jog = jog0.jog, rev0.in = stp0.mpos) and conf/festo.txt.

Component Explanation #

All work is done in rt. Positions are not wrapped, only mpos is.

Target generation:

target is moved by vel_ext_cmd + jog * max_vel (limited to 0.99 * max_vel) and acc_ext_cmd (limited to 0.99 * max_acc). vel_ext_cmd itself is integrated with acc_ext_cmd and written back.
target is clamped to min_pos..max_pos.

Planning (every period):

dtg = target - pos. The time to stop at the target from standstill with max_acc is sqrt(2 |dtg| / max_acc), rounded up to whole periods (ttg).
The velocity for that time is limited to max_vel; the acceleration needed to reach it in one period is limited to max_acc and output as acc_cmd.
pos and vel_cmd are integrated with acc_cmd.

Target reached:

When less than one period to go and |vel_cmd| < max_acc * period, pos is set to target and vel_cmd to 0.
at_target = 1 when at most one period to go and |vel_cmd| < max_vel / 10000.

Pins #

Name	Description
target	input/output, Target position, clamped and moved by jog (rad)
vel_ext_cmd	input/output, External velocity, integrated from acc_ext_cmd (rad/s)
acc_ext_cmd	input, External acceleration (rad/s^2)
jog	input, Jog -1..1, multiplied with max_vel
pos	output, Planned position, not wrapped (rad)
mpos	output, Planned position, wrapped (rad, +-pi)
vel_cmd	output, Planned velocity (rad/s)
acc_cmd	output, Planned acceleration (rad/s^2)
max_pos	parameter, Upper soft limit (rad), default 20pi
min_pos	parameter, Lower soft limit (rad), default -20pi
max_vel	parameter, Maximum velocity (rad/s), default 2pi
max_acc	parameter, Maximum acceleration (rad/s^2), default 20pi
dtg	output, Distance to go (rad)
ttg	output, Time to go (s)
at_target	output, 1 = target reached

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

SVM #

Brief #

svm adds a common mode offset to three phase voltages centred on 0, so that they fit into the 0..udc range of the half bridges. The choice of offset sets the modulation: sine, space vector (the default), flat bottom or flat top. It is built into both the F3 (HV board) and the F4 firmware, but stm32f303/src/main.c no longer loads it: on the F3, hv0 now takes idq0’s phase voltages directly, adds the dead time compensation and then applies the same space vector (midpoint) offset itself, so the offset sees the compensated phases. No template in conf/ loads svm either, so it is only there to be loaded by hand.

Mon, 01 Jan 0001 00:00:00 +0000

TERM #

Brief #

term is the serial terminal of a board. It runs the command line (every received line goes to hal_parse, so HAL commands and pin settings can be typed) and streams the 8 wave pins as scope samples to the host (the Servoterm oscilloscope). On the F4 it can also take a triggered capture of 1024 samples and upload it. It is loaded by default as term0 on both the F4 and the F3. On the F4 it talks over USB. On the F3 (HV board) there is no USB: its terminal bytes travel one per packet over the link to the F4 (ls on the F3, hv on the F4), and main.c sets term0.send_step = 0 there, so no wave data is sent. Typical use on the F4 is a config line like term0.wave0 = pid0.pos_error with term0.gain0 to scale it (see conf/template/obs_check.txt).

Mon, 01 Jan 0001 00:00:00 +0000

TH #

Brief #

th is a window comparator with an input low pass: out is 1 while the filtered input is between min and max. It runs on the F4 board. In conf/move.txt it detects a hard stop for homing: th0.in = pid0.torque_cmd, min = -1, max = 1, in_lpf = 0.25, home0.home_in = th0.out_not.

Component Explanation #

Filter (in rt): in_lp += (in - in_lp) * in_lpf every rt cycle. in_lpf is a factor per cycle (0..1), not a frequency.

Mon, 01 Jan 0001 00:00:00 +0000

UF2 #

Brief #

Deprecated: use vf instead (templates vf and vf_enc), whose slip compensation is signed and which has damping, stall prevention and an encoder path. uf is kept for old configs and is not being fixed; its known faults are listed below.

Open loop V/f (voltage over frequency) control for induction motors, with slip compensation. Note that this file registers the component as uf (HAL_COMP(uf)), so it is loaded with load uf and its pins are uf0.*; the older uf.c is no longer built. It runs on the F4 board and is loaded by conf/template/uf.txt: uf0.u_cmd -> hv0.d_cmd (with hv0.cmd_mode = 0, voltage mode), uf0.com_pos -> hv0.pos, uf0.cur = hv0.abs_cur, uf0.scale = fault0.scale, uf0.polecount = conf0.polecount. The speed command is set by the user, e.g. uf0.vel_cmd = ramp0.vel_cmd in conf/bene_uf_2kw.txt.

Mon, 01 Jan 0001 00:00:00 +0000

USART #

Brief #

usart is an experimental test component for half-duplex serial absolute encoders on the fb0 connector of the F4 logic board: every rt period it sends a request byte and receives the answer by DMA, extracts a position from the answer and can print the raw bytes. No template loads it.

Component Explanation #

Hardware (hw_init):

USART6 in half-duplex mode on PC6 (the fb0 UART TX line), PD15 switches the fb0 RS485 transmitter (FB0_Z_TXEN), DMA2 stream 1 receives up to 16 bytes.

Request (rt):

Each rt period the USART is re-initialised with baud rate freq, the transmitter is enabled, the byte req is sent, rt busy-waits until it is out, the transmitter is disabled and the RX DMA restarted. The answer is evaluated in the next rt period.

Position (rt):

Received bytes starting at byte pos_offset are copied into a 64 bit little endian integer, masked and scaled to pos:

pos = raw * 2 * pi / 2^pos_len - pi;

Debug print (rt/nrt):

Setting print > 0 captures the 16 receive bytes (and clears the buffer) and makes nrt print the request byte, the DMA count and all bytes in binary, LSB first. The next capture is possible once the print is done.

Experimental and broken as it is: pos_len is used as a byte count for the copy loop but as a bit count for the mask. With the default the loop writes 20 bytes into an 8 byte variable and reads past the 16 byte receive buffer (stack corruption), and the mask (2 << pos_len) - 1 keeps one bit more than pos_len. It only runs without memory corruption for pos_len <= 8, and then the position has at most 9 bits.

Mon, 01 Jan 0001 00:00:00 +0000

UVW #

Brief #

The uvw component turns the three digital hall / commutation signals u, v, w of a motor into a commutation angle with 60 deg resolution. On the F4 board conf/template/uvw_fb0.txt (or uvw_fb1.txt) reads the signals from io0.fb0a, io0.fb0b, io0.fb0z, links uvw0.amp = adc0.amp0 and feeds fb_switch0.com_pos, com_abs_pos and com_state. conf/template/encws_fb0.txt combines it with enc_fb0 in line saving mode (uvw0.mode = 1).

Component Explanation #

Hall code (rt):

The code is rpos = u + 2 * v + 4 * w (0..7) and is always written to rpos, which helps to find the table values while turning the motor by hand.

Code to sector table:

The angle from the sector table p0..p7 is

pos = mod(p[rpos] / 6.0 * 2.0 * M_PI);

Defaults set in nrt_init: p0 = -1, p1 = 0, p2 = 2, p3 = 1, p4 = 4, p5 = 5, p6 = 3, p7 = -1 (codes 0 and 7 are faults). The table values are truncated to integers.

Signal check:

If amp < 0.75, the component sets error = 1, state = 0 and resets timer; pos is not updated. amp is meant to carry the feedback signal amplitude (adc0.amp0); if it is left unlinked it stays 0 and the component is always in error, so link it or set it to 1.

Mode 0, plain UVW (mode = 0):

Valid code (table value >= 0): state = 3 (absolute), error = 0, pos updated.
Invalid code: error = 1, state = 0, pos keeps its last value.

Mode 1, line saving (mode = 1):

Used by encoders that send the UVW signals on the A/B/Z lines only right after power-up. For the first en_time / 2 seconds after amp becomes valid, pos is updated from the table and timer counts up by the rt period. After that pos is frozen, state = 2 (start absolute position) and error = 0, so fb_switch can take over with the incremental encoder.

In mode 1 the table value is not checked, so an invalid code (-1) during the startup window gives pos = -60 deg instead of an error. state and error are not written during that window.

Mon, 01 Jan 0001 00:00:00 +0000

VEL #

Brief #

vel is a tracking observer (a second order PLL with optional torque feedforward) that estimates velocity and a filtered position from a position signal. It is an F4 component and is loaded several times in the templates: e.g. vel1.pos_in = fb_switch0.vel_fb with pid0.vel_fb = vel1.vel gives the velocity feedback, vel2.pos_in = fb_switch0.com_fb gives a filtered commutation angle for hv0.pos, and vel0.pos_in = rev0.out differentiates the position command.

Mon, 01 Jan 0001 00:00:00 +0000

VEL_INT #

Brief #

vel_int interpolates a position command that arrives at a lower or irregular rate (e.g. from LinuxCNC via smart serial) by integrating the commanded velocity between updates. F4 component, loaded by conf/template/sserial.txt: vel_int0.pos_in = linrev0.cmd_out, vel_int0.vel_in = linrev0.cmd_d_out, rev0.in = vel_int0.pos_out, rev0.in_d = vel_int0.vel_out (to pid0.vel_ext_cmd) and rev0.in_dd = vel_int0.acc_out (to pid0.acc_ext_cmd), with vel_int0.max_acc = conf0.max_acc. It also gives the acceleration feedforward on the sserial path, where vel0 is off and pid.txt’s vel0.acc link is 0.

Mon, 01 Jan 0001 00:00:00 +0000

VELBUF #

Brief #

velbuf computes a velocity from a position signal by taking the difference over an adaptive time window from a ring buffer. This gives usable velocities from coarse or slowly changing positions. F4 component, see conf/template/velbuf.txt (velocity of the position command rev0.out, used as pid0.vel_ext_cmd). It needs both an rt_prio and an frt_prio: the frt part fills the buffer, without an frt_prio it never runs.

Mon, 01 Jan 0001 00:00:00 +0000

VELTIME #

Brief #

veltime measures velocity by timing how long it takes until a position changes (period measurement instead of frequency measurement). Useful for low resolution or slowly updating positions. F4 component, runs in frt. Used in conf/template/mpid.txt: veltime0.pos = rev0.out, mpid0.vel_ext_cmd = veltime0.vel_lp.

Component Explanation #

Measurement:

timer is incremented every frt period. When pos differs from old_pos, vel = minus(pos, old_pos) / timer, old_pos is updated and timer is reset.
The velocity is held until the next change.

Standstill:

If no change happens within max_time, vel is set to 0 and timer is clamped to max_time. The lowest measurable velocity is therefore about one position step per max_time.

Pins #

Name	Description
pos	input, Position (rad)
old_pos	output, Position at the last change (internal state, rad)
timer	output, Time since the last position change (internal state, s)
vel	output, Velocity (rad/s)
vel_lp	output, Low pass filtered velocity (rad/s)
max_time	parameter, Time without change after which vel is 0 (s), default 0.1
lpf	parameter, Cutoff of the vel_lp filter (Hz), default 100

References #

Source: .c File

Mon, 01 Jan 0001 00:00:00 +0000

VELTOPOS #

Brief #

veltopos integrates a velocity command into an electrical angle, with the velocity limited relative to the measured velocity. Intended for open loop / sensorless style commutation. F4 component; it is not used by any config in conf/.

Component Explanation #

All work is done in rt. There is no nrt_init, all pins start at 0.

Acceleration and velocity limit:

The velocity is clamped to vel_fb +- max_acc * period, i.e. it may only be ahead of or behind the measured velocity by one period of max_acc. With max_acc = 0 the output follows vel_fb.
If max_vel > 0, the result is then limited to +-max_vel.

Integration:

pos += vel * polecount * period, wrapped with mod().

Experimental.

Mon, 01 Jan 0001 00:00:00 +0000

VF #

Brief #

vf runs an induction motor open loop, V/f, and replaces uf (uf2.c) for new configs. It is loaded by conf/template/vf.txt: its frequency vel_e goes to angle0.vel_cmd (angle0.src 3) and its voltage u_cmd to hv0.d_cmd in volt mode (hv0.cmd_mode 0, hv0.q_cmd 0). en and scale come from fault0, the currents and voltages from hv0, dc_hold from conf0.high_dc_volt. conf/template/vf_enc.txt links vf, adds fb_switch and vel and sets vf0.vel_fb = vel0.vel, vf0.enc = 1 for slip frequency control on an encoder, and vel0.torque = vf0.torque. The speed command is vf0.vel_cmd (rad/s mech).

Mon, 01 Jan 0001 00:00:00 +0000

YASKAWA #

Brief #

The yaskawa component reads the absolute position of a Yaskawa Sigma serial encoder (as on SGMPH motors) over the F4 board’s feedback 0 Z line. It is loaded by conf/sgmph-*.txt and conf/sda_b.txt, which link yaskawa0.pos to fb_switch0.mot_pos / mot_abs_pos and yaskawa0.error to fault0.mot_fb_error.

Experimental, F4-only, bit-banged driver. The rt function busy-waits for the previous reply and for the end of the request, so it takes a large part of the rt period. Hardware used: the FB0_Z pin and its TX enable, TIM8 (8 MHz DMA pacing for the request), the feedback timer channel 3 in input capture mode, DMA2_Stream1 (TX) and DMA1_Stream7 (RX).

Mon, 01 Jan 0001 00:00:00 +0000

YPID #

Brief #

ypid is a simple cascaded position (P) / velocity (PI) controller whose output out has no fixed unit (for example a current or torque command). It is compiled into the F4 firmware but not loaded by any template or config in conf/ (the F3 build has it commented out). For normal servo use see pid.

Component Explanation #

All work is done in rt. There is no nrt_init: all pins start at 0. Negative gains are treated as 0.

Mon, 01 Jan 0001 00:00:00 +0000

ZV_IP #

Brief #

This is an experimental component, it’s not fully tested.

The zv_ip component is responsible for applying a Zero Vibration (ZV) input shaper to the position and velocity commands of a motor. It reads the position and velocity commands, calculates the shaped commands, and outputs them for further processing.

Component Explanation #

The zv_ip component applies a Zero Vibration (ZV) input shaper to the position and velocity commands of a motor. This component operates within a hardware abstraction layer (HAL) framework, providing real-time control and non-real-time initialization functions.

HAL Components on STMBLv5 Documentation

ACIM_FLUX #

Brief #

Model #

ACIM_FOC #

Brief #

Behaviour #

Pins #

References #

ACIM_FW #

Brief #

ACIM_TTC #

Brief #

Component Explanation #

ADC #

Brief #

AND #

Brief #

Component Explanation #

Pins #

References #

ANGLE #

Brief #

Sources (src) #

AVG #

Brief #

Component Explanation #

Pins #

References #

BIQUAD #

Brief #

CONF #

Brief #

CURPID #

Brief #

DC_LIMITS #

Brief #

Component Explanation #

DC_TTC #

Brief #

Component Explanation #

Pins #

References #

DEBOUNCE #

Brief #

Component Explanation #

Pins #

References #

DMM #

Brief #

Component Explanation #

DOB #

Brief #

DQ #

Brief #

EMF #

Brief #

EN #

Brief #

ENC_CMD #

Brief #

Component Explanation #

ENC_FB #

Brief #

Component Explanation #

ENCF #

Brief #

Component Explanation #

ENCM #

Brief #

Component Explanation #

ENCS #

Brief #

Component Explanation #

ENDAT #

Brief #

Component Explanation #

FANUC #

Brief #

Component Explanation #

Sources (`src`) #