gstimbox — Driver for g-STIMbox

g-STIMbox is a stimulator digital I/O box with an USB interface manufactured by g.tec medical engineering GmbH. The device features 14 digital inputs and 16 digital outputs. This module encapsulates a proprietary DLL (Dynamic-link library) that operates exclusively under Microsoft Windows.

g-STIMbox Installation

In order to install the device follow these steps:

1. Get USB_Driver.exe from the g-STIMbox driver package and execute it with administrator privileges. It will install the driver for the USB serial port.
2. Connect the g-STIMbox device to a free USB socket.
3. Open the device manager and find USB Serial Port under section Ports. It should specify the virtual COM port the device is connected to in brackets (e.g. COM3 meaning port number 3).
4. Now you can already test the device by calling gSTIMboxDemo1.exe that is also included in the driver package.

For this Python module to work follow these steps:

1. Make sure the gSTIMbox.dll file is available when using the device. The easiest way is to put the file into the system folder (on most Windows installations this is C:\Windows\System). Another way is to copy it to the same folder where this module resides.
2. Run the demo feedback or have a look at section Usage.

For further information refer to the PDF manual shipped with the device.

Usage

Output modes

This example shows both output port operation modes (manual, frequency).

The output ports can be either controlled manually (ON/OFF) or assigned a specific frequency. It’s possible to have different ports operate on different modes simultaneously (e.g. port 1 and 3 work in manual mode while 2 and 4 work in frequency mode).

Example code:

from sys import stdout
from time import sleep
from gstimbox import GStimbox

comport = 3
b = GStimbox(comport)
print "Connected to g-STIMbox (serial port %d)" % comport
print "Driver version %s, firmware version %s" %         (b.getDriverVersion(), b.getHWVersion())
print "Micro-controller frequency demo running..."
stdout.flush()
port = [0, 1, 2, 3, 4, 5, 6, 7]
freq = [1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5]
mode = [1, 1, 1, 1, 1, 1, 1, 1]
b.reset()
b.setFrequency(port, freq)
b.setMode(port, mode)
sleep(10)
b.reset()
print "Manual ON/OFF demo running..."
stdout.flush()
state = [0 for i in range(16)]
for i in range(5):
    for j in range(8):
        state[j] = 1
        b.setPortState(state)
        sleep(0.1)
    for j in range(8):
        state[j] = 0
        b.setPortState(state)
        sleep(0.1)
b.reset()
print "Demo finished."

Processing input

In order to handle input from the g-STIMbox input ports a callback function must be specified. The callback function receives a single argument, a list of 14 values (e.g. [0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]). Each value maps to the corresponding input port (e.g. list index 0 corresponds to input port 1). In the example input ports 2 and 4 are active while all others are not. Note that the callback function is triggered on every state change (that is on pressing and releasing of a button).

The following example prints out the complete input state vector and activates all output ports if button on input port 1 is active (pressed).

Example code:

from sys import stdout
from time import sleep
from gstimbox import GStimbox

def input_callback(input_vector):
    global b
    print "Input vector changed:"
    print input_vector
    b.setPortState([input_vector[0] for i in range(16)])
    stdout.flush()

comport = 3
b = GStimbox(comport, input_callback)
print "Connected to g-STIMbox (serial port %d)" % comport
print "Driver version %s, firmware version %s" %         (b.getDriverVersion(), b.getHWVersion())
b.reset()
print "Use a button connected to input port 1 to activate all output ports."
print "This program will exit after 15 seconds."
stdout.flush()
sleep(15)
b.reset()
print "Demo finished."

class lib.gstimbox.GStimbox(port=3, callback=None)

Create a connection to the g-STIMbox.

The serial port number defaults to 3. A callback function can be specified that handles signals from the input connectors (see Processing input).

close()

Close device connection.

getDriverVersion()

Returns API library version.

getHWVersion()

Returns firmware version.

reset()

Reset device.

setFrequency(port, freq)

Set the frequencies for output ports.

port - list of port numbers to change. Valid port numbers range from 0 to 15. (eg. [0, 6, 7])

freq - list of frequencies which are to be assigned to the ports. Allowed values range from 1 to 50. The function rounds these frequencies to one digit after the comma. The length of freq must equal the length of port list. (eg. [1, 2.7, 5.8])

setMode(port, mode)

Set the operation mode of output ports.

port is a list of port numbers to change (eg. [0, 2, 3]). Valid port numbers range from 0 to 15.

modes is a list of modes for the ports defined in the port variable. A mode value can be either 0 (controlled manually, see portState()) or 1 (microprocessor controlled frequency, see setFrequency()).

setPortState(state)

Set ON/OFF state for ports running in mode 0 (see setMode()).

state is a list with a length of 16. Valid values for a state is an integer of either 0 or 1.

eg. state = [0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

exception lib.gstimbox.GStimboxError

g-STIMbox device communication error.

moduleauthor:: Mirko Dietrich <mirko.dietrich(AT)bccn-berlin(DOT)de>