hostmot2 − LinuxCNC HAL driver for the Mesa Electronics HostMot2 firmware.
See the config modparam section below for Mesa card configuration. Typically hostmot2 is loaded with no parameters unless debugging is required.
|
loadrt hostmot2 [debug_idrom=N] [debug_module_descriptors=N] [debug_pin_descriptors=N] [debug_modules=N] |
debug_idrom [default: 0]
Developer/debug use only! Enable debug logging of the HostMot2 IDROM header.
debug_module_descriptors [default: 0]
Developer/debug use only! Enable debug logging of the HostMot2 Module Descriptors.
debug_pin_descriptors [default: 0]
Developer/debug use only! Enable debug logging of the HostMot2 Pin Descriptors.
debug_modules [default: 0]
Developer/debug use only! Enable debug logging of the HostMot2 Modules used.
hostmot2 is a device driver that interfaces the Mesa HostMot2 firmware to the LinuxCNC HAL. This driver by itself does nothing, the boards that actually run the firmware require their own drivers before anything can happen. Currently drivers are available for the 5i20, 5i22, 5i23, 5i25, 3x20, 4i65, and 4i68 (all using the hm2_pci module) and the 7i43 (using the hm2_7i43 module).
The HostMot2 firmware provides modules such as encoders, PWM generators, step/dir generators, and general purpose I/O pins (GPIOs). These things are called "Modules". The firmware is configured, at firmware compile time, to provide zero or more instances of each of these Modules.
The HostMot2 firmware runs on an FPGA board. The board interfaces with the computer via PCI, PC-104/Plus, or EPP, and interfaces with motion control hardware such as servos and stepper motors via I/O pins on the board.
Each I/O pin can be configured, at board-driver load time, to serve one of two purposes: either as a particular I/O pin of a particular Module instance (encoder, pwmgen, stepgen etc), or as a general purpose digital I/O pin. By default all Module instances are enabled, and all the board’s pins are used by the Module instances.
The user can disable Module instances at board-driver load time, by specifying a hostmot2 config string modparam. Any pins which belong to Module instances that have been disabled automatically become GPIOs.
All IO pins have some HAL presence, whether they belong to an active module instance or are full GPIOs. GPIOs can be changed (at run-time) between inputs, normal outputs, and open drains, and have a flexible HAL interface. IO pins that belong to active Module instances are constrained by the requirements of the owning Module, and have a more limited interface in HAL. This is described in the General Purpose I/O section below.
All the board-driver modules (hm2_pci and hm2_7i43) accept a load-time modparam of type string array, named "config". This array has one config string for each board the driver should use. Each board’s config string is passed to and parsed by the hostmot2 driver when the board-driver registers the board.
The config string can contain spaces, so it is usually a good idea to wrap the whole thing in double-quotes (the " character).
The comma character (,) separates members of the config array from each other.
For example, if your control computer has one 5i20 and one 5i23 you might load the hm2_pci driver with a HAL command (in halcmd) something like this:
loadrt hm2_pci config="firmware=hm2/5i20/SVST8_4.BIT num_encoders=3 num_pwmgens=3 num_stepgens=3,firmware=hm2/5i23/SVSS8_8.BIT sserial_port_0=0000 num_encoders=4"
Note: this assumes that the hm2_pci driver detects the 5i20 first and the 5i23 second. If the detection order does not match the order of the config strings, the hostmot2 driver will refuse to load the firmware and the board-driver (hm2_pci or hm2_7i43) will fail to load. To the best of my knowledge, there is no way to predict the order in which PCI boards will be detected by the driver, but the detection order will be consistent as long as PCI boards are not moved around. Best to try loading it and see what the detection order is.
The format of each board’s config string is:
[firmware=F] [num_encoders=N] [num_resolvers=N] [num_pwmgens=N] [num_3pwmgens=N] [num_stepgens=N] [sserial_port_0=00000000] [num_leds=N] [enable_raw]
firmware [optional]
Load the firmware specified by
F into the FPGA on this board. If no
"firmware=F" string is specified,
the FPGA will not be programmed, and had better have a valid
configuration already.
The 5i25 comes pre-programmed with firmware and no
"firmware=" string should be used. It can be
loaded, if desired with no config string at all.
The requested firmware F is fetched by udev. udev searches for the firmware in the system’s firmware search path, usually /lib/firmware. F typically has the form "hm2/<BoardType>/file.bit"; a typical value for F might be "hm2/5i20/SVST8_4.BIT". The hostmot2 firmware files are supplied by the hostmot2-firmware packages, available from linuxcnc.org.
num_encoders [optional, default: -1]
Only enable the first N encoders. If N is -1, all encoders are enabled. If N is 0, no encoders are enabled. If N is greater than the number of encoders available in the firmware, the board will fail to register.
num_resolvers [optional, default: -1]
Only enable the first N resolvers. If N = -1 then all resolvers are enabled. This module does not work with generic resolvers (unlike the encoder module which works with any encoder). At the time of writing the Hostmot2 Resolver function only works with the Mesa 7i49 card.
num_pwmgens [optional, default: -1]
Only enable the first N pwmgens. If N is -1, all pwmgens are enabled. If N is 0, no pwmgens are enabled. If N is greater than the number of pwmgens available in the firmware, the board will fail to register.
num_3pwmgens [optional, default: -1]
Only enable the first N Three-phase pwmgens. If N is -1, all 3pwmgens are enabled. If N is 0, no pwmgens are enabled. If N is greater than the number of pwmgens available in the firmware, the board will fail to register.
num_stepgens [optional, default: -1]
Only enable the first N stepgens. If N is -1, all stepgens are enabled. If N is 0, no stepgens are enabled. If N is greater than the number of stepgens available in the firmware, the board will fail to register.
sserial_port_N (N = 0 ..
3) [optional, default: 00000000 for all
ports]
Up to 32 Smart Serial devices
can be connected to a Mesa Anything IO board depending on
the firmware used and the number of physical connections on
the board. These are arranged in 1-4 ports of 1 to 8
channels.
Some Smart Serial (SSLBP) cards offer more than one
load-time configuration, for example all inputs, or all
outputs, or offering additional analogue input on some
digital pins.
To set the modes for port 0 use, for example
sserial_port_0=0120xxxx
A ’0’in the string sets the corresponding port
to mode 0, 1 to mode 1, and so on up to mode 9. An
"x" in any position disables that channel and
makes the corresponding FPGA pins available as GPIO.
The string can be up to 8 characters long, and if it defines
more modes than there are channels on the port then the
extras are ignored. Channel numbering is left to right so
the example above would set sserial device 0.0 to mode 0,
0.2 to mode2 and disable channels 0.4 onwards.
The sserial driver will auto-detect connected devices, no
further configuration should be needed. Unconnected channels
will default to GPIO, but the pin values will vary
semi-randomly during boot when card-detection runs, to it is
best to actively disable any channel that is to be used for
GPIO.
num_leds [optional, default: -1]
Only enable the first N of the LEDs on the FPGA board. If N is -1, then HAL pins for all the LEDs will be created. If N=0 then no pins will be added.
enable_raw [optional]
If specified, this turns on a raw access mode, whereby a user can peek and poke the firmware from HAL. See Raw Mode below.
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.
So, for example, the HAL pin that has the current position of the second encoder of the first 5i20 board is: hm2_5i20.0.encoder.01.position (this assumes that the firmware in that board is configured so that this HAL object is available)
Each encoder uses three or four input IO 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:
(s32 out) count
Number of encoder counts since the previous reset.
(float out) position
Encoder position in position units (count / scale).
(float out) velocity
Estimated encoder velocity in position units per second.
(bit in) reset
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.
(bit in/out) index-enable
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.
(s32 out) rawcounts
Total number of encoder counts since the start, not adjusted for index or reset.
Parameters:
(float r/w) scale
Converts from ’count’ units to ’position’ units.
(bit r/w) index-invert
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.
(bit r/w) index-mask
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).
(bit r/w) index-mask-invert
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.
(bit r/w) counter-mode
Set to False (the default) for Quadrature. Set to True for Step/Dir (in which case Step is on the A pin and Dir is on the B pin).
(bit r/w) filter
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 AnyIO cards and 50 MHz on the 7i43.
(float r/w) vel-timeout
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.
Resolvers have names like hm2_<BoardType>.<BoardNum>.resolver.<Instance>. <Instance is a 2-digit number, which for the 7i49 board will be between 00 and 05. This function only works with the Mesa Resolver interface boards (of which the 7i49 is the only example at the time of writing). This board uses an SPI interface to the FPGA card, and will only work with the correct firmware. The pins allocated will be listed in the dmesg output, but are unlikely to be usefully probed with HAL tools.
Pins:
(float, out) angle
This pin indicates the angular position of the resolver. It is a number between 0 and 1 for each electrical rotation.
(float, out) position
Calculated from the number of complete and partial revolutions since startup, reset, or index-reset multiplied by the scale parameter.
(float, out) velocity
Calculated from the rotational velocity and the velocity-scale parameter. The default scale is electrical rotations per second.
(s32, out) count
This pins outputs a simulated encoder count at 2^24 counts per rev (16777216 counts).
(s32, out) rawcounts
This is identical to the counts pin, except it is not reset by the ’index’ or ’reset’ pins. This is the pin which would be linked to the bldc HAL component if the resolver was being used to commutate a motor.
(bit, in) reset
Resets the position and counts pins to zero immediately.
(bit, in/out) index-enable
When this pin is set high the position and counts pins will be reset the next time the resolver passes through the zero position. At the same time the pin is driven low to indicate to connected modules that the index has been seen, and that the counters have been reset.
(bit, out) error
Indicates an error in the particular channel. If this value is "true" then the reported position and velocity are invalid.
Parameters:
(float, read/write) scale
The position scale, in machine units per resolver electrical revolution.
(float, read/write) velocity-scale
The conversion factor between resolver rotation speed and machine velocity. A value of 1 will typically give motor speed in rps, a value of 0.01666667 will give (approximate) RPM.
(float, read/write) excitation-khz
This pin sets the excitation
frequency for the resolver. This pin is module-level rather
than instance-level as all resolvers share the same
excitation frequency.
Valid values are 10 (~10kHz), 5 (~5kHz) and 2.5 (~2.5kHz).
The actual frequency depends on the FPGA frequency, and they
correspond to CLOCK_LOW/5000, CLOCK_LOW/10000 and
CLOCK_LOW/20000 respectively. The parameter will be set to
the closest available of the three frequencies.
A value of -1 (the default) indicates that the current
setting should be retained.
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.
So, for example, the HAL pin that enables output from the fourth pwmgen of the first 7i43 board is: hm2_7i43.0.pwmgen.03.enable (this assumes that the firmware in that board is configured so that this HAL object is available)
In HM2, each pwmgen uses three output IO pins: Not-Enable, Out0, and Out1.
The function of the Out0 and Out1 IO 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:
(bit input) enable
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.
(float input) value
The current pwmgen command value, in arbitrary units.
Parameters:
(float rw) scale
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.
(s32 rw) output-type
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").
In addition to the per-instance HAL Parameters listed above, there are a couple of HAL Parameters that affect all the pwmgen instances:
(u32 rw) pwm_frequency
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 from 1 Hz up to 193 kHz. Note that the max frequency is determined by the ClockHigh frequency of the Anything IO 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, 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’re pretty close. The default pwm_frequency is 20,000 Hz (20 kHz).
(u32 rw) pdm_frequency
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 AnyIO 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 2e6 (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 IO 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, it will be clipped to the max supported frequency of the board. The default pdm_frequency is 20,000 Hz (20 kHz).
Three-Phase PWM generators (3pwmgens) are intended for controlling the high-side and low-side gates in a 3-phase motor driver. The function is included to support the Mesa motor controller daughter-cards but can be used to control an IGBT or similar driver directly. 3pwmgens have names like "hm2_<BoardType>.<BoardNum>.3pwmgen.<Instance>" where <Instance> is a 2-digit number. There will be num_3pwmgens instances, starting at 00. Each instance allocates 7 output and one input pins on the Mesa card connectors. Outputs are: PWM A, PWM B, PWM C, /PWM A, /PWM B, /PWM C, Enable. The first three pins are the high side drivers, the second three are their complementary low-side drivers. The enable bit is intended to control the servo amplifier. The input bit is a fault bit, typically wired to over-current detection. When set the PWM generator is disabled. The three phase duty-cycles are individually controllable from -Scale to +Scale. Note that 0 corresponds to a 50% duty cycle and this is the inialization value.
Pins:
(float input)
A-value, B-value, C-value: The PWM command value for each
phase, limited to +/- "scale". Defaults to zero
which is 50% duty cycle on high-side and low-sidepins (but
see the "deadtime" parameter)
(bit input) enable
When high the PWM is enabled as long as the fault bit is not set by the external fault input pin. When low the PWM is disabled, with both high- side and low-side drivers low. This is not the same as 0 output (50% duty cycle on both sets of pins) or negative full scale (where the low side drivers are "on" 100% of the time)
(bit output) fault
Indicates the status of the fault bit. This output latches high once set by the physical fault pin until the "enable" pin is set to high.
Parameters:
(u32 rw) deadtime
Sets the dead-time between the high-side driver turning off and the low-side driver turning on and vice-versa. Deadtime is subtracted from on time and added to off time symmetrically. For example with 20 kHz PWM (50 uSec period), 50% duty cycle and zero dead time, the PWM and NPWM outputs would be square waves (NPWM being inverted from PWM) with high times of 25 uS. With the same settings but 1 uS of deadtime, the PWM and NPWM outputs would both have high times of 23 uS (25 - (2X 1 uS), 1 uS per edge). The value is specified in nS and defaults to a rather conservative 5000nS. Setting this parameter to too low a value could be both expensive and dangerous as if both gates are open at the same time there is effectively a short circuit accross the supply.
(float rw) scale
Sets the half-scale of the specified 3-phase PWM generator. PWM values from -scale to +scale are valid. Default is +/- 1.0
(bit rw) fault-invert
Sets the polarity of the fault input pin. A value of 1 means that a fault is triggered with the pin high, and 0 means that a fault it triggered when the pin is pulled low. Default 0, fault = low so that the PWM works with the fault pin unconnected.
(u32 rw) sample-time
Sets the time during the cycle when an ADC pulse is generated. 0 = start of PWM cycle and 1 = end. Not currently useful to LinuxCNC. Default 0.5.
In addition the per-instance parameters above there is the following parameter that affects all instances
(u32 rw) frequency
Sets the master PWM frequency. Maximum is approx 48kHz, minimum is 1kHz. Defaults to 20kHz.
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.
So, for example, the HAL pin that has the current position feedback from the first stepgen of the second 5i22 board is: hm2_5i22.1.stepgen.00.position-fb (this assumes that the firmware in that board is configured so that this HAL object is available)
Each stepgen uses 2 IO pins. The signals on these pins depends on the step_type parameter (described below).
The stepgen representation is modeled on the stepgen software component. Each stepgen instance has the following pins and parameters:
Pins:
(float input) position-cmd
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
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).
(s32 output) counts
Feedback position in counts (number of steps).
(float output) position-fb
Feedback position in arbitrary position units. This is similar to "counts/position_scale", but has finer than step resolution.
(float output) velocity-fb
Feedback velocity in arbitrary position units per second.
(bit input) enable
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
Switches between position control mode (0) and velocity control mode (1). Defaults to position control (0).
Parameters:
(float r/w) position-scale
Converts from counts to position units. position = counts / position_scale
(float r/w) maxvel
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 r/w) maxaccel
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 r/w) steplen
Duration of the step signal, in nanoseconds.
(u32 r/w) stepspace
Minimum interval between step signals, in nanoseconds.
(u32 r/w) dirsetup
Minimum duration of stable Direction signal before a step begins, in nanoseconds.
(u32 r/w) dirhold
Minimum duration of stable Direction signal after a step ends, in nanoseconds.
(u32 r/w) step_type
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.
The Smart Serial Interface allows up to 32 different devices such as the Mesa 8i20 2.2kW 3-phase drive or 7i64 48-way IO cards to be connected to a single FPGA card. The driver auto-detects the connected hardware port, channel and device type. Devices can be connected in any order to any active channel of an active port. (see the config modparam definition above).
In addition to the per-channel/device pins detailed below there are three per-port pins, three parameters and a further 7 pins shared between all ports used for changing on-device settings.
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. 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 sections for more details.
(u32, in) .sserial.port: When programming device parameters, this pin sets the active port.
(u32, in) .sserial.channel: This sets the active channel on the port defined above.
(u32, in) .sserial.parameter: The two LSBs of this pin determine the parameter address on the device connected to the channel and port defined above which will be read from or written to. Byte 2 is used to pass the data type for non-volatile writes, and byte 3 passes the access type flags. For example 0xEC010002 is the code to use to set 8i20 NVMAXCURRENT.
(u32, in) .sserial.value: This pin is used to set the value to be written to a device parameter. It can also be used to read-back a value from the device, but as it is an input pin the read-back value is only useful to humans.
(bit, in) .sserial.read: Starts the parameter read cycle. On completion the pin will return to zero (if not connected in HAL)
(bit, in) .sserial.write: Starts the parameter write cycle. On completion the pin will return to zero (if not connected in HAL)
(u32, out) .sserial.state: Shows the state of the read or write process (which typically takes many servo cycles). See the source code if the precise meanings are important to your application.
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)
The other pins and parameters created in HAL depend on the devices detected.
Pins:
(bit, in) amp-enable
Set this pin high to enable the drive. With the pin low communications are active but the phase angle and current are set to zero.
(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 0V. 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) voltage
The drive bus voltage in V. This will tend to show 25.6V when the drive is unpowered and the drive will not operate below about 50V.
(float, ro) temp
The temperature of the driver in degrees C.
(u32, ro) fault
The fault status of the drive. See the 8i20 manual for a detailed description.
(u32, ro) status
The operating status of the drive. See the 8i20 manual for more details.
(u32, ro) comms
The communication status of the drive. See the manual for more details.
Parameters:
(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.7i63.1.3.digout.01.out |
Pins: (bit, in) .digout.NN.out: 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.
(bit, out) .digin.NN.in: 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) .digin.NN.in-not: An inverted copy of the corresponding input.
(float, out) .adcin.00.in & .adcin.01.in: The two analogue inputs (0 to 3.3V) on the board.
Parameters: (bit, rw) .digout.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.
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. IO 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.
So, for example, the HAL pin that has the current inverted input value read from GPIO 012 of the second 7i43 board is: hm2_7i43.1.gpio.012.in-not (this assumes that the firmware in that board is configured so that this HAL object is available)
The HAL parameter that controls whether the last GPIO of the first 5i22 is an input or an output is: hm2_5i22.0.gpio.095.is_output (this assumes that the firmware in that board is configured so that this HAL object is available)
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). Each GPIO can have the following HAL Pins:
(bit out) in
& in_not: State (normal and inverted) of the hardware
input pin. Both full GPIO pins and IO pins used as inputs by
active module instances have these pins.
(bit in) out
Value to be written (possibly inverted) to the hardware output pin. Only full GPIO pins have this pin.
Each GPIO can have the following Parameters:
(bit r/w) is_output
If set to 0, the GPIO is an input. The IO pin is put in a high-impedance state (weakly pulled high), to be driven by other devices. The logic value on the IO 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.
(bit r/w) is_opendrain
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 IO 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 IO pin low, writing 1 to the "out" HAL pin puts the IO pin in a high-impedance state. In this high-impedance state the IO pin floats (weakly pulled high), and other devices can drive the value; the resulting value on the IO pin is available on the "in" and "in_not" pins. Only full GPIO pins and IO pins used as outputs by active module instances have this parameter.
(bit r/w) invert_output
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 IO pins used as outputs by active module instances have this parameter.
Creates HAL pins for the LEDs on the FPGA board.
Pins:
(bit in) CR<NN>
The pins are numbered from CR01 upwards with the name corresponding to the PCB silkscreen. Setting the bit to "true" or 1 lights the led.
The HostMot2 firmware may include a watchdog Module; if it does, the hostmot2 driver will use it. The HAL representation of the watchdog is named "hm2_<BoardType>.<BoardNum>.watchdog".
The watchdog starts out asleep and inactive. Once you access the board the first time by running any the hm2 HAL functions read(), write(), or pet_watchdog() (see below), the watchdog wakes up. From them on it must be petted periodically or it will bite. Pet the watchdog by running the pet_watchdog() HAL function.
When the watchdog bites, all the board’s I/O pins are disconnected from their Module instances and become high-impedance inputs (pulled high), and all communication with the board stops. The state of the HostMot2 firwmare modules is not disturbed (except for the configuration of the IO Pins). Encoder instances keep counting quadrature pulses, and pwm- and step-generators keep generating signals (which are *not* relayed to the motors, because the IO Pins have become inputs).
Resetting the watchdog (by clearing the has_bit pin, see below) resumes communication and 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:
(bit in/out) has_bit
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:
(u32 read/write) timeout_ns
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 pet_watchdog() function, the watchdog will bite.
Functions:
pet_watchdog(): Calling this function resets the watchdog timer (postponing the watchdog biting until timeout_ns nanoseconds later).
If the "enable_raw" config keyword is specified, some extra debugging pins are made available in HAL. The raw mode HAL pin names begin with "hm2_<BoardType>.<BoardNum>.raw".
With Raw mode enabled, a user may peek and poke the firmware from HAL, and may dump the internal state of the hostmot2 driver to the syslog.
Pins:
(u32 in) read_address
The bottom 16 bits of this is used as the address to read from.
(u32 out) read_data
Each time the hm2_read() function is called, this pin is updated with the value at .read_address.
(u32 in) write_address
The bottom 16 bits of this is used as the address to write to.
(u32 in) write_data
This is the value to write to .write_address.
(bit in) write_strobe
Each time the hm2_write() function is called, this pin is examined. If it is True, then value in .write_data is written to the address in .write_address, and .write_strobe is set back to False.
(bit in/out) dump_state
This pin is normally False. If it gets set to True the hostmot2 driver will write its representation of the board’s internal state to the syslog, and set the pin back to False.
If a Smart Serial port is stopped, it is then possible to read and set the onboard firmware settings using "setp" commands from within halrun or with halcmd. The hostmot read function needs to be attached to a realtime thread to allow parameters to be read and set, but the write thread is not needed. A typical command-line sequence to read the max current setting of an 8i20 on channel 1 of port 0 would be:
$>halrun
halcmd: loadrt
hostmot2
halcmd: loadrt hm2_pci
config="firmware=hm2/5i23/svss8_44
sserial_port_0=x0xxxxxxx"
halcmd: loadrt threads
halcmd: addf hm2_5i23.0.read thread1
halcmd: addf hm2_5i23.0.write thread1
halcmd: start
halcmd: setp hm2_5i23.0.sserial.0.port-0.run 0
halcmd: setp hm2_5i23.0.sserial.0.port 0
halcmd: setp hm2_5i23.0.sserial.0.channel 1
halcmd: setp hm2_5i23.0.sserial.0.0.parameter 0x8e8
halcmd: setp hm2_5i23.0.sserial.0.0.read 1
halcmd: show pin hm2_5i23.0.sserial.0.0.value
It is not expected that this would be a frequent task. The pin descriptions appear earlier in this document.
hm2_<BoardType>.<BoardNum>.read
This reads the encoder counters, stepgen feedbacks, and GPIO input pins from the FPGA.
hm2_<BoardType>.<BoardNum>.write
This updates the PWM duty cycles, stepgen rates, and GPIO outputs on the FPGA. Any changes to configuration pins such as stepgen timing, GPIO inversions, etc, are also effected by this function.
hm2_<BoardType>.<BoardNum>.pet-watchdog
Pet the watchdog to keep it from biting us for a while.
hm2_<BoardType>.<BoardNum>.read_gpio
Read the GPIO input pins. Note that the effect of this function is a subset of the effect of the .read() function described above. Normally only .read() is used. The only reason to call this function is if you want to do GPIO things in a faster-than-servo thread. (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. Note that the effect of this function is a subset of the effect of the .write() function described above. Normally only .write() is used. The only reason to call this function is if you want to do GPIO things in a faster-than-servo thread. (This function is not available on the 7i43 due to limitations of the EPP bus.)
hm2_7i43(9)
hm2_pci(9)
Mesa’s documentation for the Anything I/O boards, at
<http://www.mesanet.com>
GPL