:lang: en
:toc:

[[cha:servo-to-go]]
= Servo To Go 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}

The Servo-To-Go (STG) is one of the first PC motion control cards supported
by LinuxCNC. It is an ISA card and it exists in different flavors (all
supported by this driver). The board includes up to 8 channels of
quadrature encoder input, 8 channels of analog input and output, 32
bits digital I/O, an interval timer with interrupt and a watchdog.

NOTE: We have had reports that the opamps on the Servo To Go card do
not work with newer ATX power supplies that use modern switch
mode DC-DC converters.  The failure mode is that STG card outputs a
constant voltage regardless of what the driver is commanding it to do.
Older ATX power supplies with linear voltage regulators do not have
this problem, and work fine with the STG cards.

== Installing

[source,{hal}]
----
loadrt hal_stg [base=<address>] [num_chan=<nr>] [dio="<dio-string>"] \
                 [model=<model>]
----

The base address field is optional; if it's not provided the driver
attempts to autodetect the board. The num_chan field is used to specify
the number of channels available on the card, if not used the 8 axis
version is assumed. The digital inputs/outputs configuration is
determined by a config string passed to insmod when loading the module.
The format consists of a four character string that sets the direction
of each group of pins. Each character of the direction string is either
"I" or "O". The first character sets the direction of port A (Port A -
DIO.0-7), the next sets port B (Port B - DIO.8-15), the next sets port
C (Port C - DIO.16-23), and the fourth sets port D (Port D -
DIO.24-31). The model field can be used in case the driver doesn't
autodetect the right card version.

HINT: after starting up the driver, 'dmesg' can be consulted for
messages relevant to the driver (e.g. autodetected version number and
base address). For example:

[source,{hal}]
----
loadrt hal_stg base=0x300 num_chan=4 dio="IOIO"
----

This example installs the STG driver for a card found at the base
address of 0x300, 4 channels of encoder feedback, DACs and ADCs,
along with 32 bits of I/O configured like this: the first 8 (Port A)
configured as Input, the next 8 (Port B) configured as Output, the next
8 (Port C) configured as Input, and the last 8 (Port D) configured as
Output

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

This example installs the driver and attempts to autodetect the board
address and board model, it installs 8 axes by default along with a
standard I/O setup: Port A & B configured as Input, Port C & D
configured as Output.

== Pins

* 'stg.<channel>.counts' - (s32) Tracks the counted encoder ticks.
* 'stg.<channel>.position' - (float) Outputs a converted position.
* 'stg.<channel>.dac-value' - (float) Drives the voltage for the
  corresponding DAC.
* 'stg.<channel>.adc-value' - (float) Tracks the measured voltage from
  the corresponding ADC.
* 'stg.in-<pinnum>' - (bit) Tracks a physical input pin.
* 'stg.in-<pinnum>-not' - (bit) Tracks a physical input pin, but
  inverted.
* 'stg.out-<pinnum>' - (bit) Drives a physical output pin

For each pin, <channel> is the axis number, and <pinnum> is the logic
pin number of the STG if `IIOO` is defined, there are 16 input pins
(in-00 .. in-15) and 16 output pins (out-00 .. out-15), and they
correspond to PORTs ABCD (in-00 is PORTA.0, out-15 is PORTD.7).

The in-<pinnum> HAL pin is TRUE if the physical pin is high, and FALSE
if the physical pin is low. The in-<pinnum>-not HAL pin is inverted --
it is FALSE if the physical pin is high. By connecting a signal to one
or the other, the user can determine the state of the input.

== Parameters

* 'stg.<channel>.position-scale' - (float) The number of counts / user
  unit (to convert from counts to units).
* 'stg.<channel>.dac-offset' - (float) Sets the offset for the
  corresponding DAC.
* 'stg.<channel>.dac-gain' - (float) Sets the gain of the corresponding
  DAC.
* 'stg.<channel>.adc-offset' - (float) Sets the offset of the
  corresponding ADC.
* 'stg.<channel>.adc-gain' - (float) Sets the gain of the corresponding
  ADC.
* 'stg.out-<pinnum>-invert' - (bit) Inverts an output pin.

The -invert parameter determines whether an output pin is active high
or active low. If -invert is FALSE, setting the HAL out- pin TRUE
drives the physical pin high, and FALSE drives it low. If -invert is
TRUE, then setting the HAL out- pin TRUE will drive the physical pin
low.

== Functions

* 'stg.capture-position' - Reads the encoder counters from the axis
  <channel>.
* 'stg.write-dacs' - Writes the voltages to the DACs.
* 'stg.read-adcs' - Reads the voltages from the ADCs.
* 'stg.di-read' - Reads physical in- pins of all ports and updates
  all HAL in-<pinnum> and in-<pinnum>-not pins.
* 'stg.do-write' - Reads all HAL out-<pinnum> pins and updates all
  physical output pins.

// vim: set syntax=asciidoc:
