<commit_before>/*
 *  Copyright (C) 2004  The Concord Consortium, Inc.,
 *  10 Concord Crossing, Concord, MA 01742
 *
 *  Web Site: http://www.concord.org
 *  Email: <EMAIL>
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * END LICENSE */

/*
 * Last modification information:
 * $Revision: 1.9 $
 * $Date: 2007-04-23 16:55:44 $
 * $Author: scytacki $
 *
 * Licence Information
 * Copyright 2004 The Concord Consortium 
*/
package org.concord.sensor.device;

import org.concord.sensor.ExperimentConfig;
import org.concord.sensor.ExperimentRequest;


/**
 * SensorDevice
 * Class name and description
 *
 * Date created: Dec 24, 2004
 *
 * @author scott<p>
 *
 */
public interface SensorDevice
{
	/**
	 * This is the first method called in the life cycle of this object.
	 * The passed in string can contain whatever configuration information
	 * this device needs.  For a serial port device it probably needs to 
	 * contain the port name.  For a usb device this might not be necessary.
     * 
     * For the serial devices a speical string _auto_ is supported.  This will
     * cycle through the avaiable serial ports and try each one.  This testing
     * might not happen until isAttached is called.
     * 
	 * @param openString
	 */
	public void open(String openString);
	
	/**
	 * This is the last method called in the life cycle of this object.  
	 * The object should release any resources it is holding.  It should
	 * close serial ports, usb ports, or expansion card handles.   
	 * The object will not be used again after this is called,  A new 
	 * object will be created instead.
	 */
	public void close();
	
	/**
	 * This method is called after open but before start.  The request is 
	 * a general sensor configuration request.  The device should try to
	 * meet this request.  If the device can id sensors then it should just
	 * assume the appropriate sensors are attached based on the request.  
	 * 
	 * If the device can id sensors then it should verify the appropriate
	 * sensors are attached.  If not then it should return a ExperimentConfig
	 * with an isValid that returns false.  The sensors should be set to the 
	 * actual sensors even if they are wrong.  If the device returns an invalid
	 * config with sensors that don't match then a message will be shown to the
	 * user asking them to plug in the appropriate sensors.  The getInvalidReaon
	 * might be used in this case.  If getSensorConfig() returns null then 
	 * getInvalidReason will be displayed to the user.
	 * 
	 * This method might be called more than once, especially if it reports
	 * the wrong sensors are attached.
	 * @param request
	 * @return
	 */
	public ExperimentConfig configure(ExperimentRequest request);
	
	/**
	 * This method is called after configure returns a valid ExperimentConfig
	 * If the external device has its own timer and needs to be started this
	 * is the method where that should be done.
	 * 
	 * After stop has been called this method might be called again.
	 * @return
	 */
	public boolean start();

	/**
	 * After the device is started this method is called again and again
	 * it should be called within the value returned by getDataReadPeriod()
	 * If it takes longer than getDataReadPeriod() to execute then it will
	 * be called again as soon as possible.
	 * 
	 * It should place values read from the device in the values buffer, starting<commit_msg>fixed some typos in the documentation.<commit_after>/*
 *  Copyright (C) 2004  The Concord Consortium, Inc.,
 *  10 Concord Crossing, Concord, MA 01742
 *
 *  Web Site: http://www.concord.org
 *  Email: <EMAIL>
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * END LICENSE */

/*
 * Last modification information:
 * $Revision: 1.9 $
 * $Date: 2007-04-23 16:55:44 $
 * $Author: scytacki $
 *
 * Licence Information
 * Copyright 2004 The Concord Consortium 
*/
package org.concord.sensor.device;

import org.concord.sensor.ExperimentConfig;
import org.concord.sensor.ExperimentRequest;


/**
 * SensorDevice
 * Class name and description
 *
 * Date created: Dec 24, 2004
 *
 * @author scott<p>
 *
 */
public interface SensorDevice
{
	/**
	 * This is the first method called in the life cycle of this object.
	 * The passed in string can contain whatever configuration information
	 * this device needs.  For a serial port device it probably needs to 
	 * contain the port name.  For a usb device this might not be necessary.
     * 
     * For the serial devices a speical string _auto_ is supported.  This will
     * cycle through the avaiable serial ports and try each one.  This testing
     * might not happen until isAttached is called.
     * 
	 * @param openString
	 */
	public void open(String openString);
	
	/**
	 * This is the last method called in the life cycle of this object.  
	 * The object should release any resources it is holding.  It should
	 * close serial ports, usb ports, or expansion card handles.   
	 * The object will not be used again after this is called,  A new 
	 * object will be created instead.
	 */
	public void close();
	
	/**
	 * This method is called after open but before start.  The request is 
	 * a general sensor configuration request.  The device should try to
	 * meet this request.  If the device cannot id sensors then it should just
	 * assume the appropriate sensors are attached based on the request.  
	 * 
	 * If the device can id sensors then it should verify the appropriate
	 * sensors are attached.  If not then it should return a ExperimentConfig
	 * with an isValid that returns false.  The sensors should be set to the 
	 * actual sensors even if they are wrong.  If the device returns an invalid
	 * config with sensors that don't match then a message will be shown to the
	 * user asking them to plug in the appropriate sensors.  The getInvalidReason
	 * might be used in this case.  If getSensorConfig() returns null then 
	 * getInvalidReason will be displayed to the user.
	 * 
	 * This method might be called more than once, especially if it reports
	 * the wrong sensors are attached.
	 * @param request
	 * @return
	 */
	public ExperimentConfig configure(ExperimentRequest request);
	
	/**
	 * This method is called after configure returns a valid ExperimentConfig
	 * If the external device has its own timer and needs to be started this
	 * is the method where that should be done.
	 * 
	 * After stop has been called this method might be called again.
	 * @return
	 */
	public boolean start();

	/**
	 * After the device is started this method is called again and again
	 * it should be called within the value returned by getDataReadPeriod()
	 * If it takes longer than getDataReadPeriod() to execute then it will
	 * be called again as soon as possible.
	 * 
	 * It should place values read from the device in the values buffer, starting
{'fraction_non_alphanumeric': 0.05909589374923845, 'fraction_numerical': 0.012915803582307785, 'mean_word_length': 3.277227722772277, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2228271', 'n_tokens_mistral': 2271, 'n_tokens_neox': 2046, 'n_words': 1153}