def set_attribute_values(self, attrs):
        """
        """
        if log.isEnabledFor(logging.DEBUG):
            log.debug("set_attribute_values: attrs = %s" % str(attrs))

        error_vals = self._validate_set_attribute_values(attrs)
        if len(error_vals) > 0:
            # remove offending attributes for the request below
            attrs_dict = dict(attrs)
            for bad_attr_name in error_vals:
                del attrs_dict[bad_attr_name]

            # no good attributes at all?
            if len(attrs_dict) == 0:
                # just immediately return with the errors:
                return error_vals

            # else: update attrs with the good attributes:
            attrs = attrs_dict.items()

        # ok, now make the request to RSN OMS:
        retval = self._oms.setPlatformAttributeValues(self._platform_id, attrs)
        log.debug("setPlatformAttributeValues = %s", retval)

        if not self._platform_id in retval:
            raise PlatformException("Unexpected: response does not include "
                                    "requested platform '%s'" % self._platform_id)

        attr_values = retval[self._platform_id]

        # OOIION-631 the reported timestamps are in NTP; see below for
        # conversion to system time.

        if log.isEnabledFor(logging.DEBUG):
            log.debug("set_attribute_values: response before conversion = %s" %
                      str(attr_values))

        # conv_attr_values: the time converted dictionary to return, initialized
        # with the error ones determined above if any:
        conv_attr_values = error_vals

        for attr_name, attr_val_ts in attr_values.iteritems():
            (val, ntp_time) = attr_val_ts

            if isinstance(ntp_time, (float, int)):
                # do conversion:
                sys_ts = ntp_2_ion_ts(ntp_time)
            else:
                # NO conversion; just keep whatever the returned value is --
                # normally an error code in str format:
                sys_ts = ntp_time

            conv_attr_values[attr_name] = (val, sys_ts)

        if log.isEnabledFor(logging.DEBUG):
            log.debug("set_attribute_values: response  after conversion = %s" %
                      str(conv_attr_values))

        return conv_attr_values

    def start_resource_monitoring(self):
        """
        Starts greenlets to periodically retrieve values of the attributes
        associated with my platform, and do corresponding event notifications.
        """

        if log.isEnabledFor(logging.DEBUG):
            log.debug("CIDEVSA-450 %r: starting resource monitoring: attr_info=%s",
                  self._platform_id, str(self._attr_info))

        #
        # TODO attribute grouping so one single greenlet is launched for a
        # group of attributes having same or similar monitoring rate. For
        # simplicity at the moment, start a greenlet per attribute.
        #

        for attr_id, attr_defn in self._attr_info.iteritems():
            if log.isEnabledFor(logging.DEBUG):
                log.debug("CIDEVSA-450 %r: dispatching resource monitoring for attr_id=%r attr_defn=%s",
                      self._platform_id, attr_id, attr_defn)

            if 'monitorCycleSeconds' in attr_defn:
                self._start_monitor_greenlet(attr_id, attr_defn)
            else:
                log.warn(
                    "CIDEVSA-450 %r: unexpected: attribute info does not contain %r "
                    "for attribute %r. attr_defn = %s",
                        self._platform_id,
                        'monitorCycleSeconds', attr_id, str(attr_defn))

    def listener(self, line):
        """
        The line listener
        """
        if log.isEnabledFor(logging.DEBUG):
            log.debug("CgsnState.listener called. line=%r" % line)

        toks = line.split(',')
        (dst, src, nnn, lng) = tuple(int(toks[i]) for i in range(4))
        msg = toks[4]

        assert CIPOP == dst
        assert CICGINT == nnn
        assert lng == len(msg)

        m = re.match(r"(ACK|NACK) (.*)", msg)
        if m:
            an = m.group(1)
            cmd = m.group(2)
            key = (src, cmd)
            self._an[key] = an
            if log.isEnabledFor(logging.DEBUG):
                log.debug("Set %s to %s" % (str(key), an))
        else:
            # TODO handle remaining cases
            pass

    def _retrieve_attribute_value(self):
        """
        Retrieves the attribute value using the given function and calls
        _values_retrieved with retrieved values.
        """
        attrNames = [self._attr_id]
        from_time = (self._last_ts + _DELTA_TIME) if self._last_ts else 0.0

        if log.isEnabledFor(logging.DEBUG):
            log.debug("CIDEVSA-450 %r: retrieving attribute %r from_time %f",
                      self._platform_id, self._attr_id, from_time)

        retrieved_vals = self._get_attribute_values(attrNames, from_time)

        if log.isEnabledFor(logging.DEBUG):
            log.debug("CIDEVSA-450 %r: _get_attribute_values returned %s", self._platform_id, retrieved_vals)

        if log.isEnabledFor(logging.DEBUG):
            log.debug("CIDEVSA-450 %r: retrieved attribute %r values from_time %f = %s",
                      self._platform_id, self._attr_id, from_time, str(retrieved_vals))

        if self._attr_id in retrieved_vals:
            values = retrieved_vals[self._attr_id]
            if values:
                self._values_retrieved(values)

            elif log.isEnabledFor(logging.DEBUG):
                log.debug("CIDEVSA-450 %r: No values reported for attribute=%r from_time=%f",
                    self._platform_id, self._attr_id, from_time)
        else:
            log.warn("CIDEVSA-450 %r: unexpected: response does not include requested attribute %r",
                self._platform_id, self._attr_id)

 def _sendto(self, data):
     if log.isEnabledFor(logging.DEBUG):
         log.debug("calling sendto(%r)" % data)
     nobytes = self._sock.sendto(data, self._address)
     if log.isEnabledFor(logging.TRACE):
         log.trace("sendto returned: %i" % nobytes)
     return nobytes

        def set_ports(pnode):
            platform_id = pnode.platform_id
            port_infos = rsn_oms.get_platform_ports(platform_id)
            if not isinstance(port_infos, dict):
                log.warn("%r: get_platform_ports returned: %s",
                         platform_id, port_infos)
                return

            if log.isEnabledFor(logging.TRACE):
                log.trace("%r: port_infos: %s", platform_id, port_infos)

            assert platform_id in port_infos
            ports = port_infos[platform_id]
            for port_id, dic in ports.iteritems():
                port = PortNode(port_id, dic['network'])
                port.set_on(dic['is_on'])
                pnode.add_port(port)

                # add connected instruments:
                instrs_res = rsn_oms.get_connected_instruments(platform_id, port_id)
                if not isinstance(instrs_res, dict):
                    log.warn("%r: port_id=%r: get_connected_instruments "
                             "returned: %s" % (platform_id, port_id, instrs_res))
                    continue

                if log.isEnabledFor(logging.TRACE):
                    log.trace("%r: port_id=%r: get_connected_instruments "
                              "returned: %s" % (platform_id, port_id, instrs_res))
                assert platform_id in instrs_res
                assert port_id in instrs_res[platform_id]
                instr = instrs_res[platform_id][port_id]
                for instrument_id, attrs in instr.iteritems():
                    port.add_instrument(InstrumentNode(instrument_id, attrs))

    def __init__(self, oms, platform_id, attr_id, attr_defn, notify_driver_event):
        """
        Creates a monitor for a specific attribute in a given platform.
        Call start to start the monitoring greenlet.

        @param oms The CI-OMS object
        @param platform_id Platform ID
        @param attr_id Attribute name
        @param attr_defn Corresp. attribute definition
        @param notify_driver_event Callback to notify whenever a value is
                retrieved.
        """
        if log.isEnabledFor(logging.DEBUG):
            log.debug("%r: OmsResourceMonitor entered. attr_defn=%s",
                      platform_id, attr_defn)

        assert platform_id, "must give a valid platform ID"
        assert 'monitorCycleSeconds' in attr_defn, "must include monitorCycleSeconds"

        self._oms = oms
        self._platform_id = platform_id
        self._attr_defn = attr_defn
        self._notify_driver_event = notify_driver_event

        self._attr_id = attr_id
        self._monitorCycleSeconds = attr_defn['monitorCycleSeconds']

        # timestamp of last retrieved attribute value
        self._last_ts = None

        self._active = False

        if log.isEnabledFor(logging.DEBUG):
            log.debug("%r: OmsResourceMonitor created. attr_defn=%s",
                      self._platform_id, attr_defn)

    def create_instance(cls, uri=None):
        """
        Creates an CIOMSClient instance.

        @param uri URI to connect to the RSN OMS server or simulator.
        If None (the default) the value of the OMS environment variable is used
        as argument. If not defined or if the resulting argument is "embsimulator"
        then an CIOMSSimulator instance is created and returned. Otherwise, the
        argument is looked up in the OMS URI aliases file and if found the
        corresponding URI is used for the connection. Otherwise, the given
        argument (or value of the OMS environment variable) is used as given
        to try the connection with corresponding XML/RPC server.
        """

        if cls._uri_aliases is None:
            cls._load_uri_aliases()

        if uri is None:
            uri = os.getenv('OMS', 'embsimulator')

        if "embsimulator" == uri:
            # "embedded" simulator, so instantiate CIOMSSimulator here:
            log.debug("Using embedded CIOMSSimulator instance")
            instance = CIOMSSimulator()
        else:
            # try alias resolution and then create ServerProxy instance:
            uri = cls._uri_aliases.get(uri, uri)
            if log.isEnabledFor(logging.DEBUG):
                log.debug("Creating xmlrpclib.ServerProxy: uri=%s", uri)
            instance = xmlrpclib.ServerProxy(uri, allow_none=True)
            if log.isEnabledFor(logging.DEBUG):
                log.debug("Created xmlrpclib.ServerProxy: uri=%s", uri)

        return instance

    def handle_attribute_value_event(self, driver_event):
        if log.isEnabledFor(logging.TRACE):  # pragma: no cover
            # show driver_event as retrieved (driver_event.vals_dict might be large)
            log.trace("%r: driver_event = %s", self._platform_id, driver_event)
            log.trace("%r: vals_dict:\n%s",
                      self._platform_id, self._pp.pformat(driver_event.vals_dict))

        elif log.isEnabledFor(logging.DEBUG):  # pragma: no cover
            log.debug("%r: driver_event = %s", self._platform_id, driver_event.brief())

        stream_name = driver_event.stream_name

        publisher = self._data_publishers.get(stream_name, None)
        if not publisher:
            log.warn('%r: no publisher configured for stream_name=%r. '
                     'Configured streams are: %s',
                     self._platform_id, stream_name, self._data_publishers.keys())
            return

        param_dict = self._param_dicts[stream_name]
        stream_def = self._stream_defs[stream_name]

        if isinstance(stream_def, str):
            rdt = RecordDictionaryTool(param_dictionary=param_dict.dump(),
                                       stream_definition_id=stream_def)
        else:
            rdt = RecordDictionaryTool(stream_definition=stream_def)

        self._publish_granule_with_multiple_params(publisher, driver_event,
                                                   param_dict, rdt)

        def set_ports(pnode):
            platform_id = pnode.platform_id
            port_infos = rsn_oms.port.get_platform_ports(platform_id)
            if not isinstance(port_infos, dict):
                raise PlatformDriverException(
                    "%r: get_platform_ports response is not a dict: %s" % (
                    platform_id, port_infos))

            if log.isEnabledFor(logging.TRACE):
                log.trace("%r: port_infos: %s", platform_id, port_infos)

            if not platform_id in port_infos:
                raise PlatformDriverException(
                    "%r: get_platform_ports response does not include "
                    "platform_id: %s" % (platform_id, port_infos))

            ports = port_infos[platform_id]

            if not isinstance(ports, dict):
                raise PlatformDriverException(
                    "%r: get_platform_ports: entry for platform_id is "
                    "not a dict: %s" % (platform_id, ports))

            for port_id, dic in ports.iteritems():
                port = PortNode(port_id, dic['network'])
                port.set_state(dic['state'])
                pnode.add_port(port)

                # add connected instruments:
                instrs_res = rsn_oms.instr.get_connected_instruments(platform_id, port_id)
                if not isinstance(instrs_res, dict):
                    log.warn("%r: port_id=%r: get_connected_instruments "
                             "response is not a dict: %s" % (platform_id, port_id, instrs_res))
                    continue

                if log.isEnabledFor(logging.TRACE):
                    log.trace("%r: port_id=%r: get_connected_instruments "
                              "returned: %s" % (platform_id, port_id, instrs_res))

                if not platform_id in instrs_res:
                    raise PlatformDriverException(
                        "%r: port_id=%r: get_connected_instruments response"
                        "does not have entry for platform_id: %s" % (
                        platform_id, ports))

                if not port_id in instrs_res[platform_id]:
                    raise PlatformDriverException(
                        "%r: port_id=%r: get_connected_instruments response "
                        "for platform_id does not have entry for port_id: %s" % (
                        platform_id, port_id, instrs_res[platform_id]))

                instr = instrs_res[platform_id][port_id]
                for instrument_id, attrs in instr.iteritems():
                    port.add_instrument(InstrumentNode(instrument_id, attrs))

    def get_attribute_values(self, attr_names, from_time):
        """
        """
        if log.isEnabledFor(logging.DEBUG):
            log.debug("get_attribute_values: attr_names=%s from_time=%s" % (
                str(attr_names), from_time))

        self._assert_rsn_oms()

        # OOIION-631 convert the system time from_time to NTP, which is used by
        # the RSN OMS interface:
        ntp_from_time = ion_ts_2_ntp(from_time)
        retval = self._rsn_oms.get_platform_attribute_values(self._platform_id, attr_names, ntp_from_time)

        if not self._platform_id in retval:
            raise PlatformException("Unexpected: response does not include "
                                    "requested platform '%s'" % self._platform_id)

        attr_values = retval[self._platform_id]

        # OOIION-631 the reported timestamps are in NTP; do conversion to system time

        if log.isEnabledFor(logging.TRACE):
            log.trace("get_attribute_values: response before conversion = %s" %
                      str(attr_values))

        conv_attr_values = {}  # the converted dictionary to return
        for attr_name, array in attr_values.iteritems():
            conv_array = []
            for (val, ntp_time) in array:

                if isinstance(ntp_time, (float, int)):
                    # do conversion:
                    sys_ts = ntp_2_ion_ts(ntp_time)
                else:
                    # NO conversion; just keep whatever the returned value is --
                    # normally an error code in str format:
                    sys_ts = ntp_time

                conv_array.append((val, sys_ts))

            conv_attr_values[attr_name] = conv_array

        if log.isEnabledFor(logging.TRACE):
            log.trace("get_attribute_values: response  after conversion = %s" %
                      str(conv_attr_values))

        return conv_attr_values

    def setUp(self):
        self.DVR_CONFIG = {
            'oms_uri':    self._dispatch_simulator('launchsimulator'),
            'attributes': {},
            'ports':      {}
        }
        log.debug("DVR_CONFIG['oms_uri'] = %s", self.DVR_CONFIG['oms_uri'])

        yaml_filename = 'ion/agents/platform/rsn/simulator/network.yml'
        log.debug("retrieving network definition from %s", yaml_filename)
        network_definition = NetworkUtil.deserialize_network_definition(file(yaml_filename))

        if log.isEnabledFor(logging.DEBUG):
            network_definition_ser = NetworkUtil.serialize_network_definition(network_definition)
            log.debug("NetworkDefinition serialization:\n%s", network_definition_ser)

        platform_id = self.PLATFORM_ID
        pnode = network_definition.pnodes[platform_id]

        def evt_recv(driver_event):
            log.debug('GOT driver_event=%s', str(driver_event))

        self._plat_driver = RSNPlatformDriver(pnode, evt_recv, Mock(), Mock())
        res_state = self._plat_driver.get_resource_state()
        self.assertEqual(res_state, RSNPlatformDriverState.UNCONFIGURED)

    def _handler_connected_turn_off_port(self, *args, **kwargs):
        """
        """
        if log.isEnabledFor(logging.TRACE):  # pragma: no cover
            log.trace("%r/%s args=%s kwargs=%s" % (
                      self._platform_id, self.get_driver_state(),
                      str(args), str(kwargs)))

        port_id = kwargs.get('port_id', None)
        if port_id is None:
            raise FSMError('turn_off_port: missing port_id argument')

        port_id = kwargs.get('port_id', None)
        instrument_id = kwargs.get('instrument_id', None)
        if port_id is None and instrument_id is None:
            raise FSMError('turn_off_port: at least one of port_id and '
                           'instrument_id argument must be given')

        try:
            result = self.turn_off_port(port_id=port_id, instrument_id=instrument_id)
            return None, result

        except PlatformConnectionException as e:
            return self._connection_lost(RSNPlatformDriverEvent.TURN_OFF_PORT,
                                         args, kwargs, e)

    def test_build_network_definition(self):
        ndef = RsnOmsUtil.build_network_definition(self._rsn_oms)

        if log.isEnabledFor(logging.TRACE):
            # serialize object to string
            serialization = NetworkUtil.serialize_network_definition(ndef)
            log.trace("NetworkDefinition serialization:\n%s", serialization)

        if not isinstance(self._rsn_oms, CIOMSSimulator):
            # OK, no more tests if we are not using the embedded simulator
            return

        # Else: do some verifications against network.yml (the spec used by
        # the simulator):

        self.assertTrue("UPS" in ndef.platform_types)

        pnode = ndef.root

        self.assertEqual(pnode.platform_id, "ShoreStation")
        self.assertTrue("ShoreStation_attr_1" in pnode.attrs)
        self.assertTrue("ShoreStation_port_1" in pnode.ports)

        sub_pnodes = pnode.subplatforms
        self.assertTrue("L3-UPS1" in sub_pnodes)
        self.assertTrue("Node1A" in sub_pnodes)
        self.assertTrue("input_voltage" in sub_pnodes["Node1A"].attrs)
        self.assertTrue("Node1A_port_1" in sub_pnodes["Node1A"].ports)

    def setUp(self):
        self._start_container()

        self.container.start_rel_from_url('res/deploy/r2deploy.yml')

        self.RR   = ResourceRegistryServiceClient(node=self.container.node)
        self.IMS  = InstrumentManagementServiceClient(node=self.container.node)
        self.DAMS = DataAcquisitionManagementServiceClient(node=self.container.node)
        self.DP   = DataProductManagementServiceClient(node=self.container.node)
        self.PSC  = PubsubManagementServiceClient(node=self.container.node)
        self.PDC  = ProcessDispatcherServiceClient(node=self.container.node)
        self.DSC  = DatasetManagementServiceClient()
        self.IDS  = IdentityManagementServiceClient(node=self.container.node)
        self.RR2  = EnhancedResourceRegistryClient(self.RR)


        # Use the network definition provided by RSN OMS directly.
        rsn_oms = CIOMSClientFactory.create_instance(DVR_CONFIG['oms_uri'])
        self._network_definition = RsnOmsUtil.build_network_definition(rsn_oms)
        # get serialized version for the configuration:
        self._network_definition_ser = NetworkUtil.serialize_network_definition(self._network_definition)
        if log.isEnabledFor(logging.TRACE):
            log.trace("NetworkDefinition serialization:\n%s", self._network_definition_ser)


        self._async_data_result = AsyncResult()
        self._data_subscribers = []
        self._samples_received = []
        self.addCleanup(self._stop_data_subscribers)

        self._async_event_result = AsyncResult()
        self._event_subscribers = []
        self._events_received = []
        self.addCleanup(self._stop_event_subscribers)
        self._start_event_subscriber()

    def __init__(self, pnode, evt_recv):
        """
        Creates a PlatformDriver instance.

        @param pnode     Root PlatformNode defining the platform network rooted at
                         this platform.
        @param evt_recv  Listener of events generated by this driver
        """
        assert pnode, "pnode must be given"
        assert evt_recv, "evt_recv parameter must be given"

        self._pnode = pnode
        self._send_event = evt_recv

        self._platform_id = self._pnode.platform_id
        if self._pnode.parent:
            self._parent_platform_id = self._pnode.parent.platform_id
        else:
            self._parent_platform_id = None

        self._platform_attributes = \
            dict((a.attr_id, a.defn) for a in self._pnode.attrs.itervalues())

        if log.isEnabledFor(logging.DEBUG):
            log.debug("%r: PlatformDriver constructor called: pnode:\n%s\n"
                      "_platform_attributes=%s",
                      self._platform_id,
                      NetworkUtil._dump_pnode(self._pnode, include_subplatforms=False),
                      self._platform_attributes)

        self._driver_config = None

        # construct FSM and start it with initial state UNCONFIGURED:
        self._construct_fsm()
        self._fsm.start(PlatformDriverState.UNCONFIGURED)

    def _handler_connected_connect_instrument(self, *args, **kwargs):
        """
        """
        if log.isEnabledFor(logging.TRACE):  # pragma: no cover
            log.trace("%r/%s args=%s kwargs=%s" % (
                      self._platform_id, self.get_driver_state(),
                      str(args), str(kwargs)))

        port_id = kwargs.get('port_id', None)
        if port_id is None:
            raise FSMError('connect_instrument: missing port_id argument')

        instrument_id = kwargs.get('instrument_id', None)
        if instrument_id is None:
            raise FSMError('connect_instrument: missing instrument_id argument')

        attributes = kwargs.get('attributes', None)
        if attributes is None:
            raise FSMError('connect_instrument: missing attributes argument')

        try:
            result = self.connect_instrument(port_id, instrument_id, attributes)
            return None, result

        except PlatformConnectionException as e:
            return self._connection_lost(RSNPlatformDriverEvent.CONNECT_INSTRUMENT,
                                         args, kwargs, e)

    def _handler_connected_set_over_current(self, *args, **kwargs):
        """
        """
        if log.isEnabledFor(logging.TRACE):  # pragma: no cover
            log.trace("%r/%s args=%s kwargs=%s" % (
                      self._platform_id, self.get_driver_state(),
                      str(args), str(kwargs)))

        port_id = kwargs.get('port_id', None)
        if port_id is None:
            raise FSMError('set_over_current: missing port_id argument')
        ma = kwargs.get('ma', None)
        if ma is None:
            raise FSMError('set_over_current: missing ma argument')
        us = kwargs.get('us', None)
        if us is None:
            raise FSMError('set_over_current: missing us argument')

        # TODO: provide source info if not explicitly given:
        src = kwargs.get('src', 'source TBD')

        try:
            result = self.set_over_current(port_id, ma, us, src)
            return None, result

        except PlatformConnectionException as e:
            return self._connection_lost(RSNPlatformDriverEvent.TURN_OFF_PORT,
                                         args, kwargs, e)

    def _construct_stream_and_publisher(self, stream_name, stream_config):

        if log.isEnabledFor(logging.TRACE):  # pragma: no cover
            log.trace("%r: _construct_stream_and_publisher: "
                      "stream_name:%r, stream_config:\n%s",
                      self._platform_id, stream_name,
                      self._pp.pformat(stream_config))

        decoder = IonObjectDeserializer(obj_registry=get_obj_registry())

        if 'stream_def_dict' not in stream_config:
            # should not happen: PlatformAgent._validate_configuration validates this.
            log.error("'stream_def_dict' key not in configuration for stream %r" % stream_name)
            return

        stream_def_dict = stream_config['stream_def_dict']
        stream_def_dict['type_'] = 'StreamDefinition'
        stream_def_obj = decoder.deserialize(stream_def_dict)
        self._stream_defs[stream_name] = stream_def_obj

        routing_key           = stream_config['routing_key']
        stream_id             = stream_config['stream_id']
        exchange_point        = stream_config['exchange_point']
        parameter_dictionary  = stream_def_dict['parameter_dictionary']
        log.debug("%r: got parameter_dictionary from stream_def_dict", self._platform_id)

        self._data_streams[stream_name] = stream_id
        self._param_dicts[stream_name] = ParameterDictionary.load(parameter_dictionary)
        stream_route = StreamRoute(exchange_point=exchange_point, routing_key=routing_key)
        publisher = self._create_publisher(stream_id, stream_route)
        self._data_publishers[stream_name] = publisher

        log.debug("%r: created publisher for stream_name=%r", self._platform_id, stream_name)

    def test_compute_checksum(self):
        # create NetworkDefinition object by de-serializing the simulated network:
        ndef = NetworkUtil.deserialize_network_definition(file("ion/agents/platform/rsn/simulator/network.yml"))

        checksum = ndef.compute_checksum()
        if log.isEnabledFor(logging.DEBUG):
            log.debug("NetworkDefinition checksum = %s", checksum)