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

NAME

       hostmot2 - Smart Serial LinuxCNC HAL driver for the Mesa Electronics HostMot2 Smart-Serial
       remote cards

SYNOPSIS

       The Mesa Smart-Serial interface  is  a  2.5Mbs  proprietary  interface  between  the  Mesa
       Anything-IO  cards  and  a range of subsidiary devices termed "smart-serial remotes".  The
       remote cards perform a variety of functions, but typically they combine various classes of
       IO.   The  remote cards are self-configuring, in that they tell the main LinuxCNC Hostmot2
       driver what their pin functions are and what they should be named.

       Many sserial remotes offer different pinouts depending on the mode they are started up in.
       This  is  set  using  the sserial_port_N= option in the hm2_pci modparam. See the hostmot2
       manpage for further details.

       It is likely that this documentation will be permanently out of date.

       Each Anything-IO board can attach up to 8 sserial remotes to each header (either the 5-pin
       headers  on  the 5I20/5I22/5I23/7I43 or the 25-pin connectors on the 5I25, 6I25 and 7I80).
       The remotes are grouped into "ports" of up to 8 "channels".  Typically each header will be
       a single 8 channel port, but this is not necessarily always the case.

PORTS

       In  addition  to  the per-channel/device pins detailed below there are three per-port pins
       and three parameters.

       Pins:

       (bit, in) .sserial.port-N.run: Enables the specific Smart Serial module.  Setting this pin
       low  will  disable  all  boards on the port and puts the port in a pass-through mode where
       device parameter setting is possible.  It is necessary to toggle the state of this pin  if
       there is a requirement to alter a remote parameter on a live system.  This pin defaults to
       TRUE and can be left unconnected.  However, toggling the pin low-to-high will re-enable  a
       faulted  drive  so  the pin could usefully be connected to the iocontrol.0.user-enable-out
       pin.

       (u32, ro) .run_state: Shows the state of the sserial communications  state-machine.   This
       pin  will  generally show a value of 0x03 in normal operation, 0x07 in setup mode and 0x00
       when the "run" pin is false.

       (u32, ro) .error-count: Indicates the state of the Smart Serial  error  handler,  see  the
       parameters section for more details.

       Parameters:

       (u32  r/w) .fault-inc: Any over-run or handshaking error in the SmartSerial communications
       will increment the .fault-count pin by the amount specified by this parameter.  Default  =
       10.

       (u32  r/w)  .fault-dec:  Every successful read/write cycle decrements the fault counter by
       this amount. Default = 1.

       (u32 r/w) .fault-lim: When the fault counter  reaches  this  threshold  the  Smart  Serial
       interface  on  the  corresponding  port  will  be  stopped  and an error printed in dmesg.
       Together these three pins allow for control over the degree of fault- tolerance allowed in
       the  interface.   The  default values mean that if more than one transaction in ten fails,
       more than 20 times, then a hard error will be raised.  If the increment were to be set  to
       zero  then  no  error  would  ever  be  raised,  and the system would carry on regardless.
       Conversely setting decrement to zero, threshold to 1 and limit to 1 means that  absolutely
       no  errors  will  be  tolerated.   (This  structure  is  copied  directly from vehicle ECU
       practice.)

       Any other parameters than the ones above are created by the card istelf from data  in  the
       remote firmware.  They may be set in the HAL file using "setp" in the usual way.

       NOTE: Because a Smart-Serial remote can only communicate non-process data to the host card
       in setup mode, it is necessary to stop and re-start the smart-serial port associated  with
       the card to alter the value of a parameter.

       ALSO NOTE: in the case of parameters beginning with "nv" (which are stored in non-volatile
       memory) the effect will not be seen until after the next power cycle of the drive.

       Unchanged values will not be re-written so it is safe to leave the "setp" commands in  the
       HAL file or delete them as you see fit.

DEVICES

       The  other  pins  and  parameters  created  in  HAL  depend  on the devices detected.  The
       following list of Smart Serial devices is by no means exhaustive.

   8I20
       The 8I20 is a 2.2 kW three-phase drive for brushless DC motors and AC servo motors.   8I20
       pins            and            parameters            have            names            like
       "hm2_<BoardType>.<BoardNum>.8i20.<PortNum>.<ChanNum>.<Pin>",          for          example
       "hm2_5i23.0.8i20.1.3.current"  would  set the phase current for the drive connected to the
       fourth channel of the second sserial port of the first 5I23 board.  Note that the  sserial
       ports do not necessarily correlate in layout or number to the physical ports on the card.

       Pins:

       (float in) angle
              The  rotor angle of the motor in fractions of a full phase revolution.  An angle of
              0.5 indicates that the motor is half a turn / 180 degrees / π radians from the zero
              position.   The  zero  position  is  taken to be the position that the motor adopts
              under no load with a poitive voltage applied to the A (or U) phase and both B and C
              (or V and W) connected to -V or 0 V.  A 6 pole motor will have 3 zero positions per
              physical rotation.  Note that the 8I20 drive automatically adds the phase  lead/lag
              angle,  and  that  this  pin should see the raw rotor angle.  There is a HAL module
              (bldc) which handles the complexity of differing motor and drive types.

       (float, in) current
              The phase current command to the drive.  This is scaled from -1 to +1 for  forwards
              and  reverse  maximum  currents.   The  absolute value of the current is set by the
              max_current parameter.

       (float, ro) bus-voltage
              The drive bus voltage in V. This will tend  to  show  25.6  V  when  the  drive  is
              unpowered and the drive will not operate below about 50 V.

       (float, ro) temp
              The temperature of the driver in degrees C.

       (u32, ro) comms
              The communication status of the drive. See the manual for more details.

       (bit, ro) status and fault.
              The  following  fault/status  bits  are  exported. For further details see the 8I20
              manual.     fault.U-current     /     fault.U-current-not     fault.V-current     /
              fault.V-current-not   fault.W-current   /   fault.W-current-not   fault.bus-high  /
              fault.bus-high-not  fault.bus-overv  /   fault.bus-overv-not   fault.bus-underv   /
              fault.bus-underv-not    fault.framingr    /   fault.framingr-not   fault.module   /
              fault.module-not  fault.no-enable   /   fault.no-enable-not   fault.overcurrent   /
              fault.overcurrent-not    fault.overrun   /   fault.overrun-not   fault.overtemp   /
              fault.overtemp-not fault.watchdog / fault.watchdog-not

              status.brake-old  /  status.brake-old-not  status.brake-on  /   status.brake-on-not
              status.bus-underv       /      status.bus-underv-not      status.current-lim      /
              status.current-lim-no status.ext-reset /  status.ext-reset-not  status.no-enable  /
              status.no-enable-not    status.pid-on   /   status.pid-on-not   status.sw-reset   /
              status.sw-reset-not status.wd-reset / status.wd-reset-not

       Parameters:
              The following parameters are exported.  See the PDF documentation downloadable from
              Mesa for further details.

               hm2_5i25.0.8i20.0.1.angle-maxlim
               hm2_5i25.0.8i20.0.1.angle-minlim
               hm2_5i25.0.8i20.0.1.angle-scalemax
               hm2_5i25.0.8i20.0.1.current-maxlim
               hm2_5i25.0.8i20.0.1.current-minlim
               hm2_5i25.0.8i20.0.1.current-scalemax
               hm2_5i25.0.8i20.0.1.nvbrakeoffv
               hm2_5i25.0.8i20.0.1.nvbrakeonv
               hm2_5i25.0.8i20.0.1.nvbusoverv
               hm2_5i25.0.8i20.0.1.nvbusundervmax
               hm2_5i25.0.8i20.0.1.nvbusundervmin
               hm2_5i25.0.8i20.0.1.nvkdihi
               hm2_5i25.0.8i20.0.1.nvkdil
               hm2_5i25.0.8i20.0.1.nvkdilo
               hm2_5i25.0.8i20.0.1.nvkdp
               hm2_5i25.0.8i20.0.1.nvkqihi
               hm2_5i25.0.8i20.0.1.nvkqil
               hm2_5i25.0.8i20.0.1.nvkqilo
               hm2_5i25.0.8i20.0.1.nvkqp
               hm2_5i25.0.8i20.0.1.nvmaxcurrent
               hm2_5i25.0.8i20.0.1.nvrembaudrate
               hm2_5i25.0.8i20.0.1.swrevision
               hm2_5i25.0.8i20.0.1.unitnumber

       (float, rw) max_current
              Sets  the  maximum drive current in Amps.  The default value is the maximum current
              programmed into the drive EEPROM.  The value must be positive, and an error will be
              raised if a current in excess of the drive maximum is requested.

       (u32, ro) serial_number
              The  serial  number  of the connected drive. This is also shown on the label on the
              drive.

   7I64
       The 7I64 is a 24-input 24-output IO card.   7I64  pins  and  parameters  have  names  like
       "hm2_<BoardType>.<BoardNum>.7i64.<PortNum>.<ChanNum>.<Pin>",          for          example
       hm2_5i23.0.7i64.1.3.output-01 .

       Pins:

       (bit, in) 7i64.0.0.output-NN: Writing a 1 or TRUE to this pin will  enable  output  driver
       NN.   Note  that  the outputs are drivers (switches) rather than voltage outputs.  The LED
       adjacent to the connector on the board shows the status.  The output can  be  inverted  by
       setting a parameter.

       (bit,  out)  7i64.0.0.input-NN:  The value of input NN.  Note that the inputs are isolated
       and both pins of each input must be connected, typically to signal and the ground  of  the
       signal.  (This need not be the ground of the board.)

       (bit, out)  7i64.0.0.input-NN-not: An inverted copy of the corresponding input.

       (float,  out) 7i64.0.0.analog0 & 7i64.0.0.analog1: The two analogue inputs (0 to 3.3 V) on
       the board.

       Parameters:

       (bit, rw) 7i64.0.0.output-NN-invert: Setting this parameter to 1 / TRUE  will  invert  the
       output value, such that writing 0 to .gpio.NN.out will enable the output and vice-versa.

   7I76
       The  7I76  is  not  really  a smart-serial device. It serves as a breakout for a number of
       other Hostmot2 functions.  There are connections for 5 step generators (for which see  the
       main   hostmot2   manpage).    The   stepgen   pins   are   associated   with   the   5I25
       (hm2_5i25.0.stepgen.00....)  whereas the smart-serial pins are associated  with  the  7I76
       (hm2_5i25.0.7i76.0.0.output-00).

       Pins:

       (float out) .7i76.0.0.analogN (modes 1 and 2 only) Analogue input values.

       (float out) .7i76.0.0.fieldvoltage (mode 2 only) Field voltage monitoring pin.

       (bit  in)  .7i76.0.0.spindir: This pin provides a means to drive the spindle VFD direction
       terminals on the 7I76 board.

       (bit in) .7i76.0.0.spinena: This pin drives  the  spindle-enable  terminals  on  the  7I76
       board.

       (float  in)  .7i76.0.0.spinout:  This  controls  the analogue output of the 7I76.  This is
       intended as a speed control signal for a VFD.

       (bit out) .7i76.0.0.output-NN: (NN = 0 to 15). 16 digital outputs. The sense of the signal
       can be set via a parameter.

       (bit out) .7i76.0.0.input-NN: (NN = 0 to 31) 32 digital inputs.

       (bit  in)  .7i76.0.0.input-NN-not:  (NN = 0 to 31) An inverted copy of the inputs provided
       for convenience.  The two complementary pins may be connected to different signal nets.

       Parameters:

       (u32 ro) .7i76.0.0.nvbaudrate: Indicates the vbaud  rate.  This  probably  should  not  be
       altered.

       (u32  ro)  .7i76.0.0.nvunitnumber:  Indicates  the  serial number of the device and should
       match a sticker on the card.  This can be useful for working out which card is which.

       (u32 ro) .7i76.0.0.nvwatchdogtimeout:  The  sserial  remote  watchdog  timeout.   This  is
       separate from the Anything-IO card timeout. This is unlikely to need to be changed.

       (bit rw) .7i76.0.0.output-NN-invert: Invert the sense of the corresponding output pin.

       (bit rw) .7i76.0.0.spindir-invert: Invert the senseof the spindle direction pin.

       (bit rw) .7i76.0.0.spinena-invert: Invert the sense of the spindle-enable pin.

       (float rw) .7i76.0.0.spinout-maxlim: The maximum speed request allowable

       (float rw) .7i76.0.0.spinout-minlim: The minimum speed request.

       (float  rw)  .7i76.0.0.spinout-scalemax:  The  spindle  speed  scaling.  This is the speed
       request which would correspond to full-scale output from the  spindle  control  pin.   For
       example  with  a  10 V drive voltage and a 10000 RPM scalemax a value of 10,000 RPM on the
       spinout pin would produce 10 V output.  However, if spinout-maxlim were set to  5,000  RPM
       then no voltage above 5 V would be output.

       (u32  ro)  .7i76.0.0.swrevision:  The  onboard  firmware  revision number.  Utilities (man
       setsserial for details) exist to update and change this firmware.

   7I77
       The 7I77 is an 6-axis servo control card. The analogue outputs are  smart-serial  devices,
       but  the  encoders  are  conventional hostmot2 encoders and further details of them may be
       found in the hostmot2 manpage.

       Pins:

       (bit out) .7i77.0.0.input-NN: (NN = 0 to 31) 32 digital inputs.

       (bit in) .7i77.0.0.input-NN-not: (NN = 0 to 31) An inverted copy of  the  inputs  provided
       for convenience.  The two complementary pins may be connected to different signal nets.

       (bit out) .7i77.0.0.output-NN: (NN = 0 to 15). 16 digital outputs. The sense of the signal
       can be set via a parameter

       (bit in) .7i77.0.0.spindir: This pin provides a means to drive the spindle  VFD  direction
       terminals on the 7I76 board.

       (bit  in)  .7i77.0.0.spinena:  This  pin  drives  the spindle-enable terminals on the 7I76
       board.

       (float in) .7i77.0.0.spinout: This controls the  analog  output  of  the  7I77.   This  is
       intended as a speed control signal for a VFD.

       (bit  in)  .7i77.0.1.analogena:  This  pin  drives the analog enable terminals on the 7I77
       board.

       (float in) .7i77.0.1.analogoutN: (N = 0 to 5) This controls the analog output of the 7I77.

       Parameters:

       (bit rw) .7i77.0.0.output-NN-invert: Invert the sense of the corresponding output pin.

       (bit rw) .7i77.0.0.spindir-invert: Invert the sense of the spindle direction pin.

       (bit rw) .7i77.0.0.spinena-invert: Invert the sense of the spindle-enable pin.

       (float rw) .7i77.0.0.spinout-maxlim: The maximum speed request allowable

       (float rw) .7i77.0.0.spinout-minlim: The minimum speed request.

       (float rw) .7i77.0.0.spinout-scalemax: The spindle  speed  scaling.   This  is  the  speed
       request  which  would  correspond  to full-scale output from the spindle control pin.  For
       example with a 10 V drive voltage and a 10000 RPM scalemax a value of 10,000  RPM  on  the
       spinout  pin  would produce 10 V output.  However, if spinout-maxlim were set to 5,000 RPM
       then no voltage above 5 V would be output.

       (float rw) .7i77.0.0.analogoutN-maxlim: (N = 0 to 5) The maximum speed request allowable

       (float rw) .7i77.0.0.analogoutN-minlim: (N = 0 to 5) The minimum speed request.

       (float rw) .7i77.0.0.analogoutN-scalemax: (N = 0 to 5) The analog speed scaling.  This  is
       the  speed  request  which  would correspond to full-scale output from the spindle control
       pin.  For example with a 10 V drive voltage and a 10000 RPM scalemax a value of 10,000 RPM
       on  the  spinout  pin  would  produce 10 V output.  However, if spinout-maxlim were set to
       5,000 RPM then no voltage above 5 V would be output.

   7I69
       The 7I69 is a 48 channel digital IO card. It can be configured in four different modes:

        MODE 0: Bidirectional mode (48 bits in 48 bits out)
        MODE 1: Input only mode (48 bits in)
        MODE 2: Output only mode (48 bits out)
        MODE 3: 24/24mode (24 bits in = bits 0..23 and 24 bits out = bits 24..47)
        MODE 4: Bidirectional mode (48 bits in 48 bits out) plus 4 MPG encoder channels  oninputs
       0 through 7

       Pins:

       (bit in) .7i69.0.0.output-NN: Digital output. Sense can be inverted with the corresponding
       Parameter.

       (bit out) .7i69.0.0.input-NN: Digital input

       (bit out) .7i69.0.0.input-NN-not: Digital input, inverted.

       Parameters:

       (u32 ro) .7i69.0.0.nvbaudrate: Indicates the vbaud  rate.  This  probably  should  not  be
       altered.

       (u32  ro)  .7i69.0.0.nvunitnumber:  Indicates  the  serial number of the device and should
       match a sticker on the card.  This can be useful for working out which card is which.

       (u32 ro) .7i69.0.0.nvwatchdogtimeout:  The  sserial  remote  watchdog  timeout.   This  is
       separate from the Anything-IO card timeout. This is unlikely to need to be changed.

       (bit rw) .7i69.0.0.output-NN-invert: Invert the sense of the corresponding output pin.

       (u32  ro)  .7i69.0.0.swrevision: The onboard firmware revision number.  Utilities exist to
       update and change this firmware.

   7I70
       The 7I70 is a remote isolated 48  input  card.  The  7I70  inputs  sense  positive  inputs
       relative  to  a common field ground.  Input impedance is 10 kΩ and input voltage can range
       from 5 VDC to 32 VDC. All inputs have LED  status  indicators.   The  input  common  field
       ground is galvanically isolated from the communications link.

       The  7I70 has three software selectable modes. These different modes select different sets
       of 7I70 data to be transferred between the host and the 7I70 during real time process data
       exchanges.   For  high  speed applications, choosing the correct mode can reduced the data
       transfer sizes, resulting in higher maximum update rates.

        MODE 0: Input mode (48 bits input data only
        MODE 1: Input plus analog mode (48 bits input data plus 6 channels of analog data)
        MODE 2: Input plus field voltage

       Pins:

       (float out) .7i70.0.0.analogN (modes 1 and 2 only) Analogue input values.

       (float out) .7i70.0.0.fieldvoltage (mode 2 only) Field voltage monitoring pin.

       (bit out) .7i70.0.0.input-NN: (NN = 0 to 47) 48 digital inputs.

       (bit in) .7i70.0.0.input-NN-not: (NN = 0 to 47) An inverted copy of  the  inputs  provided
       for convenience.  The two complementary pins may be connected to different signal nets.

       Parameters:

       (u32  ro)  .7i70.0.0.nvbaudrate:  Indicates  the  vbaud  rate. This probably should not be
       altered.

       (u32 ro) .7i70.0.0.nvunitnumber: Indicates the serial number  of  the  device  and  should
       match a sticker on the card.  This can be useful for working out which card is which.

       (u32  ro)  .7i70.0.0.nvwatchdogtimeout:  The  sserial  remote  watchdog  timeout.  This is
       separate from the Anything-IO card timeout.  This is unlikely to need to be changed.

       (u32 ro) .7i69.0.0.swrevision: The onboard firmware revision number.  Utilities  exist  to
       update and change this firmware.

   7I71
       The  7I71  is a remote isolated 48 output card.  The 48 outputs are 8VDC to 28VDC sourcing
       drivers (common + field power) with 300 mA maximum current capability.  All  outputs  have
       LED status indicators.

       The  7I71  has  two  software  selectable modes. For high speed applications, choosing the
       correct mode can reduced the data transfer sizes, resulting in higher maximum update rates

        MODE 0: Output only mode (48 bits output data only)
        MODE 1: Outputs plus read back field voltage

       Pins:

       (float out) .7i71.0.0.fieldvoltage (mode 2 only) Field voltage monitoring pin.

       (bit out) .7i71.0.0.output-NN: (NN = 0 to  47)  48  digital  outputs.  The  sense  may  be
       inverted by the invert parameter.

       Parameters:

       (bit rw) .7i71.0.0.output-NN-invert: Invert the sense of the corresponding output pin.

       (u32  ro)  .7i71.0.0.nvbaudrate:  Indicates  the  vbaud  rate. This probably should not be
       altered.

       (u32 ro) .7i71.0.0.nvunitnumber: Indicates the serial number  of  the  device  and  should
       match a sticker on the card.  This can be useful for determining which card is which.

       (u32  ro)  .7i71.0.0.nvwatchdogtimeout:  The  sserial  remote  watchdog  timeout.  This is
       separate from the Anything-IO card timeout. This is unlikely to need to be changed.

       (u32 ro) .7i69.0.0.swrevision: The onboard firmware revision number.  Utilities  exist  to
       update and change this firmware.

   7I73
       The 7I73 is a remote real time pendant or control panel interface.

       The  7I73  supports  up  to  four  50  kHz encoder inputs for MPGs, 8 digital inputs and 6
       digital outputs and up to a 64 Key keypad.  If a smaller  keypad  is  used,  more  digital
       inputs  and  outputs  become available.  Up to eight 0.0 V to 3.3 V analog inputs are also
       provided.  The 7I73 can drive a 4 line 20 character LCD for local DRO applications.

       The 7I73 has 3 software selectable process  data  modes.   These  different  modes  select
       different  sets  of  7I73 data to be transferred between the host and the 7I73 during real
       time process data exchanges.  For high speed applications, choosing the correct  mode  can
       reduced the data transfer sizes, resulting in higher maximum update rates

        MODE 0: I/O + ENCODER
        MODE 1: I/O + ENCODER + ANALOG IN
        MODE 2: I/O + ENCODER + ANALOG IN FAST DISPLAY

       Pins:

       (float  out)  .7i73.0.0.analoginN:  Analogue  inputs.  Up  to  8 channels may be available
       dependent on software and hardware configuration modes (see the  PDF  manual  downloadable
       from www.mesanet.com).

       (u32  in)  .7i73.0.1.display  (modes  1  and  2).  Data  for LCD display.  This pin may be
       conveniently driven by the HAL "lcd" component which allows the formatted display  of  the
       values any number of HAL pins and textual content.

       (u32 in) .7i73.0.1.display32 (mode 2 only). 4 bytes of data for LCD display.  This mode is
       not supported by the HAL "lcd" component.

       (s32 out) .7i73.0.1.encN: The position of the MPG encoder counters.

       (bit out) .7i73.0.1.input-NN: Up to 24 digital inputs (dependent on config)

       (bit out) .7i73.0.1.input-NN-not: Inverted copy of the digital inputs

       (bit in) .7i73.0.1.output-NN: Up to 22 digital outputs (dependent on config)

       Parameters:

        (u32 ro) .7i73.0.1.nvanalogfilter
        (u32 ro) .7i73.0.1.nvbaudrate
        (u32 ro) .7i73.0.1.nvcontrast
        (u32 ro) .7i73.0.1.nvdispmode
        (u32 ro) .7i73.0.1.nvencmode0
        (u32 ro) .7i73.0.1.nvencmode1
        (u32 ro) .7i73.0.1.nvencmode2
        (u32 ro) .7i73.0.1.nvencmode3
        (u32 ro) .7i73.0.1.nvkeytimer
        (u32 ro) .7i73.0.1.nvunitnumber
        (u32 ro) .7i73.0.1.nvwatchdogtimeout
        (u32 ro) .7i73.0.1.output-00-invert

       For further details of the use of the above see the Mesa manual.

       (bit rw) .7i73.0.1.output-01-invert: Invert the corresponding output bit.

       (s32 ro) .7i73.0.1.swrevision: The version of firmware installed.