root/trunk/mfiles/GetSwitch.m @ 502

function out = GetSwitch(f_sensorport, varargin)
% Reads the current value of the NXT switch / touch sensor
%
% Syntax
%   |switch = GetSwitch(port)|
%
%   |switch = GetSwitch(port, handle)|
%
% Description
%   |switch = GetSwitch(port)| returns the current switch value |switch| of the NXT switch / touch
%   sensor. The measurement value |switch| represents the pressing mode of the switch / touch
%   sensor. |true| is returned if the switch / touch sensor is being pressed and |false| if it is
%   being released. The given |port| number specifies the connection port. The value |port| can be
%   addressed by the symbolic constants |SENSOR_1|, |SENSOR_2|, |SENSOR_3| and |SENSOR_4| analog to
%   the labeling on the NXT Brick.
%
%   The last optional argument can be a valid NXT handle. If none is
%   specified, the default handle will be used (call |COM_SetDefaultNXT| to
%   set one).
%
%   For more complex settings the function |NXT_GetInputValues| can be used.
%
%
% Example
%+   OpenSwitch(SENSOR_4);
%+   switchState = GetSwitch(SENSOR_4);
%+   CloseSensor(SENSOR_4);
%
% See also: NXT_GetInputValues, OpenSwitch, CloseSensor, SENSOR_1, SENSOR_2, SENSOR_3, SENSOR_4
%
% Signature
%   Author: Linus Atorf, Alexander Behrens (see AUTHORS)
%   Date: 2008/12/05
%   Copyright: 2007-2008, RWTH Aachen University
%
;
%
% ***********************************************************************************************
% *  This file is part of the RWTH - Mindstorms NXT Toolbox.                                    *
% *                                                                                             *
% *  The RWTH - Mindstorms NXT Toolbox is free software: you can redistribute it and/or modify  *
% *  it under the terms of the GNU General Public License as published by the Free Software     *
% *  Foundation, either version 3 of the License, or (at your option) any later version.        *
% *                                                                                             *
% *  The RWTH - Mindstorms NXT Toolbox 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 General Public License for more details.             *
% *                                                                                             *
% *  You should have received a copy of the GNU General Public License along with the           *
% *  RWTH - Mindstorms NXT Toolbox. If not, see <http://www.gnu.org/licenses/>.                 *
% ***********************************************************************************************

% We're using RAWMODE here, because BOOLEAN mode would be nice, but isn't
% really necessary. We can use the .NormalizedADVal from GetInputValues, as
% we have this variable ALLWAYS. If we were to use BOOLEAN mode, and then
% use the .ScaledVal (what we had to do in this case because that is where
% the BOOLEAN mode val is effectively stored), we'd take away ourselves the
% possibility to use PERIODCNTMODE later on to detect "taps" or something
% else. 
% Also this function would stop working if someone used NXT_SetInputMode
% with something other then BOOLEANMODE. And we certainly want to save
% the possibility to do so later on. That's why we take the
% .NormalizedADVal and compare it against the empirically found
% threshold...
%

%% check if handle is given; if not use default one
    if nargin > 1
        handle = varargin{1};
    else
        handle = COM_GetDefaultNXT;
    end%if


%% Call NXT_GetInputValues function
    in = NXT_GetInputValues(f_sensorport, handle);
    
%% Check valid-flag, re-request data if necessary
    if ~in.Valid
        % init timeout-counter
        startTime = clock();
        timeOut = 0.1; % in seconds
        % loop until valid
        while (~in.Valid) && (etime(clock, startTime) < timeOut)
            in = NXT_GetInputValues(f_sensorport, handle);
        end%while
        %TODO please note that we DO NOT warn or do anything else if this
        %procedure above times out -- that seems ok, since we didn't do
        %that before (old ver. up to 2.02) either...
        % in that case, the returned value will probably be invalid...
        % dangerous.
        % solutions: either WARN, or return NaN...
    end%if
        
%% Do threshold decision
    % 511 should be ok, being right in the middle between both "peaks"
    if in.NormalizedADVal > 511
        % note how this val is "inverted"...
        out = false;
    else
        out = true;
    end%if

end