hostmot2_fr.txt
1 = Mesa HostMot2 2 3 == Introduction 4 5 HostMot2 is an FPGA configuration developed by Mesa Electronics for 6 their line of "Anything I/O" motion control cards. The firmware is open 7 source, portable and flexible. It can be configured (at compile-time) 8 with zero or more instances (an object created at runtime) of each of 9 several Modules: encoders (quadrature counters), PWM generators, and 10 step/dir generators. The firmware can be configured (at run-time) to 11 connect each of these instances to pins on the I/O headers. I/O pins 12 not driven by a Module instance revert to general-purpose 13 bi-directional digital I/O. 14 15 == Firmware Binaries 16 17 Several pre-compiled HostMot2 firmware binaries are available for the 18 different Anything I/O boards. (This list is incomplete, check the 19 hostmot2-firmware distribution for up-to-date firmware lists.) 20 21 * 3x20 (144 I/O pins): using hm2_pci module 22 - 24-channel servo 23 - 16-channel servo plus 24 step/dir generators 24 25 * 5i22 (96 I/O pins): using hm2_pci module 26 - 16-channel servo 27 - 8-channel servo plus 24 step/dir generators 28 29 * 5i20, 5i23, 4i65, 4i68 (72 I/O pins): using hm2_pci module 30 - 12-channel servo 31 - 8-channel servo plus 4 step/dir generators 32 - 4-channel servo plus 8 step/dir generators 33 34 * 7i43 (48 I/O pins): using hm2_7i43 module 35 - 8-channel servo (8 PWM generators & 8 encoders) 36 - 4-channel servo plus 4 step/dir generators 37 38 == Installing Firmware 39 40 Depending on how you installed LinuxCNC you may have to open the Synaptic 41 Package Manager from the System menu and install the package for your 42 Mesa card. The quickest way to find them is to do a search for 43 "hostmot2" in the Synaptic Package Manager. Mark the firmware for 44 installation, then apply. 45 46 == Loading HostMot2 47 48 The LinuxCNC support for the HostMot2 firmware is split into a generic 49 driver called "hostmot2" and two low-level I/O drivers for the Anything 50 I/O boards. The low-level I/O drivers are "hm2_7i43" and "hm2_pci" (for 51 all the PCI- and PC-104/Plus-based Anything I/O boards). The hostmot2 driver 52 must be loaded first, using a HAL command like this: 53 54 loadrt hostmot2 55 56 See the hostmot2(9) man page for details. 57 58 The hostmot2 driver by itself does nothing, it needs access to actual 59 boards running the HostMot2 firmware. The low-level I/O drivers provide 60 this access. The low-level I/O drivers are loaded with commands like 61 this: 62 63 loadrt hm2_pci config="firmware=hm2/5i20/SVST8_4.BIT num_encoders=3 64 num_pwmgens=3 num_stepgens=1" 65 66 The config parameters are described in the hostmot2 man page. 67 68 == Watchdog 69 70 The HostMot2 firmware may include a watchdog Module; if it does, the 71 hostmot2 driver will use it. 72 73 The watchdog must be petted by LinuxCNC periodically or it will bite. 74 75 When the watchdog bites, all the board's I/O pins are disconnected 76 from their Module instances and become high-impedance inputs (pulled 77 high), and all communication with the board stops. The state of the 78 HostMot2 firmware modules is not disturbed (except for the 79 configuration of the I/O Pins). Encoder instances keep counting 80 quadrature pulses, and pwm- and step-generators keep generating signals 81 (which are not relayed to the motors, because the I/O Pins have become 82 inputs). 83 84 Resetting the watchdog resumes communication and resets the I/O pins 85 to the configuration chosen at load-time. 86 87 If the firmware includes a watchdog, the following HAL objects will be 88 exported: 89 90 === Pins: 91 92 has_bit:: 93 (bit i/o) True if the watchdog has bit, False if the watchdog has not 94 bit. If the watchdog has bit and the has_bit bit is True, the user can 95 reset it to False to resume operation. 96 97 === Parameters: 98 99 timeout_ns:: 100 (u32 read/write) Watchdog timeout, in nanoseconds. This is initialized 101 to 1,000,000,000 (1 second) at module load time. If more than this 102 amount of time passes between calls to the hm2 write function, the 103 watchdog will bite. 104 105 == HostMot2 Functions 106 107 hm2_<BoardType>.<BoardNum>.read:: 108 Read all inputs, update input HAL pins. 109 110 hm2_<BoardType>.<BoardNum>.write:: 111 Write all outputs. 112 113 hm2_<BoardType>.<BoardNum>.pet-watchdog:: 114 Pet the watchdog to keep it from biting us for a while. 115 116 hm2_<BoardType>.<BoardNum>.read_gpio:: 117 Read the GPIO input pins only. (This function 118 is not available on the 7i43 due to limitations of the EPP bus.) 119 120 hm2_<BoardType>.<BoardNum>.write_gpio:: 121 Write the GPIO control registers and output pins only. (This function 122 is not available on the 7i43 due to limitations of the EPP bus.) 123 124 [NOTE] 125 ===================================================================== 126 The above *read_gpio* and *write_gpio* functions should not 127 normally be needed, since the GPIO bits are read and written along 128 with everything else in the standard *read* and *write* 129 functions above, which are normally run in the servo thread. 130 131 The *read_gpio* and *write_gpio* functions were provided in 132 case some very fast (frequently updated) I/O is needed. These 133 functions should be run in the base thread. If you have need for 134 this, please send an email and tell us about it, and what your 135 application is. 136 ===================================================================== 137 138 == Pinouts 139 140 The hostmot2 driver does not have a particular pinout. The pinout 141 comes from the firmware that the hostmot2 driver sends to the Anything I/O 142 board. Each firmware has different pinout, and the pinout depends on 143 how many of the available encoders, pwmgens, and stepgens are used. To 144 get a pinout list for your configuration after loading LinuxCNC in the 145 terminal window type: 146 147 dmesg > hm2.txt 148 149 The resulting text file will contain lots of information as well as 150 the pinout for the HostMot2 and any error and warning messages. 151 152 To reduce the clutter by clearing the message buffer before loading 153 LinuxCNC type the following in the terminal window: 154 155 sudo dmesg -c 156 157 Now when you run LinuxCNC and then do a "dmesg > hm2.txt" in the terminal 158 only the info from the time you loaded LinuxCNC will be in your file along 159 with your pinout. The file will be in the current directory of the 160 terminal window. Each line will contain the card name, the card number, 161 the I/O Pin number, the connector and pin, and the usage. From this 162 printout you will know the physical connections to your card based on 163 your configuration. 164 165 An example of a 5i20 configuration: 166 167 [HOSTMOT2] 168 DRIVER=hm2_pci 169 BOARD=5i20 170 CONFIG="firmware=hm2/5i20/SVST8_4.BIT num_encoders=1 num_pwmgens=1 num_stepgens=3" 171 172 The above configuration produced this printout. 173 174 [ 1141.053386] hm2/hm2_5i20.0: 72 I/O Pins used: 175 [ 1141.053394] hm2/hm2_5i20.0: IO Pin 000 (P2-01): IOPort 176 [ 1141.053397] hm2/hm2_5i20.0: IO Pin 001 (P2-03): IOPort 177 [ 1141.053401] hm2/hm2_5i20.0: IO Pin 002 (P2-05): Encoder #0, pin B (Input) 178 [ 1141.053405] hm2/hm2_5i20.0: IO Pin 003 (P2-07): Encoder #0, pin A (Input) 179 [ 1141.053408] hm2/hm2_5i20.0: IO Pin 004 (P2-09): IOPort 180 [ 1141.053411] hm2/hm2_5i20.0: IO Pin 005 (P2-11): Encoder #0, pin Index (Input) 181 [ 1141.053415] hm2/hm2_5i20.0: IO Pin 006 (P2-13): IOPort 182 [ 1141.053418] hm2/hm2_5i20.0: IO Pin 007 (P2-15): PWMGen #0, pin Out0 183 (PWM or Up) (Output) 184 [ 1141.053422] hm2/hm2_5i20.0: IO Pin 008 (P2-17): IOPort 185 [ 1141.053425] hm2/hm2_5i20.0: IO Pin 009 (P2-19): PWMGen #0, pin Out1 186 (Dir or Down) (Output) 187 [ 1141.053429] hm2/hm2_5i20.0: IO Pin 010 (P2-21): IOPort 188 [ 1141.053432] hm2/hm2_5i20.0: IO Pin 011 (P2-23): PWMGen #0, pin 189 Not-Enable (Output) 190 <snip>... 191 [ 1141.053589] hm2/hm2_5i20.0: IO Pin 060 (P4-25): StepGen #2, pin Step (Output) 192 [ 1141.053593] hm2/hm2_5i20.0: IO Pin 061 (P4-27): StepGen #2, pin Direction (Output) 193 [ 1141.053597] hm2/hm2_5i20.0: IO Pin 062 (P4-29): StepGen #2, pin (unused) (Output) 194 [ 1141.053601] hm2/hm2_5i20.0: IO Pin 063 (P4-31): StepGen #2, pin (unused) (Output) 195 [ 1141.053605] hm2/hm2_5i20.0: IO Pin 064 (P4-33): StepGen #2, pin (unused) (Output) 196 [ 1141.053609] hm2/hm2_5i20.0: IO Pin 065 (P4-35): StepGen #2, pin (unused) (Output) 197 [ 1141.053613] hm2/hm2_5i20.0: IO Pin 066 (P4-37): IOPort 198 [ 1141.053616] hm2/hm2_5i20.0: IO Pin 067 (P4-39): IOPort 199 [ 1141.053619] hm2/hm2_5i20.0: IO Pin 068 (P4-41): IOPort 200 [ 1141.053621] hm2/hm2_5i20.0: IO Pin 069 (P4-43): IOPort 201 [ 1141.053624] hm2/hm2_5i20.0: IO Pin 070 (P4-45): IOPort 202 [ 1141.053627] hm2/hm2_5i20.0: IO Pin 071 (P4-47): IOPort 203 [ 1141.053811] hm2/hm2_5i20.0: registered 204 [ 1141.053815] hm2_5i20.0: initialized AnyIO board at 0000:02:02.0 205 206 Note that the I/O Pin nnn will correspond to the pin number shown on 207 the HAL Configuration screen for GPIOs. Some of the Stepgen, Encoder 208 and PWMGen will also show up as GPIOs in the HAL Configuration screen. 209 210 == PIN Files 211 212 The default pinout is described in a .PIN file (human-readable text). 213 When you install a firmware package .deb, the .PIN files are installed in 214 215 /usr/share/doc/hostmot2-firmware-<board>/ 216 217 == Firmware 218 219 The selected firmware (.BIT file) and configuration is uploaded from 220 the PC motherboard to the Mesa mothercard on LinuxCNC startup. 221 If you are using Run In Place, you must still install a 222 hostmot2-firmware-<board> package. There is more information about 223 firmware and configuration in the "Configurations" section. 224 225 == HAL Pins 226 227 The HAL pins for each configuration can be seen by opening up "Show 228 HAL Configuration" from the Machine menu. All the HAL pins and 229 parameters can be found there. The following figure is of the 5i20 230 configuration used above. 231 232 .5i20 HAL Pins[[cap:5i20-HAL-Pins]] 233 234 image::images/5i20-halpins.png[alt="5i20 HAL Pins"] 235 236 == Configurations 237 238 The Hostmot2 firmware is available in several versions, depending on 239 what you are trying to accomplish. You can get a reminder of what a 240 particular firmware is for by looking at the name. Let's look at a 241 couple of examples. 242 243 In the 7i43 (two ports), SV8 ("Servo 8") would be for having 8 servos 244 or fewer, using the "classic" 7i33 4-axis (per port) servo board. 245 So 8 servos would use up all 48 signals in the two ports. But if 246 you only needed 3 servos, you could say `num_encoders=3` and `num_pwmgens=3` 247 and recover 5 servos at 6 signals each, thus gaining 30 bits of GPIO. 248 249 Or, in the 5i22 (four ports), SVST8_24 ("Servo 8, Stepper 24") would be 250 for having 8 servos or fewer (7i33 x2 again), and 24 steppers or fewer 251 (7i47 x2). This would use up all four ports. 252 If you only needed 4 servos you could say `num_encoders=4` and 253 `num_pwmgens=4` and recover 1 port (and save a 7i33). 254 And if you only needed 12 steppers you could say `num_stepgens=12` and 255 free up one port (and save a 7i47). 256 So in this way we can save two ports (48 bits) for GPIO. 257 258 Here are tables of the firmwares available in the official packages. 259 There may be additional firmwares available at the Mesanet.com website 260 that have not yet made it into the LinuxCNC official firmware packages, so 261 check there too. 262 263 3x20 (6-port various) Default Configurations (The 3x20 comes in 1M, 1.5M, and 2M gate versions. 264 So far, all firmware is available in all gate sizes.) 265 [width="90%", options="header"] 266 |==================================================================== 267 |Firmware | Encoder | PWMGen | StepGen | GPIO 268 |SV24 | 24 | 24 | 0 | 0 269 |SVST16_24 | 16 | 16 | 24 | 0 270 |==================================================================== 271 272 5i22 (4-port PCI) Default Configurations (The 5i22 comes in 1M and 1.5M gate versions. 273 So far, all firmware is available in all gate sizes.) 274 [width="90%", options="header"] 275 |==================================================================== 276 |Firmware | Encoder | PWM | StepGen | GPIO 277 |SV16 | 16 | 16 | 0 | 0 278 |SVST2_4_7I47 | 4 | 2 | 4 | 72 279 |SVST8_8 | 8 | 8 | 8 | 0 280 |SVST8_24 | 8 | 8 | 24 | 0 281 |==================================================================== 282 283 5i23 (3-port PCI) Default Configurations (The 5i23 has 400k gates.) 284 [width="90%", options="header"] 285 |==================================================================== 286 |Firmware | Encoder | PWM | StepGen | GPIO 287 |SV12 | 12 | 12 | 0 | 0 288 |SVST2_8 | 2 | 2 | 8 (tbl5) | 12 289 |SVST2_4_7I47 | 4 | 2 | 4 | 48 290 |SV12_2X7I48_72 | 12 | 12 | 0 | 24 291 |SV12IM_2X7I48_72 | 12 (+IM) | 12 | 0 | 12 292 |SVST4_8 | 4 | 4 | 8 (tbl5) | 0 293 |SVST8_4 | 8 | 8 | 4 (tbl5) | 0 294 |SVST8_4IM2 | 8 (+IM) | 8 | 4 | 8 295 |SVST8_8IM2 | 8 (+IM) | 8 | 8 | 0 296 |SVTP6_7I39 | 6 | 0 (6 BLDC) | 0 | 0 297 |==================================================================== 298 299 5i20 (3-port PCI) Default Configurations (The 5i20 has 200k gates.) 300 [width="90%", options="header"] 301 |==================================================================== 302 |Firmware | Encoder | PWM | StepGen | GPIO 303 |SV12 | 12 | 12 | 0 | 0 304 |SVST2_8 | 2 | 2 | 8 (tbl5) | 12 305 |SVST2_4_7I47 | 4 | 2 | 4 | 48 306 |SV12_2X7I48_72 | 12 | 12 | 0 | 24 307 |SV12IM_2X7I48_72 | 12 (+IM) | 12 | 0 | 12 308 |SVST8_4 | 8 | 8 | 4 (tbl5) | 0 309 |SVST8_4IM2 | 8 (+IM) | 8 | 4 | 8 310 |==================================================================== 311 312 4i68 (3-port PC/104) Default Configurations (The 4i68 has 400k gates.) 313 [width="90%", options="header"] 314 |==================================================================== 315 |Firmware | Encoder | PWM | StepGen | GPIO 316 |SV12 | 12 | 12 | 0 | 0 317 |SVST2_4_7I47 | 4 | 2 | 4 | 48 318 |SVST4_8 | 4 | 4 | 8 | 0 319 |SVST8_4 | 8 | 8 | 4 | 0 320 |SVST8_4IM2 | 8 (+IM) | 8 | 4 | 8 321 |SVST8_8IM2 | 8 (+IM) | 8 | 8 | 0 322 |==================================================================== 323 324 . 325 326 . 327 328 4i65 (3-port PC/104) Default Configurations (The 4i65 has 200k gates.) 329 [width="90%", options="header"] 330 |==================================================================== 331 |Firmware | Encoder | PWM | StepGen | GPIO 332 |SV12 | 12 | 12 | 0 | 0 333 |SVST8_4 | 8 | 8 | 4 | 0 334 |SVST8_4IM2 | 8 (+IM) | 8 | 4 | 8 335 |==================================================================== 336 337 7i43 (2-port parallel) 400k gate versions, Default Configurations 338 [width="90%", options="header"] 339 |==================================================================== 340 |Firmware | Encoder | PWM | StepGen | GPIO 341 |SV8 | 8 | 8 | 0 | 0 342 |SVST4_4 | 4 | 4 | 4 (tbl5) | 0 343 |SVST4_6 | 4 | 4 | 6 (tbl3) | 0 344 |SVST4_12 | 4 | 4 | 12 | 0 345 |SVST2_4_7I47 | 4 | 2 | 4 | 24 346 |==================================================================== 347 348 7i43 (2-port parallel) 200k gate versions, Default Configurations 349 [width="90%", options="header"] 350 |==================================================================== 351 |Firmware | Encoder | PWM | StepGen | GPIO 352 |SV8 | 8 | 8 | 0 | 0 353 |SVST4_4 | 4 | 4 | 4 (tbl5) | 0 354 |SVST4_6 | 4 | 4 | 6 (tbl3) | 0 355 |SVST2_4_7I47 | 4 | 2 | 4 | 24 356 |==================================================================== 357 358 Even though several cards may have the same named .BIT file you cannot use 359 a .BIT file that is not for that card. Different cards have different 360 clock frequencies so make sure you load the proper .BIT file for your 361 card. Custom hm2 firmwares can be created for special applications and 362 you may see some custom hm2 firmwares in the directories with the 363 default ones. 364 365 When you load the board-driver (hm2_pci or hm2_7i43), you can tell it 366 to disable instances of the three primary modules (pwmgen, stepgen, and 367 encoder) by setting the count lower. Any I/O pins belonging to disabled 368 module instances become GPIOs. 369 370 == GPIO 371 372 General Purpose I/O pins on the board which are not used by a module 373 instance are exported to HAL as "full" GPIO pins. Full GPIO pins can be 374 configured at run-time to be inputs, outputs, or open drains, and have 375 a HAL interface that exposes this flexibility. I/O pins that are owned 376 by an active module instance are constrained by the requirements of the 377 owning module, and have a restricted HAL interface. 378 379 GPIOs have names like "hm2_<BoardType>.<BoardNum>.gpio.<IONum>." 380 IONum. is a three-digit number. The mapping from IONum to connector and 381 pin-on-that-connector is written to the syslog when the driver loads, 382 and it's documented in Mesa's manual for the Anything I/O boards. 383 384 The hm2 GPIO representation is modeled after the Digital Inputs and 385 Digital Outputs described in the Canonical Device Interface (part of 386 the HAL General Reference document). 387 388 GPIO pins default to input. 389 390 === Pins 391 392 in:: 393 (Bit, Out) Normal state of the hardware input pin. Both full GPIO pins 394 and I/O pins used as inputs by active module instances have this pin. 395 396 in_not:: 397 (Bit, Out) Inverted state of the hardware input pin. Both full GPIO 398 pins and I/O pins used as inputs by active module instances have this 399 pin. 400 401 out:: 402 (Bit, In) Value to be written (possibly inverted) to the hardware 403 output pin. Only full GPIO pins have this pin. 404 405 === Parameters 406 407 invert_output:: 408 (Bit, RW) This parameter only has an effect if the "is_output" 409 parameter is true. If this parameter is true, the output value of the 410 GPIO will be the inverse of the value on the "out" HAL pin. Only full 411 GPIO pins and I/O pins used as outputs by active module instances have 412 this parameter. To invert an active module pin you have to invert the 413 GPIO pin not the module pin. 414 415 is_opendrain:: 416 (Bit, RW) This parameter only has an effect if the "is_output" 417 parameter is true. If this parameter is false, the GPIO behaves as a 418 normal output pin: the I/O pin on the connector is driven to the value 419 specified by the "out" HAL pin (possibly inverted), and the value of 420 the "in" and "in_not" HAL pins is undefined. If this parameter is true, 421 the GPIO behaves as an open-drain pin. Writing 0 to the "out" HAL pin 422 drives the I/O pin low, writing 1 to the "out" HAL pin puts the I/O pin 423 in a high-impedance state. In this high-impedance state the I/O pin 424 floats (weakly pulled high), and other devices can drive the value; the 425 resulting value on the I/O pin is available on the "in" and "in_not" 426 pins. Only full GPIO pins and I/O pins used as outputs by active module 427 instances have this parameter. 428 429 is_output:: 430 (Bit, RW) If set to 0, the GPIO is an input. The I/O pin is put in a 431 high-impedance state (weakly pulled high), to be driven by other 432 devices. The logic value on the I/O pin is available in the "in" and 433 "in_not" HAL pins. Writes to the "out" HAL pin have no effect. If this 434 parameter is set to 1, the GPIO is an output; its behavior then depends 435 on the "is_opendrain" parameter. Only full GPIO pins have this 436 parameter. 437 438 == StepGen 439 440 Stepgens have names like 441 "hm2_<BoardType>.<BoardNum>.stepgen.<Instance>.". "Instance" is a 442 two-digit number that corresponds to the HostMot2 stepgen instance 443 number. There are "num_stepgens" instances, starting with 00. 444 445 Each stepgen allocates 2-6 I/O pins (selected at firmware compile 446 time), but currently only uses two: Step and Direction outputs.footnote:[At 447 present, the firmware supports multi-phase stepper outputs, but 448 the driver doesn't. Interested volunteers are solicited.] 449 450 The stepgen representation is modeled on the stepgen software 451 component. Stepgen default is active high step output (high during step 452 time low during step space). To invert a StepGen output pin you invert 453 the corresponding GPIO pin that is being used by StepGen. To find the 454 GPIO pin being used for the StepGen output run dmesg as shown above. 455 456 Each stepgen instance has the following pins and parameters: 457 458 === Pins 459 460 control-type:: 461 (Bit, In) Switches between position control mode (0) and velocity 462 control mode (1). Defaults to position control (0). 463 464 counts:: 465 (s32, Out) Feedback position in counts (number of steps). 466 467 enable:: 468 (Bit, In) Enables output steps. When false, no steps are generated. 469 470 position-cmd:: 471 (Float, In) Target position of stepper motion, in user-defined 472 position units. 473 474 position-fb:: 475 (Float, Out) Feedback position in user-defined position units (counts 476 / position_scale). 477 478 velocity-cmd:: 479 (Float, In) Target velocity of stepper motion, in user-defined 480 position units per second. This pin is only used when the stepgen is in 481 velocity control mode (control-type=1). 482 483 velocity-fb:: 484 (Float, Out) Feedback velocity in user-defined position units per 485 second. 486 487 === Parameters 488 489 dirhold:: 490 (u32, RW) Minimum duration of stable Direction signal after a step 491 ends, in nanoseconds. 492 493 dirsetup:: 494 (u32, RW) Minimum duration of stable Direction signal before a step 495 begins, in nanoseconds. 496 497 maxaccel:: 498 (Float, RW) Maximum acceleration, in position units per second per 499 second. If set to 0, the driver will not limit its acceleration. 500 501 maxvel:: 502 (Float, RW) Maximum speed, in position units per second. If set to 0, 503 the driver will choose the maximum velocity based on the values of 504 steplen and stepspace (at the time that maxvel was set to 0). 505 506 position-scale:: 507 (Float, RW) Converts from counts to position units. position = counts 508 / position_scale 509 510 step_type:: 511 (u32, RW) Output format, like the step_type modparam to the software 512 stegen(9) component. 0 = Step/Dir, 1 = Up/Down, 2 = Quadrature. In 513 Quadrature mode (step_type=2), the stepgen outputs one complete Gray 514 cycle (00 -> 01 -> 11 -> 10 -> 00) for each "step" it takes. 515 516 steplen:: 517 (u32, RW) Duration of the step signal, in nanoseconds. 518 519 stepspace:: 520 (u32, RW) Minimum interval between step signals, in nanoseconds. 521 522 === Output Parameters 523 524 The Step and Direction pins of each StepGen have two additional 525 parameters. To find which I/O pin belongs to which step and direction 526 output run dmesg as described above. 527 528 invert_output:: 529 (Bit, RW) This parameter only has an effect if the "is_output" 530 parameter is true. If this parameter is true, the output value of the 531 GPIO will be the inverse of the value on the "out" HAL pin. 532 533 is_opendrain:: 534 (Bit, RW) If this parameter is false, the GPIO behaves as a normal 535 output pin: the I/O pin on the connector is driven to the value 536 specified by the "out" HAL pin (possibly inverted). If this parameter 537 is true, the GPIO behaves as an open-drain pin. Writing 0 to the "out" 538 HAL pin drives the I/O pin low, writing 1 to the "out" HAL pin puts the 539 I/O pin in a high-impedance state. In this high-impedance state the I/O 540 pin floats (weakly pulled high), and other devices can drive the value; 541 the resulting value on the I/O pin is available on the "in" and "in_not" 542 pins. Only full GPIO pins and I/O pins used as outputs by active module 543 instances have this parameter. 544 545 == PWMGen 546 547 PWMgens have names like 548 "hm2_<BoardType>.<BoardNum>.pwmgen.<Instance>.". "Instance" is a 549 two-digit number that corresponds to the HostMot2 pwmgen instance 550 number. There are "num_pwmgens" instances, starting with 00. 551 552 In HM2, each pwmgen uses three output I/O pins: Not-Enable, Out0, and 553 Out1. To invert a PWMGen output pin you invert the corresponding GPIO 554 pin that is being used by PWMGen. To find the GPIO pin being used for 555 the PWMGen output run dmesg as shown above. 556 557 The function of the Out0 and Out1 I/O pins varies with output-type 558 parameter (see below). 559 560 The hm2 pwmgen representation is similar to the software pwmgen 561 component. Each pwmgen instance has the following pins and parameters: 562 563 === Pins 564 565 enable:: 566 (Bit, In) If true, the pwmgen will set its Not-Enable pin false and 567 output its pulses. If "enable" is false, pwmgen will set its Not-Enable 568 pin true and not output any signals. 569 570 value:: 571 (Float, In) The current pwmgen command value, in arbitrary units. 572 573 === Parameters 574 575 output-type:: 576 (s32, RW) This emulates the output_type load-time argument to the 577 software pwmgen component. This parameter may be changed at runtime, 578 but most of the time you probably want to set it at startup and then 579 leave it alone. Accepted values are 1 (PWM on Out0 and Direction on 580 Out1), 2 (Up on Out0 and Down on Out1), 3 (PDM mode, PDM on Out0 and 581 Dir on Out1), and 4 (Direction on Out0 and PWM on Out1, "for locked 582 antiphase"). 583 584 scale:: 585 (Float, RW) Scaling factor to convert "value" from arbitrary units to 586 duty cycle: dc = value / scale. Duty cycle has an effective range of 587 -1.0 to +1.0 inclusive, anything outside that range gets clipped. 588 589 pdm_frequency:: 590 (u32, RW) This specifies the PDM frequency, in Hz, of all the pwmgen 591 instances running in PDM mode (mode 3). This is the "pulse slot 592 frequency"; the frequency at which the pdm generator in the Anything I/O board 593 chooses whether to emit a pulse or a space. Each pulse (and space) in 594 the PDM pulse train has a duration of 1/pdm_frequency seconds. For 595 example, setting the pdm_frequency to 2e6 (2 MHz) and the duty cycle to 596 50% results in a 1 MHz square wave, identical to a 1 MHz PWM signal 597 with 50% duty cycle. The effective range of this parameter is from 598 about 1525 Hz up to just under 100 MHz. Note that the max frequency is 599 determined by the ClockHigh frequency of the Anything I/O board; the 600 5i20 and 7i43 both have a 100 MHz clock, resulting in a 100 Mhz max PDM 601 frequency. Other boards may have different clocks, resulting in 602 different max PDM frequencies. If the user attempts to set the 603 frequency too high, it will be clipped to the max supported frequency 604 of the board. 605 606 pwm_frequency:: 607 (u32, RW) This specifies the PWM frequency, in Hz, of all the pwmgen 608 instances running in the PWM modes (modes 1 and 2). This is the 609 frequency of the variable-duty-cycle wave. Its effective range is from 610 1 Hz up to 193 KHz. Note that the max frequency is determined by the 611 ClockHigh frequency of the Anything I/O board; the 5i20 and 7i43 both 612 have a 100 MHz clock, resulting in a 193 KHz max PWM frequency. Other 613 boards may have different clocks, resulting in different max PWM 614 frequencies. If the user attempts to set the frequency too high, it 615 will be clipped to the max supported frequency of the board. 616 Frequencies below about 5 Hz are not terribly accurate, but above 5 Hz 617 they're pretty close. 618 619 === Output Parameters 620 621 The output pins of each PWMGen have two additional parameters. To find 622 which I/O pin belongs to which output run dmesg as described above. 623 624 invert_output:: 625 (Bit, RW) This parameter only has an effect if the "is_output" 626 parameter is true. If this parameter is true, the output value of the 627 GPIO will be the inverse of the value on the "out" HAL pin. 628 629 is_opendrain:: 630 (Bit, RW) If this parameter is false, the GPIO behaves as a normal 631 output pin: the I/O pin on the connector is driven to the value 632 specified by the "out" HAL pin (possibly inverted). If this parameter 633 is true, the GPIO behaves as an open-drain pin. Writing 0 to the "out" 634 HAL pin drives the I/O pin low, writing 1 to the "out" HAL pin puts the 635 I/O pin in a high-impedance state. In this high-impedance state the I/O 636 pin floats (weakly pulled high), and other devices can drive the value; 637 the resulting value on the I/O pin is available on the "in" and "in_not" 638 pins. Only full GPIO pins and I/O pins used as outputs by active module 639 instances have this parameter. 640 641 == Encoder 642 643 Encoders have names like 644 "hm2_<BoardType>.<BoardNum>.encoder.<Instance>.". "Instance" is a 645 two-digit number that corresponds to the HostMot2 encoder instance 646 number. There are "num_encoders" instances, starting with 00. 647 648 Each encoder uses three or four input I/O pins, depending on how the 649 firmware was compiled. Three-pin encoders use A, B, and Index 650 (sometimes also known as Z). Four-pin encoders use A, B, Index, and 651 Index-mask. 652 653 The hm2 encoder representation is similar to the one described by the 654 Canonical Device Interface (in the HAL General Reference document), and 655 to the software encoder component. Each encoder instance has the 656 following pins and parameters: 657 658 === Pins 659 660 count:: 661 (s32, Out) Number of encoder counts since the previous reset. 662 663 index-enable:: 664 (Bit, I/O) When this pin is set to True, the count (and therefore also 665 position) are reset to zero on the next Index (Phase-Z) pulse. At the 666 same time, index-enable is reset to zero to indicate that the pulse has 667 occurred. 668 669 position:: 670 (Float, Out) Encoder position in position units (count / scale). 671 672 rawcounts:: 673 (s32, Out) Total number of encoder counts since the start, not 674 adjusted for index or reset. 675 676 reset:: 677 (Bit, In) When this pin is TRUE, the count and position pins are set 678 to 0. (The value of the velocity pin is not affected by this.) The 679 driver does not reset this pin to FALSE after resetting the count to 0, 680 that is the user's job. 681 682 velocity:: 683 (Float, Out) Estimated encoder velocity in position units per second. 684 685 === Parameters 686 687 counter-mode:: 688 (Bit, RW) Set to False (the default) for Quadrature. Set to True for 689 Up/Down or for single input on Phase A. Can be used for a frequency to 690 velocity converter with a single input on Phase A when set to true. 691 692 filter:: 693 (Bit, RW) If set to True (the default), the quadrature counter needs 694 15 clocks to register a change on any of the three input lines (any 695 pulse shorter than this is rejected as noise). If set to False, the 696 quadrature counter needs only 3 clocks to register a change. The 697 encoder sample clock runs at 33 MHz on the PCI Anything I/O cards and 50 MHz 698 on the 7i43. 699 700 index-invert:: 701 (Bit, RW) If set to True, the rising edge of the Index input pin 702 triggers the Index event (if index-enable is True). If set to False, 703 the falling edge triggers. 704 705 index-mask:: 706 (Bit, RW) If set to True, the Index input pin only has an effect if 707 the Index-Mask input pin is True (or False, depending on the 708 index-mask-invert pin below). 709 710 index-mask-invert:: 711 (Bit, RW) If set to True, Index-Mask must be False for Index to have 712 an effect. If set to False, the Index-Mask pin must be True. 713 714 scale:: 715 (Float, RW) Converts from "count" units to "position" units. A 716 quadrature encoder will normally have 4 counts per pulse so a 100 PPR 717 encoder would be 400 counts per revolution. In ".counter-mode" a 100 718 PPR encoder would have 100 counts per revelution as it only uses the 719 rising edge of A and direction is B. 720 721 vel-timeout:: 722 (Float, RW) When the encoder is moving slower than one pulse for each 723 time that the driver reads the count from the FPGA (in the hm2_read() 724 function), the velocity is harder to estimate. The driver can wait 725 several iterations for the next pulse to arrive, all the while 726 reporting the upper bound of the encoder velocity, which can be 727 accurately guessed. This parameter specifies how long to wait for the 728 next pulse, before reporting the encoder stopped. This parameter is in 729 seconds. 730 731 == Examples 732 733 Several example configurations are included with LinuxCNC for both stepper 734 and servo applications. The configurations are located in the hm2-servo 735 and hm2-stepper sections of the LinuxCNC Configuration Selector window. You 736 will need the same board installed for the configuration you pick to 737 load. The examples are a good place to start and will save you time. 738 Just pick the proper example from the LinuxCNC Configuration Selector and 739 save a copy to your computer so you can edit it. To see the exact pins 740 and parameters that your configuration gave you, open the Show HAL 741 Configuration window from the Machine menu, or do dmesg as outlined 742 above. 743 744