stabiltemp4(desiredtemp,numstable,waitper,tempcompliance,tools,plotfig,verbose)

% RETVAL = stabiltemp4(DESIREDTEMP,NUMSTABLE,WAITPER,TEMPCOMPLIANCE,TOOLS,PLOTFIG,VERBOSE)
function retval = stabiltemp4(desiredtemp,numstable,waitper,tempcompliance,tools,plotfig,verbose)
% STABILTEMP sets the temperature controller setpoint and then waits for the
%  temperature to stabilize. "Stable Temperature" is defined as when the
%  temperature has been +/- the TEMPCOMPLIANCE value from the temperature
%  setpoint for NUMSTABLE readings. The loop waits WAITPER seconds between
%  temperature readings. Both the oven temperature sensor and an independent
%  sensor read by SENSOR must be stable. If no sensor is specified, only the
%  oven controller reading is used. A minimum of NUMSTABLE loop iterations
%  will happen.
% If NUMSTABLE is negative, then abs(NUMSTABLE) iterations will occur and
%  the function will exit, regardless of stability.
% stabiltemp4 uses a plot instead of the command window to display its
%  progress. Use PLOTFIG=0 to supress the plot.
%
% Requires kpib.m v2.9 or later
%
% MH Dec2010
% v2.0  remove some deprecated code; update for AcuOven
%
% JS Oct2006
% v1.5  changed the fprinted Tstable value after a timeout to the mean of 
%       the last NUMSTABLE temp readings
%
% MH AUG2006
%  v1.4 add optional counter, fix no sensor defaults, fix field names
%  v1.2 print closing, fix time result

% v1.0 use "tools" structure for input, so that any combination of ovens and
%   sensors can be used
%


%% set defaults
if nargin < 7
    verbose = 1;
end
% set defaults
if nargin < 6 || isempty(plotfig)
    plotfig = figure;
end
if nargin < 5 % default instruments: BlueOven and no independent sensor
    tools.oven.instr = 'AO_800'; % 'BlueOven' or 'GreyOven' or 'AO_800'
    tools.oven.gpib = 'COM1'; %5 = B1 7 = B3 6 = B2
    tools.sensor.instr = tools.oven.instr;
    tools.sensor.gpib = tools.oven.gpib;
end
if nargin < 4
    tempcompliance = 0.11; % temp readings must be +/- TEMPCOMPLIANCE.
end
if nargin < 3
    waitper = 10; % wait WAITPER seconds between temperature measurements
end
if nargin < 2
    numstable = 10; % NUMSTABLE measurements must be within TEMPCOMPLIANCE of DESIREDTEMP
end

timeout = 60; % timeout after this many seconds
if timeout < waitper*numstable
    timeout=waitper*numstable+timeout;
end


% print welcome
if verbose >= 1
    fprintf(1, 'stabiltemp4: %s/%s temperature stabilizing at %.1f C (%d/%.1f sec/%g C)\n',...
        tools.oven.instr,tools.sensor.instr,desiredtemp,numstable,waitper,tempcompliance);
    fprintf(1, '             Press alt-q to quit.\n\n');
end

% figure for plot
if plotfig > 0
	figure(plotfig); clf;
    set(plotfig,'KeyPressFcn', @stoptest); % so we can stop by pressing alt-q
	title(['stabiltemp4: Temperature stabilizing at ' num2str(desiredtemp) ' \circC']);
	xlabel('Measurement #');
	ylabel('Temperature (\circC)');
	hold on;
end
%%%%%%%%
%%%%%%%%


% gentlemen, start your ovens
kpib(tools.oven,'lock',0,0,0,verbose);


% algorithm: Set oven controller to desired temperature. Loop, pausing
% WAITPER seconds between each loop, reading the temperature from the oven
% controller and the temperature from the on-board LM35 temperature sensor.
% Compare temperature readings with readings from previous loop. Stability
% is defined as numstable measurements in a row for which:
%
% 1) The oven controller measures the temperature to be +/- 0.1C of the
% setpoint, and
% 2) The temperature sensor reading is within 0.1C of the previous sensor reading.
%

% set the oven temperature setpoint
kpib(tools.oven,'set',desiredtemp,0,0,verbose); pause(1);
setpoint = kpib(tools.oven,'set','query',0,0,verbose);
if setpoint ~= desiredtemp
    fprintf(1,'stabiltemp4: WARNING: Oven setpoint not set\n');
end
% if verbose >= 1
%     fprintf(1, 'stabiltemp4: Oven temperature stabilizing at %d C (%d/%d sec/%g C)\n',...
%         desiredtemp,numstable,waitper,tempcompliance);
% end

j=0; i=0;
prevTsensor = desiredtemp;
tic;
% a callback function checking for Alt-q will stop the test with runtest
clear RUNTEST; global RUNTEST; RUNTEST = 1;

while i < abs(numstable) && RUNTEST > 0
    i = i+1; j = j+1;
    
    % pause before next measurement
    pause(waitper);

    t=toc;
    Toven = kpib(tools.oven,'read',0,0,0,verbose);
    Tsensor = kpib(tools.sensor,'read','temp',3,0,verbose);
    if isfield(tools,'counter');
        freq = kpib(tools.counter,'getdata',0,0,verbose-1);
    else
        freq = 0;
    end

    
    % is the temperature within proscribed limits?
    if ((Toven >= (desiredtemp-tempcompliance)) && (Toven <= (desiredtemp+tempcompliance)) && (Tsensor >= (prevTsensor-tempcompliance)) && (Tsensor <= (prevTsensor+tempcompliance)))
        % if so, good; allow the counter to increment
        if verbose >= 2
            fprintf(1,'stabiltemp4: [%+.1f/%+.1f/%+.2f C] Number Stable: %d/%d (%d)\n',setpoint,Toven,Tsensor,i,numstable,j);
        end
        ptitle=sprintf('stabiltemp4: [%+.1f/%+.1f/%+.2f C] Number Stable: %d/%d (%d)',setpoint,Toven,Tsensor,i,numstable,j);
    else
        % if not, too bad; reset the counter
        i=0;
        if verbose >= 2
            fprintf(1,'stabiltemp4: [%+.1f/%+.1f/%+.2f C] Temperature not stable. (%d)\n',setpoint,Toven,Tsensor,j);
        end
        ptitle=sprintf('stabiltemp4: [%+.1f/%+.1f/%+.2f C] Temperature not stable. (%d)',setpoint,Toven,Tsensor,j);
    end
    % save results of this measurement    
    prevTsensor = Tsensor;
    retval.time(j) = t;
    retval.Toven(j) = Toven;
    retval.Tsensor(j) = Tsensor;
    retval.freq(j) = freq;


    % timeout if stabilizing takes too long
    if t > timeout
        fprintf(1, 'stabiltemp4: Timeout (%d seconds)!\n',timeout);
        break
    end
    
    % if NUMSTABLE is negative, then just go through the loop
    %  abs(NUMSTABLE) times and quit
    if numstable < 0 && j > abs(numstable)
        if verbose >= 1,
            fprintf(1,'stabiltemp4: Loop executed %d times. Elapsed time: %.0f seconds.\n', abs(numstable), t);
            fprintf(1,'stabiltemp4: Final Temperature: %.1f/%.2f C\n', Toven, Tsensor);
        end
        break
    end    
    
    
    % plot
    if plotfig > 0
        figure(plotfig); hold on;
        plot(j,Toven,'ob');
        if Tsensor ~= 1776
            plot(j,Tsensor,'og');
        end
        plot([1 j],[desiredtemp desiredtemp],'-k');
        plot([1 j],[desiredtemp+tempcompliance desiredtemp+tempcompliance],'-r');
        plot([1 j],[desiredtemp-tempcompliance desiredtemp-tempcompliance],'-r');
        title(ptitle);
        %xlabel('Measurement #');
        %ylabel('Temperature (\circC)');
    end
    
end % end loop, oven is stable
if verbose >= 1,
            fprintf(1,'stabiltemp4: Temperature stable at %.2f C. Elapsed time: %.0f seconds.\n', mean(retval.Tsensor(max(end-numstable,1):end)), t);
end

% save the PID values for the chuck
%if strcmp(tools.oven.instr,'AO_800');
%    retval.PID = PID_read(tools,verbose-1);
%end

% if numstable == 0 (for testing), give values for retval
if numstable == 0
    retval.time=0;
    retval.oven=0;
    retval.Tsensor=0;
    retval.freq=0;
end

retval.setpoint=desiredtemp;
retval.numstable=numstable;
retval.waitper=waitper;

return


function [] = stoptest(src,evnt)
% stoptest is a local function that acts as the stop condition to cleanly
%  exit the test. It sets the value RUNTEST to 0 when the user presses
%  alt-q in the progress figure. 
global RUNTEST;
if length(evnt.Modifier) == 1 && strcmp(evnt.Modifier{:}, 'alt') &&  evnt.Key == 'q'
    RUNTEST = 0;
    fprintf('stabiltemp4: Operator exited loop by pressing (alt-q)\n');
end
return