         ValveConfigurator: A configuration tool for controlling
               valves attached to microfluidics device.

                ValveConfigurator development team
         http://fun.bio.keio.ac.jp/software/valveconfigurator/
                mailto:hardware@fun.bio.keio.ac.jp

-- Last modified: Sat, 21 Feb 2015 02:10:11 +0900

* Overview
  ValveConfigurator is a configuration tool for controlling solenoid
  valves attached to microfluidics device through Elexol USB I/O 24 R
  Module(*1). By using this software, user can design opening / closing
  patterns of solenoid valves on each time point. The solenoid valves
  which are directly controlled by this software will contoll the
  streams in the cell culturing device by opening and closing in each
  solenoid valve. The integration of these techniques allows automated
  control of multiple different cell culture conditions.
  The software should build and work without serious troubles on MacOSX
  (confirmed to work on Mavericks (10.9.x).

  (*1 Elexol USB I/O 24 R: https://www.elexol.com/IO_Modules/USB_IO_24.php)

* Installation
- Dependencies
  ValveConfigurator requires Java to be installed on your system. If
  you have not yet installed Java runtime on your MacOSX, please follow
  the instruction on Java for OS X 2014-001 to install Java 6 provided
  by Apple, or Java SE Downloads to install Java 8 provided by Oracle.
  ValveConfigurator is compiled on Java 6, so you can run on both
  Java 6 and 8 environment.

  To actually controll solenoid valves with your specified opening /
  closing patterns, you have to download and install Xcode from Apple
  to get the LLVM compiler installed on your MacOSX.

- Install of ValveConfigurator
  ValveConfigurator is written in Java, and it is distributed as a
  pre-compiled binary. To install ValveConfigurator, just double-click
  ValveConfigurator-1.0.0.zip and move extracted folder
  (ValveConfigurator-1.0.0) to your working directory.

* Usage
  Dobule-clicking ValveConfigurator.jar will launch the ValveConfigurator.
  From the user-interface, users can directly specify "when" and "which"
  valve should be opened / closed by following procedure.

  1. Set the initial state (opened or closed) of each valve through a
     radiobutton under "valve initial state".
  2. After setting the initial state of each valves, type in a time point
     "when" the state of a valve should be reversed in a text field under
     "valve reversing pattern". For example, if a valve 1 on port A is set as
     "ON" for a initial state, and then a value "2" is written in the "valve
     reversing pattern", the state of the valve will be reverted (set as
     "OFF") on time point 2 (unit is in seconds).
  3. Pressing [Visualize] button will show the timing chart of valves.
     You can open multiple timing charts and select which behavior of the
     valves should be observed on each dialog.
  4. By adding new lines in procedure 2, you can add more reversing patterns.
     For example, if you add "4" and "6" after "2" for valve 1, the state
     will be reverted on time point 2, 4 and 6 respectively.
  5. Click [Finish] button once you have finished creating opening / closing
     patterns. The patterns will be save as a code of C programing language
     in the following location.
  6. To actually control the behavior of solenoid valves, open a terminal
     (Terminal.app) and go to the folder where the code is stored and then
     type "make".
     === Terminal ==========================
       cd /Users/funa/Downloads/ValveConfigurator-1.0.0/myControlProg
       make
     =======================================
  7. The output of "make" command will be displayed as follows:
     === Terminal ==========================
       gcc -Wall -c myControlProg.c
       gcc -o myControlProg libftd2xx.a libvalvecontroller.a myControlProg.o
           -lobjc -Wl,-framework -Wl,IOKit -Wl,-framework -Wl,CoreFoundation
           -Wl,-prebind
     =======================================
  8. After a successful compilation of code, an executable file "myControlProg"
     will be generated in the same folder.
  9. Plug "Elexol USB I/O 24 R Module" into your Mac and execute following
     command to actually start the control of solenoid valves.
     === Terminal ==========================
       ./myControlProg
     =======================================
 10. An output will be as follows:
     === Terminal ==========================
       Serial: ELSBY5LB
       FT_OpenEx: Success - ELSBY5LB is open
       Purging receive/transmit buffers...
       FT_Write OK 1 bytes
       FT_Read OK: [USB I/O 24] (10 bytes)
       FT_Write OK 9 bytes
       FT_Write OK 2 bytes
       FT_Write OK 2 bytes
       FT_Write OK 2 bytes
       Valve initial state of PortA:00000001
       Valve initial state of PortB:00000000
       Valve initial state of PortC:00000000
       start controlling!
       start multi processing!
       FT_Write OK 2 bytes
       Valve 1 of PortA reversed at 2.000000. valve state is 00000000.
       FT_Write OK 2 bytes
       Valve 1 of PortA reversed at 4.000000. valve state is 00000001.
       FT_Write OK 2 bytes
       Valve 1 of PortA reversed at 6.000000. valve state is 00000000.
       finish multi processing!
       finish controlling!
       FT_Write OK 2 bytes
       FT_Write OK 2 bytes
       FT_Write OK 2 bytes
       Purging receive/transmit buffers...
       Closed device ELSBY5LB
     =======================================
     where the log "Valve 1 of PortA reversed at ..." represents that
     myControlProg changed the state of valves at your specified time point.

* Trouble shooting
  If you have encountered an error while executing myControlProg as follows,
  === Terminal ==========================
    ./myControlProg
    Serial: ELSBY5LB
    Error: FT_OpenEx with ELSBY5LB failed
  =======================================
  it might be caused by a conflict with VCP(Virtual Communication Port)
  driver and D2XX Driver(libftd2xx). This problem occurs when you are using
  MacOSX Mavericks (10.9.x) or higher, because it includes VCP driver by
  default, which is not welcomed by libftd2xx users ;-)
  To avoid this problem, please execute the following command:
  === Terminal ==========================
  sudo kextunload -b com.apple.driver.AppleUSBFTDI
  Password: ******** (your password)
  =======================================
  Which will unload VCP driver from your Mac. Please notice that the VCP
  driver will be loaded again once you have restarted your Mac. That means,
  whenever you restart (reboot) your Mac, you have to type the above command.
  There is another solution to unload VCP driver forever.
  If you are interested in the other solution, please refer to this document(*2)
  (section 7.1 "Using VCP or D2XX with OSX 10.9") provided by FTDI.

  (*2 FTDI Drivers Installation Guide for MacOSX:
  http://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf)

Have fun!
-- 
ValveConfigurator development team <hardware@fun.bio.keio.ac.jp>
