def setUpClass(cls):
        """
        Sets up _conn_config, _timeout, according to environment variables.
        """

        cls._skip_reason = None

        #
        # cls._conn_config
        #
        cls._conn_config = None
        vadcp = os.getenv('VADCP')
        if vadcp:
            filename = vadcp
            log.info("loading connection params from '%s'" % filename)
            try:
                f = open(filename)
                yml = yaml.load(f)
                f.close()

                def create_unit_conn_config(yml):
                    return AdcpUnitConnConfig(yml.get('host'),
                                              yml.get('port'),
                                              yml.get('ooi_digi_host'),
                                              yml.get('ooi_digi_port'))

                cls._conn_config = {
                    'four_beam': create_unit_conn_config(yml['four_beam']),
                    'fifth_beam': create_unit_conn_config(yml['fifth_beam'])
                }
            except Exception, e:
                cls._skip_reason = "Problem with connection config file: '%s': %s" % (
                                    filename, str(e))
                log.warn(cls._skip_reason)

    def test_execute_get_latest_sample(self):
        self._prepare_and_connect()

        result = self.driver.execute_get_latest_sample(timeout=self._timeout)
        log.info("get_latest_sample result = %s" % str(result))

        self._disconnect()

 def tearDownClass(cls):
     try:
         if cls._client:
             log.info("ending VadcpClient object")
             cls._client.end()
     finally:
         super(Test, cls).tearDownClass()

    def __init__(self, device_address, device_port):
        """
        Setup test cases.
        """

        driver_module = "mi.instrument.uw.res_probe.ooicore.trhph_driver"
        driver_class = "TrhphInstrumentDriver"

        self._support = DriverIntegrationTestSupport(driver_module, driver_class, device_address, device_port)

        # Create and start the port agent.
        mi_logger.info("starting port agent")
        self.comms_config = {"addr": "localhost", "port": self._support.start_pagent()}

        # Create and start the driver.
        mi_logger.info("starting driver client")

        ##<update-july-2012>:
        ## start_driver and _dvr_client no longer defined in
        ## DriverIntegrationTestSupport
        #        self._support.start_driver()
        #        self._dvr_client = self._support._dvr_client
        dvr_config = {
            "comms_config": self.comms_config,
            "dvr_mod": driver_module,
            "dvr_cls": driver_class,
            "workdir": "/tmp/",
            "process_type": ("ZMQPyClassDriverLauncher",),
        }
        self._start_driver(dvr_config)

    def run(self):
        """
        Runs the receiver.
        """

        # set a timeout to the socket so we can regularly check that we are
        # still to be active (see self._recv());
        if self._sock.gettimeout() is None:
            self._sock.settimeout(0.4)

        log.info("_Receiver running")
        self._active = True

        # set up pipeline
        if self._ooi_digi:
            # no need to parse for timestamps or PD0 ensembles:
            pipeline = self.sink()
        else:
            pipeline = timestamp_filter(pd0_filter(self.sink()))

        # and read in and push received data into the pipeline:
        while self._active:
            recv = self._recv()
            if recv is not None:
                pipeline.send(({}, recv))

        pipeline.close()
        self._end_outfile()
        log.info("_Receiver ended.")

    def build_receiver(cls, sock, bufsize=4096,
                       ooi_digi=False, data_listener=None,
                       outfile=None, prefix_state=True):
        """
        Creates a returns a receiver object that handles all received responses
        from the connection, keeping relevant information and a state.

        @param sock To read in from the instrument, sock.recv(bufsize)
        @param bufsize To read in from the instrument, sock.recv(bufsize)
        @param ooi_digi True to indicate the connection is with an OOI Digi;
               False to indicate the connection is with an actual ADCP unit.
               By default, False.
        @param data_listener
        @param outfile
        @param prefix_state
        """

        receiver = _Receiver(sock, bufsize, ooi_digi,
                             data_listener, outfile, prefix_state)

        if cls._use_greenlet:
            from gevent import Greenlet
            runnable = Greenlet(receiver.run)
            log.info("Created Greenlet-based _Receiver")
        else:
            from threading import Thread
            runnable = Thread(target=receiver.run)
            runnable.setDaemon(True)
            log.info("Created Thread-based _Receiver")

        receiver._thr = runnable

        return receiver

    def __init__(self, device_address, device_port):
        """
        Setup test cases.
        """

        driver_module = 'mi.instrument.uw.res_probe.ooicore.trhph_driver'
        driver_class = 'TrhphInstrumentDriver'

        self._support = DriverIntegrationTestSupport(driver_module,
                                                     driver_class,
                                                     device_address,
                                                     device_port)

        # Create and start the port agent.
        mi_logger.info('starting port agent')
        self.comms_config = {
            'addr': 'localhost',
            'port': self._support.start_pagent()}

        # Create and start the driver.
        mi_logger.info('starting driver client')

        ##<update-july-2012>:
        ## start_driver and _dvr_client no longer defined in
        ## DriverIntegrationTestSupport
#        self._support.start_driver()
#        self._dvr_client = self._support._dvr_client
        dvr_config = {
            'comms_config': self.comms_config,
            'dvr_mod': driver_module,
            'dvr_cls': driver_class,
            'workdir' : '/tmp/',
            'process_type': ('ZMQPyClassDriverLauncher',)
        }
        self._start_driver(dvr_config)

    def setUpClass(cls):
        super(Test, cls).setUpClass()
        if cls._skip_reason:
            return

        ReceiverBuilder.use_greenlets()

        cls._samples_recd = 0

        c4 = cls._conn_config['four_beam']
        outfilename = 'vadcp_output_%s_%s.txt' % (c4.host, c4.port)
        u4_outfile = file(outfilename, 'w')
        c5 = cls._conn_config['fifth_beam']
        outfilename = 'vadcp_output_%s_%s.txt' % (c5.host, c5.port)
        u5_outfile = file(outfilename, 'w')

        cls._client = VadcpClient(cls._conn_config, u4_outfile, u5_outfile)

        cls._client.set_generic_timeout(cls._timeout)

        log.info("connecting")
        cls._client.set_data_listener(cls._data_listener)
        cls._client.connect()

        log.info("sending break and waiting for prompt")
        cls._client.send_break()

    def _build_connection(self, config):
        """
        Constructs and returns a Connection object according to the given
        configuration. The object returned here is a VadcpClient instance.

        @param config configuration dict

        @retval a VadcpClient instance

        @throws InstrumentParameterException Invalid configuration.
        """
        log.info('_build_connection: config=%s' % config)

        c4 = config['four_beam']
        outfilename = 'vadcp_output_%s_%s.txt' % (c4.host, c4.port)
        u4_outfile = file(outfilename, 'w')
        c5 = config['fifth_beam']
        outfilename = 'vadcp_output_%s_%s.txt' % (c5.host, c5.port)
        u5_outfile = file(outfilename, 'w')

        log.info("setting VadcpClient with config: %s" % config)
        try:
            client = VadcpClient(config, u4_outfile, u5_outfile)
        except (TypeError, KeyError):
            raise InstrumentParameterException('Invalid comms config dict.'
                                               ' config=%s' % config)

        # set data_listener to the client so we can notify corresponding
        # DriverAsyncEvent.SAMPLE events:
        def _data_listener(sample):
            log.info("_data_listener: sample = %s" % str(sample))
            self._driver_event(DriverAsyncEvent.SAMPLE, val=sample)

        client.set_data_listener(_data_listener)
        return client

 def user_loop(client):
     """
     Sends lines received from stdin to the socket. EOF and "q" break the
     loop.
     """
     polled = False
     while True:
         cmd = sys.stdin.readline()
         if not cmd:
             break
         cmd = cmd.strip()
         if cmd == "q":
             break
         elif re.match(r"CP\s*(0|1)", cmd, re.IGNORECASE):
             cmd = cmd.upper()
             polled = cmd.endswith('1')
             client.send(cmd)
             log.info("polled set to: %s" % polled)
         elif cmd == "break":
             client.send_break()
         elif polled and cmd.upper() in ['!', '+', '-', 'D', 'E', 'T']:
             # See Table 10: Polled Mode Commands in "Workhorse Commands
             # an Output Data Format" doc.
             # I've noted (on both units) that only '!' and '+' are
             # actually handled, that is, with no echo and apparently
             # triggering the documented behavior (certainly for the '!'
             # break reset one); the others are echoed and probably not
             # causing the corresponding behavior.
             cmd = cmd.upper()
             client._send(cmd, info="sending polled mode cmd='%s'" % cmd)
         else:
             client.send(cmd)

    def _connect_ooi_digi(self):
        """
        Establishes the connection to the OOI digi.

        The connection is attempted a number of times.

        NOTE: The connection has sporadically failed, which have been fixed by
        rebooting the unit through the web interface (which is
        http://10.180.80.178/html/reboot.htm for the 4-beam unit).
        """

        host = self._conn_config.ooi_digi_host
        port = self._conn_config.ooi_digi_port

        sock = connect_socket(host, port, timeout=self._generic_timeout)

        if 'localhost' == host:
            outfilename = 'vadcp_ooi_digi_output.txt'
        else:
            outfilename = 'vadcp_output_%s_%s.txt' % (host, port)
        outfile = open(outfilename, 'a')
        log.info("creating OOI Digi _Receiver")
        rt = ReceiverBuilder.build_receiver(sock, ooi_digi=True,
                                            outfile=outfile)
        log.info("starting OOI Digi _Receiver")
        rt.start()

        return (sock, rt, host, port)

    def test_execute_run_all_tests(self):
        self._prepare_and_connect()

        result = self.driver.execute_run_all_tests(timeout=self._timeout)
        log.info("execute_run_all_tests result=%s" % prefix(result))

        self._disconnect()

 def _set_state(self, state):
     if self._state != state:
         log.info("{{TRANSITION: %s => %s %r}}" % (self._state, state,
                                                self._last_line))
         if self._last_line:
             log.debug("LINES=\n\t|%s" % "\n\t|".join(self._lines))
         self._state = state

 def use_default(cls):
     """
     This method instructs the builder to use Thread-based receivers, which
     is the default,
     """
     if cls._use_greenlet:
         cls._use_greenlet = False
         log.info("ReceiverBuilder configured to use threads")

    def setUp(self):
        """
        """

        if self._skip_reason:
            self.skipTest(self._skip_reason)

        log.info("== VADCP _conn_config: %s" % self._conn_config)

 def use_greenlets(cls):
     """
     The builder creates Thread-based receivers by default.
     This method instructs the builder to use Greenlet-based receivers
     in subsequent calls to build_receiver.
     """
     if not cls._use_greenlet:
         cls._use_greenlet = True
         log.info("ReceiverBuilder configured to use greenlets")

 def test_get_metadata(self):
     sections = None  # None => all sections
     result = self._client.get_metadata(sections)
     self.assertTrue(isinstance(result, dict))
     s = ""
     for name, text in result.items():
         self.assertTrue(name in md_section_names)
         s += "**%s:%s\n\n" % (name, prefix(text, "\n    "))
     log.info("METADATA result=%s" % prefix(s))

    def _connect(self):
        self.driver.connect()
        state = self.driver.get_resource_state()
        log.info("connect -> %s" % str(state))
#        self.assertEqual(DriverState.CONNECTED, state)
        if DriverState.CONNECTED == state:
            pass  # OK
        else:
            self.assertTrue(state.startswith('PROTOCOL_STATE'))

    def test_start_and_stop_autosample(self):
        self._prepare_and_connect()

        result = self.driver.execute_start_autosample(timeout=self._timeout)
        log.info("execute_start_autosample result=%s" % prefix(result))

        time.sleep(6)

        result = self.driver.execute_stop_autosample(timeout=self._timeout)
        log.info("execute_stop_autosample result=%s" % prefix(result))

        self._disconnect()

    def _send(self, s, info=None):
        """
        Sends a string. Returns the number of bytes written.

        @param s the string to send
        @param info string for logging purposes
        """
        c = self._sock.send(s)
        if log.isEnabledFor(logging.INFO):
            info_str = (' (%s)' % info) if info else ''
            log.info("_send:%s%s" % (repr(s), info_str))
        return c