rtcomps.txt
1 [[cha:realtime-components]] 2 3 = HAL Component Descriptions 4 5 [[sec:stepgen]] (((stepgen))) 6 7 == Stepgen 8 9 This component provides software based generation of step pulses in 10 response to position or velocity commands. In position mode, it has a 11 built in pre-tuned position loop, so PID tuning is not required. In 12 velocity mode, it drives a motor at the commanded speed, while obeying 13 velocity and acceleration limits. It is a realtime component only, and 14 depending on CPU speed, etc, is capable of maximum step rates of 10kHz 15 to perhaps 50kHz. The step pulse generator block diagram shows three block 16 diagrams, each is a single step pulse generator. The first diagram is for 17 step type '0', (step and direction). The second is for step type '1' 18 (up/down, or pseudo-PWM), and the third is for step types 2 through 14 19 (various stepping patterns). The first two diagrams show position mode 20 control, and the third one shows velocity mode. Control mode and step type 21 are set independently, and any combination can be selected. 22 23 (((Stepgen Block Diagram))) 24 .Step Pulse Generator Block Diagram position mode 25 26 image::images/stepgen-block-diag.png[align="center"] 27 28 .Installing 29 30 ---- 31 halcmd: loadrt stepgen step_type=<type-array> [ctrl_type=<ctrl_array>] 32 ---- 33 34 '<type-array>' is a series of comma separated decimal integers. Each 35 number causes a 36 single step pulse generator to be loaded, the value of the number 37 determines the stepping type. '<ctrl_array>' is a comma separated 38 series of 'p' or 'v' characters, to specify position or velocity 39 mode. 'ctrl_type' is optional, if ommitted, all of the step generators 40 will be position 41 mode. 42 43 For example: 44 ---- 45 halcmd: loadrt stepgen step_type=0,0,2 ctrl_type=p,p,v 46 ---- 47 48 will install three step generators. The first two use step type '0' 49 (step and direction) and run in position mode. The last one uses step 50 type '2' (quadrature) and runs in velocity mode. The default value for 51 '<config-array>' is '0,0,0' which will install three type '0' 52 (step/dir) generators. The maximum 53 number of step generators is 8 (as defined by MAX_CHAN in stepgen.c). 54 Each generator is independent, but all are updated by the same 55 function(s) at the same time. In the following descriptions, '<chan>' 56 is the number of a specific generator. The first generator is number 0. 57 (((Stepgen Block Diagram))) 58 .Removing 59 60 ---- 61 halcmd: unloadrt stepgen 62 ---- 63 64 .Pins 65 66 Each step pulse generator will have only some of these pins, depending 67 on the step type and control type selected. 68 69 * '(float) stepgen.<chan>.position-cmd' - Desired motor position, in 70 position units (position mode only). 71 * '(float) stepgen.<chan>.velocity-cmd' - Desired motor velocity, in 72 position units per second (velocity mode only). 73 * '(s32) stepgen.<chan>.counts' - Feedback position in counts, 74 updated by 'capture_position()'. 75 * '(float) stepgen.<chan>.position-fb' - Feedback position in 76 position units, updated by 'capture_position()'. 77 * '(bit) stepgen.<chan>.enable' - Enables output steps - when false, 78 no steps are generated. 79 * '(bit) stepgen.<chan>.step' - Step pulse output (step type 0 only). 80 * '(bit) stepgen.<chan>.dir' - Direction output (step type 0 only). 81 * '(bit) stepgen.<chan>.up' - UP pseudo-PWM output (step type 1 only). 82 * '(bit) stepgen.<chan>.down' - DOWN pseudo-PWM output (step type 1 only). 83 * '(bit) stepgen.<chan>.phase-A' - Phase A output (step types 2-14 only). 84 * '(bit) stepgen.<chan>.phase-B' - Phase B output (step types 2-14 only). 85 * '(bit) stepgen.<chan>.phase-C' - Phase C output (step types 3-14 only). 86 * '(bit) stepgen.<chan>.phase-D' - Phase D output (step types 5-14 only). 87 * '(bit) stepgen.<chan>.phase-E' - Phase E output (step types 11-14 only). 88 89 .Parameters[[sub:stepgen-parameters]] 90 91 * '(float) stepgen.<chan>.position-scale' - Steps per position unit. 92 This parameter is used for both output and feedback. 93 * '(float) stepgen.<chan>.maxvel' - Maximum velocity, in position 94 units per second. If 0.0, has no effect. 95 * '(float) stepgen.<chan>.maxaccel' - Maximum accel/decel rate, in 96 positions units per second squared. 97 If 0.0, has no effect. 98 * '(float) stepgen.<chan>.frequency' - The current step rate, in 99 steps per second. 100 * '(float) stepgen.<chan>.steplen' - Length of a step pulse (step 101 type 0 and 1) or minimum time in a 102 given state (step types 2-14), in nano-seconds. 103 * '(float) stepgen.<chan>.stepspace' - Minimum spacing between two 104 step pulses (step types 0 and 1 only), in nano-seconds. Set to 0 to 105 enable the stepgen 'doublefreq' function. To use 'doublefreq' the 106 <<sub:parport-functions,parport reset function>> must be enabled. 107 * '(float) stepgen.<chan>.dirsetup' - Minimum time from a direction 108 change to the beginning of the next 109 step pulse (step type 0 only), in nanoseconds. 110 * '(float) stepgen.<chan>.dirhold' - Minmum time from the end of a 111 step pulse to a direction change 112 (step type 0 only), in nanoseconds. 113 * '(float) stepgen.<chan>.dirdelay' - Minmum time any step to a step 114 in the opposite direction (step 115 types 1-14 only), in nano-seconds. 116 * '(s32) stepgen.<chan>.rawcounts' - The raw feedback count, updated 117 by 'make_pulses()'. 118 119 In position mode, the values of maxvel and maxaccel are used by the 120 internal position loop to avoid generating step pulse trains that the 121 motor cannot follow. When set to values that are appropriate for the 122 motor, even a large instantaneous change in commanded position will 123 result in a smooth trapezoidal move to the new location. The algorithm 124 works by measuring both position error and velocity error, and 125 calculating an acceleration that attempts to reduce both to zero at the 126 same time. For more details, including the contents of the 'control 127 equation' box, consult the code. 128 129 In velocity mode, maxvel is a simple limit that is applied to the 130 commanded velocity, and maxaccel is used to ramp the actual frequency 131 if the commanded velocity changes abruptly. As in position mode, proper 132 values for these parameters ensure that the motor can follow the 133 generated pulse train. 134 135 .Step Types 136 137 .Step Type 0 138 Step type 0 is the standard step and direction type. When configured for 139 step type 0, there are four extra parameters that determine the exact 140 timing of the step and direction signals. In the following figure 141 the meaning of these parameters is shown. The 142 parameters are in nanoseconds, but will be rounded up to an integer 143 multiple of the thread period for the threaed that calls 144 'make_pulses()'. For example, if 'make_pulses()' is called every 16 us, 145 and steplen is 20000, then the step pulses will 146 be 2 x 16 = 32 us long. The default value for all four of the parameters 147 is 1ns, but the automatic rounding takes effect the first time the code 148 runs. Since one step requires 'steplen' ns high and 'stepspace' ns 149 low, the maximum frequency is 1,000,000,000 divided by 150 '(steplen+stepspace)'. If 'maxfreq' is set higher than that limit, it 151 will be lowered automatically. If 152 maxfreq is zero, it will remain zero, but the output frequency will 153 still be limited. 154 155 When using the parallel port driver the step frequency can be doubled using 156 the <<sub:parport-functions,parport reset>> function together with stepgen's 157 'doublefreq' setting. 158 159 .Step and Direction Timing 160 161 image::images/stepgen-type0.png[align="center"] 162 163 .Step Type 1 164 Step type 1 has two outputs, up and down. Pulses appear on one or the 165 other, depending on the direction of travel. Each pulse is 'steplen' ns 166 long, and the pulses are separated by at least 'stepspace' ns. The 167 maximum frequency is the same as for step type 0. If 'maxfreq' is set 168 higher than the limit it will be lowered. If 'maxfreq' is zero, it 169 will remain zero but the output frequency will still be 170 limited. 171 172 [WARNING] 173 Do not use the parport reset function with step types 2 - 14. Unexpected 174 results can happen. 175 176 .Step Type 2 - 14 177 Step types 2 through 14 are state based, and have from two to five 178 outputs. On each step, a state counter is incremented or decremented. 179 The Two-and-Three-Phase, Four-Phase, and Five-Phase show the output 180 patterns as a function of the state counter. The maximum frequency is 181 1,000,000,000 divided by 'steplen', and as in the other modes, 'maxfreq' 182 will be lowered if it is above the limit. 183 184 .Two-and-Three-Phase Step Types 185 (((Two and Three Phase))) 186 187 image::images/stepgen-type2-4.png[align="center"] 188 189 .Four-Phase Step Types 190 (((Four Phase))) 191 192 image::images/stepgen-type5-10.png[align="center"] 193 194 .Five-Phase Step Types 195 (((Five Phase))) 196 197 image::images/stepgen-type11-14.png[align="center"] 198 199 .Functions 200 201 The component exports three functions. Each function acts on all of 202 the step pulse generators - running different generators in different 203 threads is not supported. 204 205 * '(funct) stepgen.make-pulses' - High speed function to generate 206 and count pulses (no floating point). 207 * '(funct) stepgen.update-freq' - Low speed function does position 208 to velocity conversion, scaling and limiting. 209 * '(funct) stepgen.capture-position' - Low speed function for 210 feedback, updates latches and scales position. 211 212 The high speed function 'stepgen.make-pulses' should be run in a very 213 fast thread, from 10 to 50 us depending on the 214 capabilities of the computer. That thread's period determines the 215 maximum step frequency, since 'steplen', 'stepspace', 'dirsetup', 216 'dirhold', and 'dirdelay' are all rounded up to a integer multiple of 217 the thread periond in 218 nanoseconds. The other two functions can be called at a much lower 219 rate. 220 221 [[sec:pwmgen]] (((PWMgen))) 222 223 == PWMgen 224 225 This component provides software based generation of PWM (Pulse Width 226 Modulation) and PDM (Pulse Density Modulation) waveforms. It is a 227 realtime component only, and depending on CPU speed, etc, is capable of 228 PWM frequencies from a few hundred Hertz at pretty good resolution, to 229 perhaps 10KHz with limited resolution. 230 231 .Installing 232 233 ---- 234 loadrt pwmgen output_type=<config-array> 235 ---- 236 237 The '<config-array>' is a series of comma separated decimal integers. Each 238 number causes a single PWM generator to be loaded, the value of the number 239 determines the output type. The following example will install three PWM 240 generators. There is no default value, if '<config-array>' is not specified, 241 no PWM generators will be installed. The maximum number of frequency generators 242 is 8 (as defined by MAX_CHAN in pwmgen.c). Each generator is independent, 243 but all are updated by the same function(s) at the same time. In the following 244 descriptions, '<chan>' is the number of a specific generator. The first 245 generator is number 0. 246 247 .Example 248 ---- 249 loadrt pwmgen output_type=0,1,2 250 ---- 251 252 .Removing 253 254 ---- 255 unloadrt pwmgen 256 ---- 257 258 .Output Types 259 260 The PWM generator supports three different 'output types'. 261 262 * 'Output type 0' - PWM output pin only. Only positive commands are accepted, 263 negative values are treated as zero (and will be affected by the parameter 264 'min-dc' if it is non-zero). 265 266 * 'Output type 1' - PWM/PDM and direction pins. Positive and negative inputs 267 will be output as positive and negative PWM. The direction pin is false 268 for positive commands, and true for negative commands. If your control 269 needs positive PWM for both CW and CCW use the <<sub:abs,abs>> component 270 to convert your PWM signal to positive value when a negative input is input. 271 272 * 'Output type 2' - UP and DOWN pins. For positive commands, the PWM signal 273 appears on the up output, and the down output remains false. For negative 274 commands, the PWM signal appears on the down output, and the up output 275 remains false. Output type 2 is suitable for driving most H-bridges. 276 277 .Pins 278 279 Each PWM generator will have the following pins: 280 281 * '(float) pwmgen.<chan>.value' - Command value, in arbitrary units. 282 Will be scaled by the 'scale' parameter (see below). 283 * '(bit) pwmgen.<chan>.enable' - Enables or disables the PWM 284 generator outputs. 285 286 Each PWM generator will also have some of these pins, depending on the 287 output type selected: 288 289 * '(bit) pwmgen.<chan>.pwm' - PWM (or PDM) output, (output types 0 290 and 1 only). 291 * '(bit) pwmgen.<chan>.dir' - Direction output (output type 1 only). 292 * '(bit) pwmgen.<chan>.up' - PWM/PDM output for positive input value 293 (output type 2 only). 294 * '(bit) pwmgen.<chan>.down' - PWM/PDM output for negative input 295 value (output type 2 only). 296 297 .Parameters 298 299 * '(float) pwmgen.<chan>.scale' - Scaling factor to convert 'value' 300 from arbitrary units to duty cycle. For example if scale is set to 4000 301 and the input value passed to the pwmgen.<chan>.value is 4000 then it will 302 be 100% duty-cycle (always on). If the value is 2000 then it will be a 50% 303 25Hz square wave. 304 * '(float) pwmgen.<chan>.pwm-freq' - Desired PWM frequency, in Hz. 305 If 0.0, generates PDM instead of PWM. If set higher than internal limits, 306 next call of 'update_freq()' will set it to the internal limit. If non-zero, 307 and 'dither' is false, next call of 'update_freq()' will set it to the 308 nearest integer multiple of the 'make_pulses()' function period. 309 * '(bit) pwmgen.<chan>.dither-pwm' - If true, enables dithering to 310 achieve average PWM frequencies or 311 duty cycles that are unobtainable with pure PWM. If false, both the PWM 312 frequency and the duty cycle will be rounded to values that can be 313 achieved exactly. 314 * '(float) pwmgen.<chan>.min-dc' - Minimum duty cycle, between 0.0 315 and 1.0 (duty cycle will go to 316 zero when disabled, regardless of this setting). 317 * '(float) pwmgen.<chan>.max-dc' - Maximum duty cycle, between 0.0 318 and 1.0. 319 * '(float) pwmgen.<chan>.curr-dc' - Current duty cycle - after all 320 limiting and rounding (read only). 321 322 .Functions 323 324 The component exports two functions. Each function acts on all of the 325 PWM generators - running different generators in different threads is 326 not supported. 327 328 * '(funct) pwmgen.make-pulses' - High speed function to generate PWM waveforms 329 (no floating point). The high speed function 'pwmgen.make-pulses' should be 330 run in the base (fastest) thread, from 10 to 50 us depending on the 331 capabilities of the computer. That thread's period determines the maximum PWM 332 carrier frequency, as well as the resolution of the PWM or PDM signals. If 333 the base thread is 50,000nS then every 50uS the module decides if it is time 334 to change the state of the output. At 50% duty cycle and 25Hz PWM frequency 335 this means that the output changes state every (1 / 25) seconds / 50uS * 50% 336 = 400 iterations. This also means that you have a 800 possible duty cycle 337 values (without dithering) 338 * '(funct) pwmgen.update' - Low speed function to scale and limit value and 339 handle other parameters. This is the function of the module that does the 340 more complicated mathematics to work out how many base-periods the output 341 should be high for, and how many it should be low for. 342 343 [[sec:encoder]](((encoder))) 344 345 == Encoder 346 347 This component provides software based counting of signals from 348 quadrature encoders. It is a realtime component only, and depending on 349 CPU speed, latency, etc, is capable of maximum count rates of 10kHz to 350 perhaps up to 50kHz. 351 352 The base thread should be 1/2 count speed to allow for noise and timing 353 variation. For example if you have a 100 pulse per revolution encoder on the 354 spindle and your maximnum RPM is 3000 the maximum base thread should be 25 us. 355 A 100 pulse per revolution encoder will have 400 counts. The spindle speed 356 of 3000 RPM = 50 RPS (revolutions per second). 400 * 50 = 20,000 counts per 357 second or 50 us between counts. 358 359 The Encoder Counter Block Diagram is a block diagram of one channel of an 360 encoder counter. 361 362 (((Encoder Block Diagram))) 363 364 .Encoder Counter Block Diagram 365 366 image::images/encoder-block-diag.png[align="center"] 367 368 .Installing 369 370 ---- 371 halcmd: loadrt encoder [num_chan=<counters>] 372 ---- 373 374 '<counters>' is the number of encoder counters that you want to 375 install. If 'numchan' is not specified, three counters will be 376 installed. The maximum 377 number of counters is 8 (as defined by MAX_CHAN in encoder.c). Each 378 counter is independent, but all are updated by the same function(s) at 379 the same time. In the following descriptions, '<chan>' is the number 380 of a specific counter. The first counter is number 0. 381 382 .Removing 383 384 ---- 385 halcmd: unloadrt encoder 386 ---- 387 388 .Pins 389 390 * 'encoder.<chan>.counter-mode' (bit, I/O) (default: FALSE) - Enables 391 counter mode. When true, the 392 counter counts each rising edge of the phase-A input, ignoring the 393 value on phase-B. This is useful for counting the output of a single 394 channel (non-quadrature) sensor. When false, it counts in quadrature 395 mode. 396 * 'encoder.<chan>.counts' (s32, Out) - Position in encoder counts. 397 * 'encoder.<chan>.counts-latched' (s32, Out) - Not used at this time. 398 * 'encoder.<chan>.index-enable' (bit, I/O) - When True, 'counts' and 399 'position are' reset to zero on next rising edge of Phase Z. At the 400 same time, 'index-enable' is reset to zero to indicate that the rising 401 edge has occoured. The 'index-enable' pin is bi-directional. If 402 'index-enable' is False, the Phase Z channel of the encoder will be 403 ignored, and the 404 counter will count normally. The encoder driver will never set 405 'index-enable' True. However, some other component may do so. 406 * 'encoder.<chan>.latch-falling' (bit, In) (default: TRUE) - Not used 407 at this time. 408 * 'encoder.<chan>.latch-input' (bit, In) (default: TRUE) - Not used at 409 this time. 410 * 'encoder.<chan>.latch-rising' (bit, In) - Not used at this time. 411 * 'encoder.<chan>.min-speed-estimate' (float, in) - Determine the 412 minimum true velocity magnitude at which 413 velocity will be estimated as nonzero and postition-interpolated will 414 be interpolated. The units of 'min-speed-estimate' are the same as the 415 units of 'velocity' . Scale factor, in counts per length unit. Setting 416 this parameter too 417 low will cause it to take a long time for velocity to go to 0 after 418 encoder pulses have stopped arriving. 419 * 'encoder.<chan>.phase-A' (bit, In) - Phase A of the quadrature encoder signal. 420 * 'encoder.<chan>.phase-B' (bit, In) - Phase B of the quadrature encoder signal. 421 * 'encoder.<chan>.phase-Z' (bit, In) - Phase Z (index pulse) of the quadrature encoder signal. 422 * 'encoder.<chan>.position' (float, Out) - Position in scaled units (see 'position-scale'). 423 * 'encoder.<chan>.position-interpolated' (float, Out) - Position in 424 scaled units, interpolated between 425 encoder counts. The 'position-interpolated' attempts to interpolate 426 between encoder counts, based on the most 427 recently measured velocity. Only valid when velocity is approximately 428 constant and above 'min-speed-estimate'. Do not use for position 429 control, since its value is incorrect at 430 low speeds, during direction reversals, and during speed changes. 431 However, it allows a low ppr encoder (including a one pulse per 432 revolution 'encoder') to be used for lathe threading, and may have 433 other uses as well. 434 * 'encoder.<chan>.position-latched (float, Out)' - Not used at this time. 435 * 'encoder.<chan>.position-scale (float, I/O)' - Scale factor, in 436 counts per length unit. For example, if 437 position-scale is 500, then 1000 counts of the encoder will be reported 438 as a position of 2.0 units. 439 * 'encoder.<chan>.rawcounts (s32, In)' - The raw count, as determined 440 by update-counters. This value is 441 updated more frequently than counts and position. It is also unaffected 442 by reset or the index pulse. 443 * 'encoder.<chan>.reset' (bit, In) - When True, force 'counts' and 444 'position' to zero immediately. 445 * 'encoder.<chan>.velocity' (float, Out) - Velocity in scaled units per 446 second. 'encoder' uses an algorithm that greatly reduces quantization 447 noise as compared 448 to simply differentiating the 'position' output. When the magnitude 449 of the true velocity is below 450 min-speed-estimate, the velocity output is 0. 451 * 'encoder.<chan>.x4-mode (bit, I/O) (default: TRUE)' - Enables 452 times-4 mode. When true, the counter counts each edge of 453 the quadrature waveform (four counts per full cycle). When false, it 454 only counts once per full cycle. In counter-mode, this parameter is 455 ignored. The 1x mode is useful for some jogwheels. 456 457 .Parameters 458 459 * 'encoder.<chan>.capture-position.time (s32, RO)' 460 * 'encoder.<chan>.capture-position.tmax (s32, RW)' 461 * 'encoder.<chan>.update-counters.time (s32, RO)' 462 * 'encoder.<chan>.update-counter.tmax (s32, RW)' 463 464 .Functions 465 466 The component exports two functions. Each function acts on all of the 467 encoder counters - running different counters in different threads is 468 not supported. 469 470 * '(funct) encoder.update-counters' - High speed function to count 471 pulses (no floating point). 472 * '(funct) encoder.capture-position' - Low speed function to update 473 latches and scale position. 474 475 [[sec:pid]](((PID))) 476 477 == PID 478 479 This component provides Proportional/Integral/Derivative control 480 loops. It is a realtime component only. For simplicity, this discussion 481 assumes that we are talking about position loops, however this 482 component can be used to implement other feedback loops such as speed, 483 torch height, temperature, etc. The PID Loop Block Diagram is a 484 block diagram of a single PID loop. 485 486 [[fig:pid-block-diag]] (((PID Block Diagram))) 487 488 .PID Loop Block Diagram 489 490 image::images/pid-block-diag.png[align="center"] 491 492 .Installing 493 494 ---- 495 halcmd: loadrt pid [num_chan=<loops>] [debug=1] 496 ---- 497 498 '<loops>' is the number of PID loops that you want to install. If 499 'numchan' is not specified, one loop will be installed. The maximum 500 number of 501 loops is 16 (as defined by MAX_CHAN in pid.c). Each loop is completely 502 independent. In the following descriptions, '<loopnum>' is the loop 503 number of a specific loop. The first loop is number 0. 504 505 If 'debug=1' is specified, the component will export a few extra 506 pins that 507 may be useful during debugging and tuning. By default, the extra 508 pins are not exported, to save shared memory space and avoid 509 cluttering the pin list. 510 511 .Removing 512 513 ---- 514 halcmd: unloadrt pid 515 ---- 516 517 .Pins 518 519 The three most important pins are 520 521 * '(float) pid.<loopnum>.command' - The desired position, as 522 commanded by another system component. 523 * '(float) pid.<loopnum>.feedback' - The present position, as 524 measured by a feedback device such as an encoder. 525 * '(float) pid.<loopnum>.output' - A velocity command that attempts 526 to move from the present position to the desired position. 527 528 For a position loop, 'command' and 'feedback' are in position units. 529 For a linear axis, this could be inches, mm, meters, or whatever is 530 relevant. Likewise, for an angular axis, it could be degrees, radians, 531 etc. The units of the 'output' pin represent the change needed to make 532 the feedback match the command. As such, for a position loop 'Output' 533 is a velocity, in inches/sec, mm/sec, degrees/sec, etc. Time units are 534 always seconds, and the velocity units match the position units. If 535 command and feedback are in meters, then output is in meters per 536 second. 537 538 Each loop has two pins which are used to monitor or control the 539 general operation of the component. 540 541 * '(float) pid.<loopnum>.error' - Equals '.command' minus '.feedback'. 542 * '(bit) pid.<loopnum>.enable' - A bit that enables the loop. If 543 '.enable' is false, all integrators are reset, and the output is 544 forced to zero. If '.enable' is true, the loop operates normally. 545 546 Pins used to report saturation. Saturation occurs when the output of 547 the PID block is at its maximum or minimum limit. 548 549 * '(bit) pid.<loopnum>.saturated' - True when output is saturated. 550 * '(float) pid.<loopnum>.saturated_s' - The time the output has been saturated. 551 * '(s32) pid.<loopnum>.saturated_count' - The time the output has been saturated. 552 553 The PID gains, limits, and other 'tunable' features of the loop are 554 available as pins so that they can be adjusted dynamically for more 555 advanced tuning possibilities. 556 557 * '(float) pid.<loopnum>.Pgain' - Proportional gain 558 * '(float) pid.<loopnum>.Igain' - Integral gain 559 * '(float) pid.<loopnum>.Dgain' - Derivative gain 560 * '(float) pid.<loopnum>.bias' - Constant offset on output 561 * '(float) pid.<loopnum>.FF0' - Zeroth order feedforward - output 562 proportional to command (position). 563 * '(float) pid.<loopnum>.FF1' - First order feedforward - output 564 proportional to derivative of command (velocity). 565 * '(float) pid.<loopnum>.FF2' - Second order feedforward - output 566 proportional to 2nd derivative 567 of command (acceleration). 568 * '(float) pid.<loopnum>.deadband' - Amount of error that will be ignored 569 * '(float) pid.<loopnum>.maxerror' - Limit on error 570 * '(float) pid.<loopnum>.maxerrorI' - Limit on error integrator 571 * '(float) pid.<loopnum>.maxerrorD' - Limit on error derivative 572 * '(float) pid.<loopnum>.maxcmdD' - Limit on command derivative 573 * '(float) pid.<loopnum>.maxcmdDD' - Limit on command 2nd derivative 574 * '(float) pid.<loopnum>.maxoutput' - Limit on output value 575 576 If 'debug=1' was specified when the component was installed, four 577 additional pins will be exported: 578 579 * '(float) pid.<loopnum>.errorI' - Integral of error. 580 * '(float) pid.<loopnum>.errorD' - Derivative of error. 581 * '(float) pid.<loopnum>.commandD' - Derivative of the command. 582 * '(float) pid.<loopnum>.commandDD' - 2nd derivative of the command. 583 584 .Functions 585 586 The component exports one function for each PID loop. This function 587 performs all the calculations needed for the loop. Since each loop has 588 its own function, individual loops can be included in different threads 589 and execute at different rates. 590 591 * '(funct) pid.<loopnum>.do_pid_calcs' - Performs all calculations 592 for a single PID loop. 593 594 If you want to understand the exact algorithm used to compute the 595 output of the PID loop, refer to figure <<fig:pid-block-diag,PID Loop Block Diagram>>, the 596 comments at the beginning of 'emc2/src/hal/components/pid.c' , and of 597 course to the code itself. The loop calculations are in the C 598 function 'calc_pid()'. 599 600 [[sec:simulated-encoder]](((Simulated Encoder))) 601 602 == Simulated Encoder 603 604 The simulated encoder is exactly that. It produces quadrature pulses 605 with an index pulse, at a speed controlled by a HAL pin. Mostly useful 606 for testing. 607 608 .Installing 609 610 ---- 611 halcmd: loadrt sim-encoder num_chan=<number> 612 ---- 613 614 '<number>' is the number of encoders that you want to simulate. If not 615 specified, one encoder will be installed. The maximum number is 8 (as 616 defined by MAX_CHAN in sim_encoder.c). 617 618 .Removing 619 620 ---- 621 halcmd: unloadrt sim-encoder 622 ---- 623 624 .Pins 625 626 * '(float) sim-encoder.<chan-num>.speed' - The speed command for the 627 simulated shaft. 628 * '(bit) sim-encoder.<chan-num>.phase-A' - Quadrature output. 629 * '(bit) sim-encoder.<chan-num>.phase-B' - Quadrature output. 630 * '(bit) sim-encoder.<chan-num>.phase-Z' - Index pulse output. 631 632 When '.speed' is positive, '.phase-A' leads '.phase-B'. 633 634 .Parameters 635 636 * '(u32) sim-encoder.<chan-num>.ppr' - Pulses Per Revolution. 637 * '(float) sim-encoder.<chan-num>.scale' - Scale Factor for 'speed'. 638 The default is 1.0, which means that 'speed' is in revolutions per 639 second. Change to 60 for RPM, to 360 for 640 degrees per second, 6.283185 for radians per seconed, etc. 641 642 Note that pulses per revolution is not the same as counts per 643 revolution. A pulse is a complete quadrature cycle. Most encoder 644 counters will count four times during one complete cycle. 645 646 .Functions 647 648 The component exports two functions. Each function affects all 649 simulated encoders. 650 651 * '(funct) sim-encoder.make-pulses' - High speed function to 652 generate quadrature pulses (no floating point). 653 * '(funct) sim-encoder.update-speed' - Low speed function to read 654 'speed', do scaling, and set up 'make-pulses'. 655 656 [[sec:debounce]] (((debounce))) 657 658 == Debounce 659 660 Debounce is a realtime component that can filter the glitches created 661 by mechanical switch contacts. It may also be useful in other 662 applications where short pulses are to be rejected. 663 664 .Installing 665 666 ---- 667 halcmd: loadrt debounce cfg=<config-string> 668 ---- 669 670 '<config-string>' is a series of comma separated decimal integers. 671 Each number installs 672 a group of identical debounce filters, the number determines how many 673 filters are in the group. 674 675 For example: 676 677 ---- 678 halcmd: loadrt debounce cfg=1,4,2 679 ---- 680 681 will install three groups of filters. Group 0 contains one filter, 682 group 1 contains four, and group 2 contains two filters. The default 683 value for '<config-string>' is '"1"' which will install a single group 684 containing a single filter. The 685 maximum number of groups 8 (as defined by MAX_GROUPS in debounce.c). 686 The maximum number of filters in a group is limited only by shared 687 memory space. Each group is completely independent. All filters in a 688 single group are identical, and they are all updated by the same 689 function at the same time. In the following descriptions, '<G>' is the 690 group number and '<F>' is the filter number within the group. The 691 first filter is group 0, 692 filter 0. 693 694 .Removing 695 696 ---- 697 halcmd: unloadrt debounce 698 ---- 699 700 .Pins 701 702 Each individual filter has two pins. 703 704 * '(bit) debounce.<G>.<F>.in' - Input of filter '<F>' in group '<G>'. 705 * '(bit) debounce.<G>.<F>.out' - Output of filter '<F>' in group '<G>'. 706 707 .Parameters 708 709 Each group of filters has one parameterfootnote:[Each individual 710 filter also has an internal state variable. There is a 711 compile time switch that can export that variable as a parameter. This 712 is intended for testing, and simply wastes shared memory under normal 713 circumstances.]. 714 715 * '(s32) debounce.<G>.delay' - Filter delay for all filters in group '<G>'. 716 717 The filter delay is in units of thread periods. The minimum delay is 718 zero. The output of a zero delay filter exactly follows its input - it 719 doesn't filter anything. As 'delay' increases, longer and longer 720 glitches are rejected. If 'delay' is 4, all glitches less than or 721 equal to four thread periods will be rejected. 722 723 .Functions 724 725 Each group of filters has one function, which updates all the filters 726 in that group 'simultaneously'. Different groups of filters can be 727 updated from different threads at different periods. 728 729 * '(funct) debounce.<G>' - Updates all filters in group '<G>'. 730 731 [[sec:siggen]](((Siggen))) 732 733 == Siggen 734 735 Siggen is a realtime component that generates square, triangle, and 736 sine waves. It is primarily used for testing. 737 738 .Installing 739 740 ---- 741 halcmd: loadrt siggen [num_chan=<chans>] 742 ---- 743 744 '<chans>' is the number of signal generators that you want to install. 745 If 'numchan' is not specified, one signal generator will be installed. 746 The maximum 747 number of generators is 16 (as defined by MAX_CHAN in siggen.c). Each 748 generator is completely independent. In the following descriptions, 749 '<chan>' is the number of a specific signal generator (the numbers 750 start at 0). 751 752 .Removing 753 754 ---- 755 halcmd: unloadrt siggen 756 ---- 757 758 .Pins 759 760 Each generator has five output pins. 761 762 * '(float) siggen.<chan>.sine' - Sine wave output. 763 * '(float) siggen.<chan>.cosine' - Cosine output. 764 * '(float) siggen.<chan>.sawtooth' - Sawtooth output. 765 * '(float) siggen.<chan>.triangle' - Triangle wave output. 766 * '(float) siggen.<chan>.square' - Square wave output. 767 768 All five outputs have the same frequency, amplitude, and offset. 769 770 In addition to the output pins, there are three control pins: 771 772 * '(float) siggen.<chan>.frequency' - Sets the frequency in Hertz, 773 default value is 1 Hz. 774 * '(float) siggen.<chan>.amplitude' - Sets the peak amplitude of the 775 output waveforms, default is 1. 776 * '(float) siggen.<chan>.offset' - Sets DC offset of the output 777 waveforms, default is 0. 778 779 For example, if 'siggen.0.amplitude' is 1.0 and 'siggen.0.offset' is 780 0.0, the outputs will swing from -1.0 to +1.0. If 'siggen.0.amplitude' 781 is 2.5 and 'siggen.0.offset' is 10.0, then the outputs will swing from 782 7.5 to 12.5. 783 784 .Parameters 785 786 None. footnote:[Prior to version 2.1, frequency, amplitude, and offset 787 were parameters. They were changed to pins to allow control by other 788 components.] 789 790 .Functions 791 792 * '(funct) siggen.<chan>.update' - Calculates new values for all five outputs. 793 794 [[sec:lut5]](((lut5))) 795 796 == lut5 797 798 The lut5 component is a 5 input logic component based on a look up table. 799 800 * 'lut5' does not require a floating point thread. 801 802 .Installing 803 804 ---- 805 loadrt lut5 [count=N|names=name1[,name2...]] 806 addf lut5.N servo-thread | base-thread 807 setp lut5.N.function 0xN 808 ---- 809 810 .Computing Function 811 812 To compute the hexadecimal number for the function starting from the top put 813 a 1 or 0 to indicate if that row would be true or false. Next write down every 814 number in the output column starting from the top and writing them from right 815 to left. This will be the binary number. Using a calculator with a program 816 view like the one in Ubuntu enter the binary number and then convert it to 817 hexadecimal and that will be the value for function. 818 819 .Look Up Table 820 [width="50%",cols="6*^",options="header"] 821 |==================================== 822 |Bit 4|Bit 3|Bit 2|Bit 1|Bit 0|Output 823 |0|0|0|0|0| 824 |0|0|0|0|1| 825 |0|0|0|1|0| 826 |0|0|0|1|1| 827 |0|0|1|0|0| 828 |0|0|1|0|1| 829 |0|0|1|1|0| 830 |0|0|1|1|1| 831 |0|1|0|0|0| 832 |0|1|0|0|1| 833 |0|1|0|1|0| 834 |0|1|0|1|1| 835 |0|1|1|0|0| 836 |0|1|1|0|1| 837 |0|1|1|1|0| 838 |0|1|1|1|1| 839 |1|0|0|0|0| 840 |1|0|0|0|1| 841 |1|0|0|1|0| 842 |1|0|0|1|1| 843 |1|0|1|0|0| 844 |1|0|1|0|1| 845 |1|0|1|1|0| 846 |1|0|1|1|1| 847 |1|1|0|0|0| 848 |1|1|0|0|1| 849 |1|1|0|1|0| 850 |1|1|0|1|1| 851 |1|1|1|0|0| 852 |1|1|1|0|1| 853 |1|1|1|1|0| 854 |1|1|1|1|1| 855 |==================================== 856 857 .Two Input Example 858 859 In the following table we have selected the output state for each line 860 that we wish to be true. 861 862 .Look Up Table 863 [width="50%",cols="6*^",options="header"] 864 |==================================== 865 |Bit 4|Bit 3|Bit 2|Bit 1|Bit 0|Output 866 |0|0|0|0|0|0 867 |0|0|0|0|1|1 868 |0|0|0|1|0|0 869 |0|0|0|1|1|1 870 |==================================== 871 872 Looking at the output column of our example we want the output to be on 873 when Bit 0 or Bit 0 and Bit1 is on and nothing else. The binary number is 874 'b1010' (rotate the output 90 degrees CW). Enter this number into the 875 calculator then change the display to hexadecimal and the number needed for 876 function is '0xa'. The hexadecimal prefix is '0x'. 877 878