:lang: en
:toc:

[[cha:mesa-hostmot2-driver]]
= Mesa HostMot2 Driver

// Custom lang highlight
// must come after the doc title, to work around a bug in asciidoc 8.6.6
:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}
:ngc: {basebackend@docbook:'':ngc}

== Introduction

HostMot2 is an FPGA configuration developed by Mesa Electronics for
their line of 'Anything I/O' motion control cards.
The firmware is open source, portable and flexible.
It can be configured (at compile-time)
with zero or more instances (an object created at runtime) of each of several Modules:
encoders (quadrature counters), PWM generators, and step/dir generators.
The firmware can be configured (at run-time) to connect each of these instances to pins on the I/O headers.
I/O pins not driven by a Module instance revert to general-purpose bi-directional digital I/O.

== Firmware Binaries

.50 Pin Header FPGA cards

Several pre-compiled HostMot2 firmware binaries are available for the different Anything I/O boards.
This list is incomplete, check the hostmot2-firmware distribution for up-to-date firmware lists.

* 3x20 (144 I/O pins): using hm2_pci module
** 24-channel servo
** 16-channel servo plus 24 step/dir generators

* 5I22 (96 I/O pins): using hm2_pci module
** 16-channel servo
** 8-channel servo plus 24 step/dir generators

* 5I20, 5I23, 4I65, 4I68 (72 I/O pins): using hm2_pci module
** 12-channel servo
** 8-channel servo plus 4 step/dir generators
** 4-channel servo plus 8 step/dir generators

* 7I43 (48 I/O pins): using hm2_7i43 module
** 8-channel servo (8 PWM generators & 8 encoders)
** 4-channel servo plus 4 step/dir generators

.DB25 FPGA cards

The 5I25 Superport FPGA card is preprogrammed when purchased and does not
need a firmware binary.

== Installing Firmware

Depending on how you installed LinuxCNC you may have to open the Synaptic
Package Manager from the System menu and install the package for your
Mesa card. The quickest way to find them is to do a search for
'hostmot2' in the Synaptic Package Manager. Mark the firmware for
installation, then apply.

== Loading HostMot2

The LinuxCNC support for the HostMot2 firmware is split into a generic
driver called 'hostmot2' and two low-level I/O drivers for the Anything
I/O boards. The low-level I/O drivers are 'hm2_7i43' and 'hm2_pci' (for
all the PCI- and PC-104/Plus-based Anything I/O boards). The hostmot2 driver
must be loaded first, using a HAL command like this:

[source,{hal}]
----
loadrt hostmot2
----

See the hostmot2(9) man page for details.

The hostmot2 driver by itself does nothing, it needs access to actual
boards running the HostMot2 firmware. The low-level I/O drivers provide
this access. The low-level I/O drivers are loaded with commands like
this:

[source,{hal}]
----
loadrt hm2_pci config="firmware=hm2/5i20/SVST8_4.BIT
       num_encoders=3 num_pwmgens=3 num_stepgens=1"
----

The config parameters are described in the hostmot2 man page.

== Watchdog

The HostMot2 firmware may include a watchdog Module; if it does, the
hostmot2 driver will use it.

The watchdog must be petted by LinuxCNC periodically or it will bite.
The hm2 write function (see below) pets the watchdog.

When the watchdog bites, all the board's I/O pins are disconnected from
their Module instances and become high-impedance inputs (pulled high).
The state of the HostMot2 firmware modules is not disturbed (except
for the configuration of the I/O Pins). Encoder instances keep counting
quadrature pulses, and pwm- and step-generators keep generating signals
(which are not relayed to the motors, because the I/O Pins have become
inputs).

Resetting the watchdog resets the I/O pins to the configuration chosen
at load-time.

If the firmware includes a watchdog, the following HAL objects will be
exported:

=== Pins

* 'has_bit' - (bit i/o) True if the watchdog has bit, False if the
  watchdog has not bit. If the watchdog has bit and the has_bit bit is
  True, the user can reset it to False to resume operation.

=== Parameters

* 'timeout_ns' - (u32 read/write) Watchdog timeout, in nanoseconds.
  This is initialized to 5,000,000 (5 milliseconds) at module load time.
  If more than this amount of time passes between calls to the hm2 write
  function, the watchdog will bite.

== HostMot2 Functions

 * 'hm2_<BoardType>.<BoardNum>.read' - Read all inputs, update input HAL pins.

 * 'hm2_<BoardType>.<BoardNum>.write' - Write all outputs.

 * 'hm2_<BoardType>.<BoardNum>.read_gpio' - Read the GPIO input pins only.
   (This function is not available on the 7I43 due to limitations of the EPP bus.)

 * 'hm2_<BoardType>.<BoardNum>.write_gpio' - Write the GPIO control registers and output pins only.
   (This function is not available on the 7I43 due to limitations of the EPP bus.)

[NOTE]
====
The above 'read_gpio' and 'write_gpio' functions should not
normally be needed, since the GPIO bits are read and written along
with everything else in the standard 'read' and 'write'
functions above, which are normally run in the servo thread.

The 'read_gpio' and 'write_gpio' functions were provided in
case some very fast (frequently updated) I/O is needed. These
functions should be run in the base thread. If you have need for
this, please send an email and tell us about it, and what your
application is.
====

== Pinouts

The hostmot2 driver does not have a particular pinout. The pinout
comes from the firmware that the hostmot2 driver sends to the Anything I/O
board. Each firmware has different pinout, and the pinout depends on
how many of the available encoders, pwmgens, and stepgens are used. To
get a pinout list for your configuration after loading LinuxCNC in the
terminal window type:

----
dmesg > hm2.txt
----

The resulting text file will contain lots of information as well as
the pinout for the HostMot2 and any error and warning messages.

To reduce the clutter by clearing the message buffer before loading
LinuxCNC type the following in the terminal window:

----
sudo dmesg -c
----

Now when you run LinuxCNC and then do a 'dmesg > hm2.txt' in the terminal
only the info from the time you loaded LinuxCNC will be in your file along
with your pinout. The file will be in the current directory of the
terminal window. Each line will contain the card name, the card number,
the I/O Pin number, the connector and pin, and the usage. From this
printout you will know the physical connections to your card based on
your configuration.

An example of a 5I20 configuration:

[source,{ini}]
----
[HOSTMOT2]
DRIVER=hm2_pci
BOARD=5i20
CONFIG="firmware=hm2/5i20/SVST8_4.BIT num_encoders=1 num_pwmgens=1 num_stepgens=3"
----

The above configuration produced this printout.

----
[ 1141.053386] hm2/hm2_5i20.0: 72 I/O Pins used:
[ 1141.053394] hm2/hm2_5i20.0: IO Pin 000 (P2-01): IOPort
[ 1141.053397] hm2/hm2_5i20.0: IO Pin 001 (P2-03): IOPort
[ 1141.053401] hm2/hm2_5i20.0: IO Pin 002 (P2-05): Encoder #0, pin B (Input)
[ 1141.053405] hm2/hm2_5i20.0: IO Pin 003 (P2-07): Encoder #0, pin A (Input)
[ 1141.053408] hm2/hm2_5i20.0: IO Pin 004 (P2-09): IOPort
[ 1141.053411] hm2/hm2_5i20.0: IO Pin 005 (P2-11): Encoder #0, pin Index (Input)
[ 1141.053415] hm2/hm2_5i20.0: IO Pin 006 (P2-13): IOPort
[ 1141.053418] hm2/hm2_5i20.0: IO Pin 007 (P2-15): PWMGen #0, pin Out0 (PWM or Up) (Output)
[ 1141.053422] hm2/hm2_5i20.0: IO Pin 008 (P2-17): IOPort
[ 1141.053425] hm2/hm2_5i20.0: IO Pin 009 (P2-19): PWMGen #0, pin Out1 (Dir or Down) (Output)
[ 1141.053429] hm2/hm2_5i20.0: IO Pin 010 (P2-21): IOPort
[ 1141.053432] hm2/hm2_5i20.0: IO Pin 011 (P2-23): PWMGen #0, pin Not-Enable (Output)
<snip>...
[ 1141.053589] hm2/hm2_5i20.0: IO Pin 060 (P4-25): StepGen #2, pin Step (Output)
[ 1141.053593] hm2/hm2_5i20.0: IO Pin 061 (P4-27): StepGen #2, pin Direction (Output)
[ 1141.053597] hm2/hm2_5i20.0: IO Pin 062 (P4-29): StepGen #2, pin (unused) (Output)
[ 1141.053601] hm2/hm2_5i20.0: IO Pin 063 (P4-31): StepGen #2, pin (unused) (Output)
[ 1141.053605] hm2/hm2_5i20.0: IO Pin 064 (P4-33): StepGen #2, pin (unused) (Output)
[ 1141.053609] hm2/hm2_5i20.0: IO Pin 065 (P4-35): StepGen #2, pin (unused) (Output)
[ 1141.053613] hm2/hm2_5i20.0: IO Pin 066 (P4-37): IOPort
[ 1141.053616] hm2/hm2_5i20.0: IO Pin 067 (P4-39): IOPort
[ 1141.053619] hm2/hm2_5i20.0: IO Pin 068 (P4-41): IOPort
[ 1141.053621] hm2/hm2_5i20.0: IO Pin 069 (P4-43): IOPort
[ 1141.053624] hm2/hm2_5i20.0: IO Pin 070 (P4-45): IOPort
[ 1141.053627] hm2/hm2_5i20.0: IO Pin 071 (P4-47): IOPort
[ 1141.053811] hm2/hm2_5i20.0: registered
[ 1141.053815] hm2_5i20.0: initialized AnyIO board at 0000:02:02.0
----

[NOTE]
That the I/O Pin nnn will correspond to the pin number shown on
the HAL Configuration screen for GPIOs. Some of the StepGen, Encoder
and PWMGen will also show up as GPIOs in the HAL Configuration screen.

== PIN Files

The default pinout is described in a .PIN file (human-readable text).
When you install a firmware package the .PIN files are installed in

----
/usr/share/doc/hostmot2-firmware-<board>/
----

== Firmware

The selected firmware (.BIT file) and configuration is uploaded from
the PC motherboard to the Mesa mothercard on LinuxCNC startup.
If you are using Run In Place, you must still install a
hostmot2-firmware-<board> package. There is more information about
firmware and configuration in the 'Configurations' section.

== HAL Pins

The HAL pins for each configuration can be seen by opening up 'Show
HAL Configuration' from the Machine menu. All the HAL pins and
parameters can be found there. The following figure is of the 5I20
configuration used above.

[[cap:5i20-HAL-Pins]]
.5i20 HAL Pins
image::images/5i20-halpins.png["5i20 HAL Pins"]

== Configurations

The Hostmot2 firmware is available in several versions, depending on
what you are trying to accomplish. You can get a reminder of what a
particular firmware is for by looking at the name. Let's look at a
couple of examples.

In the 7I43 (two ports), SV8 ('Servo 8') would be for having 8 servos
or fewer, using the 'classic' 7I33 4-axis (per port) servo board.
So 8 servos would use up all 48 signals in the two ports. But if
you only needed 3 servos, you could say 'num_encoders=3' and 'num_pwmgens=3'
and recover 5 servos at 6 signals each, thus gaining 30 bits of GPIO.

Or, in the 5I22 (four ports), SVST8_24 ('Servo 8, Stepper 24') would be
for having 8 servos or fewer (7I33 x2 again), and 24 steppers or fewer
(7I47 x2). This would use up all four ports.
If you only needed 4 servos you could say 'num_encoders=4' and
'num_pwmgens=4' and recover 1 port (and save a 7I33).
And if you only needed 12 steppers you could say 'num_stepgens=12' and
free up one port (and save a 7I47).
So in this way we can save two ports (48 bits) for GPIO.

Here are tables of the firmwares available in the official packages.
There may be additional firmwares available at the Mesanet.com website
that have not yet made it into the LinuxCNC official firmware packages, so
check there too.

3x20 (6-port various) Default Configurations (The 3x20 comes in 1M,
1.5M, and 2M gate versions.
So far, all firmware is available in all gate sizes.)

[width="90%",options="header"]
|===
|Firmware   | Encoder | PWMGen | StepGen | GPIO
|SV24       | 24      | 24     | 0       | 0
|SVST16_24  | 16      | 16     | 24      | 0
|===

5I22 (4-port PCI) Default Configurations (The 5I22 comes in 1M and 1.5M
gate versions.
So far, all firmware is available in all gate sizes.)

[width="90%",options="header"]
|===
|Firmware     | Encoder | PWM | StepGen | GPIO
|SV16         | 16      | 16  | 0       | 0
|SVST2_4_7I47 | 4       | 2   | 4       | 72
|SVST8_8      | 8       | 8   | 8       | 0
|SVST8_24     | 8       | 8   | 24      | 0
|===

5I23 (3-port PCI) Default Configurations (The 5I23 has 400k gates.)

[width="90%",options="header"]
|===
|Firmware         | Encoder  | PWM        | StepGen  | GPIO
|SV12             | 12       | 12         | 0        | 0
|SVST2_8          | 2        | 2          | 8 (tbl5) | 12
|SVST2_4_7I47     | 4        | 2          | 4        | 48
|SV12_2X7I48_72   | 12       | 12         | 0        | 24
|SV12IM_2X7I48_72 | 12 (+IM) | 12         | 0        | 12
|SVST4_8          | 4        | 4          | 8 (tbl5) | 0
|SVST8_4          | 8        | 8          | 4 (tbl5) | 0
|SVST8_4IM2       | 8 (+IM)  | 8          | 4        | 8
|SVST8_8IM2       | 8 (+IM)  | 8          | 8        | 0
|SVTP6_7I39       | 6        | 0 (6 BLDC) | 0        | 0
|===

5I20 (3-port PCI) Default Configurations (The 5I20 has 200k gates.)

[width="90%",options="header"]
|===
|Firmware         | Encoder  | PWM        | StepGen  | GPIO
|SV12             | 12       | 12         | 0        | 0
|SVST2_8          | 2        | 2          | 8 (tbl5) | 12
|SVST2_4_7I47     | 4        | 2          | 4        | 48
|SV12_2X7I48_72   | 12       | 12         | 0        | 24
|SV12IM_2X7I48_72 | 12 (+IM) | 12         | 0        | 12
|SVST8_4          | 8        | 8          | 4 (tbl5) | 0
|SVST8_4IM2       | 8 (+IM)  | 8          | 4        | 8
|===

4I68 (3-port PC/104) Default Configurations (The 4I68 has 400k gates.)

[width="90%",options="header"]
|===
|Firmware     | Encoder  | PWM        | StepGen  | GPIO
|SV12         | 12       | 12         | 0        | 0
|SVST2_4_7I47 | 4        | 2          | 4        | 48
|SVST4_8      | 4        | 4          | 8        | 0
|SVST8_4      | 8        | 8          | 4        | 0
|SVST8_4IM2   | 8 (+IM)  | 8          | 4        | 8
|SVST8_8IM2   | 8 (+IM)  | 8          | 8        | 0
|===


4I65 (3-port PC/104) Default Configurations (The 4I65 has 200k gates.)

[width="90%",options="header"]
|===
|Firmware   | Encoder  | PWM        | StepGen  | GPIO
|SV12       | 12       | 12         | 0        | 0
|SVST8_4    | 8        | 8          | 4        | 0
|SVST8_4IM2 | 8 (+IM)  | 8          | 4        | 8
|===

7I43 (2-port parallel) 400k gate versions, Default Configurations

[width="90%",options="header"]
|===
|Firmware     | Encoder  | PWM        | StepGen  | GPIO
|SV8          | 8        | 8          | 0        | 0
|SVST4_4      | 4        | 4          | 4 (tbl5) | 0
|SVST4_6      | 4        | 4          | 6 (tbl3) | 0
|SVST4_12     | 4        | 4          | 12       | 0
|SVST2_4_7I47 | 4        | 2          | 4        | 24
|===

7I43 (2-port parallel) 200k gate versions, Default Configurations

[width="90%",options="header"]
|===
|Firmware     | Encoder  | PWM        | StepGen  | GPIO
|SV8          | 8        | 8          | 0        | 0
|SVST4_4      | 4        | 4          | 4 (tbl5) | 0
|SVST4_6      | 4        | 4          | 6 (tbl3) | 0
|SVST2_4_7I47 | 4        | 2          | 4        | 24
|===

Even though several cards may have the same named .BIT file you cannot use
a .BIT file that is not for that card. Different cards have different
clock frequencies so make sure you load the proper .BIT file for your
card. Custom hm2 firmwares can be created for special applications and
you may see some custom hm2 firmwares in the directories with the
default ones.

When you load the board-driver (hm2_pci or hm2_7i43), you can tell it
to disable instances of the three primary modules (pwmgen, stepgen, and
encoder) by setting the count lower. Any I/O pins belonging to disabled
module instances become GPIOs.

== GPIO

General Purpose I/O pins on the board which are not used by a module
instance are exported to HAL as 'full' GPIO pins. Full GPIO pins can be
configured at run-time to be inputs, outputs, or open drains, and have
a HAL interface that exposes this flexibility. I/O pins that are owned
by an active module instance are constrained by the requirements of the
owning module, and have a restricted HAL interface.

GPIOs have names like 'hm2_<BoardType>.<BoardNum>.gpio.<IONum>.'
IONum is a three-digit number. The mapping from IONum to connector and
pin-on-that-connector is written to the syslog when the driver loads,
and it's documented in Mesa's manual for the Anything I/O boards.

The hm2 GPIO representation is modeled after the Digital Inputs and
Digital Outputs described in the Canonical Device Interface (part of
the HAL General Reference document).

GPIO pins default to input.

=== Pins

* 'in' - (Bit, Out) Normal state of the hardware input pin.
  Both full GPIO pins and I/O pins used as inputs by active module
  instances have this pin.

* 'in_not' - (Bit, Out) Inverted state of the hardware input pin.
  Both full GPIO pins and I/O pins used as inputs by active module
  instances have this pin.

* 'out' - (Bit, In) Value to be written (possibly inverted) to the
  hardware output pin.
  Only full GPIO pins have this pin.

=== Parameters

* 'invert_output' - (Bit, RW) This parameter only has an effect if the
  'is_output' parameter is true.
  If this parameter is true, the output value of the
  GPIO will be the inverse of the value on the 'out' HAL pin. Only full
  GPIO pins and I/O pins used as outputs by active module instances have
  this parameter. To invert an active module pin you have to invert the
  GPIO pin not the module pin.

* 'is_opendrain' - (Bit, RW) This parameter only has an effect if the
  'is_output' parameter is true.
  If this parameter is false, the GPIO behaves as a
  normal output pin: the I/O pin on the connector is driven to the value
  specified by the 'out' HAL pin (possibly inverted), and the value of
  the 'in' and 'in_not' HAL pins is undefined. If this parameter is true,
  the GPIO behaves as an open-drain pin. Writing 0 to the 'out' HAL pin
  drives the I/O pin low, writing 1 to the 'out' HAL pin puts the I/O pin
  in a high-impedance state. In this high-impedance state the I/O pin
  floats (weakly pulled high), and other devices can drive the value; the
  resulting value on the I/O pin is available on the 'in' and 'in_not'
  pins. Only full GPIO pins and I/O pins used as outputs by active module
  instances have this parameter.

* 'is_output' - (Bit, RW) If set to 0, the GPIO is an input.
  The I/O pin is put in a
  high-impedance state (weakly pulled high), to be driven by other
  devices. The logic value on the I/O pin is available in the 'in' and
  'in_not' HAL pins. Writes to the 'out' HAL pin have no effect. If this
  parameter is set to 1, the GPIO is an output; its behavior then depends
  on the 'is_opendrain' parameter. Only full GPIO pins have this parameter.

== StepGen

StepGens have names like 'hm2_<BoardType>.<BoardNum>.stepgen.<Instance>'.
'Instance' is a two-digit number that corresponds to the HostMot2 stepgen
instance number.
There are 'num_stepgens' instances, starting with 00.

Each stepgen allocates 2-6 I/O pins (selected at firmware compile
time), but currently only uses two: Step and Direction outputs.
footnote:[At present, the firmware supports multi-phase stepper outputs,
but the driver doesn't. Interested volunteers are solicited.]

The StepGen representation is modeled on the stepgen software
component. StepGen default is active high step output (high during step
time low during step space). To invert a StepGen output pin you invert
the corresponding GPIO pin that is being used by StepGen. To find the
GPIO pin being used for the StepGen output run 'dmesg' as shown above.

Each StepGen instance has the following pins and parameters:

=== Pins

* 'control-type' - (Bit, In) Switches between position control mode (0)
  and velocity control mode (1).
  Defaults to position control (0).

* 'counts' - (s32, Out) Feedback position in counts (number of steps).

* 'enable' - (Bit, In) Enables output steps. When false, no steps are
  generated.

* 'position-cmd' - (Float, In) Target position of stepper motion, in
  user-defined position units.

* 'position-fb' - (Float, Out) Feedback position in user-defined position
  units (counts / position_scale).

* 'velocity-cmd' - (Float, In) Target velocity of stepper motion, in
  user-defined position units per second.
  This pin is only used when the stepgen is in velocity control mode
  (control-type=1).

* 'velocity-fb' - (Float, Out) Feedback velocity in user-defined position
  units per second.

=== Parameters

* 'dirhold' - (u32, RW) Minimum duration of stable Direction signal
  after a step ends, in nanoseconds.

* 'dirsetup' - (u32, RW) Minimum duration of stable Direction signal
  before a step begins, in nanoseconds.

* 'maxaccel' - (Float, RW) Maximum acceleration, in position units per
  second per second.
  If set to 0, the driver will not limit its acceleration.

* 'maxvel' - (Float, RW) Maximum speed, in position units per second.
  If set to 0, the driver will choose the maximum velocity based on the
  values of steplen and stepspace (at the time that maxvel was set to 0).

* 'position-scale' - (Float, RW) Converts from counts to position units.
  position = counts / position_scale

* 'step_type' - (u32, RW) Output format, like the step_type modparam to
  the software stegen(9) component.
  0 = Step/Dir, 1 = Up/Down, 2 = Quadrature. In
  Quadrature mode (step_type=2), the stepgen outputs one complete Gray
  cycle (00 \-> 01 \-> 11 \-> 10 \-> 00) for each 'step' it takes.

* 'steplen' - (u32, RW) Duration of the step signal, in nanoseconds.

* 'stepspace' - (u32, RW) Minimum interval between step signals, in
  nanoseconds.

=== Output Parameters

The Step and Direction pins of each StepGen have two additional
parameters. To find which I/O pin belongs to which step and direction
output run 'dmesg' as described above.

* 'invert_output' - (Bit, RW) This parameter only has an effect if the
  'is_output' parameter is true.
  If this parameter is true, the output value of the
  GPIO will be the inverse of the value on the 'out' HAL pin.

* 'is_opendrain' - (Bit, RW) If this parameter is false, the GPIO
  behaves as a normal output pin: the I/O pin on the connector is driven
  to the value specified by the 'out' HAL pin (possibly inverted).
  If this parameter
  is true, the GPIO behaves as an open-drain pin. Writing 0 to the 'out'
  HAL pin drives the I/O pin low, writing 1 to the 'out' HAL pin puts the
  I/O pin in a high-impedance state. In this high-impedance state the I/O
  pin floats (weakly pulled high), and other devices can drive the value;
  the resulting value on the I/O pin is available on the 'in' and 'in_not'
  pins. Only full GPIO pins and I/O pins used as outputs by active module
  instances have this parameter.

== PWMGen

PWMgens have names like
'hm2_<BoardType>.<BoardNum>.pwmgen.<Instance>'. 'Instance' is a
two-digit number that corresponds to the HostMot2 pwmgen instance
number. There are 'num_pwmgens' instances, starting with 00.

In HM2, each pwmgen uses three output I/O pins: Not-Enable, Out0, and
Out1. To invert a PWMGen output pin you invert the corresponding GPIO
pin that is being used by PWMGen. To find the GPIO pin being used for
the PWMGen output run 'dmesg' as shown above.

The function of the Out0 and Out1 I/O pins varies with output-type
parameter (see below).

The hm2 pwmgen representation is similar to the software pwmgen
component. Each pwmgen instance has the following pins and parameters:

=== Pins

* 'enable' - (Bit, In) If true, the pwmgen will set its Not-Enable pin
  false and output its pulses.
  If 'enable' is false, pwmgen will set its Not-Enable pin true and not
  output any signals.

* 'value' - (Float, In) The current pwmgen command value, in arbitrary
  units.

=== Parameters

* 'output-type' - (s32, RW) This emulates the output_type load-time argument to the software pwmgen component.
  This parameter may be changed at runtime, but most of the time you probably want to set it at startup and then leave it alone.
  Accepted values are 1 (PWM on Out0 and Direction on Out1), 2 (Up on Out0 and Down on Out1),
  3 (PDM mode, PDM on Out0 and Dir on Out1), and 4 (Direction on Out0 and PWM on Out1, 'for locked antiphase').
* 'scale' - (Float, RW) 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.
* 'pdm_frequency' - (u32, RW) This specifies the PDM frequency, in Hz,
  of all the pwmgen instances running in PDM mode (mode 3).
  This is the 'pulse slot frequency'; the frequency at which the pdm
  generator in the Anything I/O board chooses whether to emit a pulse or a space.
  Each pulse (and space) in the PDM pulse train has a duration of 1/pdm_frequency seconds.
  For example, setting the pdm_frequency to 2*10^6^ Hz (2 MHz) and the duty cycle to 50% results in a 1 MHz square wave,
  identical to a 1 MHz PWM signal with 50% duty cycle.
  The effective range of this parameter is from about 1525 Hz up to just under 100 MHz.
  Note that the max frequency is determined by the ClockHigh frequency of the Anything I/O board;
  the 5I20 and 7I43 both have a 100 MHz clock, resulting in a 100 MHz max PDM frequency.
  Other boards may have different clocks, resulting in different max PDM frequencies.
  If the user attempts to set the frequency too high, then it will be clipped to the max supported frequency of the board.
* 'pwm_frequency' - (u32, RW) This specifies the PWM frequency, in Hz,
  of all the pwmgen instances running in the PWM modes (modes 1 and 2).
  This is the frequency of the variable-duty-cycle wave.
  Its effective range is fromc1 Hz up to 193 kHz.
  Note that the max frequency is determined by the ClockHigh frequency of the Anything I/O board;
  the 5i20 and 7i43 both have a 100 MHz clock, resulting in a 193 kHz max PWM frequency.
  Other boards may have different clocks, resulting in different max PWM frequencies.
  If the user attempts to set the frequency too high,
  then it will be clipped to the max supported frequency of the board.
  Frequencies below about 5 Hz are not terribly accurate, but above 5 Hz they are pretty close.

=== Output Parameters

The output pins of each PWMGen have two additional parameters. To find
which I/O pin belongs to which output run `dmesg` as described above.

* `invert_output` - (Bit, RW) This parameter only has an effect if the `is_output` parameter is true.
  If this parameter is true, the output value of the GPIO will be the inverse of the value on the `out` HAL pin.
* `is_opendrain` - (Bit, RW) If this parameter is false, the GPIO behaves as a normal output pin:
  The I/O pin on the connector is driven to the value specified by the `out` HAL pin (possibly inverted).
  If this parameter is true, the GPIO behaves as an open-drain pin.
  Writing 0 to the `out` HAL pin drives the I/O pin low, writing 1 to the `out` HAL pin puts the I/O pin in a high-impedance state.
  In this high-impedance state the I/O pin floats (weakly pulled high),
  and other devices can drive the value; the resulting value on the I/O pin is available on the `in` and `in_not` pins.
  Only full GPIO pins and I/O pins used as outputs by active module instances have this parameter.

[[sec:hm2-encoder]]
== Encoder

Encoders have names like `hm2_<BoardType>.<BoardNum>.encoder.<Instance>.`.
`Instance` is a two-digit number that corresponds to the HostMot2 encoder instance number.
There are _num_encoders_ instances, starting with 00.

Each encoder uses three or four input I/O pins, depending on how the firmware was compiled.
Three-pin encoders use A, B, and Index (sometimes also known as Z).
Four-pin encoders use A, B, Index, and Index-mask.

The hm2 encoder representation is similar to the one described by the Canonical Device Interface
(in the HAL General Reference document), and to the software encoder component.
Each encoder instance has the following pins and parameters:

=== Pins

* `count` - (s32, Out) Number of encoder counts since the previous reset.
* `index-enable` - (Bit, I/O) When this pin is set to True,
  the count (and therefore also position) are reset to zero on the next Index (Phase-Z) pulse.
  At the same time, index-enable is reset to zero to indicate that the pulse has occurred.
* `position` - (Float, Out) Encoder position in position units (count / scale).
* `rawcounts` - (s32, Out) Total number of encoder counts since the start, not adjusted for index or reset.
* `reset` - (Bit, In) When this pin is TRUE, the count and position pins are set to 0.
  The value of the velocity pin is not affected by this.
  The driver does not reset this pin to FALSE after resetting the count to 0, that is the user's job.
* `velocity` - (Float, Out) Estimated encoder velocity in position units per second.

=== Parameters

* `counter-mode` - (Bit, RW) Set to False (the default) for Quadrature.
  Set to True for Up/Down or for single input on Phase A.
  Can be used for a frequency to velocity converter with a single input on Phase A when set to true.

* `filter` - (Bit, RW) If set to True (the default), the quadrature
  counter needs 15 clocks to register a change on any of the three input
  lines (any pulse shorter than this is rejected as noise).
  If set to False, the quadrature counter needs only 3 clocks to register a change.
  The encoder sample clock runs at 33 MHz on the PCI Anything I/O cards and 50 MHz on the 7I43.

* `index-invert` - (Bit, RW) If set to 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.

* `index-mask` - (Bit, RW) If set to True, the Index input pin only has
  an effect if the Index-Mask input pin is True (or False, depending on
  the `index-mask-invert` pin below).

* `index-mask-invert` - (Bit, RW) If set to True, Index-Mask must be
  False for Index to have an effect.
  If set to False, the `Index-Mask` pin must be True.

* `scale` - (Float, RW) Converts from 'count' units to 'position' units.
  A quadrature encoder will normally have 4 counts per pulse so a 100 PPR
  encoder would be 400 counts per revolution. In `.counter-mode` a 100
  PPR encoder would have 100 counts per revolution as it only uses the
  rising edge of A and direction is B.

* `vel-timeout` - (Float, RW) When the encoder is moving slower than one
  pulse for each time that the driver reads the count from the FPGA (in
  the hm2_read() 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.

== 5I25 Configuration

=== Firmware

The 5I25 firmware comes preloaded for the daughter card it is purchased with.
So the `firmware=xxx.BIT` is not part of the hm2_pci configuration string when
using a 5I25.

=== Configuration

Example configurations of the 5I25/7I76 and 5I25/7I77 cards are included in
the <<sub:configuration-selector,Configuration Selector>>.

If you like to roll your own configuration the following examples show how
to load the drivers in the HAL file.

.5I25 + 7I76 Card
[source,{hal}]
----
# load the generic driver
loadrt hostmot2

# load the PCI driver and configure
loadrt hm2_pci config="num_encoders=1 num_stepgens=5 sserial_port_0=0XXX"
----

.5I25 + 7I77 Card
[source,{hal}]
----
# load the generic driver
loadrt hostmot2

# load the PCI driver and configure
loadrt hm2_pci config="num_encoders=6 num_pwmgens=6 sserial_port_0=0XXX"
----

=== SSERIAL Configuration

The `sserial_port_0=0XXX` configuration string sets some options for the smart
serial daughter card. These options are specific for each daughter card. See
the Mesa manual for more information on the exact usage (typically in the section
called SOFTWARE PROCESS DATA MODES) or see the manual page of
link:../man/man9/sserial.9.html[SSERIAL(9)].

=== 7I77 Limits

The minlimit and maxlimit are bounds on the pin value (in this case the analog
out value) fullscalemax is the scale factor.

These are by default set to the analog in or analog range (most likely in Volts).

So for example on the 7I77 +-10 V analog outputs, the default values are:

minlimit: -10 +
maxlimit: +10 +
maxfullscale: 10 +

If you wanted to say scale the analog out of a channel to IPS for a velocity
mode servo (say 24 IPS max) you could set the limits like this:

minlimit: -24 +
maxlimit: +24 +
maxfullscale: 24 +

If you wanted to scale the analog out of a channel to RPM for a 0 to 6000 RPM
spindle with 0-10 V control you could set the limits like this:

minlimit: 0 +
maxlimit: 6000 +
maxfullscale: 6000 +
(this would prevent unwanted negative output voltages from being set)

== Example Configurations

Several example configurations for Mesa hardware are included with LinuxCNC.
The configurations are located in the hm2-servo and hm2-stepper sections of
the <<sub:configuration-selector,Configuration Selector>>.
Typically you will need the board installed for the configuration you pick to load.
The examples are a good place to start and will save you time.
Just pick the proper example from the LinuxCNC Configuration Selector and
save a copy to your computer so you can edit it.
To see the exact pins and parameters that your configuration gave you, open the Show HAL
Configuration window from the Machine menu, or do `dmesg` as outlined above.

// vim: set syntax=asciidoc:
