Diffusion Instrument Control (FreqRINCal) Browse

MyScpiInstrument.m
a7c86b29b4e8FreqRINCal

MyScpiInstrument.m
View Options

			% Class featuring a specialized framework for instruments supporting SCPI
			%
			% Undefined/dummy methods:
			% queryString(this, cmd)
			% writeString(this, cmd)

			classdef MyScpiInstrument < MyInstrument

			methods (Access = public)

			% Extend the functionality of base class method
			function addCommand(this, tag, command, varargin)
			p = inputParser();
			p.KeepUnmatched = true;
			addRequired(p, 'command', @ischar);

			addParameter(p, 'access', 'rw', @ischar);
			addParameter(p, 'format', '%e', @ischar);
			addParameter(p, 'value_list', {}, @iscell);
			addParameter(p, 'validationFcn', function_handle.empty(), ...
			@(x)isa(x, 'function_handle'));
			addParameter(p, 'default', 0);

			% Command ending for reading
			addParameter(p, 'read_ending', '?', @ischar);

			% Command ending for writing, e.g. '%10e'
			addParameter(p, 'write_ending', '', @ischar);
			parse(p, command, varargin{:});

			% Create a list of remaining parameters to be supplied to
			% the base class method
			sub_varargin = struct2namevalue(p.Unmatched);

			% Introduce variables for brevity
			format = p.Results.format;
			write_ending = p.Results.write_ending;

			if ismember('format', p.UsingDefaults) && ...
			~ismember('write_ending', p.UsingDefaults)

			% Extract format specifier and symbol from the write ending
			[smb, format] = parseFormat(this, write_ending);
			else

			% Extract format symbol
			smb = parseFormat(this, format);
			end

			if ismember('b', smb)

			% '%b' is a non-MATLAB format specifier that is introduced
			% to designate logical variables
			format = replace(format, '%b', '%i');
			write_ending = replace(write_ending, '%b', '%i');
			end
			this.CommandList.(tag).format = format;

			% Add the full read form of the command, e.g. ':FREQ?'
			if contains(p.Results.access, 'r')
			read_command = [p.Results.command, p.Results.read_ending];
			readFcn = ...
			@()sscanf(queryString(this, read_command), format);
			sub_varargin = [sub_varargin, {'readFcn', readFcn}];
			else
			read_command = '';
			end
			this.CommandList.(tag).read_command = read_command;

			% Add the full write form of the command, e.g. ':FREQ %e'
			if contains(p.Results.access,'w')
			if ismember('write_ending', p.UsingDefaults)
			write_command = [p.Results.command, ' ', format];
			else
			write_command = [p.Results.command, write_ending];
			end
			writeFcn = ...
			@(x)writeString(this, sprintf(write_command, x));
			sub_varargin = [sub_varargin, {'writeFcn', writeFcn}];
			else
			write_command = '';
			end
			this.CommandList.(tag).write_command = write_command;

			% If the value list contains textual values, extend it with
			% short forms and add a postprocessing function
			value_list = p.Results.value_list;
			validationFcn = p.Results.validationFcn;
			if ~isempty(value_list)
			if any(cellfun(@ischar, value_list))

			% Put only unique full-named values in the value list
			[long_vl, short_vl] = splitValueList(this, value_list);
			value_list = long_vl;

			% For validation, use an extended list made of full and
			% abbreviated name forms and case-insensitive
			% comparison
			validationFcn = createScpiListValidationFcn(this, ...
			[long_vl, short_vl]);

			postSetFcn = createToStdFormFcn(this, tag, long_vl);

			sub_varargin = [sub_varargin, ...
			{'postSetFcn', postSetFcn}];
			end
			end

			% Assign validation function based on the value format
			if isempty(validationFcn)
			validationFcn = createArrayValidationFcn(this, smb);
			end

			sub_varargin = [sub_varargin, { ...
			'value_list', value_list, ...
			'validationFcn', validationFcn}];

			% Assign default based on the format of value
			if ~ismember('default', p.UsingDefaults)
			default = p.Results.default;
			elseif ~isempty(value_list)
			default = value_list{1};
			else
			default = createValidValue(this, smb);
			end

			sub_varargin = [sub_varargin, {'default', default}];

			% Execute the base class method
			addCommand@MyInstrument(this, tag, sub_varargin{:});
			end

			% Redefine the base class method to use a single read operation for
			% faster communication
			function sync(this)
			cns = this.command_names;
			ind_r = structfun(@(x) ~isempty(x.read_command), ...
			this.CommandList);

			read_cns = cns(ind_r); % List of names of readable commands

			read_commands = cellfun(...
			@(x) this.CommandList.(x).read_command, read_cns,...
			'UniformOutput',false);

			res_list = queryStrings(this, read_commands{:});

			if length(read_cns)==length(res_list)

			% Assign outputs to the class properties
			for i=1:length(read_cns)
			tag = read_cns{i};

			val = sscanf(res_list{i}, ...
			this.CommandList.(tag).format);

			if ~isequal(this.CommandList.(tag).last_value, val)

			% Assign value without writing to the instrument
			this.CommandWriteEnabled.(tag) = false;
			this.(tag) = val;
			this.CommandWriteEnabled.(tag) = true;
			end
			end
			else
			warning(['Not all the properties could be read, ',...
			'instrument class values are not updated.']);
			end
			end

			%% Write/query
			% These methods implement handling multiple SCPI commands. Unless
			% overloaded, they rely on write/readString methods for
			% communication with the device, which particular subclasses must
			% implement or inherit separately.

			% Write command strings listed in varargin
			function writeStrings(this, varargin)
			if ~isempty(varargin)

			% Concatenate commands and send to the device
			cmd_str = join(varargin,';');
			cmd_str = cmd_str{1};
			writeString(this, cmd_str);
			end
			end

			% Query commands and return the resut as cell array of strings
			function res_list = queryStrings(this, varargin)
			if ~isempty(varargin)

			% Concatenate commands and send to the device
			cmd_str = join(varargin,';');
			cmd_str = cmd_str{1};
			res_str = queryString(this, cmd_str);

			% Drop the end-of-the-string symbol and split
			res_list = split(deblank(res_str),';');
			else
			res_list = {};
			end
			end
			end

			methods (Access = protected)
			%% Misc utility methods

			% Split the list of string values into a full-form list and a
			% list of abbreviations, where the abbreviated forms are inferred
			% based on case. For example, the value that has the full name
			% 'AVErage' has the short form 'AVE'.
			function [long_vl, short_vl] = splitValueList(~, vl)
			short_vl = {}; % Abbreviated forms

			% Iterate over the list of values
			for i=1:length(vl)

			% Short forms exist only for string values
			if ischar(vl{i})
			idx = isstrprop(vl{i},'upper');
			short_form = vl{i}(idx);
			if ~isequal(vl{i}, short_form) && ~isempty(short_form)
			short_vl{end+1} = short_form; %#ok<AGROW>
			end
			end
			end

			% Remove duplicates
			short_vl = unique(lower(short_vl));

			% Make the list of full forms without reordering
			long_vl = setdiff(lower(vl), short_vl, 'stable');
			end

			% Create a function that returns the long form of value from
			% value_list
			function f = createToStdFormFcn(this, cmd, value_list)
			function std_val = toStdForm(val)

			% Standardization is applicable to char-valued properties
			% which have value list
			if isempty(value_list) \|\| ~ischar(val)
			std_val = val;
			return
			end

			% find matching values
			n = length(val);
			ismatch = cellfun(@(x) strncmpi(val, x, ...
			min([n, length(x)])), value_list);

			assert(any(ismatch), ...
			sprintf(['%s is not present in the list of values ' ...
			'of command %s.'], val, cmd));

			% out of the matching values pick the longest
			mvals = value_list(ismatch);
			n_el = cellfun(@(x) length(x), mvals);
			std_val = mvals{n_el==max(n_el)};
			end

			assert(ismember(cmd, this.command_names), ['''' cmd ...
			''' is not an instrument command.'])

			f = @toStdForm;
			end

			% Find the format specifier symbol and options
			function [smb, format] = parseFormat(~, fmt_spec)
			[start, stop, tok] = regexp(fmt_spec, '%([\d\.]*)([a-z])', ...
			'start', 'end', 'tokens');

			assert(~isempty(tok) && ~isempty(tok{1}{2}), ...
			['Format symbol is not found in ' fmt_spec]);

			% The first cell index corresponds to different matches if
			% there are more than one specifier
			smb = cellfun(@(x)x{2}, tok);

			% Return a substring that includes all the specifiers
			format = fmt_spec(min(start):max(stop));
			end

			function createMetadata(this)
			createMetadata@MyInstrument(this);

			% Re-iterate the creation of command parameters to add the
			% format specifier
			for i = 1:length(this.command_names)
			cmd = this.command_names{i};
			addObjProp(this.Metadata, this, cmd, ...
			'comment', this.CommandList.(cmd).info, ...
			'fmt_spec', this.CommandList.(cmd).format);
			end
			end

			% List validation function with case-insensitive comparison
			function f = createScpiListValidationFcn(~, value_list)
			function listValidationFcn(val)
			val = lower(val);
			assert( ...
			any(cellfun(@(y) isequal(val, y), value_list)), ...
			['Value must be one from the following list:', ...
			newline, var2str(value_list)]);
			end

			f = @listValidationFcn;
			end

			% smb is an array of format specifier symbols
			function f = createArrayValidationFcn(~, smb)
			function validateNumeric(val)
			assert((length(val) == length(smb)) && isnumeric(val), ...
			['Value must be a numeric array of length ' ...
			length(smb) '.'])
			end

			function validateInteger(val)
			assert((length(val) == length(smb)) && ...
			all(floor(val) == val), ['Value must be an ' ...
			'integer array of length ' length(smb) '.'])
			end

			function validateLogical(val)
			assert((length(val) == length(smb)) && ...
			all(val==1 \| val==0), ['Value must be a logical ' ...
			'array of length ' length(smb) '.'])
			end

			function valudateCharacterString(val)
			assert(ischar(val), 'Value must be a character string.');
			end

			% Determine the type of validation function
			if all(smb == 's' \| smb == 'c')
			f = @valudateCharacterString;
			elseif all(smb == 'b')
			f = @validateLogical;
			elseif all(smb == 'b' \| smb == 'i')
			f = @validateInteger;
			else
			f = @validateNumeric;
			end
			end

			function val = createValidValue(~, smb)
			if all(smb == 's' \| smb == 'c')
			val = '';
			elseif all(smb == 'b')
			val = false(length(smb), 1);
			else
			val = zeros(length(smb), 1);
			end
			end
			end
			end

rINSTCONTROL/@MyScpiInstrument/MyScpiInstrument.ma7c86b29b4e8FreqRINCal

MyScpiInstrument.mView Options

rINSTCONTROL/@MyScpiInstrument/MyScpiInstrument.m
a7c86b29b4e8FreqRINCal

MyScpiInstrument.m
View Options