From d997ac121e1112aca0256375e91c7d90a175b956 Mon Sep 17 00:00:00 2001 From: Michael Haberler Date: Sat, 25 Jun 2016 12:20:08 +0000 Subject: [PATCH 1/2] hal_pru_generic: import man page from Charles' repo wget https://raw.githubusercontent.com/cdsteinkuehler/linuxcnc/18ee2e8445d1ef73a17f62d79af465ee4f020fb8/man/man9/hal_pru_generic.9.asciidoc --- docs/man/man9/hal_pru_generic.9.asciidoc | 517 +++++++++++++++++++++++ 1 file changed, 517 insertions(+) create mode 100644 docs/man/man9/hal_pru_generic.9.asciidoc diff --git a/docs/man/man9/hal_pru_generic.9.asciidoc b/docs/man/man9/hal_pru_generic.9.asciidoc new file mode 100644 index 0000000000..2f4a6f6e72 --- /dev/null +++ b/docs/man/man9/hal_pru_generic.9.asciidoc @@ -0,0 +1,517 @@ += HAL_PRU_GENERIC(9) +:manmanual: HAL Components +:mansource: ../man/man9/hal_pru_generic.9.asciidoc +:man version : + +== NAME +hal_pru_generic - Machinekit HAL driver for the TI Programmable Realtime Unit (PRU). + + +== SYNOPSIS +**loadrt hal_pru_generic [format_string]** + +The valid entries in the format_string are: + +* [**prucode=**____] +* [**pru=**__(0|1)__] +* [**pru_period=**__N__] +* [**halname=**____] +* [**num_stepgens=**__N__] +* [**num_pwmgens=**__N[,N]__] +* [**num_encoders=**__N[,N]__] +* [**disabled=**__(0|1)__] + +=== **prucode** [required] +Binary PRU firmware to load and run on the specified PRU. + +=== **pru** [optional, default: 1] +Which PRU (0 or 1) to use to run the code. This only matters if you are using +direct PRU I/O pins, in which case the PRU specified needs to be able to access +the pins used in the HAL configuration. + +=== **pru_period** [optional, default: 10000] +The task period time for the PRU, in nano-seconds. The default of 10000 nS +results in a PRU task frequency of 100 KHz. Smaller values here provide better +timing performance for pwm and step/dir generators, but the setting must be +large enough to allow all PRU tasks to complete. + +=== **halname** [optional, default: hal_pru_generic] +This identifier is used to prefix all created HAL pins and parameters. The +default is for legacy configurations and should otherwise be avoided. Recent +convention sets halname=hpg to provide for shorter HAL names. + +=== **num_stepgens** [optional, default: 0] +Create N stepgen instances. + +=== **num_pwmgens** [optional, default: 0] +Create pwmgen instance[s] with N channels. + +=== **num_encoders** [optional, default: 0] +Create N encoder instances. + +=== **disabled** [optional, default: 0] +If you set disabled=1, the driver will start with the PRU in the disabled +state, which can be useful for debugging. In this state, it is possible to +single-step through the PRU startup code after the driver is loaded. + +== DESCRIPTION +hal_pru_generic is a device driver that uses the PRU subsystem available on +the BeagleBone SBC to perform high-speed hard-real-time bit-twiddling to +generate step/direction and PWM outputs, avoiding the need to run a base +thread on the ARM core which has fairly poor interrupt latency. + +The driver is written for flexibility rather than raw speed (hence the +'generic' in the name). Various functions are supported by small bits +of PRU code (tasklets) that are linked into a function chain for the PRU +when the driver is first loaded. The minimum pru_period (and thus the +maximum step frequency) is determined by how long the PRU takes to execute +all configured tasklets, so simple configurations can run faster than +complex setups with lots of outputs. + +Currently, there are tasklets written for step/direction generation, PWM +output, and encoder inputs (using direct PRU input pins). + +== I/O PINS +The hal_pru_generic driver runs on a BeagleBone and has used a variety of +numbering schemes to identify I/O pins. All legacy pin numbering schemes +are still supported for backwards compatibility, but are not documented here +to avoid confusion (see fixup_pin() the code if you really need to know +how the previous schemes worked). The current numbering scheme is based on +the P8/P9 pin headers found on the BeagleBone. + +Pins are specified using a 4 digit value. The four digit value is composed +of three fields: + + An optional prefix to indicate direct PRU I/O: + 0 or no prefix = standard GPIO pin + 1 = PRU direct output + 2 = PRU direct input + 8 or 9 to indicate the P8 or P9 header + 2 digits to represent the specific pin on the P8 or P9 header + + Examples: + 0811 = GPIO on P8, pin 11 + 811 = GPIO on P8, pin 11 (identical to above) + 1811 = PRU direct output on P8, pin 11 + 2927 = PRU direct input on P9, pin 27 + +Note that not all P8/P9 pins can be used as I/O (some pins are dedicated +to specific signals or power) and not all GPIO pins can be used as PRU +direct input or output. + +WARNINGS: +Direct PRU I/O pins are attatched to a specific PRU. If you choose to use +direct I/O pins, you are responsible for selecting a valid combination of +pin numbers and pru= such that the PRU code runs on a PRU core that can +access the configured pins. + +This driver does not setup any pin multiplexing or GPIO settings (pin +direction, pull-up/down). The user is required to configure these +settings prior to launching the driver, typically by using either a +device tree overlay or the cape-universal overlay and the config-pin +utility. + +== STEPGEN + +stepgens have names like "hpg.stepgen.____". +"Instance" is a two-digit number that corresponds to the stepgen +instance number. There are 'num_stepgens' instances, starting with 00. + +Each stepgen uses 2 IO pins, one for the step signal and one for the direction +signal. + +Each stepgen instance has the following pins and parameters: + +=== Pins: + +(float input) position-cmd + +[indent=4] +==== +Target position of stepper motion, in +arbitrary position units. This pin is only used when the stepgen is in +position control mode (control-type=0). +==== + +(float input) velocity-cmd + +[indent=4] +==== +Target velocity of stepper motion, in +arbitrary position units per second. This pin is only used when the +stepgen is in velocity control mode (control-type=1). +==== + +(float output) position-fb + +[indent=4] +==== +Feedback position in arbitrary position +units. This is similar to "counts/position_scale", but has finer than +step resolution. +==== + +(float output) velocity-fb + +[indent=4] +==== +Feedback velocity in arbitrary position +units per second. +==== + +(s32 output) counts + +[indent=4] +==== +Feedback position in counts (number of steps). +==== + +(bit input) enable + +[indent=4] +==== +This pin enables the step generator instance. +When True, the stepgen instance works as expected. When False, no steps +are generated and velocity-fb goes immediately to 0. If the stepgen is +moving when enable goes false it stops immediately, without obeying the +maxaccel limit. +==== + +(bit input) control-type + +[indent=4] +==== +Switches between position control mode (0) +and velocity control mode (1). Defaults to position control (0). +==== + +(float input) position-scale + +[indent=4] +==== +Converts from counts to position units. +position = counts / position_scale +==== + +(float input) maxvel + +[indent=4] +==== +Maximum speed, in position units per second. If set +to 0, the driver will always use the maximum possible velocity based +on the current step timings and position-scale. The max velocity will +change if the step timings or position-scale changes. Defaults to 0. +==== + +(float input) maxaccel + +[indent=4] +==== +Maximum acceleration, in position units per second +per second. Defaults to 1.0. If set to 0, the driver will not limit its +acceleration at all - this requires that the position-cmd or velocity-cmd +pin is driven in a way that does not exceed the machine's capabilities. +This is probably what you want if you're going to be using the LinuxCNC +trajectory planner to jog or run G-code. +==== + +(u32 input) steplen + +[indent=4] +==== +Minimum duration of the step signal, in nanoseconds. +==== + +(u32 input) stepspace + +[indent=4] +==== +Minimum interval between step signals, in +nanoseconds. +==== + +(u32 input) dirsetup + +[indent=4] +==== +Minimum duration of stable Direction signal before +a step begins, in nanoseconds. +==== + +(u32 input) dirhold + +[indent=4] +==== +Minimum duration of stable Direction signal after a +step ends, in nanoseconds. +==== + +(u32 input) step_pin +==== +I/O pin to use for the step output +==== + +(u32 input) dir_pin +==== +I/O pin to use for the direction output +==== + +(bit input) stepinvert +==== +Inverts the step output (normally high with pulses going low) +==== + +== PWMGEN +pwmgens have names like "hpg.pwmgen.____.out.____". +"Instance" is a two-digit number that corresponds to the pwmgen +instance number. Each channel number value passed to 'num_pwmgens' +creates a pwmgen instance, starting with 00. "Channel" is a two-digit +number that corresponds to a specific pwmgen channel in a pwmgen +instance, starting with 00. + +Each pwmgen instance has a single pwm_peroid, so all channels in that +instance have the same pwm frequency. To support multiple PWM +frequencies, it is possible to create more than one PWM instance, with +each instance having a configurable number of channels. To do so, pass +multiple values separated by commas to num_pwmgens, eg: num_pwmgens=2,1 +would create 2 pwmgen instances with a total of 3 channels: + +[indent=4] +==== +hpg.pwmgen.00.out.00 +hpg.pwmgen.00.out.01 +hpg.pwmgen.01.out.00 +==== + +Each pwmgen uses 1 IO pin + +=== Pins: + +(bit input) enable + +[indent=4] +==== +If true, the pwmgen will output pulses. +If 'enable' is false, pwmgen will not output any signals. +==== + +(float input) value + +[indent=4] +==== +The current pwmgen command value, in arbitrary units. +==== + +(float input) scale + +[indent=4] +==== +Scaling factor to convert 'value' from arbitrary units +to duty cycle: dc = value / scale. Duty cycle has an effective range +of -1.0 to +1.0 inclusive, anything outside that range gets clipped. +The default scale is 1.0. +==== + +(u32 input) pin +==== +I/O pin to use for the pwm output +==== + +In addition to the per-channel pins listed above, there is one +setting that affects all pwmgen channels in an instance: + +(u32 input) pwm_period + +[indent=4] +==== +This specifies the PWM period, in nS. The default is 10,000,000 nS, or +100 Hz. The lower bound is determined by the pru_period and the desired +resolution. The longer the pwm_period, the more bits of resolution are +available but the lower the PWM frequency. +==== + +== ENCODER +Encoders have names like "hpg.encoder.____.out.____". +"Instance" is a two-digit number that corresponds to the encoder +instance number. Each channel number value passed to 'num_encoders' +creates an encoder instance, starting with 00. "Channel" is a two-digit +number that corresponds to a specific encoder channel in an encoder +instance, starting with 00. + +Currently, there is no particular reason to use multiple encoder +instances unless you happen to prefer the way the pins are exported to +HAL (perhaps to keep encoders for motion separate from encoders for a +jog wheel). Support for multiple instances is intended to allow for +different settings for high-speed encoder instances using direct PRU +input pins and lower-speed instances that access standard GPIO pins. + +Currently all encoders **MUST** use direct PRU input pins. + +Each encoder uses up to three PRU direct input pins, depending on the +counting mode. + +WARNING: The encoder uses different pin numbering than the rest of the +hal_pru_generic driver. The pin number values for (A|B|index)-pin +should be the PRU dedicated input pin number, a value in the range of +0-16 inclusive. It is the user's responsibility to insure the physical +I/O pins used are available as direct PRU input pins on the PRU used +to run the hal_pru_generic PRU binary. Unused pins should be assigned +to a PRU input that will not change value (the 'unconnected' inputs +17-29 work well for this). + +Each encoder instance has the following pins: + +=== Pins: + +(s32 output) count + +[indent=4] +==== +Number of encoder counts since the previous reset. +==== + +(float output) position + +[indent=4] +==== +Encoder position in position units (count / scale). +==== + +(float output) velocity + +[indent=4] +==== +Estimated encoder velocity in position units per second. +==== + +(bit input) reset + +[indent=4] +==== +Currently unsupported, included for compatability with hm2. +==== + +(bit in/out) index-enable + +[indent=4] +==== +Currently unsupported, included for compatability with hm2. +==== + +(s32 output) rawcount + +[indent=4] +==== +Total number of encoder counts since the start, not adjusted for index or reset. +==== + +(float input) scale + +[indent=4] +==== +Converts from 'count' units to 'position' units. +==== + +(u32 input) A-pin +==== +PRU direct input pin to use for the A signal +==== + +(bit input) A-invert + +[indent=4] +==== +If True, inverts the polarity of the A signal +==== + +(u32 input) B-pin +==== +PRU direct input pin to use for the B signal +==== + +(bit input) B-invert + +[indent=4] +==== +If True, inverts the polarity of the B signal +==== + +(u32 input) index-pin +==== +PRU direct input pin to use for the index (Z) signal +==== + +(bit input) index-invert + +[indent=4] +==== +If True, the rising edge of the Index input pin triggers the Index event +(if index-enable is True). If set to False, the falling edge triggers. +==== + +(bit input) index-mask + +[indent=4] +==== +Currently unsupported, included for compatability with hm2. +==== + +(bit input) index-mask-invert + +[indent=4] +==== +Currently unsupported, included for compatability with hm2. +==== + +(u32 input) counter-mode + +[indent=4] +==== +0 = Quadrature mode (default) +1 = Step/Dir mode (A = Step, B = Up/Down) +2 = Up counter (counts rising edges on A, B is ignored) +3 = Quadrature x1 mode (matches HAL software encoder x1 mode) +All other values are reserved +==== + +(bit input) filter + +[indent=4] +==== +Currently unsupported, included for compatability with hm2. +==== + +(float input) vel-timeout + +[indent=4] +==== +When the encoder is moving slower than one +pulse for each time that the driver reads the count from the PRU (in +the capture-position() function), the velocity is harder to estimate. The driver +can wait several iterations for the next pulse to arrive, all the while +reporting the upper bound of the encoder velocity, which can be accurately +guessed. This parameter specifies how long to wait for the next pulse, +before reporting the encoder stopped. This parameter is in seconds. +==== + +== FUNCTIONS +**.capture-position** + +[indent=4] +==== +This reads the encoder counters and stepgen feedbacks from the PRU. +==== + +**.update** + +[indent=4] +==== +This updates the PWM duty cycles and stepgen rates on the PRU. Any +changes to configuration pins such as stepgen timing, inversions, +etc, are also effected by this function. +==== + +== SEE ALSO + +== LICENSE +GPL From 701a6143dbe8e5d044327080d2d353f87f1620f5 Mon Sep 17 00:00:00 2001 From: Michael Haberler Date: Sat, 25 Jun 2016 13:19:43 +0000 Subject: [PATCH 2/2] hal_pru_generic: cosmetic touchups --- docs/man/man9/hal_pru_generic.9.asciidoc | 373 ++++++----------------- 1 file changed, 94 insertions(+), 279 deletions(-) diff --git a/docs/man/man9/hal_pru_generic.9.asciidoc b/docs/man/man9/hal_pru_generic.9.asciidoc index 2f4a6f6e72..84a198100b 100644 --- a/docs/man/man9/hal_pru_generic.9.asciidoc +++ b/docs/man/man9/hal_pru_generic.9.asciidoc @@ -1,3 +1,7 @@ +--- +--- +:skip-front-matter: + = HAL_PRU_GENERIC(9) :manmanual: HAL Components :mansource: ../man/man9/hal_pru_generic.9.asciidoc @@ -6,20 +10,19 @@ == NAME hal_pru_generic - Machinekit HAL driver for the TI Programmable Realtime Unit (PRU). - == SYNOPSIS -**loadrt hal_pru_generic [format_string]** +**loadrt hal_pru_generic [argument]...** -The valid entries in the format_string are: +Valid arguments are: -* [**prucode=**____] -* [**pru=**__(0|1)__] -* [**pru_period=**__N__] -* [**halname=**____] -* [**num_stepgens=**__N__] -* [**num_pwmgens=**__N[,N]__] -* [**num_encoders=**__N[,N]__] -* [**disabled=**__(0|1)__] +* **prucode=**____ +* **pru=**__[0|1]__ +* **pru_period=**__N__ +* **halname=**____ +* **num_stepgens=**__N__ +* **num_pwmgens=**__N[,N]__ +* **num_encoders=**__N[,N]__ +* **disabled=**__[0|1]__] === **prucode** [required] Binary PRU firmware to load and run on the specified PRU. @@ -55,10 +58,11 @@ state, which can be useful for debugging. In this state, it is possible to single-step through the PRU startup code after the driver is loaded. == DESCRIPTION -hal_pru_generic is a device driver that uses the PRU subsystem available on +hal_pru_generic is a device driver that uses the PRU subsystem available +in Texas Instruments Sitara processors like on the BeagleBone SBC to perform high-speed hard-real-time bit-twiddling to generate step/direction and PWM outputs, avoiding the need to run a base -thread on the ARM core which has fairly poor interrupt latency. +thread on the ARM core which has fairly poor latency. The driver is written for flexibility rather than raw speed (hence the 'generic' in the name). Various functions are supported by small bits @@ -82,25 +86,27 @@ the P8/P9 pin headers found on the BeagleBone. Pins are specified using a 4 digit value. The four digit value is composed of three fields: - An optional prefix to indicate direct PRU I/O: - 0 or no prefix = standard GPIO pin - 1 = PRU direct output - 2 = PRU direct input - 8 or 9 to indicate the P8 or P9 header - 2 digits to represent the specific pin on the P8 or P9 header +direction digit - an optional prefix to indicate direct PRU I/O:: +* 0 or no prefix = standard GPIO pin +* 1 = PRU direct output +* 2 = PRU direct input +header digit:: +* 8 or 9 to indicate the header (P8 or P9) +pin number on P8 or P9 header:: +* 2 digits to represent the specific pin on the P8 or P9 header + +Examples: - Examples: - 0811 = GPIO on P8, pin 11 - 811 = GPIO on P8, pin 11 (identical to above) - 1811 = PRU direct output on P8, pin 11 - 2927 = PRU direct input on P9, pin 27 + 0811 = GPIO on P8, pin 11 + 811 = GPIO on P8, pin 11 (identical to above) + 1811 = PRU direct output on P8, pin 11 + 2927 = PRU direct input on P9, pin 27 Note that not all P8/P9 pins can be used as I/O (some pins are dedicated to specific signals or power) and not all GPIO pins can be used as PRU direct input or output. -WARNINGS: -Direct PRU I/O pins are attatched to a specific PRU. If you choose to use +WARNING: Direct PRU I/O pins are attatched to a specific PRU. If you choose to use direct I/O pins, you are responsible for selecting a valid combination of pin numbers and pru= such that the PRU code runs on a PRU core that can access the configured pins. @@ -124,142 +130,63 @@ Each stepgen instance has the following pins and parameters: === Pins: -(float input) position-cmd - -[indent=4] -==== -Target position of stepper motion, in +*position-cmd* (float input):: Target position of stepper motion, in arbitrary position units. This pin is only used when the stepgen is in position control mode (control-type=0). -==== - -(float input) velocity-cmd -[indent=4] -==== -Target velocity of stepper motion, in +*velocity-cmd* (float input):: Target velocity of stepper motion, in arbitrary position units per second. This pin is only used when the stepgen is in velocity control mode (control-type=1). -==== -(float output) position-fb - -[indent=4] -==== -Feedback position in arbitrary position +*position-fb* (float output):: Feedback position in arbitrary position units. This is similar to "counts/position_scale", but has finer than step resolution. -==== - -(float output) velocity-fb -[indent=4] -==== -Feedback velocity in arbitrary position +*velocity-fb* (float output):: Feedback velocity in arbitrary position units per second. -==== -(s32 output) counts +*counts* (s32 output):: Feedback position in counts (number of steps). -[indent=4] -==== -Feedback position in counts (number of steps). -==== - -(bit input) enable - -[indent=4] -==== -This pin enables the step generator instance. +*enable* (bit input):: This pin enables the step generator instance. When True, the stepgen instance works as expected. When False, no steps are generated and velocity-fb goes immediately to 0. If the stepgen is moving when enable goes false it stops immediately, without obeying the maxaccel limit. -==== - -(bit input) control-type -[indent=4] -==== -Switches between position control mode (0) +*control-type* (bit input):: Switches between position control mode (0) and velocity control mode (1). Defaults to position control (0). -==== -(float input) position-scale - -[indent=4] -==== -Converts from counts to position units. +*position-scale* (float input):: Converts from counts to position units. position = counts / position_scale -==== - -(float input) maxvel -[indent=4] -==== -Maximum speed, in position units per second. If set +*maxvel* (float input):: Maximum speed, in position units per second. If set to 0, the driver will always use the maximum possible velocity based on the current step timings and position-scale. The max velocity will change if the step timings or position-scale changes. Defaults to 0. -==== - -(float input) maxaccel -[indent=4] -==== -Maximum acceleration, in position units per second +*maxaccel* (float input):: Maximum acceleration, in position units per second per second. Defaults to 1.0. If set to 0, the driver will not limit its acceleration at all - this requires that the position-cmd or velocity-cmd pin is driven in a way that does not exceed the machine's capabilities. This is probably what you want if you're going to be using the LinuxCNC trajectory planner to jog or run G-code. -==== -(u32 input) steplen +*steplen* (u32 input):: Minimum duration of the step signal, in nanoseconds. -[indent=4] -==== -Minimum duration of the step signal, in nanoseconds. -==== - -(u32 input) stepspace - -[indent=4] -==== -Minimum interval between step signals, in +*stepspace* (u32 input):: Minimum interval between step signals, in nanoseconds. -==== - -(u32 input) dirsetup -[indent=4] -==== -Minimum duration of stable Direction signal before +*dirsetup* (u32 input):: Minimum duration of stable Direction signal before a step begins, in nanoseconds. -==== - -(u32 input) dirhold -[indent=4] -==== -Minimum duration of stable Direction signal after a +*dirhold* (u32 input):: Minimum duration of stable Direction signal after a step ends, in nanoseconds. -==== -(u32 input) step_pin -==== -I/O pin to use for the step output -==== +*step_pin* (u32 input):: I/O pin to use for the step output -(u32 input) dir_pin -==== -I/O pin to use for the direction output -==== +*dir_pin* (u32 input):: I/O pin to use for the direction output -(bit input) stepinvert -==== -Inverts the step output (normally high with pulses going low) -==== +*stepinvert* (bit input):: Inverts the step output (normally high with pulses going low) == PWMGEN pwmgens have names like "hpg.pwmgen.____.out.____". @@ -287,48 +214,26 @@ Each pwmgen uses 1 IO pin === Pins: -(bit input) enable - -[indent=4] -==== -If true, the pwmgen will output pulses. +*enable* (bit input):: If true, the pwmgen will output pulses. If 'enable' is false, pwmgen will not output any signals. -==== -(float input) value +*value* (float input):: The current pwmgen command value, in arbitrary units. -[indent=4] -==== -The current pwmgen command value, in arbitrary units. -==== - -(float input) scale - -[indent=4] -==== -Scaling factor to convert 'value' from arbitrary units +*scale* (float input):: Scaling factor to convert 'value' from arbitrary units to duty cycle: dc = value / scale. Duty cycle has an effective range of -1.0 to +1.0 inclusive, anything outside that range gets clipped. The default scale is 1.0. -==== - -(u32 input) pin -==== -I/O pin to use for the pwm output -==== +*pin* (u32 input):: I/O pin to use for the pwm output ++ In addition to the per-channel pins listed above, there is one setting that affects all pwmgen channels in an instance: -(u32 input) pwm_period - -[indent=4] -==== -This specifies the PWM period, in nS. The default is 10,000,000 nS, or +*pwm_period* (u32 input):: This specifies the PWM period, in nS. The default is 10,000,000 nS, or 100 Hz. The lower bound is determined by the pru_period and the desired resolution. The longer the pwm_period, the more bits of resolution are available but the lower the PWM frequency. -==== + == ENCODER Encoders have names like "hpg.encoder.____.out.____". @@ -363,153 +268,63 @@ Each encoder instance has the following pins: === Pins: -(s32 output) count - -[indent=4] -==== -Number of encoder counts since the previous reset. -==== - -(float output) position - -[indent=4] -==== -Encoder position in position units (count / scale). -==== - -(float output) velocity - -[indent=4] -==== -Estimated encoder velocity in position units per second. -==== - -(bit input) reset - -[indent=4] -==== -Currently unsupported, included for compatability with hm2. -==== - -(bit in/out) index-enable - -[indent=4] -==== -Currently unsupported, included for compatability with hm2. -==== - -(s32 output) rawcount - -[indent=4] -==== -Total number of encoder counts since the start, not adjusted for index or reset. -==== - -(float input) scale - -[indent=4] -==== -Converts from 'count' units to 'position' units. -==== - -(u32 input) A-pin -==== -PRU direct input pin to use for the A signal -==== - -(bit input) A-invert - -[indent=4] -==== -If True, inverts the polarity of the A signal -==== - -(u32 input) B-pin -==== -PRU direct input pin to use for the B signal -==== - -(bit input) B-invert - -[indent=4] -==== -If True, inverts the polarity of the B signal -==== - -(u32 input) index-pin -==== -PRU direct input pin to use for the index (Z) signal -==== - -(bit input) index-invert - -[indent=4] -==== -If True, the rising edge of the Index input pin triggers the Index event +*count* (s32 output):: Number of encoder counts since the previous reset. +*position* (float output):: Encoder position in position units (count / scale). +*velocity* (float output):: Estimated encoder velocity in position units per second. +*reset* (bit input):: Currently unsupported, included for compatability with hm2. +*index-enable* (bit in/out):: Currently unsupported, included for compatability with hm2. +*rawcount* (s32 output):: Total number of encoder counts since the start, not adjusted for index or reset. +*scale* (float input):: Converts from 'count' units to 'position' units. +*A-pin* (u32 input):: PRU direct input pin to use for the A signal +*A-invert* (bit input):: If True, inverts the polarity of the A signal +*B-pin* (u32 input):: PRU direct input pin to use for the B signal +*B-invert* (bit input):: If True, inverts the polarity of the B signal +*index-pin* (u32 input):: PRU direct input pin to use for the index (Z) signal +*index-invert* (bit input):: If True, the rising edge of the Index input pin triggers the Index event (if index-enable is True). If set to False, the falling edge triggers. -==== - -(bit input) index-mask - -[indent=4] -==== -Currently unsupported, included for compatability with hm2. -==== +*index-mask* (bit input):: Currently unsupported, included for compatability with hm2. +*index-mask-invert* (bit input):: Currently unsupported, included for compatability with hm2. +*counter-mode* (u32 input):: ++ +[cols="2*", options="header"] +|=== +|Value +|Function -(bit input) index-mask-invert - -[indent=4] -==== -Currently unsupported, included for compatability with hm2. -==== +|0 +|Quadrature mode (default) -(u32 input) counter-mode +|1 +|Step/Dir mode (A = Step, B = Up/Down) -[indent=4] -==== -0 = Quadrature mode (default) -1 = Step/Dir mode (A = Step, B = Up/Down) -2 = Up counter (counts rising edges on A, B is ignored) -3 = Quadrature x1 mode (matches HAL software encoder x1 mode) -All other values are reserved -==== +|2 +|Up counter (counts rising edges on A, B is ignored) -(bit input) filter +|3 +|Quadrature x1 mode (matches HAL software encoder x1 mode) -[indent=4] -==== -Currently unsupported, included for compatability with hm2. -==== +|All other values +|reserved +|=== -(float input) vel-timeout +*filter* (bit input):: Currently unsupported, included for compatability with hm2. -[indent=4] -==== -When the encoder is moving slower than one +*vel-timeout* (float input):: When the encoder is moving slower than one pulse for each time that the driver reads the count from the PRU (in the capture-position() function), the velocity is harder to estimate. The driver can wait several iterations for the next pulse to arrive, all the while reporting the upper bound of the encoder velocity, which can be accurately guessed. This parameter specifies how long to wait for the next pulse, before reporting the encoder stopped. This parameter is in seconds. -==== -== FUNCTIONS -**.capture-position** - -[indent=4] -==== -This reads the encoder counters and stepgen feedbacks from the PRU. -==== -**.update** +== FUNCTIONS +*.capture-position*:: This reads the encoder counters and stepgen feedbacks from the PRU. -[indent=4] -==== -This updates the PWM duty cycles and stepgen rates on the PRU. Any +*.update*:: This updates the PWM duty cycles and stepgen rates on the PRU. Any changes to configuration pins such as stepgen timing, inversions, etc, are also effected by this function. -==== + == SEE ALSO