This is a non-realtime HAL program to control the S11 series of VFDs from Toshiba.

vfs11_vfd supports serial and TCP connections. Serial connections may be RS232 or RS485. RS485 is supported in full- and half-duplex mode. TCP connections may be passive (wait for incoming connection), or active outgoing connections, which may be useful to connect to TCP-based devices or through a terminal server.

Regardless of the connection type, vfs11_vfd operates as a Modbus master.

This component is loaded using the halcmd "loadusr" command:

loadusr -Wn spindle-vfd vfs11_vfd -n spindle-vfd

The above command says: loadusr, wait for named to load, component vfs11_vfd, named spindle-vfd

1. Command Line Options

vfs11_vfd is mostly configured through INI file options. The command line options are:

  • -n or --name <halname> : set the HAL component name

  • -I or --ini <inifilename> : take configuration from this INI file. Defaults to environment variable INI_FILE_NAME.

  • -S or --section <section name> : take configuration from this section in the INI file. Defaults to VFS11.

  • -d or --debug enable debug messages on console output.

  • -m or --modbus-debug enable modbus messages on console output

  • -r or --report-device report device properties on console at startup

Debugging can be toggled by sending a USR1 signal to the vfs11_vfd process. Modbus debugging can be toggled by sending a USR2 signal to vfs11_vfd process (example: kill -USR1 `pidof vfs11_vfd`).

Nota
 That if there are serial configuration errors, turning on verbose may result in a flood of timeout errors.

2. Pins

Where <n> is vfs11_vfd or the name given during loading with the -n option.

  • <n>.acceleration-pattern (bit, in) when true, set acceleration and deceleration times as defined in registers F500 and F501 respectively. Used in PID loops to choose shorter ramp times to avoid oscillation.

  • <n>.alarm-code (s32, out) non-zero if drive is in alarmed state. Bitmap describing alarm information (see register FC91 description). Use err-reset (see below) to clear the alarm.

  • <n>.at-speed (bit, out) when drive is at commanded speed (see speed-tolerance below)

  • <n>.current-load-percentage (float, out) reported from the VFD

  • <n>.dc-brake (bit, in) engage the DC brake. Also turns off spindle-on.

  • <n>.enable (bit, in) enable the VFD. If false, all operating parameters are still read but control is released and panel control is enabled (subject to VFD setup).

  • <n>.err-reset (bit, in) reset errors (alarms a.k.a Trip and e-stop status). Resetting the VFD may cause a 2-second delay until it’s rebooted and Modbus is up again.

  • <n>.estop (bit, in) put the VFD into emergency-stopped status. No operation possible until cleared with err-reset or powercycling.

  • <n>.frequency-command (float, out) current target frequency in Hz as set through speed-command (which is in RPM), from the VFD

  • <n>.frequency-out (float, out) current output frequency of the VFD

  • <n>.inverter-load-percentage (float, out) current load report from VFD

  • <n>.is-e-stopped (bit, out) the VFD is in emergency stop status (blinking "E" on panel). Use err-reset to reboot the VFD and clear the e- stop status.

  • <n>.is-stopped (bit, out) true when the VFD reports 0 Hz output

  • <n>.max-rpm (float, R) actual RPM limit based on maximum frequency the VFD may generate, and the motors nameplate values. For instance, if nameplate-HZ is 50, and nameplate-RPM_ is 1410, but the VFD may generate up to 80 Hz, then max-rpm would read as 2256 (80*1410/50). The frequency limit is read from the VFD at startup. To increase the upper frequency limit, the UL and FH parameters must be changed on the panel. See the VF-S11 manual for instructions how to set the maximum frequency.

  • <n>.modbus-ok (bit, out) true when the Modbus session is successfully established and the last 10 transactions returned without error.

  • <n>.motor-RPM (float, out) estimated current RPM value, from the VFD

  • <n>.output-current-percentage (float, out) from the VFD

  • <n>.output-voltage-percentage (float, out) from the VFD

  • <n>.output-voltage (float, out) from the VFD

  • <n>.speed-command (float, in) speed sent to VFD in RPM. It is an error to send a speed faster than the Motor Max RPM as set in the VFD

  • <n>.spindle-fwd (bit, in) 1 for FWD and 0 for REV, sent to VFD

  • <n>.spindle-on (bit, in) 1 for ON and 0 for OFF sent to VFD, only on when running

  • <n>.spindle-rev (bit, in) 1 for ON and 0 for OFF, only on when running

  • <n>.jog-mode (bit, in) 1 for ON and 0 for OFF, enables the VF-S11 jog mode. Speed control is disabled, and the output frequency is determined by register F262 (preset to 5 Hz). This might be useful for spindle orientation. In normal mode, the VFD shuts off if the frequency drops below 12 Hz.

  • <n>.status (s32, out) Drive Status of the VFD (see the TOSVERT VF-S11 Communications Function Instruction Manual, register FD01). A bitmap.

  • <n>.trip-code (s32, out) trip code if VF-S11 is in tripped state.

  • <n>.error-count (s32, out) number of Modbus transactions which returned an error

  • <n>.max-speed (bit, in) ignore the loop-time parameter and run Modbus at maximum speed, at the expense of higher CPU usage. Suggested use during spindle positioning.

3. Parameters

Where <n> is vfs11_vfd or the name given during loading with the -n option.

  • <n>.frequency-limit (float, RO) upper limit read from VFD setup.

  • <n>.loop-time (float, RW) how often the Modbus is polled (default interval 0.1 seconds)

  • <n>.nameplate-HZ (float, RW) Nameplate Hz of motor (default 50). Used to calculate target frequency (together with nameplate-RPM ) for a target RPM value as given by speed-command.

  • <n>.nameplate-RPM (float, RW) Nameplate RPM of motor (default 1410)

  • <n>.rpm-limit (float, RW) do-not-exceed soft limit for motor RPM (defaults to nameplate-RPM ).

  • <n>.tolerance (float, RW) speed tolerance (default 0.01) for determining whether spindle is at speed (0.01 meaning: Output frequency is within 1% of target frequency)

4. INI file configuration

This lists all options understood by vfs11_vfd. Typical setups for RS-232, RS-485 and TCP can be found in src/hal/user_comps/vfs11_vfd/*.ini.

[VFS11]
# serial connection
TYPE=rtu

# serial port
DEVICE=/dev/ttyS0

# TCP server - wait for incoming connection
TYPE=tcpserver

# tcp portnumber for TYPE=tcpserver or tcpclient
PORT=1502

# TCP client - active outgoing connection
TYPE=tcpclient

# destination to connect to if TYPE=tcpclient
TCPDEST=192.168.1.1

#---------- meaningful only if TYPE=rtu -------
# serial device detail
# 5 6 7 8
BITS= 5

# even odd none
PARITY=none

# 110, 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
BAUD=19200

# 1 2
STOPBITS=1

#rs232 rs485
SERIAL_MODE=rs485

# up down none
# this feature might not work with a stock Ubuntu
# libmodbus5/libmodbus-dev package, and generate a warning
# execution will continue as if RTS_MODE=up were given.
RTS_MODE=up
#---------------------

# modbus timers in seconds
# inter-character timer
BYTE_TIMEOUT=0.5
# packet timer
RESPONSE_TIMEOUT=0.5

# target modbus ID
TARGET=1

# on I/O failure, try to reconnect after sleeping
# for RECONNECT_DELAY seconds
RECONNECT_DELAY=1

# misc. parameters
DEBUG=10
MODBUS_DEBUG=0
POLLCYCLES=10

5. HAL example

#
# example usage of the VF-S11 VFD driver
#
#
loadusr -Wn spindle-vfd vfs11_vfd -n spindle-vfd

# connect the spindle direction pins to the VFD
net vfs11-fwd spindle-vfd.spindle-fwd <= spindle.0.forward
net vfs11-rev spindle-vfd.spindle-rev <= spindle.0.reverse

# connect the spindle on pin to the VF-S11
net vfs11-run spindle-vfd.spindle-on <= spindle.0.on

# connect the VF-S11 at speed to the motion at speed
net vfs11-at-speed spindle.0.at-speed <= spindle-vfd.at-speed

# connect the spindle RPM to the VF-S11
net vfs11-RPM spindle-vfd.speed-command <= spindle.0.speed-out

# connect the VF-S11 DC brake
# since this draws power during spindle off, the dc-brake pin would
# better be driven by a monoflop which triggers on spindle-on falling edge
#net vfs11-spindle-brake spindle.N.brake => spindle-vfd.dc-brake

# to use the VFS11 jog mode for spindle orient
# see orient.9 and motion.9
net spindle-orient spindle.0.orient spindle-vfd.max-speed spindle-vfd.jog-mode

# take precedence over control panel
setp spindle-vfd.enable 1

6. Panel operation

The vfs11_vfd driver takes precedence over panel control while it is enabled (see enable pin), effectively disabling the panel. Clearing the enable pin re-enables the panel. Pins and parameters can still be set, but will not be written to the VFD untile the enable pin is set. Operating parameters are still read while bus control is disabled. Exiting the vfs11_vfd driver in a controlled way will release the VFD from the bus and restore panel control.

See the LinuxCNC Integrators Manual for more information. For a detailed register description of the Toshiba VFDs, see the "TOSVERT VF-S11 Communications Function Instruction Manual" (Toshiba document number E6581222) and the "TOSVERT VF-S11 Instruction manual" (Toshiba document number E6581158).

7. Error Recovery

vfs11_vfd recovers from I/O errors as follows: First, all HAL pins are set to default values, and the driver will sleep for RECONNECT_DELAY seconds (default 1 second).

  • Serial (TYPE=rtu) mode: on error, close and reopen the serial port.

  • TCP server (TYPE=tcpserver) mode: on losing the TCP connection, the driver will go back to listen for incoming connections.

  • TCP client (TYPE=tcpclient) mode: on losing the TCP connection, the driver will reconnect to TCPDEST:PORTNO.

8. Configuring the VFS11 VFD for Modbus usage

8.1. Connecting the Serial Port

The VF-S11 has an RJ-45 jack for serial communication. Unfortunately, it does not have a standard RS-232 plug and logic levels. The Toshiba-recommended way is: connect the USB001Z USB-to-serial conversion unit to the drive, and plug the USB port into the PC. A cheaper alternative is a homebrew interface ( hints from Toshiba support, circuit diagram).

Note: the 24V output from the VFD has no short-circuit protection.

Serial port factory defaults are 9600/8/1/even, the protocol defaults to the proprietary "Toshiba Inverter Protocol".

8.2. Modbus setup

Several parameters need setting before the VF-S11 will talk to this module. This can either be done manually with the control panel, or over the serial link - Toshiba supplies a Windows application called PCM001Z which can read/set parameters in the VFD. Note - PCM001Z only talks the Toshiba inverter protocol. So the last parameter which you’d want to change is the protocol - set from Toshiba Inverter Protocol to Modbus; thereafter, the Windows app is useless.

To increase the upper frequency limit, the UL and FH parameters must be changed on the panel. I increased them from 50 to 80.

See dump-params.mio for a description of non-standard VF-S11 parameters of my setup. This file is for the modio Modbus interactive utility.

9. Programming Note

The vfs11_vfd driver uses the libmodbus version 3 library which is more recent than the version 2 code used in gs2_vfd.

The Ubuntu libmodbus5 and libmodbus-dev packages are only available starting from Ubuntu 12 (Precise Pengolin). Moreover, these packages lack support for the MODBUS_RTS_MODE_* flags. Therefore, building vfs11_vfd using this library might generate a warning if RTS_MODE= is specified in the INI file.

To use the full functionality on lucid and precise:

  • remove the libmodbus packages: sudo apt-get remove libmodbus5 libmodbus-dev

  • build and install libmodbus version 3 from source as outlined here.

Libmodbus does not build on Ubuntu Hardy, hence vfs11_vfd is not available on Hardy.