Provided by: linuxcnc-uspace_2.9.0~pre1+git20230208.f1270d6ed7-1_amd64 bug

NAME

       bldc - BLDC and AC-servo control component

SYNOPSIS

       loadrt bldc cfg=qi6,aH

DESCRIPTION

       This  component  is  designed as an interface between the most common forms of three-phase
       motor feedback devices and the  corresponding  types  of  drive.   However,  there  is  no
       requirement that the motor and drive should necessarily be of inherently compatible types.

       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.

Tags

       Input type definitions are all lower-case.

       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.

       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-case h in the cfg string indicates that these should be used.

       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  the  rawcounts  encoder  pin  to  prevent  loss  of
       commutation on index-reset.

       q  Incremental (quadrature) encoder input.  If this input is used then the rotor will need
       to be homed before the motor can be run.

       i Use the index of an incremental encoder as a home reference.

       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.

       Output type descriptions are all upper-case.

       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.

       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.

       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.

       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.

       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.

       T Force Trapezoidal mode.

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

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

       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.

FUNCTIONS

       bldc.N (requires a floating-point thread)

PINS

       bldc.N.hall1 bit in [if personality & 0x01]
              Hall sensor signal 1

       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]
              Indicates that the selected hall pattern gives inconsistent  rotor  position  data.
              This  can  be  due to the pattern being wrong for the motor, or one or more sensors
              being unconnected or broken.  A consistent pattern is not neceesarily valid, but an
              inconsistent one can never be valid.

       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
              PWM master amplitude input

       bldc.N.lead-angle float in [if personality & 0x06] (default: 90)
              The phase lead between the electrical vector and the rotor position in degrees

       bldc.N.rev bit in
              Set  this  pin  true to reverse the motor. Negative PWM amplitudes will alsoreverse
              the motor and there will generally be a Hall pattern that runs the  motor  in  each
              direction too.

       bldc.N.frequency float in [if ( personality & 0x0F ) == 0]
              Frequency  input  for  motors  with no feedback at all, or those with only an index
              (which is ignored)

       bldc.N.initvalue float in [if personality & 0x04] (default: 0.2)
              The current to be used for the homing sequence in applications where an incremental
              encoder is used with no hall-sensor feedback

       bldc.N.rawcounts s32 in [if personality & 0x06] (default: 0)
              Encoder  counts  input. This must be linked to the encoder rawcounts pin or encoder
              index resets will cause the motor commutation to fail.

       bldc.N.index-enable bit io [if personality & 0x08]
              This pin should be connected to the associated encoder index-enable pin to zero the
              encoder  when  it  passes  index.   This  is only used indicate to the bldc control
              component that an index has been seen.

       bldc.N.init bit in [if ( personality & 0x05 ) == 4]
              A rising edge on this pin starts the motor alignment sequence.  This  pinshould  be
              connected  in  such a way that the motors re-align any time that encoder monitoring
              has been interrupted.  Typically this will  only  be  at  machine  power-off.   The
              alignment  process  involves  powering the motor phases in such a way as to put the
              motor in a known position.  The encoder  counts  are  then  stored  in  the  offset
              parameter.   The  alignment  process  will tend to cause a following error if it is
              triggered while the  axis  is  enabled,  so  should  be  set  before  the  matching
              axis.N.enable  pin.   The  complementary  init-done  pin  can be used to handle the
              required sequencing.

              Both pins can be ignored if the encoder offset is known explicitly, such as is  the
              case  with  an  absolute  encoder.   In  that  case the offset parameter can be set
              directly in the HAL file.

       bldc.N.init-done bit out [if ( personality & 0x05 ) == 4] (default: 0)
              Indicates homing sequence complete.

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

       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)
              Phase angle including  lead/lag  angle  after  encoder  zeroing,  etc.  Useful  for
              angle/current  drives.   This  value  has a range of 0 to 1 and measures electrical
              revolutions.  It will have two zeros for a 4 pole motor, three for a 6-pole, etc.

       bldc.N.rotor-angle float out (default: 0)
              Rotor angle after encoder zeroing etc. Useful for angle/current  drives  which  add
              their  own  phase  offset  such  as the 8I20.  This value has a range of 0 to 1 and
              measures electrical revolutions. It will have two zeros for a 4 pole  motor,  three
              for a 6-pole, etc.

       bldc.N.out float out
              Current output, including the effect of the dir pin and the alignment sequence.

       bldc.N.out-dir bit out
              Direction output, high if /fBvalue/fR is negative XOR /fBrev/fR is true.

       bldc.N.out-abs float out
              Absolute value of the input value

PARAMETERS

       bldc.N.in-type s32 r (default: -1)
              state machine output, will probably hide after debug

       bldc.N.out-type s32 r (default: -1)
              state machine output, will probably hide after debug

       bldc.N.scale s32 rw [if personality & 0x06] (default: 512)
              The number of encoder counts per rotor revolution.

       bldc.N.poles s32 rw [if personality & 0x06] (default: 4)
              The  number  of  motor  poles.  The  encoder scale will be divided by this value to
              determine the number of encoder counts per electrical revolution.

       bldc.N.encoder-offset s32 rw [if personality & 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-measured s32 r [if personality & 0x04] (default: 0)
              The encoder offset measured by the homing sequence (in certain modes)

       bldc.N.drive-offset float rw (default: 0)
              The  angle,  in  degrees,  applied  to the commanded angle by the drive in degrees.
              This value is only used during the  homing  sequence  of  drives  with  incremental
              encoder  feedback.   It  is  used  to back-calculate from commanded angle to actual
              phase angle.  It is only relevant to drives which expect rotor-angle  input  rather
              than phase-angle demand. Should be 0 for most drives.

       bldc.N.output-pattern u32 rw [if personality & 0x400] (default: 25)
              Commutation  pattern  to  be  output  in  Hall  Signal  translation  mode.  See the
              description of /fBpattern/fR for details.

       bldc.N.pattern u32 rw [if personality & 0x01] (default: 25)
              Commutation pattern to use, from 0 to 47. Default  is  type  25.   Every  plausible
              combination is included.  The table shows the excitation pattern along the top, and
              the pattern code on the left hand side.  The table entries are the hall patterns in
              H1,  H2,  H3  order.   Common  patterns  are: 0 (30 degree commutation) and 26, its
              reverse.  17 (120 degree).  18 (alternate 60 degree).  21 (300 degree, Bodine).  22
              (240 degree).  25 (60 degree commutation).

              Note  that  a  number of incorrect commutations will have non-zero net torque which
              might look as if they work, but don't really.

              If your motor lacks documentation it might be worth trying every pattern.

              ┌────────────────────────────────────────┐
              │         Phases, Source - Sink          │
              ├────┬───────────────────────────────────┤
              │patB-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

LICENSE

       GPL