function gvsState(signal)
% developer: yaroslav.konar@gmail.com
% gvsState(signal)
% Function accepts signal as a vector of HEX code (columnar structure) OR an
% array of DECIMAL (Byte) values, row or column structure. Function
% assumes that the Vestibulator is connected to COM1.
%
% States to know:
% 1) Initialize unit: this resets the channels to zero current
% 2) Start DIRECT Mode: allows direct control of the channels
% 3) Set current levels of all channels (or just one channel)
%
% Commands to know:
% 1) initialize = 1; % or in HEX: initialize = '01';
% 2) direct = 2; % or in HEX: direct = '02';
% 3) signal = [10 166 90 127 127];
% % HEX: signal = ['0a';'a6';'5a';'7f';'7f'];
% % 10 = cdgSelAllElectrodes ('0a' in HEX)
% Or if you want to set the 1st channel to +1mA, use
% signal = [9 1 178]; % 9 = cdgSetElectrode ('09' in HEX); 1 = 1st channel;
% % 178 = Bytes (= +1mA)
%
% Conversions:
% Current = Byte * 0.02 - 2.56
% Byte = (Current + 2.56) / 0.02
%
% Usage:
% DECIMAL example: set currents to 0.75, -0.75, 0, and 0.75
% initialize = 1;
% direct = 2;
% signal = [10 166 90 127 166];
% gvsState(direct)
% gvsState(signal); pause(1)
% gvsState(initialize) % this resets currents to baseline after 1 sec
%
% HEX example:
% initialize = '01';
% direct = '02';
% signal = ['0a'; 'a6'; '5a'; '7f'; 'a6'];
% gvsState(direct)
% gvsState(signal); pause(1)
% gvsState(initialize) % this resets currents to baseline after 1 sec
%
% Function works with the Vestibulator, Good Vibrations. The signal is sent
% via a serial port and the state of the Vectibulator can be monitored via
% a MCC DAQ (or equivalent). The commands to make this function were
% obtained from the Low Spec Document that comes with the Vestibulator
% unit.
%
% Yaroslav Konar, Queen's University, Oct. 24, 2012

% % This may come in handy if one only wants to start running a preloaded
% % script:
% commands = uint8(hex2dec(['aa';'01';'06';'06';'55';... % ENTER SCRIPT RUN mode
% 'aa';'03';'12';'00';'00';'12';'55'])); % RUN SCRIPT AT ADDRESS 0x0000

% Header:
Header = 'aa';
Header = hex2dec(Header);

% Trailer:
Trailer = '55';
Trailer = hex2dec(Trailer);

% Check if signal is in vector format:
if length(signal) > 2 & size(signal,1) < size(signal,2)
signal = signal';
end

% Convert from HEX to DEC:
if ischar(signal)
signal = hex2dec(signal);
end

numBytes = length(signal);
chkSum = mod(sum(signal),256);
commands = uint8([Header; numBytes; signal; chkSum; Trailer]);

%--------------------------------------------------------------------------
% Send signal:
port = serial('COM1', 'Baudrate', 9600 );
fopen(port)
fwrite(port, commands);
fclose(port);
%--------------------------------------------------------------------------