BLDC(9)
💖 BLDC(9) — HAL Component 💖
okay so bestie, this is the manual for the bldc component, and it's giving main character energy. let's get into it, no cap.
✨ NAME ✨
bldc — BLDC and AC-servo control component. periodt.
🌸 SYNOPSIS 🌸
loadrt bldc cfg=qi6,aH🦋 DESCRIPTION 🦋
so this component is designed as an interface between the most common forms of three-phase motor feedback devices and the corresponding types of drive. but here's the tea: there is no requirement that the motor and drive should necessarily be of inherently compatible types. fr fr, you can mix and match.
each instance of the component is defined by a group of letters describing the input and output types. a comma separates individual instances of the component. for example loadrt bldc cfg=qi6,aH. yep, that's the vibe.
🏷️ Tags 🏷️
input type definitions are all lower-case, bestie. let's break them down:
n— No motor feedback. this mode could be used to drive AC induction motors, but is also potentially useful for creating free-running motor simulators for drive testing. it's giving "simulation slay".h— Hall sensor input. Brushless DC motors (electronically commutated permanent magnet 3-phase motors) typically use a set of three Hall sensors to measure the angular position of the rotor. a lower-casehin thecfgstring indicates that these should be used. so if you see anh, that's what's up.a— Absolute encoder input. (Also possibly used by some forms of Resolver conversion hardware). the presence of this tag over-rides all other inputs. note that the component still requires to be be connected to therawcountsencoder pin to prevent loss of commutation on index-reset. do not skip that, bestie, it's important. (and yes, the original says "be be", we're keeping that energy.)q— Incremental (quadrature) encoder input. if this input is used then the rotor will need to be homed before the motor can be run. so don't forget to home it, okay?i— Use the index of an incremental encoder as a home reference. it's the little reference point that could.f— Use a 4-bit Gray-scale patttern to determine rotor alignment. this scheme is only used on the Fanuc "Red Cap" motors. this mode could be used to control one of these motors using a non-Fanuc drive. (yes, "patttern" — we don't make the rules, we just report them.)
output type descriptions are all upper-case. and here's the defaults tea:
Defaults — The component will always calculate rotor angle, phase angle and the absolute value of the input value for interfacing with drives such as the Mesa 8I20. It will also default to three individual, bipolar phase output values if no other output type modifiers are used. so that's the baseline, bestie.
now the output modifiers:
B— Bit level outputs. Either 3 or 6 logic-level outputs indicating which high or low gate drivers on an external drive should be used. it's giving "gatekeeping, but literally".6— Create 6 rather than the default 3 outputs. In the case of numeric value outputs these are separate positive and negative drive amplitudes. Both have positive magnitude. double the outputs, double the fun.H— Emulated Hall sensor output. This mode can be used to control a drive which expects 3x Hall signals, or to convert between a motor with one hall pattern and a drive which expects a different one. it's the translator of the motor world.F— Emulated Fanuc Red Cap Gray-code encoder output. This mode might be used to drive a non-Fanuc motor using a Fanuc drive intended for the "Red-Cap" motors. cross-compatibility? we love to see it.T— Force Trapezoidal mode. sometimes you just gotta force it, iykyk.
🔥 OPERATING MODES 🔥
the component can control a drive in either Trapezoidal or Sinusoidal mode, but will always default to sinusoidal if the input and output modes allow it. this can be over-ridden by the T tag. Sinusoidal commutation is significantly smoother (trapezoidal commutation induces 13% torque ripple). so like, sinusoidal is the smooth operator, and trapezoidal has that 13% torque ripple. choose wisely.
🎀 ROTOR HOMING. 🎀
to use an encoder for commutation a reference 0-degrees point must be found. the component uses the convention that motor zero is the point that an unloaded motor aligns to with a positive voltage on the A (or U) terminal and the B & C (or V and W) terminals connected together and to -ve voltage. there will be two such positions on a 4-pole motor, 3 on a 6-pole and so on. they are all functionally equivalent as far as driving the motor is concerned. so don't stress about which one, bestie.
if the motor has Hall sensors then the motor can be started in trapezoidal commutation mode, and will switch to sinusoidal commutation when an alignment is found. if the mode is qh then the first Hall state-transition will be used. if the mode is qhi then the encoder index will be used. this gives a more accurate homing position if the distance in encoder counts between motor zero and encoder index is known. to force homing to the Hall edges instead simply omit the i. so qh vs qhi is the vibe check here.
motors without Hall sensors may be homed in synchronous/direct mode. the better of these options is to home to the encoder zero using the iq config parameter. when the init pin goes high the motor will rotate (in a direction determined by the rev pin) until the encoder indicates an index-latch (the servo thread runs too slowly to rely on detecting an encoder index directly). if there is no encoder index or its location relative to motor zero can not be found, then an alternative is to use magnetic homing using the q config. in this mode the motor will go through an alignment sequence ending at motor zero when the init pin goes high It will then set the final position as motor zero. unfortunately the motor is rather springy in this mode and so alignment is likely to be fairly sensitive to load. so like, it's a little extra, but it works.
💅 FUNCTIONS 💅
bldc.N (requires a floating-point thread)
bestie this is only part 1, part 2 is coming 💅
💅 PINS 💅
okay bestie, strap in, because this is the whole pin list and honestly it's giving encyclopedia energy 📚 but we do NOT skip pins in this house, every single one is getting its moment, periodt. ✨
🚨 heads up before you plug ANYTHING in: a whole bunch of these pins only exist if the personality bitmask test in the brackets passes. If the [if ...] thing is false, that pin literally does not exist — not quiet, not hidden, just gone. Read the bracket first, wire second. iykyk 💀
bldc.N.hall1—bit in[if personality & 0x01]— Hall sensor signal 1 🌀 (that's the first one, bestie)bldc.N.hall2—bit in[if personality & 0x01]— Hall sensor signal 2 🌀bldc.N.hall3—bit in[if personality & 0x01]— Hall sensor signal 3 🌀bldc.N.hall-error—bit out[if personality & 0x01]— screaming (politely) that the hall pattern you picked is giving inconsistent rotor position data 😭 this can happen because the pattern is just wrong for that motor, or because one or more of the sensors is unconnected / broken. and here's the tea: a consistent pattern isn't necessarily a valid one, but an inconsistent one can never be valid. so like, consistency is necessary not sufficient, okurrr 💅bldc.N.C1—bit in[if ( personality & 0x10 )]— Fanuc Gray-code bit 0 input 🧚bldc.N.C2—bit in[if ( personality & 0x10 )]— Fanuc Gray-code bit 1 input 🧚bldc.N.C4—bit in[if ( personality & 0x10 )]— Fanuc Gray-code bit 2 input 🧚bldc.N.C8—bit in[if ( personality & 0x10 )]— Fanuc Gray-code bit 3 input 🧚bldc.N.value—float in— the PWM master amplitude input 👑 the big boss amplitude, no capbldc.N.lead-angle—float in[if personality & 0x06](default: 90) — the phase lead between the electrical vector and the rotor position, measured in degrees 📐bldc.N.rev—bit in— set this bad boytrueand the motor spins backwards 🔄 and lowkey there's more than one way to do it: negative PWM amplitudes will also reverse the motor, and generally there'll be a Hall pattern that runs the motor in each direction too. options, bestie ✨bldc.N.frequency—float in[if ( personality & 0x0F ) == 0]— frequency input for motors with no feedback at all, or the ones that only have an index (which, btw, gets ignored) 🙈bldc.N.initvalue—float in[if personality & 0x04](default: 0.2) — the current used for the homing sequence, for when you've got an incremental encoder and zero hall-sensor feedback ⚡bldc.N.rawcounts—s32 in[if personality & 0x06](default: 0) — encoder counts input. and this is a must: it has to be linked to the encoderrawcountspin, otherwise encoder index resets will make the motor commutation just. fail. 💀 no cap, link itbldc.N.index-enable—bit io[if personality & 0x08]— hook this up to the matching encoderindex-enablepin so the encoder gets zeroed when it passes index 🎯 its only job here is letting the bldc control component know an index has been seen, that's it, that's the whole assignmentbldc.N.init—bit in[if ( personality & 0x05 ) == 4]— a rising edge on this pin kicks off the motor alignment sequence 🔥 and it should be wired up in a way that makes the motor re-align anytime encoder monitoring has been interrupted — typically that only happens at machine power-off. the alignment process involves powering the motor phases such that the motor ends up in a known position. the encoder counts then get stored in theoffsetparameter. ⚠️ big warning though: the alignment process will tend to cause a following error if it gets triggered while the axis is enabled, so set it before the matchingaxis.N.enablepin. the complementaryinit-donepin exists to handle the sequencing you need. 🫶
and good news: both of these pins can be ignored entirely if the encoder offset is already known explicitly — like with an absolute encoder 🌈 in that case you just set the offset parameter directly in the HAL file and move on with your life. slay.
bldc.N.init-done—bit out[if ( personality & 0x05 ) == 4](default: 0) — indicates the homing sequence is complete ✅ the little green checkmark of the pin worldbldc.N.A-value—float out[if ( personality & 0xF00 ) == 0]— output amplitude for phase A 🌊bldc.N.B-value—float out[if ( personality & 0xF00 ) == 0]— output amplitude for phase B 🌊bldc.N.C-value—float out[if ( personality & 0xF00 ) == 0]— output amplitude for phase C 🌊bldc.N.A-on—bit out[if ( personality & 0xF00 ) == 0x100]— output bit for phase A 💡bldc.N.B-on—bit out[if ( personality & 0xF00 ) == 0x100]— output bit for phase B 💡bldc.N.C-on—bit out[if ( personality & 0xF00 ) == 0x100]— output bit for phase C 💡bldc.N.A-high—float out[if ( personality & 0xF00 ) == 0x200]— high-side driver for phase A ⬆️bldc.N.B-high—float out[if ( personality & 0xF00 ) == 0x200]— high-side driver for phase B ⬆️bldc.N.C-high—float out[if ( personality & 0xF00 ) == 0x200]— high-side driver for phase C ⬆️bldc.N.A-low—float out[if ( personality & 0xF00 ) == 0x200]— low-side driver for phase A ⬇️bldc.N.B-low—float out[if ( personality & 0xF00 ) == 0x200]— low-side driver for phase B ⬇️bldc.N.C-low—float out[if ( personality & 0xF00 ) == 0x200]— low-side driver for phase C ⬇️bldc.N.A-high-on—bit out[if ( personality & 0xF00 ) == 0x300]— high-side driver for phase A ⬆️ (the bit version this time)bldc.N.B-high-on—bit out[if ( personality & 0xF00 ) == 0x300]— high-side driver for phase B ⬆️bldc.N.C-high-on—bit out[if ( personality & 0xF00 ) == 0x300]— high-side driver for phase C ⬆️bldc.N.A-low-on—bit out[if ( personality & 0xF00 ) == 0x300]— low-side driver for phase A ⬇️bldc.N.B-low-on—bit out[if ( personality & 0xF00 ) == 0x300]— low-side driver for phase B ⬇️bldc.N.C-low-on—bit out[if ( personality & 0xF00 ) == 0x300]— low-side driver for phase C ⬇️bldc.N.hall1-out—bit out[if ( personality & 0x400 )]— Hall 1 output 🌀bldc.N.hall2-out—bit out[if ( personality & 0x400 )]— Hall 2 output 🌀bldc.N.hall3-out—bit out[if ( personality & 0x400 )]— Hall 3 output 🌀bldc.N.C1-out—bit out[if ( personality & 0x800 )]— Fanuc Gray-code bit 0 output 🧚bldc.N.C2-out—bit out[if ( personality & 0x800 )]— Fanuc Gray-code bit 1 output 🧚bldc.N.C4-out—bit out[if ( personality & 0x800 )]— Fanuc Gray-code bit 2 output 🧚bldc.N.C8-out—bit out[if ( personality & 0x800 )]— Fanuc Gray-code bit 3 output 🧚bldc.N.phase-angle—float out(default: 0) — the phase angle, including the lead/lag angle, after encoder zeroing etc. super useful for angle/current drives 💜 value ranges0to1and it measures electrical revolutions. so for a 4 pole motor you get two zeros, a 6-pole gives you three, and so on 🌈bldc.N.rotor-angle—float out(default: 0) — rotor angle after encoder zeroing etc. this one's the moment for angle/current drives that add their own phase offset — the8I20says hi 👋 range is0to1, measured in electrical revolutions, and again: two zeros for a 4 pole motor, three for a 6-pole, etc. etc. 💫bldc.N.out—float out— current output, and yes it includes the effect of thedirpin and the alignment sequence 🎬 the whole ensemble, togetherbldc.N.out-dir—bit out— direction output, and it goes high if value is negative XOR rev is true 🔀 exclusive or sweetie, it's exclusive orbldc.N.out-abs—float out— absolute value of the input value ✨ (what it says on the tin, bestie, no plot twist)
💖 PARAMETERS 💖
okay bestie, this is the big one — every knob, dial and secret setting on your drive lives here. take notes 📝
bldc.N.in-types32 r (default:-1) — state machine output, and ngl it will probably get hidden once the debug era ends 🙈bldc.N.out-types32 r (default:-1) — also state machine output, and also probably getting hidden after debug. twins 💅bldc.N.scales32 rw [ifpersonality & 0x06] (default:512) — how many encoder counts fit in one full rotor revolution. the math girlies know 🔥bldc.N.poless32 rw [ifpersonality & 0x06] (default:4) — how many poles your motor has. here's the tea: the encoder scale gets divided by this number, and that tells you how many encoder counts there are per electrical revolution ⚡bldc.N.encoder-offsets32 rw [ifpersonality & 0x0A] (default:0) — the offset, in encoder counts, between the motor electrical zero and the encoder zero, modulo the number of counts per electrical revolution 🎯bldc.N.offset-measureds32 r [ifpersonality & 0x04] (default:0) — the encoder offset that the homing sequence actually measured (in certain modes). it did the work itself, iconic 💖bldc.N.drive-offsetfloat rw (default:0) — the angle, in degrees, that the drive applies to the commanded angle, in degrees. this one is only used during the homing sequence of drives with incremental encoder feedback, where it back-calculates from commanded angle to actual phase angle. it only matters for drives that want rotor-angle input instead of phase-angle demand. should be0for most drives, fr fr.bldc.N.output-patternu32 rw [ifpersonality & 0x400] (default:25) — the commutation pattern to output when you're in Hall Signal translation mode. see the description ofpatternfor the whole saga 👑bldc.N.patternu32 rw [ifpersonality & 0x01] (default:25) — the commutation pattern to actually use, from0to47. default is type25. they included every plausible combination, no cap. the table has the excitation pattern along the top and the pattern code down the left side, and each entry is the hall patterns inH1,H2,H3order. the common ones, bestie:0— 30 degree commutation26— its reverse17— 120 degree18— alternate 60 degree21— 300 degree, Bodine22— 240 degree25— 60 degree commutation
⚠️ lowkey important: a bunch of incorrect commutations will still have non-zero net torque, so they can look like they're working when they absolutely are not. it's giving fake bestie energy 💀
and if your motor came with zero documentation? honestly just try every single pattern. vibe check the whole table 🌈
┌─────────────────────────────────────────┐
│ Phases, Source - Sink │
├─────┬───────────────────────────────────┤
│ pat │ B-A C-A C-B A-B A-C B-C │
├─────┼───────────────────────────────────┤
│ 0 │ 000 001 011 111 110 100 │
│ 1 │ 001 000 010 110 111 101 │
│ 2 │ 000 010 011 111 101 100 │
│ 3 │ 001 011 010 110 100 101 │
│ 4 │ 010 011 001 101 100 110 │
│ 5 │ 011 010 000 100 101 111 │
│ 6 │ 010 000 001 101 111 110 │
│ 7 │ 011 001 000 100 110 111 │
│ 8 │ 000 001 101 111 110 010 │
│ 9 │ 001 000 100 110 111 011 │
│ 10 │ 000 010 110 111 101 001 │
│ 11 │ 001 011 111 110 100 000 │
│ 12 │ 010 011 111 101 100 000 │
│ 13 │ 011 010 110 100 101 001 │
│ 14 │ 010 000 100 101 111 011 │
│ 15 │ 011 001 101 100 110 010 │
│ 16 │ 000 100 101 111 011 010 │
│ 17 │ 001 101 100 110 010 011 │
│ 18 │ 000 100 110 111 011 001 │
│ 19 │ 001 101 111 110 010 000 │
│ 20 │ 010 110 111 101 001 000 │
│ 21 │ 011 111 110 100 000 001 │
│ 22 │ 010 110 100 101 001 011 │
│ 23 │ 011 111 101 100 000 010 │
│ 24 │ 100 101 111 011 010 000 │
│ 25 │ 101 100 110 010 011 001 │
│ 26 │ 100 110 111 011 001 000 │
│ 27 │ 101 111 110 010 000 001 │
│ 28 │ 110 111 101 001 000 010 │
│ 29 │ 111 110 100 000 001 011 │
│ 30 │ 110 100 101 001 011 010 │
│ 31 │ 111 101 100 000 010 011 │
│ 32 │ 100 101 001 011 010 110 │
│ 33 │ 101 100 000 010 011 111 │
│ 34 │ 100 110 010 011 001 101 │
│ 35 │ 101 111 011 010 000 100 │
│ 36 │ 110 111 011 001 000 100 │
│ 37 │ 111 110 010 000 001 101 │
│ 38 │ 110 100 000 001 011 111 │
│ 39 │ 111 101 001 000 010 110 │
│ 40 │ 100 000 001 011 111 110 │
│ 41 │ 101 001 000 010 110 111 │
│ 42 │ 100 000 010 011 111 101 │
│ 43 │ 101 001 011 010 110 100 │
│ 44 │ 110 010 011 001 101 100 │
│ 45 │ 111 011 010 000 100 101 │
│ 46 │ 110 010 000 001 101 111 │
│ 47 │ 111 011 001 000 100 110 │
└─────┴───────────────────────────────────┘👑 AUTHOR 👑
Andy Pugh — the legend, the moment, the main character ✨
🎀 LICENSE 🎀
GPL — free as in freedom, bestie, go forth and slay 💖
and that's the whole page, babe!! 🌸 this is from the LinuxCNC Documentation, dated 2026-03-17, and the page is BLDC(9). mwah, go wire a motor, you got this 🫶💅
📦 where this page comes from
- ubuntu resolute: linuxcnc-uspace 1:2.9.4-2ubuntu4 · GFDL-1.1-or-later
- ubuntu stonking: linuxcnc-uspace 1:2.9.4-2ubuntu4 · GFDL-1.1-or-later
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms