diff --git a/octave/examples/recordAndMarker.m b/octave/examples/recordAndMarker.m index 40d1a8a..e619c43 100644 --- a/octave/examples/recordAndMarker.m +++ b/octave/examples/recordAndMarker.m @@ -13,12 +13,16 @@ function recordAndMarker() % Connect: establish authorization, connect the selected headset, and create its active session. cortex = cortexConnect(); fig = []; +helpText = []; +statusText = []; connectionCleanup = onCleanup(@cleanupConnection); try if ~cortex.isConnected error('recordAndMarker:connect', 'Cortex connection or authorization failed.'); end cortex = cortexSession(cortex, headsetId); + activeSessionId = cortex.manager.getContext().sessionId; + exitRequested = false; fprintf('[recordAndMarker] Connected to %s. Key help:\n', headsetId); fprintf(' S: start a record.\n'); fprintf(' A-Z except S: inject an instance marker; press that key again to end its interval.\n'); @@ -26,12 +30,15 @@ function recordAndMarker() markerIds = struct(); fig = figure('Name', 'Cortex Record and Marker Example', 'NumberTitle', 'off', ... - 'KeyPressFcn', @onKeyPress, 'Interruptible', 'off', 'BusyAction', 'queue'); + 'MenuBar', 'none', 'ToolBar', 'none', ... + 'KeyPressFcn', @onKeyPress, 'WindowButtonDownFcn', @focusKeyboardTarget, ... + 'Interruptible', 'off', 'BusyAction', 'queue'); helpLines = {'Keyboard controls', '', ... 'S: start a new record', ... 'A-Z (except S): add an instance marker while recording', ... 'Press the same letter again: end its marker interval', ... 'Esc: stop the record and exit', '', ... + 'Click in this window before typing a shortcut.', '', ... 'Marker ID, type, start time, and end time are printed', ... 'in the Command Window after each marker action.'}; helpText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... @@ -39,16 +46,30 @@ function recordAndMarker() 'String', helpLines, ... 'HorizontalAlignment', 'left', 'FontSize', 12, ... 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', ... - 'KeyPressFcn', @onKeyPress, 'Interruptible', 'off', 'BusyAction', 'queue'); + 'KeyPressFcn', @onKeyPress, 'ButtonDownFcn', @focusKeyboardTarget, ... + 'Interruptible', 'off', 'BusyAction', 'queue'); statusText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... 'Position', [0.08 0.02 0.84 0.08], ... 'String', 'Ready: press S to start a record.', ... 'HorizontalAlignment', 'left', 'FontSize', 10, ... 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', ... - 'KeyPressFcn', @onKeyPress, 'Interruptible', 'off', 'BusyAction', 'queue'); + 'KeyPressFcn', @onKeyPress, 'ButtonDownFcn', @focusKeyboardTarget, ... + 'Interruptible', 'off', 'BusyAction', 'queue'); + focusKeyboardTarget([], []); - % Acquire: wait for keyboard events while Cortex keeps the active session open. - uiwait(fig); + % Poll periodically while waiting so session-close warnings are handled even when idle. + while ishandle(fig) && ~exitRequested + uiwait(fig, 1); + if ishandle(fig) + try + headset = cortex.manager.getHeadset(); + headset.update(); + syncSessionState(); + catch pollFailure + fprintf('[recordAndMarker] Cortex poll failed: %s\n', pollFailure.message); + end + end + end catch failure fprintf('[recordAndMarker] ERROR %s: %s\n', failure.identifier, failure.message); end @@ -71,6 +92,7 @@ function onKeyPress(source, event) showStatus(['Could not stop record: ' stopFailure.message]); end end + exitRequested = true; if ishandle(fig), uiresume(fig); end return; end @@ -147,8 +169,34 @@ function showStatus(message) end end + function focusKeyboardTarget(~, ~) + if ~isempty(fig) && ishandle(fig) && ~isempty(helpText) && ishandle(helpText) + figure(fig); + uicontrol(helpText); + end + end + + function syncSessionState() + context = cortex.manager.getContext(); + if strcmp(context.sessionId, activeSessionId), return; end + + cortex.isRecording = false; + cortex.recordId = ''; + markerIds = struct(); + activeSessionId = context.sessionId; + if isempty(activeSessionId) + set(fig, 'Visible', 'off'); + showStatus('Session closed. Scanning for headset...'); + else + set(fig, 'Visible', 'on'); + focusKeyboardTarget([], []); + showStatus('Session restored. Ready to start a new record.'); + end + end + function cleanupConnection() - if cortex.isRecording + context = cortex.manager.getContext(); + if cortex.isRecording && context.isRecording try [cortex, ~] = cortexRecord(cortex, 'stop'); catch stopFailure diff --git a/octave/examples/subscribeAndPlot.m b/octave/examples/subscribeAndPlot.m index 5f18856..2f9e2d4 100644 --- a/octave/examples/subscribeAndPlot.m +++ b/octave/examples/subscribeAndPlot.m @@ -5,8 +5,14 @@ function subscribeAndPlot() currentDir = fileparts(mfilename('fullpath')); addpath(fullfile(currentDir, '../functions')); -% Set your headset id (shown in EMOTIV Launcher, for example 'INSIGHT-A1B2C3D4'). +% Set your headset ID. headsetId = ''; +% For EPOC Flex, also set the electrode map. +mappings = struct('CMS', 'TP9', 'DRL', 'TP10', ... + 'LA', 'FC5', 'LB', 'O1', 'LC', 'P7', 'LD', 'T7', ... + 'LE', 'F3', 'LF', 'F7', 'LG', 'AF3', ... + 'RA', 'FC6', 'RB', 'O2', 'RC', 'P8', 'RD', 'T8', ... + 'RE', 'F4', 'RF', 'F8', 'RG', 'AF4'); streams = {'eeg'}; durationSeconds = 90; @@ -15,7 +21,11 @@ function subscribeAndPlot() cortex = cortexConnect(); connectionCleanup = onCleanup(@() cortexDisconnect(cortex)); if cortex.isConnected - cortex = cortexSession(cortex, headsetId); + if isempty(strfind(upper(headsetId), 'FLEX')) + cortex = cortexSession(cortex, headsetId); + else + cortex = cortexSession(cortex, headsetId, 'mappings', mappings); + end cortex = cortexSubscribe(cortex, streams); end @@ -89,6 +99,9 @@ function plotEeg(fig, labels, data, time) % plotEeg Plot multi-channel EEG with +/-100 uV per trace and 200 uV channel spacing. figure(fig); channels = find(strcmp(labels, 'INTERPOLATED')) + 1:find(strcmp(labels, 'RAW_CQ')) - 1; +if isempty(channels) + channels = find(~ismember(labels, {'COUNTER', 'INTERPOLATED', 'RAW_CQ', 'MARKER', 'TIMESTAMP'})); +end if isempty(channels), return; end eeg = data(:, channels); diff --git a/octave/functions/cortexSession.m b/octave/functions/cortexSession.m index 3fb52f6..6cd6dc8 100644 --- a/octave/functions/cortexSession.m +++ b/octave/functions/cortexSession.m @@ -4,9 +4,9 @@ % Calling it again for the same active headset reuses that session; another headset % cannot be connected until the current Cortex connection is closed. % Optional name/value pairs: autoRescan (true), queryInterval (3 seconds), -% and scanTimeout (30 seconds). +% scanTimeout (30 seconds), and mappings (a scalar struct for EPOC Flex). -options = struct('autoRescan', true, 'queryInterval', 3, 'scanTimeout', 30); +options = struct('autoRescan', true, 'queryInterval', 3, 'scanTimeout', 30, 'mappings', []); if mod(numel(varargin), 2) ~= 0 error('cortex:sessionFailed', 'Options must be supplied as name/value pairs.'); end @@ -25,6 +25,14 @@ if ~ischar(headsetId) || isempty(headsetId) error('cortex:sessionFailed', 'headsetId must be a non-empty character vector.'); end +if ~isempty(options.mappings) + if ~isstruct(options.mappings) || ~isscalar(options.mappings) || isempty(fieldnames(options.mappings)) + error('cortex:sessionFailed', 'mappings must be a non-empty scalar struct.'); + end + if isempty(strfind(upper(headsetId), 'FLEX')) + error('cortex:sessionFailed', 'mappings can only be supplied for an EPOC Flex headset.'); + end +end manager = cortex.manager; context = manager.getContext(); @@ -48,7 +56,7 @@ headsetId, options.scanTimeout); end - [ok, message] = headset.connectToHeadset(headsetId, {}); + [ok, message] = headset.connectToHeadset(headsetId, {}, options.mappings); if ~ok error('CortexHeadset:connect', '%s', message); end diff --git a/octave/internal/CortexHeadset.m b/octave/internal/CortexHeadset.m index 5bf39f4..9701ab2 100644 --- a/octave/internal/CortexHeadset.m +++ b/octave/internal/CortexHeadset.m @@ -14,12 +14,27 @@ queryInterval = 3 end + properties (Constant, Access = private) + flexMapping = struct('CMS', 'TP9', 'DRL', 'TP10', ... + 'LA', 'FC5', 'LB', 'O1', 'LC', 'P7', 'LD', 'T7', ... + 'LE', 'F3', 'LF', 'F7', 'LG', 'AF3', ... + 'RA', 'FC6', 'RB', 'O2', 'RC', 'P8', 'RD', 'T8', ... + 'RE', 'F4', 'RF', 'F8', 'RG', 'AF4') + end + properties (Access = private) client context scanFinished = false lastQueryAt = [] parser + reconnectHeadsetId = '' + reconnectStreams = {} + reconnectMappings = [] + reconnectProfileName = '' + reconnectProfileWasLoaded = false + reconnectPending = false + reconnectSessionReady = false end methods @@ -30,6 +45,7 @@ if isempty(context.buffer) context.buffer = CortexDataBuffer(10000); end + obj.client.onWarning(0, @(warning) obj.onSessionClosed(warning)); obj.client.onWarning(1, @(warning) obj.onSessionClosed(warning)); obj.client.onWarning(142, @(warning) obj.onScanFinished(warning)); end @@ -98,9 +114,11 @@ function stopScan(obj) end end - function [ok, message] = connectToHeadset(obj, headsetId, streams) + function [ok, message] = connectToHeadset(obj, headsetId, streams, mappings, isRecovery) % Connects the headset if needed, creates an active session, and subscribes when streams are provided. if nargin < 3, streams = {}; end + if nargin < 4, mappings = []; end + if nargin < 5, isRecovery = false; end ok = false; message = ''; @@ -111,11 +129,22 @@ function stopScan(obj) return; end + isFlex = ~isempty(strfind(upper(headsetId), 'FLEX')); + if isFlex && isempty(mappings) + mappings = CortexHeadset.flexMapping; + elseif ~isFlex && ~isempty(mappings) + error('CortexHeadset:mappings', 'mappings can only be supplied for an EPOC Flex headset.'); + end + obj.reconnectMappings = mappings; + if ~strcmp(headset.status, 'connected') if ~strcmp(headset.status, 'connecting') fprintf('[CortexHeadset] Connecting to %s...\n', headsetId); - obj.client.sendRequest('controlDevice', ... - struct('command', 'connect', 'headset', headsetId)); + params = struct('command', 'connect', 'headset', headsetId); + if isFlex + params.mappings = mappings; + end + obj.client.sendRequest('controlDevice', params); end if isempty(obj.client.waitForWarning(104, obj.connectTimeout)) message = sprintf(['Connection to %s was not successful: warning 104 ' ... @@ -127,6 +156,9 @@ function stopScan(obj) obj.isScanning = false; obj.createSession(headsetId); + if ~isRecovery + obj.clearRecoveryState(); + end if ~isempty(streams) obj.subscribe(streams); end @@ -143,13 +175,23 @@ function stopScan(obj) sessionId = response.result.id; obj.context.sessionId = sessionId; obj.context.headsetId = headsetId; + obj.reconnectHeadsetId = headsetId; end - function subscribe(obj, streams) + function subscribe(obj, streams, preserveTarget) + if nargin < 3, preserveTarget = false; end if isempty(obj.context.sessionId) error('CortexHeadset:noSession', 'Create a session before subscribing.'); end + if ~preserveTarget + for index = 1:numel(streams) + if ~any(strcmp(obj.reconnectStreams, streams{index})) + obj.reconnectStreams{end + 1} = streams{index}; + end + end + end + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... 'streams', {streams}); response = obj.client.sendRequest('subscribe', params); @@ -173,7 +215,7 @@ function subscribe(obj, streams) obj.context.buffer.configure(name, labels); fprintf('[CortexHeadset] Subscribed to %s (%d columns).\n', name, numel(labels)); end - obj.isSubscribed = ~isempty(successes); + obj.isSubscribed = ~isempty(obj.context.subscribedStreams); if ~obj.isSubscribed error('CortexHeadset:subscribe', 'Cortex did not accept any data stream.'); end @@ -186,6 +228,7 @@ function unsubscribe(obj) obj.isSubscribed = false; obj.parser.reset(); obj.context.subscribedStreams = {}; + obj.reconnectStreams = {}; obj.client.sendRequest('unsubscribe', params); end @@ -226,17 +269,34 @@ function onSessionClosed(obj, warning) return; end - obj.isScanning = false; + if ~obj.reconnectPending + obj.reconnectHeadsetId = obj.context.headsetId; + obj.reconnectStreams = obj.context.subscribedStreams; + obj.reconnectProfileName = obj.context.profileName; + obj.reconnectProfileWasLoaded = obj.context.isProfileLoaded; + end + obj.reconnectPending = ~isempty(obj.reconnectHeadsetId); + obj.reconnectSessionReady = false; + obj.isScanning = obj.reconnectPending; + obj.autoRescan = true; + obj.scanFinished = obj.reconnectPending; + obj.lastQueryAt = []; obj.isSubscribed = false; obj.context.sessionId = ''; obj.context.headsetId = ''; obj.context.subscribedStreams = {}; + obj.context.streamLabels = struct(); obj.context.isRecording = false; obj.context.recordId = ''; obj.context.profileName = ''; obj.context.isProfileLoaded = false; + obj.context.detectionInfo = struct(); + obj.context.trainingEvents = {}; obj.parser.reset(); fprintf('[CortexHeadset] Session %s was closed by Cortex.\n', warning.message.sessionId); + if obj.reconnectPending + fprintf('[CortexHeadset] Scanning to reconnect %s...\n', obj.reconnectHeadsetId); + end end function runScanTimer(obj) @@ -246,6 +306,57 @@ function runScanTimer(obj) end if isempty(obj.lastQueryAt) || toc(obj.lastQueryAt) >= obj.queryInterval obj.queryHeadsets(); + if obj.reconnectPending + obj.reconnectIfAvailable(); + end + end + end + + function reconnectIfAvailable(obj) + headset = obj.findHeadset(obj.reconnectHeadsetId); + if isempty(headset), return; end + + if ~obj.reconnectSessionReady + [ok, message] = obj.connectToHeadset( ... + obj.reconnectHeadsetId, {}, obj.reconnectMappings, true); + if ~ok + fprintf('[CortexHeadset] Reconnect attempt failed: %s\n', message); + obj.isScanning = true; + obj.lastQueryAt = tic(); + return; + end + obj.reconnectSessionReady = true; + end + + try + if obj.reconnectProfileWasLoaded + profile = CortexProfile(obj.client, obj.context); + profile.loadOrCreate(obj.reconnectProfileName); + end + targetStreams = obj.reconnectStreams; + missingStreams = targetStreams(~ismember(targetStreams, obj.context.subscribedStreams)); + if ~isempty(missingStreams) + obj.subscribe(missingStreams, true); + missingStreams = targetStreams(~ismember(targetStreams, obj.context.subscribedStreams)); + obj.reconnectStreams = targetStreams; + end + obj.isSubscribed = ~isempty(obj.context.subscribedStreams); + if ~isempty(missingStreams) + obj.reconnectStreams = targetStreams; + fprintf('[CortexHeadset] Waiting to restore streams: %s.\n', ... + strjoin(missingStreams, ', ')); + obj.isScanning = true; + obj.lastQueryAt = tic(); + return; + end + obj.reconnectPending = false; + obj.reconnectSessionReady = false; + obj.isScanning = false; + fprintf('[CortexHeadset] Reconnected to %s.\n', obj.reconnectHeadsetId); + catch failure + fprintf('[CortexHeadset] Could not restore the session: %s\n', failure.message); + obj.isScanning = true; + obj.lastQueryAt = tic(); end end @@ -259,6 +370,16 @@ function storeSample(obj, msg) obj.context.buffer.append(stream, row, time, bciAction); end + function clearRecoveryState(obj) + obj.reconnectStreams = {}; + obj.reconnectProfileName = ''; + obj.reconnectProfileWasLoaded = false; + obj.reconnectPending = false; + obj.reconnectSessionReady = false; + obj.scanFinished = false; + obj.lastQueryAt = []; + end + function storeSystemEvent(obj, values, time) % A sys sample is {detection, event}, for example {'mentalCommand', 'MC_Started'}. names = CortexStreamParser.stringsOf(values);