Subject: MFB Host Computer Operations Guide
From: <Saved by Windows Internet Explorer 7>
Date: Tue, 9 Dec 2008 05:40:22 -0800

MicroFluidics Block
Computer
Operations Guide
Copyright(C) 2008 Monterey Bay Aquarium
Research Institute
Draft 12/5/08

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 florescence 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:

Point a web browser on your network at the URL:  FTP://hostname

Telnet to the host with
the command:   telnet hostname

Ping the hostname with the
command:   ping hostname

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 networking protocol to log in to it and issues Linux commands.  The
telnet protocol is insecure, but supported an 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)

>  telnet  MFB3
Trying
134.89.10.238...
Connected to mfb3.shore.mbari.org.
Escape character is
'^]'.

MBARI ESP Embedded Linux 1.7 -- 12/2/08 [email-masked]
MFB3
login: mfb
Password:
mclane
Using
esp2local, ESPhome=/home/mfb/esp2
mfb@MFB3:~$

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

>  ssh  mfb@MFB3
The
authenticity of host 'mfb3 (134.89.10.238)' can't be established.
RSA key
fingerprint is ae:05:da:5f:4a:05:a1:7b:b8:be:2b:64:4a:00:a4:06.
Are you sure
you want to continue connecting (yes/no)? yes
Warning: Permanently
added 'mfb3,134.89.10.238' (RSA) to the list of known hosts.
mfb@mfb3's
password:  mclane
Using esp2local,
ESPhome=/home/mfb/esp2
mfb@MFB3:~$

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
sopports 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.

brent@MFB3:~$ busybox
BusyBox v1.00
(2008.09.17-21:43+0000) multi-call binary

Usage: busybox [function]
[arguments]...
or: [function]
[arguments]...

BusyBox is a multi-call binary that
combines many common Unix
utilities into a single
executable.  Most people will create a
link to
busybox for each function they wish to use, and BusyBox

will act like whatever it was invoked as.

Currently defined
functions:
[, addgroup, adduser, adjtimex, arping, ash,
awk, basename, bunzip2,
busybox, bzcat, cat, chgrp, chmod,
chown, chroot, clear, cmp,
cp, cut, date, dd, delgroup,
deluser, devfsd, df, dirname, dmesg,
dos2unix, du, echo,
egrep, env, expr, false, fgrep, find, free,
ftpget,
ftpput, getopt, getty, grep, gunzip, gzip, halt, hdparm,

head, hexdump, hostid, hostname, hwclock, id, ifconfig,
inetd,
insmod, install, kill, killall, klogd, ln, logger,
logread, losetup,
ls, lsmod, md5sum, mkdir, mkfifo, mknod,
mkswap, mktemp, modprobe,
more, mount, mv, nc, netstat,
nohup, nslookup, od, passwd, patch,
pidof, pivot_root,
poweroff, printf, ps, pwd, rdate, readlink,
realpath,
reboot, reset, rm, rmdir, rmmod, route, rx, sed, seq,
sh,
sha1sum, sleep, sort, start-stop-daemon, strings, stty,
swapoff,
swapon, sync, syslogd, tail, tar, tee, telnet,
telnetd, test,
time, touch, tr, traceroute, true, tty,
udhcpc, umount, uname,
uniq, unix2dos, unzip, uptime,
usleep, vi, watchdog, wc, wget,
which, whoami, xargs,
zcat

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

mfb@MFB3:~$
cp
--help

BusyBox v1.00
(2008.09.17-21:43+0000) multi-call binary

Usage: cp [OPTION]... SOURCE
DEST

Copies SOURCE to DEST, or multiple SOURCE(s) to
DIRECTORY.

-a    Same as
-dpR
-d    Preserves
links
-p    Preserves file attributes if
possible
-f    force (implied; ignored) -
always set
-i    interactive, prompt before
overwrite
-R,-r    Copies directories
recursively

Command shell sessions are
ended by typing:

mfb@MFB3:~$
exit

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

mfb@MFB3:~$
esp

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

@20:48:47.63 <MAIN> Copyright 2008
MBARI
/home/mfb/esp2/mfb/MFB3/configure.rb
$Revision: 1.1 $by $Author:
brent $on $Date: 2008/12/06 05:47:00 $
@21:04:10.64 SPE.stop
@21:04:10.70
SPE.configure SPEconfig
@21:04:10.83 AS.coast
@21:04:10.87 AS.configure
ASconfig
@21:04:11.05 PCR.pidtemp= 50,0.1,0,300,25,25
@21:04:11.15
PCR.caltemp= 4.803,0.0371,0
@21:04:11.19 All dwarves are running firmware
version 2.59
ESPMFB3:001:0>

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.:

ESPMFB3:001:0> ESP

SPE = Solid Phase Extraction Heater at
23.6C
AS = Analytical Syringe at 0.000ml
AFV = Analytical Fluidic Valve
state unknown
ATV = Analytical Top Valve at PCR
ASV = Analytical Sampler
Valve at waste1
ARV = Analytical Reagent Valve between carrierSolution and
air1
PCR is idle

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

ESPMFB3:002:0> MFB.ready!

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:

ESPMFB3:003:0> quit
mfb@MFB3$

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:

FTP://hostname

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

ls  -l  /var/log

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 visiable via FTP
at the URL:

FTP://hostname/mfb

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:

scp
myfile.xyz  mfb@hostname:/var/log/mfb
password:  mclane

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:

scp
mfb@hostname:/var/log/mfb/myfile.xyz  .
password:  mclane

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 in the under mfb user's home directory at esp2/mfb/hostname.
For example, the full
path to the main configuration file for hostname MFB1 would be:

/home/mfb/esp2/mfb/MFB1/configure.rb

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

scp
mfb@hostname/mfb/hostname/configure.rb  .

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

scp
configure.rb  mfb@hostname/mfb/hostname

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

mfb@hostname:~ $  vi  esp2/mfb/hostname/configure.rb

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:

mfb@hostname:~ $  cd
esp2/hostname

mfb@hostname:~/esp2/hostname $  mkdir original
mfb@hostname:~/esp2/hostname $  cp  configure.rb
original

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

mfb@hostname:~/esp2/hostname $  cp  original/configure.rb  .

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:

sshwindows  --  a
minimal implementation  (small, quick and easy to install)
cygwin -- large, complex framework that allows
windows to run many (free) Linux/Unix applications including
ssh