JACK WHITHAM    
       
    Home -> vlabif Module    

   
 
  On this page:  
 
   
 
  VL2 documentation:  
 
The vlabifhw component is intended to be controlled by a software driver: the vlabif module. This module is implemented in Python and named "vlabif". You can get vlabifhw and vlabif as a zip archive from the download page. To use vlabif, just unzip into your working directory and:
    import vlabif
Having done this, you have access to a complete API for controlling the vlabifhw component. You also have access to the debugging device. vlabif removes the need to write your own software to use the vlabif protocol.

vlabif is completely independent of VL2. The software component can use the vlab module to communicate via a VL2 board server, or the "pyserial module to communicate via a local serial port. The hardware component (vlabifhw) can be connected to a VL2 board server, or any computer with an RS232 port. The vlabifhw page gives side by side examples of using vlabif with a serial port and with VL2.

A typical usage of the module begins as follows:

 1  ip = vlabif.VlabInterfaceProtocol()
 2  
 3  # Connect "ip" to a serial port or to VL2, e.g.:
 4  serialport.SerialPort(ip, "/dev/ttyS0",
 5             reactor=reactor, baudrate=115200)
 6  yield ip.start()
 7  
 8  # create channel interface:
 9  chan = vlabif.SimpleDriver() 
10  ip.openChannel(1, chan)
11  
12  # use channel.
where: The vlabif module is used by the EMS client.


Module Documentation

 
 
vlabif.vlabif
index
vlabif.py

# vlabif.py
# Virtual Lab Interface Driver
#
# Author: Jack Whitham
# $Id: vlabif.py,v 1.14 2009/01/09 23:59:58 jack Exp $
#
#
# Copyright (C) 2008, Jack Whitham

# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <
http://www.gnu.org/licenses/>.
#

 
Classes
       
exceptions.Exception
VlabInterfaceError
processor.Twisted
VlabGenericProtocol
VlabInterfaceProtocol
VlabChannelTransport

 
class VlabChannelTransport
    An instance of this Transport class is created for each channel.
 
  Methods defined here:
__init__(self, cnum, vlihp)

 
class VlabGenericProtocol(processor.Twisted)
    This generic Protocol can form the basis for a Protocol
that communicates using a channel. It is used by the
DebugDriver and VlabInterfaceProtocol classes.
 
  Methods defined here:
__init__(self, debug=False)

 
class VlabInterfaceError(exceptions.Exception)
    This exception is raised when a communication error
occurs between the Virtual Lab Interface Hardware and the
software drivers.
 
  Methods inherited from exceptions.Exception:
__getitem__(...)
__init__(...)
__str__(...)

 
class VlabInterfaceProtocol(VlabGenericProtocol)
    This driver allows software to control the Virtual Lab
Interface Hardware. It can be connected to any Protocol
object, such as a serial port provided by the pyserial module:
 
>>> vlihp = vlabif.VlabInterfaceProtocol()
>>> serialport.SerialPort(vlihp, SERIAL_PORT,
                reactor=reactor, baudrate=115200)
>>> yield vlihp.start()
 
The above is useful if the hardware is connected directly to
a serial port on your machine. If it is connected to a virtual
lab serial port (provided by virtual lab software) then the
following initialisation sequence should be used (with vlf being
the virtual lab factory object):
 
>>> vlihp = vlabif.VlabInterfaceProtocol(debug=False)
>>> vl = yield vlf.getChannel()
>>> yield vl.connect(BOARD_NAME)
>>> yield vl.setUART(UART_NUMBER, 115200)
>>> yield vl.openUART(UART_NUMBER, vlihp)
>>> yield vlihp.start()
 
 
Method resolution order:
VlabInterfaceProtocol
VlabGenericProtocol
processor.Twisted

Methods defined here:
__init__(self, debug=False)
Create a new Protocol object.
getNumChannels(self)
Return the number of channels provided by the hardware.
 
This is the ext_channels value given as a generic parameter
to vlabifhw or vlabifhw_cn, plus two: channel zero represents
the serial line used to communicate with the software,
and the highest channel number is used for the debug chain
hardware. Since ext_channels must be greater than zero, the
smallest possible number of channels is 3.
getVersion(self)
Returns the hardware version number.
openChannel(self, cnum, proto, debug=False)
Open a Virtual Lab Interface Hardware channel.
 
The specified Protocol proto is associated with channel
number cnum (must be greater than 0 and less than getChannels()).
After association, information written to the protocol is
emitted by the specified hardware channel as output. Information
received by the hardware channel is sent to the protocol.
Any Twisted Protocol object can be used, but vlabif provides
two Protocols that might be particularly useful.
One is SimpleDriver:
 
>>> test = vlabif.SimpleDriver()
>>> vlihp.openChannel(1, test)
>>> test.write(chr(10))         # send 1 byte
>>> rc = yield test.wait(1)     # wait for 1 byte
 
The debug chain driver is also a Protocol:
 
>>> dbg = vlabif.DebugDriver(debug_config)
>>> vlihp.openChannel(CHANNEL_NUMBER, dbg)
 
You could even give a VlabInterfaceProtocol object to
openChannel in order to chain two Virtual Lab
Interface Hardware devices together.
start(self)
Start up the Virtual Lab Interface Hardware.
 
This must be called once a connection is established.
Before it is called, the hardware is in passthrough mode,
with all information from channel 0 being relayed to channel 1
and vice versa. This allows the hardware to act as a UART
for connection to software that doesn't support the
Virtual Lab Interface Hardware Protocol.
 
Returns a Deferred. The callback is called with True
when the operation is completed.
write(self, data)
Send bytes directly to the Virtual Lab Interface Hardware.
 
Do not call this method. You need to open a channel and
communicate through that.
 
 
vlabif.utils
index
vlabif.py

# utils.py
# Virtual Lab Interface - Extras
#
# Author: Jack Whitham
# $Id: utils.py,v 1.8 2009/01/09 14:38:24 jack Exp $
#
#
# Copyright (C) 2008, Jack Whitham

# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#

 
Classes
       
processor.Twisted
SimpleDriver

 
class SimpleDriver(processor.Twisted)
    This is a simple protocol for accessing a Virtual Lab
Interface Hardware channel. 
You can also attach it directly to a Virtual Lab UART
without going via vlabifhw, but the waitUntilSent method
is not available if you do that.
 
It is typically created as follows:
>>> tc = vlabif.SimpleDriver()
>>> vlihp.openChannel(CHANNEL_NUMBER, tc)
 
Then, it can be used to read or write for a channel, e.g.
>>> tc.write('hello world')
>>> received_data = yield tc.wait(5)
>>> print received_data
 
  Methods defined here:
__init__(self)
Create a new SimpleDriver.
flush(self, delay_time)
Wait for the specified period of time (in seconds) and
delete all input that arrives during this time. 
 
Returns a Deferred. The callback is called with the
number of bytes that were deleted.
wait(self, expect_nbytes)
Wait for expect_nbytes from the channel.
 
Returns a Deferred. The callback is called with the
received bytes when the operation is completed.
waitUntilSent(self)
Wait until every byte given to write() has been sent
and acknowledged by the receiver.
 
Returns a Deferred. The callback is called with the
received bytes when the operation is completed.
write(self, bytes)
Send bytes to the channel.
 
This method returns immediately and does not produce
a deferred.

 
Functions
       
makeNoise()
Generate 1 to 1000 bytes of random noise. Used for testing.



       
  Copyright (C) Jack Whitham 1997-2011