Overview

MBARI's MicroFluidic Block(MFB) is controlled by a single board host computer running Linux.  The Linux host connects to your local network and commands MBARI's "dwarf" boards and PCR module to execute series of chemical protocols necessary to complete PCR reactions.  The host computer makes resulting data, in the form of PCR fluorescence responses and execution traces, available from any web browser via its internal FTP server.  These MicroFluidic Block software and hardware components are the same as those used in MBARI's Environmental Sample Processor (ESP).

This guide focuses on the mechanics of network access, maintenance and troubleshooting of the host computer.  It does not discuss development and execution of chemical processing protocols or hardware maintenance and troubleshooting.


Networking

This host computer is normally plugged into a wired Ethernet network via the RJ-45 jack on its front panel.  It should integrate itself automatically into any network that supports both DHCP and DDNS.  

If your network supports DHCP, once you have unpacked and visually inspected the MFB for damage, you should plug it into your network via a Cat 5 Ethernet cable before applying power to the MFB.  When power is applied, a pair of tiny red and green light emitting diodes on the component side of the host computer board will blink briefly.  One of the lights should remain solidly on if the board is working properly.  If the lights continue to flash in a rapid, alternating pattern, the computer is failing to start.  In this case, remove power and try again.  If the problem persists, call MBARI.

Soon after the boot LEDs finish blinking, you should be able to observe two other blinking LEDs on the RJ-45 jack attached to the host computer board.  Note that there are no LEDs on the MFB's Lucite panel.  Follow the patch cable from that jack to the host board to see the network status LEDs.  At least one of these should be illuminated and you should see irregular blinking corresponding to network activity.  If these LEDs are still dark after 20 seconds, there is most likely a problem with the network connection.  Check cables and routers.  Try plugging a laptop or other computer into the same cable you intended to use for the MFB.  If the other computer works, but the MFB shows no network lights, try another cable and/or try plugging directly into the RJ-45 connector on the MFB host computer, bypassing the patch cable to the Lucite panel.

If the network is plugged in when the MFB host is first powered on or reset, it should be ready to contact 30 seconds after you first observe network activity on its LEDs.  However, if the network is plugged in after the host computer as started booting, the network integration process may take as long as five minutes.  During this process is queries your network router for a unique IPv4 address and requests that it be associated with the unique name assigned to the MFB at the time of its manufacture.  This "hostname" will be displayed on a prominent label affixed to the MFB's Lucite panel.

You can test whether the MFB is accessible a number of ways.  In all the examples below the MFB's hostname is to be substituted for 'hostname' in the text:

1. Point a web browser on your network at the URL:  FTP://hostname
2. Telnet to the host with the command:   telnet hostname
3. Ping the hostname with the command:   ping hostname
4. SSH into the host with the command:  ssh mfb@hostname
   

Note that commands are to be entered on the command line of a computer on the same LAN. SSH is available under Mac OSx, Linux and Unix, but may not available under Microsoft Windows unless it had been installed as a 3rd party add on.  The ping command on Linux and Unix will continue testing until aborted (typically with 'Control-C').  If telnet and ssh prompt for login or password continue to the next section.

If the above commands indicate that the MFB host computer is not reachable, it may be that your network supports DHCP but does not support DDNS.  This means that the MFB can only be identified by its numeric IP address of the form 11.22.33.44  This numeric address is typically assigned by your network router box.  Search your router's configuration web pages for information relating to DHCP assignment on your local network.  You may find an entry for the MFB host name listed there.  If you do, try substituting the IP address your router assigned in place of hostname in the above commands.  If that works, you can identify the MFB host by this number.  However, beware that it may change whenever the MFB is removed from the network or powered off.


Logging in to the mfb User's Linux Command Shell

The MFB host computer supports two alternative networking protocols to log in to it and issue Linux commands.  The telnet protocol is insecure, but supported by just about every networked computer.  The ssh protocol, or Secure SHell, is supported by all Linux, Unix and Mac OSx computers.  Use ssh if your computer supports it. 

Telnet always prompts for both a username and a password.  SSH infers the user name from parameters input on the command line and prompts only for the password.  Here's a typical command dialog for Telnet starting a telnet session:  (typed text is in italics)

Here's a typical command dialog for starting an ssh session:


Both the Telnet and SSH sessions function identically once started.  One may have any reasonable number of either session type opened simultaneously.  The command shell is based on busybox.  It supports somewhat simplified versions of most common Unix commands.  Details are here.

The command "busybox" will print a list of most commands available on the system:

One can get some help on command options by typing <command> --help:

Command shell sessions are ended by typing:


To start the esp application that controls the MFB from the host's Linux command prompt:


Allow 30 seconds for the esp application to start and issue the esp command prompt:

You should see messages indicating that various mechanical components of the MFB are being configured and initialized.  If you see messages indicating that parts are "not responding" or "MISSING", execute the shutdown procedure described below and check cabling, etc., then power up, log in and try starting the esp application again.

The esp application is written in the programming language Ruby and its command prompt is a variant of Interactive Ruby or irb.  It supports command auto-completion with the <TAB> key and command history recall using up and down arrow keys.  The example command below will display the state all valves, syringes and heaters, etc.:


When the MFB is switched on, one must prepare its Analytical Syringe and other components before using them.  The command to do that is:


After a few minutes, the command prompt returns and MFB is ready to use.
This guide does not cover operation of the MFB itself. See...

To quit the ESP application and return to the Linux command prompt:


Shutting Down the MFB

The MFB should not be shut down until it is in a safe state and has been chemically decontaminated per appropriate protocols.  At this point, the esp application should be quit and all open telnet and ssh sessions exited.  Then, wait 15 seconds and cut the power.


Reading Data Files from the MFB

The MFB host computer uses two distinct types of non-volatile flash memory to store data files.  Critical files are stored in an internal flash chip soldered on to the host board.  It holds all the system software necessary to start the MFB and it stores all the chemical protocols users have written in Ruby to customize their MFBs.  The MFB's Linux/Unix root filesystem is located on this non-removable flash chip.  It is of quite limited capacity, holding only either 8 or 16 megabytes.

However,  all data resulting from protocols run on the MFBs are stored onto the removable Compact Flash card plugged into the top of the host computer board.  The capacity of this compact flash is typically 512Mbytes to 4GBytes.  It appears within the root filesystem under the directories /cf and /var.  Note that, although the MFB's Compact Flash is easily removable by simply pulling it straight out of its socket, there is normally no reason to do so.  Further, unlike most Compact Flash sockets, the MFB host and/or the compact flash card could be damaged if the card is ever removed or inserted while the host is powered.

The MFB's internal FTP (File Transfer Protocol) server makes all files in the /var/log directory and in subdirectories thereof readable on other machines on the network.  There are many FTP client programs available and most popular web browsers can directly access data on FTP servers.  [Apple Users click here]  If you point these browsers at the URL:


You should see all the same files and directories you would see if you typed:


at the Linux command line while logged in to the host MFB computer.

The files created by the main MFB user (mfb) will in the mfb subdirectory.  They appear via FTP at the URL:


Most web browers have an option like "Save Link to File" that copy the indicated FTP file to somewhere on your local harddisk.


Modifying Data Files on the MFB

Files on the the MFB host's removable Compact Flash card may be modified either by copying them with the scp command or by editting them with the vi text editor.  The scp command copies files via the ssh command.  So, your computer must support ssh for scp to work.  [Windows Users click here]  Typically, to copy the file myfile.xyz to the MFB from your computer's command line interface with scp, you type a command like:


Existing files copied via scp are silently overwritten, so be careful.   SCP can also copy files from the MFB host by reversing the order of the command arguments:



Modifying Configuration and Protocol Files on the MFB

Files on the the MFB host's internal flash chip may also be modified either by copying them with the scp command or by editting them with the vi text editor.  Configuration files for a given MFB hostname will be found under the mfb user's home directory at esp2/mfb/hostname.
For example, the full path to the main configuration file for hostname MFB1 would be:


To copy the main MFB configuration file from your hostname to the current directory on your local harddisk, you could use the scp command:


You could then modify it with your favorite text editor on your computer and copy the revised version back with the command:


Alternatively, once you were logged in to the MFB, you could modify the configure.rb file in place, using the the MFB's built in vi text editor, with the command:

Note that, whatever method is used to modify configuration files, it is a good idea to first save a copy in case the modifications do not work as expected.  A good, easy way to do this is to put them in a new directory.  For example:

This saves a copy of the original configure.rb in the (newly created) original subdirectory.  If you need to revert to this copy:



Notes for Apple OS x Users

The OS x command line is a full-featured varient of BSD Unix.  As such, basic file manipulation commands on the MFB -- like ssh, scp, rm, ls, etc. -- work almost identically as on your Mac.  However, the Apples Safari web browser does not handle FTP.  Instead, it attempts to open FTP (or SSH) directories in the Finder.  I say "attempts" because the Finder often fails or gets confused after a few operations when browsing via FTP (or SSH).  Apple is directing people to a very intuitive freeware OS x Graphical User Interface for browsing FTP sites called cyberduck.   It can also browse the MFB via an ssh connection.  Highly recommended.


Notes for Microsoft Windows Users

Windows does not include clients for the ssh or scp commands.  There are many 3rd-party upgrade packages that include them.   Here are a couple freeware packages that can also do the job: