diff --git a/.gitignore b/.gitignore index 19d2a95..930f894 100644 --- a/.gitignore +++ b/.gitignore @@ -79,3 +79,4 @@ unity/*.unityproj ### Project-specific cortex_creds *build-* +octave/config/config.json diff --git a/README.md b/README.md index 0b04905..3db60eb 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ Example code for Cortex V2 & V3 & V4. So far we have the following languages: * NodeJS * Python * Unity +* Octave # API Documentation For Cortex V2 / V3 / V4 API documentations please check out: https://emotiv.gitbook.io/cortex-api/ diff --git a/octave/README.md b/octave/README.md new file mode 100644 index 0000000..86fc437 --- /dev/null +++ b/octave/README.md @@ -0,0 +1,275 @@ +# Emotiv Cortex Octave/MATLAB Examples + +This folder contains a MATLAB/GNU Octave client for the Emotiv Cortex API, with reusable functions and example scripts that demonstrate the Cortex API and its major Cortex workflows. + +The examples demonstrate the main Cortex API workflows: authorization, connecting to a headset, subscribing to data, creating a record and injecting markers, and BCI training. + +## What You Will Run + +The local connection has two parts: + +1. **EMOTIV Launcher**: Provides the local Cortex service and the logged-in Emotiv account. +2. **MATLAB or GNU Octave**: Runs the example and connects directly to Cortex at `wss://localhost:6868` using the bundled Java WebSocket client (`lib/`). No separate process is needed. + +## Folder Structure + +- `functions/`: Public functions (`cortexConnect`, `cortexSession`, `cortexSubscribe`, `cortexGetData`, `cortexRecord`, `cortexMarker`, `cortexProfile`, `cortexTraining`, `cortexMentalCommandInfo`, `cortexFacialExpressionInfo`, `cortexDisconnect`) that hide the internal MATLAB classes. +- `internal/`: Internal SDK classes. Not a public interface; they may change. +- `lib/`: `nv-websocket-client-2.14.jar` and `cortex-ws-client.jar`, the Java WebSocket client used for WSS. +- `java/`: Source of the small Java wrapper (`cortex-ws-client.jar`). +- `config/`: Local configuration. Copy `config/config.example.json` to `config/config.json` to store your Cortex application credentials. `config/config.json` is ignored by Git and must not be committed or shared. +- `examples/`: Beginner-friendly scripts that show complete workflows. + +The `functions/` folder provides a task-oriented, procedural interface to the Cortex API. Its helpers group related API calls where useful—for example, `cortexConnect` connects and authorizes the app, while `cortexSession` scans for and connects a headset, then creates or reuses its session. Use these functions with the shared `cortex` state to build clear, sequential workflows without instantiating or coordinating Cortex classes directly. The underlying classes and WebSocket handling are kept in `internal/`. + +## Requirements + +### EMOTIV software and account + +- EMOTIV Launcher installed and running. +- An Emotiv account signed in to EMOTIV Launcher. +- A compatible EMOTIV headset, or a virtual headset configured in EMOTIV Launcher. +- A Cortex application with a Client ID and Client Secret. + +Download EMOTIV Launcher from the [EMOTIV website](https://www.emotiv.com/products/emotiv-launcher). Follow the Launcher prompts to accept the current Terms of Use, Privacy Policy, and EULA. + +### Java + +- MATLAB or GNU Octave with a working Java VM. +- The client verifies Cortex TLS certificates using the repository's `certificates/rootCA.pem` CA bundle. +- Keep the repository-level `certificates/rootCA.pem` file when copying the Octave examples; the client reports a clear error if it is missing. +### MATLAB or GNU Octave + +Use a recent MATLAB release or GNU Octave version with: + +- `jsonencode` and `jsondecode` support. +- Java support (the bundled jars in `lib/` are loaded automatically). +- Permission to open a TLS connection to `localhost:6868`. + +The SDK does not require the MATLAB Instrument Control Toolbox, an Octave sockets package, or a separate JSON package. + +## Register a Cortex Application + +The Client ID and Client Secret identify your application. They are different from your Emotiv account password. + +1. Sign in to your Emotiv account. +2. Open the Cortex application management page: [Emotiv Cortex Apps](https://www.emotiv.com/my-account/cortex-apps/). +3. Create a Cortex application, or open an existing application. +4. Copy its **Client ID** and **Client Secret**. +5. Keep the Client Secret private. Do not paste it into source code, commit it to Git, or send it in a public issue. + +You can also follow the application-registration instructions in the repository's [Python examples README](../python/README.md) and the [official Cortex API documentation](https://emotiv.gitbook.io/cortex-api). + +## Configure Your Credentials + +The example reads credentials from `octave/config/config.json`. + +1. Copy `octave/config/config.example.json` to `octave/config/config.json`. +2. Open `octave/config/config.json` and replace the placeholder values with the Client ID and Client Secret from your Cortex application: + +```json +{ + "clientId": "YOUR_CLIENT_ID", + "clientSecret": "YOUR_CLIENT_SECRET" +} +``` + +3. Save the file. + +`cortexConnect` loads `octave/config/config.json` automatically and raises an error if the file does not exist. + +The repository ignores `octave/config/config.json` because it contains a secret. Keep your real credentials only in `octave/config/config.json` and do not commit or share it. + +## Quickstart + +Run these steps in order. + +### 1. Start EMOTIV Launcher + +Open EMOTIV Launcher and sign in. Make sure Cortex is available before running the example. + +If you are testing without a physical headset, create or enable a virtual headset in EMOTIV Launcher according to the [virtual brainwear guide](https://emotiv.gitbook.io/emotiv-launcher/devices-setting-up-virtual-brainwear-r/creating-a-virtual-brainwear-device). + +### 2. Configure `config.json` + +Complete the credential setup described above before running the example. + +### 3. Run the authentication example + +Open MATLAB or GNU Octave from the repository root and run: + +```matlab +run('octave/examples/authorizeAndShowAccount.m') +``` + +The script adds `octave/functions` to the search path automatically (`cortexConnect` adds `octave/internal` internally). It then calls this simple workflow: + +```matlab +cortex = cortexConnect(); +% Use cortex.token, cortex.userInfo, and cortex.licenseInfo here. +cortex = cortexDisconnect(cortex); +``` + +A successful run prints an authorization message, the Cortex token length or token, the logged-in username, and the license name. The example closes the connection before it finishes. + +### 4. Approve application access when prompted + +The first authorization may require approval in EMOTIV Launcher. Keep the application open and approve access when prompted. The example waits for approval for up to 180 seconds. + +## Understanding the Result + +`cortexConnect` returns a plain MATLAB/Octave struct: + +- `cortex.isConnected`: `true` after the Cortex connection and authorization succeed. +- `cortex.token`: The Cortex token for later API requests. +- `cortex.userInfo`: Information returned by `getUserInformation`. +- `cortex.licenseInfo`: License information returned by `getLicenseInfo`. + +The internal manager is stored in the struct only so that `cortexDisconnect(cortex)` can close the WebSocket. Treat that field as internal and do not edit it. + +## Subscribe and Plot + +`examples/subscribeAndPlot.m` demonstrates subscribing to the `eeg` stream and plotting its electrode channels. + +1. Open `examples/subscribeAndPlot.m` and set `headsetId` (shown in EMOTIV Launcher, for example `INSIGHT-A1B2C3D4`). +2. Run `run('octave/examples/subscribeAndPlot.m')`. + +```matlab +cortex = cortexConnect(); +cortex = cortexSession(cortex, 'INSIGHT-A1B2C3D4'); +cortex = cortexSubscribe(cortex, {'eeg'}); +[labels, data, time] = cortexGetData(cortex, 'eeg', 256); % newest 256 samples +cortex = cortexDisconnect(cortex); % unsubscribes and closes the socket +``` + +- To subscribe to other supported streams, pass their names instead, for example `{'mot','dev','eq','pow','met'}`. Call `cortexGetData(cortex, streamName)` for each stream you want to consume. +- `labels{j}` names column `j` of `data`; each row is a sample. Use the returned labels to select columns rather than hard-coding positions. For console output, loop over `labels` and print each `data(end,j)`; for plots, plot the desired numeric columns against `time`. +- `met` columns named `.isActive` are 1 when that metric is running. When it is 0 the metric value is `NaN` (Cortex sends `null`). Without a PRO license `met` arrives about every 10 seconds; with a PRO license about 2 samples per second. `pow` does not need a PRO license. +- `cortexSession` scans for the headset, connects it if needed (waiting up to 5 seconds for Cortex warning 104), and creates one active session for that headset. Calling it again for the same active headset reuses that session; a different headset requires disconnecting first. +- `cortexSubscribe(cortex, streams)` subscribes the requested streams on the active session created by `cortexSession`. +- `cortexGetData` collects the samples that have arrived and returns them from a buffer that keeps the latest 10000 samples per stream. `data` has one row per sample and one column per entry in `labels`; empty values are `NaN`. +- Call `cortexGetData` regularly. Samples are only read from the connection when it runs, and it can take up to about 1 second when no data is arriving. + +**Known limitations:** EPOC Flex headsets are not currently supported by the Octave examples, including configurations that use channel mappings. The examples also do not automatically recover if a headset disconnects; reconnect the headset and run the example again. These limitations may be addressed in a future update. + +## Record and Markers + +`examples/recordAndMarker.m` demonstrates creating and stopping a record without subscribing to any data stream, and adding keyboard-controlled markers. + +1. Set `headsetId` and `titlePrefix` near the top of `examples/recordAndMarker.m`. Add the examples folder to the MATLAB or Octave path and run the function without arguments: + +```matlab +addpath('octave/examples'); +recordAndMarker(); +``` + +2. Focus the opened figure. Press `S` to start a record titled `_`. The example adds a description and the tags `octave` and `record-marker-demo`. +3. Press any other letter to inject an instance marker; the pressed letter is used as both its label and string value. Press that letter again to update the marker with the current epoch time in milliseconds, turning it into an interval marker. The next press injects a new instance marker. +4. Press `Esc` or close the figure to stop the active record and disconnect. + +The headset-only connection and record/marker APIs are also available directly: + +```matlab +cortex = cortexConnect(); +cortex = cortexSession(cortex, 'INSIGHT-A1B2C3D4'); +[cortex, started] = cortexRecord(cortex, 'start', 'my-study_1792692000', ... + 'Example record description', {'octave', 'demo'}); +[cortex, injected] = cortexMarker(cortex, 'inject', 'A', 'A'); +endTime = double(javaMethod('currentTimeMillis', 'java.lang.System')); +[cortex, updated] = cortexMarker(cortex, 'update', injected.marker.uuid, endTime); +[cortex, stopped] = cortexRecord(cortex, 'stop'); +cortex = cortexDisconnect(cortex); +``` + +`cortexSession(cortex, headsetId)` connects the headset and creates or reuses its active session without subscribing to streams. From that session, call either `cortexSubscribe(cortex, streams)` or start a record. `cortexRecord(cortex, 'start', title, description, tags)` returns the Cortex result fields `record` and `sessionId`; `cortexRecord(cortex, 'stop')` returns the stopped `record` and its `sessionId`. `cortex.isRecording` and `cortex.recordId` reflect the active record. + +`cortexMarker(cortex, 'inject', label, value, ...)` returns `recordId`, `sessionId`, and `marker`. Optional name/value pairs are `time` (epoch milliseconds; defaults to the current time), `port` (defaults to `Software`), and `extras` (a scalar struct). `cortexMarker(cortex, 'update', markerId, endTime, ...)` returns the same result fields and accepts optional `extras`. `endTime` is required and is measured in milliseconds since 1970-01-01 UTC. Both marker actions require an active record. + +## Mental Command Training + +`examples/mentalCommandTraining.m` loads (or creates) a profile, trains mental command actions from the keyboard, and shows live commands. + +1. Set `headsetId` and `profileName` near the top of the file, then run: + +```matlab +addpath('octave/examples'); +mentalCommandTraining(); +``` + +2. Focus the figure. `N`, `P`, `L`, `D` start training neutral, push, left and drop (train neutral first). When a training succeeds, press `A` to accept it (this saves the profile) or `R` to reject it. `S` subscribes to `com` and shows the live action and power as text. `U` or `Esc` unloads the profile and exits. + +The same flow with the public functions: + +```matlab +cortex = cortexConnect(); +cortex = cortexSession(cortex, 'INSIGHT-A1B2C3D4'); +[cortex, profile] = cortexProfile(cortex, 'load', 'my-profile'); % creates it when missing +cortex = cortexSubscribe(cortex, {'sys', 'com'}); +started = cortexTraining(cortex, 'mentalCommand', 'push', 'start', 'wait', 30); +if started.isSucceeded + accepted = cortexTraining(cortex, 'mentalCommand', 'push', 'accept', 'wait', 15); % also saves the profile +end +[labels, data, time, bciActions] = cortexGetData(cortex, 'com', 1); % bciActions{end} = action, data(end, 2) = power +[cortex, ~] = cortexProfile(cortex, 'unload'); +cortex = cortexDisconnect(cortex); +``` + +- `[cortex, result] = cortexProfile(cortex, action, profileName)`: `action` is `'load'` (creates the profile if missing), `'save'` or `'unload'` (`profileName` is only needed for `'load'`). `result` has `name`, `uuid`, `existed`, `created` and `isLoaded`. It updates `cortex.isProfileLoaded` and `cortex.profileName`. Errors use `cortex:profileFailed`. +- `result = cortexTraining(cortex, detection, action, status, 'wait', seconds)`: `detection` is `'mentalCommand'` (`'facialExpression'` uses the same call), `action` is any action Cortex lists for the detection (for example `neutral`, `push`, `pull`, `left`, `right`; for `facialExpression` only `neutral`, `surprise`, `frown`, `smile` and `clench` can be trained), and `status` is `start`, `accept`, `reject`, `reset` or `erase`. With `'wait'` (requires the `sys` stream), `start` waits for `MC_Succeeded` or `MC_Failed` and `accept` waits for `MC_Completed`, then saves the profile. `result` has `detection`, `action`, `status`, `event`, `isSucceeded` and `profileSaved`. Errors use `cortex:trainingFailed`. +- `cortexGetData(cortex, 'com')` returns labels `{'act','pow'}`. The `act` column of `data` is `NaN`; the mental command actions are in the fourth output `bciActions` (one string per row) and `pow` (0 to 1) is in `data`. + +## Facial Expression Training + +`examples/facialExpressionTraining.m` works like the mental command example, for facial expressions. + +1. Set `headsetId` and `profileName` near the top of the file, then run: + +```matlab +addpath('octave/examples'); +facialExpressionTraining(); +``` + +2. Focus the figure. `N`, `S`, `F`, `M`, `C` start training neutral, surprise, frown, smile and clench (train neutral first). Press `A` to accept a successful training (this saves the profile) or `R` to reject it. `L` subscribes to `fac` and shows the live eye, upper face and lower face actions with their powers. `U` or `Esc` unloads the profile and exits. + +- `info = cortexFacialExpressionInfo(cortex)` returns `possibleActions`, `trainedActions` (structs with `action`, `threshold` from 0 to 1000 (`[]` for neutral) and `trainingCount`) and `trainingDuration` in seconds. It requires a loaded profile. Errors use `cortex:facialExpressionFailed`. +- `cortexGetData(cortex, 'fac')` returns labels `{'eyeAct','uAct','uPow','lAct','lPow'}`. The action columns of `data` are `NaN`; each element of the fourth output is `{eyeAct, uAct, lAct}`, and `uPow` and `lPow` (0 to 1) are in `data`. + +## Troubleshooting + +### Could not connect to Cortex at `wss://localhost:6868` + +- Open EMOTIV Launcher and sign in. +- Confirm that Cortex is available in the Launcher. +- If certificate verification fails, confirm that `certificates/rootCA.pem` is present in the repository. +- If a jar is reported missing, restore the `lib/` folder from the repository. +- Restart EMOTIV Launcher and run the example again. +- Check that local security software is not blocking the connection. + +### No user is logged in + +Sign in to EMOTIV Launcher and run `authorizeAndShowAccount.m` again. + +### Application access is not granted + +Approve the application-access request in EMOTIV Launcher. The example waits for up to 180 seconds. If the wait expires, run the example again after approving access. + +### Invalid Client ID or Client Secret + +Open the Cortex application page and copy the credentials again. Make sure `config.json` contains valid JSON and that the property names are exactly `clientId` and `clientSecret`. + +### `jsondecode` or `jsonencode` is unavailable + +Use a recent MATLAB or GNU Octave release with native JSON support. The SDK does not install or use a third-party JSON package. + +### Headset not found or not connected + +- Switch the headset on and make sure it is in range, or enable a virtual headset in EMOTIV Launcher. +- Check that `headsetId` matches the id shown in EMOTIV Launcher exactly. +- Increase `'scanTimeout'` in `cortexSession` if the headset is slow to appear. +- If you see "warning 104 was not received", the headset did not finish connecting in 5 seconds; try again. + +## Next Steps + +Once authentication works, new examples can reuse the same connection pattern and build additional Cortex workflows in `functions/` and `examples/`. Keep transport and authentication details in `internal/`, and keep researcher-facing scripts short and sequential. + +For the full API reference, see the [official Emotiv Cortex API documentation](https://emotiv.gitbook.io/cortex-api). diff --git a/octave/config/config.example.json b/octave/config/config.example.json new file mode 100644 index 0000000..3b734ea --- /dev/null +++ b/octave/config/config.example.json @@ -0,0 +1,4 @@ +{ + "clientId": "YOUR_CLIENT_ID", + "clientSecret": "YOUR_CLIENT_SECRET" +} diff --git a/octave/examples/authorizeAndShowAccount.m b/octave/examples/authorizeAndShowAccount.m new file mode 100644 index 0000000..1326732 --- /dev/null +++ b/octave/examples/authorizeAndShowAccount.m @@ -0,0 +1,22 @@ +% authorizeAndShowAccount Connect to Cortex, authorize this app, show user and license information, and disconnect. + +% 1. Initialization & Configuration: make the SDK functions visible. +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% 2. Connection / Authentication: needs EMOTIV Launcher running with a logged-in user. +% Credentials are loaded from config/config.json. +cortex = cortexConnect(); + +% 3. Action: show the result of the authentication. +if cortex.isConnected + fprintf('[authorizeAndShowAccount] Authorized. cortexToken length: %d\n', numel(cortex.token)); + fprintf('[authorizeAndShowAccount] User: %s\n', cortex.userInfo.username); + fprintf('[authorizeAndShowAccount] License: %s\n', cortex.licenseInfo.licenseName); +else + fprintf('[authorizeAndShowAccount] Authentication failed. See the messages above.\n'); +end + +% 4. Safe Teardown: always release the socket, even after a failed connection. +cortex = cortexDisconnect(cortex); +fprintf('[authorizeAndShowAccount] Done.\n'); diff --git a/octave/examples/facialExpressionTraining.m b/octave/examples/facialExpressionTraining.m new file mode 100644 index 0000000..0b9a51f --- /dev/null +++ b/octave/examples/facialExpressionTraining.m @@ -0,0 +1,328 @@ +function facialExpressionTraining() +% facialExpressionTraining Train facial expression actions from the keyboard and watch live expressions. +% Set headsetId and profileName below, then call facialExpressionTraining(). +% Keys (focus the figure): N neutral, S surprise, F frown, M smile, C clench start a training; +% A accept or R reject the training result; L show live expressions; +% U (or Esc) unload the profile and exit. Train neutral first, then at least one action. +% +% The fac stream sends one sample per update with five values: +% eyeAct the eye action (for example 'neutral' or 'blink') +% uAct the upper face action, with its power uPow from 0 to 1 +% lAct the lower face action, with its power lPow from 0 to 1 +% Only neutral, surprise, frown, smile and clench can be trained. + +% Set your headset id and the name of the training profile to create or load. +headsetId = ''; +profileName = 'my-facial-expression'; + +% Allow the action duration plus time for Cortex to deliver FE_Succeeded or FE_Failed. +trainStartEventWaitLimit = 15; +% FE_Completed usually arrives immediately; keep this short timeout as a safeguard. No deadline for choosing A or R. +trainAcceptEventWaitLimit = 3; + +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% Connect: authorize, connect the headset, create its session and load (or create) the profile. +cortex = cortexConnect(); +fig = []; +statusText = []; + liveText = {}; + powerAxes = {}; + powerBars = {}; + powerLabels = {}; +isBusy = false; +isExitRequested = false; +isLiveStreaming = false; +pendingAction = ''; +lastSample = ''; +connectionCleanup = onCleanup(@cleanupConnection); +try + if ~cortex.isConnected + error('facialExpressionTraining:connect', 'Cortex connection or authorization failed.'); + end + cortex = cortexSession(cortex, headsetId); + [cortex, profileResult] = cortexProfile(cortex, 'load', profileName); + if profileResult.created + fprintf('[facialExpressionTraining] Created and loaded profile %s.\n', profileName); + else + fprintf('[facialExpressionTraining] Loaded existing profile %s.\n', profileName); + end + + facialExpressionInfo = cortexFacialExpressionInfo(cortex); + trainingDuration = facialExpressionInfo.trainingDuration; + fprintf('[facialExpressionTraining] Facial expression info:\n%s\n', ... + jsonencode(facialExpressionInfo, 'PrettyPrint', true)); + + % The sys stream reports the training events (started, succeeded, completed). + cortex = cortexSubscribe(cortex, {'sys'}); + if ~cortex.isSubscribed + error('facialExpressionTraining:subscribe', 'Could not subscribe to the sys stream.'); + end + + fprintf('[facialExpressionTraining] Key help:\n'); + fprintf(' N / S / F / M / C: start training neutral / surprise / frown / smile / clench.\n'); + fprintf(' A / R: accept / reject the training result.\n'); + fprintf(' L: show live facial expressions.\n'); + fprintf(' U or Esc: unload the profile and exit.\n'); + + fig = figure('Name', 'Cortex Facial Expression Training', 'NumberTitle', 'off', ... + 'KeyPressFcn', @onKeyPress); + figurePosition = get(fig, 'Position'); + figurePosition(3) = 2 * figurePosition(3); + heightIncrease = 0.15 * figurePosition(4); + figurePosition(4) = figurePosition(4) + heightIncrease; + figurePosition(2) = figurePosition(2) - heightIncrease / 2; + set(fig, 'Position', figurePosition); + helpLines = {'Keyboard controls', '', ... + 'N: train neutral (do this first)', ... + 'S: train surprise', ... + 'F: train frown', ... + 'M: train smile', ... + 'C: train clench', ... + 'A: accept the training result (saves the profile)', ... + 'R: reject the training result', ... + 'L: show live expressions (eye, upper and lower face with power 0-1)', ... + 'U or Esc: unload the profile and exit'}; + uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.48 0.84 0.48], 'String', helpLines, ... + 'HorizontalAlignment', 'left', 'FontSize', 11, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + separatorAxes = axes('Parent', fig, 'Units', 'normalized', 'Position', [0.08 0.445 0.84 0.005], ... + 'XLim', [0 1], 'YLim', [0 1], 'Visible', 'off'); + line('Parent', separatorAxes, 'XData', [0 1], 'YData', [0.5 0.5], 'Color', [0.5 0.5 0.5], 'LineWidth', 1); + % One row per action; the upper and lower rows share their vertical center with their power bar. + rowBottoms = [0.38 0.31 0.24]; + liveText = cell(1, 3); + powerAxes = cell(1, 2); + powerBars = cell(1, 2); + powerLabels = cell(1, 2); + for row = 1:3 + liveText{row} = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 rowBottoms(row) 0.40 0.06], 'String', '', ... + 'HorizontalAlignment', 'left', 'FontSize', 14, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + end + for row = 1:2 + powerAxes{row} = axes('Parent', fig, 'Units', 'normalized', ... + 'Position', [0.52 rowBottoms(row + 1) + 0.01 0.40 0.04], ... + 'XLim', [0 1], 'YLim', [0 1], 'XTick', [], 'YTick', [], 'Box', 'on', 'Visible', 'off'); + powerBars{row} = patch('Parent', powerAxes{row}, 'Faces', [1 2 3 4], ... + 'Vertices', [0 0; 0 0; 0 1; 0 1], 'FaceColor', [0.8 0.2 0.1], ... + 'EdgeColor', 'none', 'Visible', 'off'); + powerLabels{row} = text('Parent', powerAxes{row}, 'Position', [0.5 0.5], 'String', '', ... + 'HorizontalAlignment', 'center', 'Visible', 'off'); + end + statusText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.02 0.84 0.20], ... + 'String', ['Profile ' profileName ' ready. Press N to train neutral.'], ... + 'HorizontalAlignment', 'left', 'FontSize', 10, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + + % Acquire: poll keyboard events and, once subscribed, the live facial expression stream. + while ~isExitRequested && ishandle(fig) + if isLiveStreaming && ~isBusy + updateLiveDisplay(); + else + pause(0.05); + end + drawnow(); + end +catch failure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', failure.identifier, failure.message); +end + +% Disconnect: unload the profile and close the Cortex connection on every exit path. +clear connectionCleanup; +fprintf('[facialExpressionTraining] Finished.\n'); + + function onKeyPress(~, event) + if isBusy, return; end + keyName = event.Key; + if strcmpi(keyName, 'escape') || strcmpi(keyName, 'esc') + unloadAndExit(); + return; + end + + keyCharacter = event.Character; + if isempty(keyCharacter) && numel(keyName) == 1 + keyCharacter = keyName; + end + if ~ischar(keyCharacter) || numel(keyCharacter) ~= 1 + showStatus(sprintf('Ignored key: %s.', keyName)); + return; + end + + % Process: map each key to a training action, live display or exit. + switch lower(keyCharacter) + case 'n' + trainAction('neutral'); + case 's' + trainAction('surprise'); + case 'f' + trainAction('frown'); + case 'm' + trainAction('smile'); + case 'c' + trainAction('clench'); + case 'a' + finishTraining('accept'); + case 'r' + finishTraining('reject'); + case 'l' + startLiveStream(); + case 'u' + unloadAndExit(); + otherwise + showStatus(sprintf('Ignored key: %s. Use N, S, F, M, C, A, R, L, U or Esc.', keyName)); + end + end + + function trainAction(actionName) + if ~isempty(pendingAction) + showStatus(sprintf('Press A to accept or R to reject the %s training first.', pendingAction)); + return; + end + isBusy = true; + try + showStatus(sprintf(['Training %s: hold for about %g seconds. Waiting up to %g seconds total for ' ... + 'FE_Succeeded/FE_Failed (training plus event margin).'], ... + actionName, trainingDuration, trainStartEventWaitLimit)); + started = cortexTraining(cortex, 'facialExpression', actionName, 'start', ... + 'wait', trainStartEventWaitLimit); + if ~started.isSucceeded + fprintf('[facialExpressionTraining] Training %s failed (%s).\n', actionName, started.event); + showStatus(sprintf('Training %s failed (%s). Press the key to try again.', ... + actionName, started.event)); + else + pendingAction = actionName; + fprintf('[facialExpressionTraining] Training %s succeeded (%s).\n', actionName, started.event); + showStatus(sprintf('Training %s succeeded. Press A to accept or R to reject.', actionName)); + end + catch trainFailure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', trainFailure.identifier, trainFailure.message); + showStatus(['Training failed: ' trainFailure.message]); + end + isBusy = false; + end + + function finishTraining(status) + if isempty(pendingAction) + showStatus('No training result to accept or reject. Start a training first.'); + return; + end + isBusy = true; + try + if strcmp(status, 'accept') + showStatus(sprintf(['Accepting %s. Waiting up to %g seconds for FE_Completed ' ... + '(example limit; configurable).'], pendingAction, trainAcceptEventWaitLimit)); + accepted = cortexTraining(cortex, 'facialExpression', pendingAction, 'accept', ... + 'wait', trainAcceptEventWaitLimit); + fprintf('[facialExpressionTraining] Training %s completed (%s); profile saved: %d.\n', ... + pendingAction, accepted.event, accepted.profileSaved); + if accepted.profileSaved + showStatus(sprintf('Training %s accepted and profile saved.', pendingAction)); + else + showStatus(sprintf('Training %s accepted, but saving the profile failed (see console).', pendingAction)); + end + else + cortexTraining(cortex, 'facialExpression', pendingAction, 'reject'); + fprintf('[facialExpressionTraining] Training %s rejected.\n', pendingAction); + showStatus(sprintf('Training %s rejected. Press its key to train again.', pendingAction)); + end + pendingAction = ''; + catch finishFailure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', finishFailure.identifier, finishFailure.message); + showStatus(['Could not ' status ' the training: ' finishFailure.message]); + end + isBusy = false; + end + + function startLiveStream() + if isLiveStreaming + showStatus('Live expressions are already shown.'); + return; + end + isBusy = true; + try + cortex = cortexSubscribe(cortex, {'fac'}); + if ~any(strcmp(cortex.streams, 'fac')) + error('facialExpressionTraining:subscribe', 'Could not subscribe to the fac stream.'); + end + isLiveStreaming = true; + for row = 1:2 + set(powerAxes{row}, 'Visible', 'on'); + set(powerBars{row}, 'Visible', 'on'); + set(powerLabels{row}, 'Visible', 'on'); + end + showStatus('Showing live facial expressions. Train more actions with N, S, F, M or C.'); + catch subscribeFailure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', subscribeFailure.identifier, subscribeFailure.message); + showStatus(['Subscribe failed: ' subscribeFailure.message]); + end + isBusy = false; + end + + function updateLiveDisplay() + [labels, data, ~, actions] = cortexGetData(cortex, 'fac', 1); + if isempty(data) || isempty(actions) || ~iscell(actions{end}), return; end + upperColumn = find(strcmp(labels, 'uPow'), 1); + lowerColumn = find(strcmp(labels, 'lPow'), 1); + if isempty(upperColumn) || isempty(lowerColumn), return; end + + % actions{end} is {eyeAct, uAct, lAct}. + names = actions{end}; + if numel(names) < 3, return; end + powers = [data(end, upperColumn), data(end, lowerColumn)]; + sample = sprintf('%s|%s|%s|%.2f|%.2f', names{1}, names{2}, names{3}, powers(1), powers(2)); + if strcmp(sample, lastSample), return; end + lastSample = sample; + + powers(isnan(powers)) = 0; + levels = max(0, min(1, powers)); + if all(cellfun(@ishandle, liveText)) + set(liveText{1}, 'String', ['Eye: ' names{1}]); + set(liveText{2}, 'String', ['Upper: ' names{2}]); + set(liveText{3}, 'String', ['Lower: ' names{3}]); + end + for row = 1:2 + % Red (weak) through yellow to green (strong). + barColor = [min(1, 2 * (1 - levels(row))), min(1, 2 * levels(row)), 0.1]; + if ishandle(powerBars{row}) + set(powerBars{row}, 'Vertices', [0 0; levels(row) 0; levels(row) 1; 0 1], ... + 'FaceColor', barColor); + end + if ishandle(powerLabels{row}) + set(powerLabels{row}, 'String', sprintf('%.2f', powers(row))); + end + end + end + + function unloadAndExit() + isBusy = true; + showStatus('Unloading the profile, please wait...'); + try + [cortex, unloadResult] = cortexProfile(cortex, 'unload'); + fprintf('[facialExpressionTraining] Profile %s unloaded.\n', unloadResult.name); + isExitRequested = true; + catch unloadFailure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', unloadFailure.identifier, unloadFailure.message); + showStatus(['Could not unload the profile: ' unloadFailure.message ' Press U to try again.']); + isBusy = false; + end + end + + function showStatus(message) + if ~isempty(statusText) && ishandle(statusText) + set(statusText, 'String', message); + drawnow(); + end + end + + function cleanupConnection() + if ~isempty(fig) && ishandle(fig) + delete(fig); + end + cortex = cortexDisconnect(cortex); + end +end diff --git a/octave/examples/mentalCommandTraining.m b/octave/examples/mentalCommandTraining.m new file mode 100644 index 0000000..72fca99 --- /dev/null +++ b/octave/examples/mentalCommandTraining.m @@ -0,0 +1,314 @@ +function mentalCommandTraining() +% mentalCommandTraining Train mental command actions from the keyboard and watch live commands. +% Set headsetId and profileName below, then call mentalCommandTraining(). +% Keys (focus the figure): N neutral, P push, L left, D drop start a training; +% A accept or R reject the training result; S show live commands; +% U (or Esc) unload the profile and exit. Train neutral first, then at least one action. +% +% The com stream sends one sample per update with two values: +% act the detected action name (for example 'neutral' or 'push') +% pow the action power from 0 to 1 +% It is a label plus a strength rather than a waveform, so it is shown as text instead of a plot. +% To train other actions, add a key that calls trainAction with another action name +% (see getDetectionInfo in the Cortex API for the supported list). + +% Set your headset id and the name of the training profile to create or load. +headsetId = ''; +profileName = 'my-mental-command'; + +trainStartTimeout = 10; +trainAcceptTimeout = 15; + +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% Connect: authorize, connect the headset, create its session and load (or create) the profile. +cortex = cortexConnect(); +fig = []; +statusText = []; +commandText = []; +powerAxes = []; +powerBar = []; +powerLabel = []; +isBusy = false; +isExitRequested = false; +isCommandStreaming = false; +pendingAction = ''; +lastAction = ''; +lastPower = NaN; +connectionCleanup = onCleanup(@cleanupConnection); +try + if ~cortex.isConnected + error('mentalCommandTraining:connect', 'Cortex connection or authorization failed.'); + end + cortex = cortexSession(cortex, headsetId); + [cortex, profileResult] = cortexProfile(cortex, 'load', profileName); + if profileResult.created + fprintf('[mentalCommandTraining] Created and loaded profile %s.\n', profileName); + else + fprintf('[mentalCommandTraining] Loaded existing profile %s.\n', profileName); + end + + mentalCommandInfo = cortexMentalCommandInfo(cortex, 'get'); + fprintf('[mentalCommandTraining] Mental command info:\n%s\n', ... + jsonencode(mentalCommandInfo, 'PrettyPrint', true)); + + % The sys stream reports the training events (started, succeeded, completed). + cortex = cortexSubscribe(cortex, {'sys'}); + if ~cortex.isSubscribed + error('mentalCommandTraining:subscribe', 'Could not subscribe to the sys stream.'); + end + + fprintf('[mentalCommandTraining] Key help:\n'); + fprintf(' N / P / L / D: start training neutral / push / left / drop.\n'); + fprintf(' A / R: accept / reject the training result.\n'); + fprintf(' S: show live mental commands (act and pow).\n'); + fprintf(' C: set sensitivity push 7, left 8, drop 2.\n'); + fprintf(' U or Esc: unload the profile and exit.\n'); + + fig = figure('Name', 'Cortex Mental Command Training', 'NumberTitle', 'off', ... + 'KeyPressFcn', @onKeyPress); + helpLines = {'Keyboard controls', '', ... + 'N: train neutral (do this first)', ... + 'P: train push', ... + 'L: train left', ... + 'D: train drop', ... + 'A: accept the training result (saves the profile)', ... + 'R: reject the training result', ... + 'S: show live mental commands (act = action, pow = power 0-1)', ... + 'C: set sensitivity (push 7, left 8, drop 2)', ... + 'U or Esc: unload the profile and exit'}; + uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.44 0.84 0.52], 'String', helpLines, ... + 'HorizontalAlignment', 'left', 'FontSize', 11, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + commandText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.28 0.40 0.12], 'String', '', ... + 'HorizontalAlignment', 'left', 'FontSize', 20, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + powerAxes = axes('Parent', fig, 'Units', 'normalized', 'Position', [0.52 0.29 0.40 0.08], ... + 'XLim', [0 1], 'YLim', [0 1], 'XTick', [], 'YTick', [], 'Box', 'on', 'Visible', 'off'); + powerBar = patch('Parent', powerAxes, 'Faces', [1 2 3 4], ... + 'Vertices', [0 0; 0 0; 0 1; 0 1], 'FaceColor', [0.8 0.2 0.1], 'EdgeColor', 'none', ... + 'Visible', 'off'); + powerLabel = text('Parent', powerAxes, 'Position', [0.5 0.5], 'String', '', ... + 'HorizontalAlignment', 'center', 'Visible', 'off'); + statusText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.02 0.84 0.20], ... + 'String', ['Profile ' profileName ' ready. Press N to train neutral.'], ... + 'HorizontalAlignment', 'left', 'FontSize', 10, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + + % Acquire: poll keyboard events and, once subscribed, the live mental command stream. + while ~isExitRequested && ishandle(fig) + if isCommandStreaming && ~isBusy + updateCommandDisplay(); + else + pause(0.05); + end + drawnow(); + end +catch failure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', failure.identifier, failure.message); +end + +% Disconnect: unload the profile and close the Cortex connection on every exit path. +clear connectionCleanup; +fprintf('[mentalCommandTraining] Finished.\n'); + + function onKeyPress(~, event) + if isBusy, return; end + keyName = event.Key; + if strcmpi(keyName, 'escape') || strcmpi(keyName, 'esc') + unloadAndExit(); + return; + end + + keyCharacter = event.Character; + if isempty(keyCharacter) && numel(keyName) == 1 + keyCharacter = keyName; + end + if ~ischar(keyCharacter) || numel(keyCharacter) ~= 1 + showStatus(sprintf('Ignored key: %s.', keyName)); + return; + end + + % Process: map each key to a training action, live display or exit. + switch lower(keyCharacter) + case 'n' + trainAction('neutral'); + case 'p' + trainAction('push'); + case 'l' + trainAction('left'); + case 'd' + trainAction('drop'); + case 'a' + finishTraining('accept'); + case 'r' + finishTraining('reject'); + case 's' + startCommandStream(); + case 'c' + configureSensitivity(); + case 'u' + unloadAndExit(); + otherwise + showStatus(sprintf('Ignored key: %s. Use N, P, L, D, A, R, S, C, U or Esc.', keyName)); + end + end + + function trainAction(actionName) + if ~isempty(pendingAction) + showStatus(sprintf('Press A to accept or R to reject the %s training first.', pendingAction)); + return; + end + isBusy = true; + try + showStatus(sprintf('Training %s: hold the mental state until it finishes...', actionName)); + started = cortexTraining(cortex, 'mentalCommand', actionName, 'start', ... + 'wait', trainStartTimeout); + if ~started.isSucceeded + fprintf('[mentalCommandTraining] Training %s failed (%s).\n', actionName, started.event); + showStatus(sprintf('Training %s failed (%s). Press the key to try again.', ... + actionName, started.event)); + else + pendingAction = actionName; + fprintf('[mentalCommandTraining] Training %s succeeded (%s).\n', actionName, started.event); + showStatus(sprintf('Training %s succeeded. Press A to accept or R to reject.', actionName)); + end + catch trainFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', trainFailure.identifier, trainFailure.message); + showStatus(['Training failed: ' trainFailure.message]); + end + isBusy = false; + end + + function finishTraining(status) + if isempty(pendingAction) + showStatus('No training result to accept or reject. Start a training first.'); + return; + end + isBusy = true; + try + if strcmp(status, 'accept') + accepted = cortexTraining(cortex, 'mentalCommand', pendingAction, 'accept', ... + 'wait', trainAcceptTimeout); + fprintf('[mentalCommandTraining] Training %s completed (%s); profile saved: %d.\n', ... + pendingAction, accepted.event, accepted.profileSaved); + if accepted.profileSaved + showStatus(sprintf('Training %s accepted and profile saved.', pendingAction)); + else + showStatus(sprintf('Training %s accepted, but saving the profile failed (see console).', pendingAction)); + end + else + cortexTraining(cortex, 'mentalCommand', pendingAction, 'reject'); + fprintf('[mentalCommandTraining] Training %s rejected.\n', pendingAction); + showStatus(sprintf('Training %s rejected. Press its key to train again.', pendingAction)); + end + pendingAction = ''; + catch finishFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', finishFailure.identifier, finishFailure.message); + showStatus(['Could not ' status ' the training: ' finishFailure.message]); + end + isBusy = false; + end + + function configureSensitivity() + isBusy = true; + try + showStatus('Configuring sensitivity...'); + % Sensitivities follow the order of the active actions, so activate them in this order. + settings = struct('activeActions', {{'neutral', 'push', 'left', 'drop'}}, ... + 'actionSensitivities', [7 8 2]); + configured = cortexMentalCommandInfo(cortex, 'configure', settings); + fprintf('[mentalCommandTraining] Mental command info:\n%s\n', ... + jsonencode(configured, 'PrettyPrint', true)); + showStatus('Sensitivity set: push 7, left 8, drop 2. Profile saved.'); + catch configureFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', configureFailure.identifier, configureFailure.message); + showStatus(['Could not configure sensitivity: ' configureFailure.message]); + end + isBusy = false; + end + + function startCommandStream() + if isCommandStreaming + showStatus('Live commands are already shown.'); + return; + end + isBusy = true; + try + cortex = cortexSubscribe(cortex, {'com'}); + if ~any(strcmp(cortex.streams, 'com')) + error('mentalCommandTraining:subscribe', 'Could not subscribe to the com stream.'); + end + isCommandStreaming = true; + set([powerAxes powerBar powerLabel], 'Visible', 'on'); + showStatus('Showing live mental commands. Train more actions with N, P, L or D.'); + catch subscribeFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', subscribeFailure.identifier, subscribeFailure.message); + showStatus(['Subscribe failed: ' subscribeFailure.message]); + end + isBusy = false; + end + + function updateCommandDisplay() + [labels, data, ~, actions] = cortexGetData(cortex, 'com', 1); + if isempty(data) || isempty(actions), return; end + powerColumn = find(strcmp(labels, 'pow'), 1); + if isempty(powerColumn), return; end + + action = actions{end}; + power = data(end, powerColumn); + isSamePower = (isnan(power) && isnan(lastPower)) || power == lastPower; + if strcmp(action, lastAction) && isSamePower, return; end + if ~strcmp(action, lastAction) + fprintf('[mentalCommandTraining] Action: %s (pow %.2f)\n', action, power); + end + lastAction = action; + lastPower = power; + + if isnan(power), power = 0; end + level = max(0, min(1, power)); + % Red (weak) through yellow to green (strong). + barColor = [min(1, 2 * (1 - level)), min(1, 2 * level), 0.1]; + if ishandle(commandText) + set(commandText, 'String', action); + end + if ishandle(powerBar) + set(powerBar, 'Vertices', [0 0; level 0; level 1; 0 1], 'FaceColor', barColor); + end + if ishandle(powerLabel) + set(powerLabel, 'String', sprintf('%.2f', power)); + end + end + + function unloadAndExit() + isBusy = true; + showStatus('Unloading the profile, please wait...'); + try + [cortex, unloadResult] = cortexProfile(cortex, 'unload'); + fprintf('[mentalCommandTraining] Profile %s unloaded.\n', unloadResult.name); + isExitRequested = true; + catch unloadFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', unloadFailure.identifier, unloadFailure.message); + showStatus(['Could not unload the profile: ' unloadFailure.message ' Press U to try again.']); + isBusy = false; + end + end + + function showStatus(message) + if ~isempty(statusText) && ishandle(statusText) + set(statusText, 'String', message); + drawnow(); + end + end + + function cleanupConnection() + if ~isempty(fig) && ishandle(fig) + delete(fig); + end + cortex = cortexDisconnect(cortex); + end +end diff --git a/octave/examples/recordAndMarker.m b/octave/examples/recordAndMarker.m new file mode 100644 index 0000000..40d1a8a --- /dev/null +++ b/octave/examples/recordAndMarker.m @@ -0,0 +1,167 @@ +function recordAndMarker() +% recordAndMarker Start/stop a record and inject/update markers from keyboard input. +% Set headsetId and recordTitlePrefix below, then call recordAndMarker(). +% Press S to start, any other letter to toggle a marker interval, and Esc to stop and exit. + +% Set your headset id and the prefix used to generate each record title. +headsetId = ''; +recordTitlePrefix = 'my-record'; + +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% Connect: establish authorization, connect the selected headset, and create its active session. +cortex = cortexConnect(); +fig = []; +connectionCleanup = onCleanup(@cleanupConnection); +try + if ~cortex.isConnected + error('recordAndMarker:connect', 'Cortex connection or authorization failed.'); + end + cortex = cortexSession(cortex, headsetId); + 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'); + fprintf(' Esc: stop the record and exit.\n'); + + markerIds = struct(); + fig = figure('Name', 'Cortex Record and Marker Example', 'NumberTitle', 'off', ... + 'KeyPressFcn', @onKeyPress, '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', '', ... + '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', ... + 'Position', [0.08 0.12 0.84 0.78], ... + 'String', helpLines, ... + 'HorizontalAlignment', 'left', 'FontSize', 12, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', ... + 'KeyPressFcn', @onKeyPress, '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'); + + % Acquire: wait for keyboard events while Cortex keeps the active session open. + uiwait(fig); +catch failure + fprintf('[recordAndMarker] ERROR %s: %s\n', failure.identifier, failure.message); +end + +% Disconnect: stop any active record and close the Cortex connection on every exit path. +clear connectionCleanup; +fprintf('[recordAndMarker] Finished.\n'); + + function onKeyPress(source, event) + keyName = event.Key; + showStatus(sprintf('Key %s received.', keyName)); + if strcmpi(keyName, 'escape') || strcmpi(keyName, 'esc') + if cortex.isRecording + try + [cortex, ~] = cortexRecord(cortex, 'stop'); + fprintf('[recordAndMarker] Record stopped.\n'); + showStatus('Record stopped. Closing example.'); + catch stopFailure + fprintf('[recordAndMarker] ERROR %s: %s\n', stopFailure.identifier, stopFailure.message); + showStatus(['Could not stop record: ' stopFailure.message]); + end + end + if ishandle(fig), uiresume(fig); end + return; + end + + keyCharacter = event.Character; + if isempty(keyCharacter) && numel(keyName) == 1 + keyCharacter = keyName; + end + if ~ischar(keyCharacter) || numel(keyCharacter) ~= 1 || ... + isempty(regexp(keyCharacter, '^[A-Za-z]$', 'once')) + showStatus(sprintf('Ignored key: %s. Use S, A-Z, or Esc.', keyName)); + return; + end + + % Process: reserve S for record start and use every other letter to toggle marker intervals. + if lower(keyCharacter) == 's' + if cortex.isRecording + fprintf('[recordAndMarker] A record is already active.\n'); + showStatus('A record is already active.'); + return; + end + try + recordTitle = sprintf('%s_%d', recordTitlePrefix, floor(currentTimeMilliseconds() / 1000)); + description = 'Keyboard-controlled Cortex record and marker example'; + tags = {'octave', 'record-marker-demo'}; + [cortex, result] = cortexRecord(cortex, 'start', recordTitle, description, tags); + fprintf('[recordAndMarker] Started record %s.\n', result.record.uuid); + showStatus(['Recording started: ' result.record.uuid]); + catch startFailure + fprintf('[recordAndMarker] ERROR %s: %s\n', startFailure.identifier, startFailure.message); + showStatus(['Record start failed: ' startFailure.message]); + end + return; + end + + if ~cortex.isRecording + fprintf('[recordAndMarker] Start a record with S before adding markers.\n'); + showStatus('No active record. Press S to start one first.'); + return; + end + + markerKey = lower(keyCharacter); + try + if isfield(markerIds, markerKey) + markerId = markerIds.(markerKey); + [cortex, result] = cortexMarker(cortex, 'update', markerId, currentTimeMilliseconds()); + markerIds = rmfield(markerIds, markerKey); + fprintf('[recordAndMarker] Updated marker %s (type: %s).\n', ... + result.marker.uuid, result.marker.type); + fprintf(' Start: %s\n End: %s\n', ... + result.marker.startDatetime, result.marker.endDatetime); + showStatus(['Marker interval updated: ' result.marker.uuid]); + else + [cortex, result] = cortexMarker(cortex, 'inject', keyCharacter, keyCharacter, ... + 'time', currentTimeMilliseconds(), 'port', 'MATLAB/Octave example'); + markerIds.(markerKey) = result.marker.uuid; + fprintf('[recordAndMarker] Injected marker %s (type: %s, port: %s) with value %s.\n', ... + result.marker.uuid, result.marker.type, result.marker.port, keyCharacter); + fprintf(' Start: %s\n End: %s\n', ... + result.marker.startDatetime, result.marker.endDatetime); + showStatus(['Marker injected: ' result.marker.uuid ... + ' (value: ' result.marker.value ')']); + end + catch markerFailure + fprintf('[recordAndMarker] ERROR %s: %s\n', markerFailure.identifier, markerFailure.message); + showStatus(['Marker action failed: ' markerFailure.message]); + end + end + + function showStatus(message) + if ~isempty(statusText) && ishandle(statusText) + set(statusText, 'String', message); + drawnow(); + end + end + + function cleanupConnection() + if cortex.isRecording + try + [cortex, ~] = cortexRecord(cortex, 'stop'); + catch stopFailure + fprintf('[recordAndMarker] Could not stop the active record: %s\n', stopFailure.message); + end + end + if ~isempty(fig) && ishandle(fig) + delete(fig); + end + cortex = cortexDisconnect(cortex); + end +end + +function time = currentTimeMilliseconds() +time = double(javaMethod('currentTimeMillis', 'java.lang.System')); +end diff --git a/octave/examples/subscribeAndPlot.m b/octave/examples/subscribeAndPlot.m new file mode 100644 index 0000000..5f18856 --- /dev/null +++ b/octave/examples/subscribeAndPlot.m @@ -0,0 +1,171 @@ +function subscribeAndPlot() +% subscribeAndPlot Subscribe to EEG, motion (mot), and performance metrics (met) streams and plot live. + +% 1. Initialization & Configuration: make the SDK functions visible. +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% Set your headset id (shown in EMOTIV Launcher, for example 'INSIGHT-A1B2C3D4'). +headsetId = ''; +streams = {'eeg'}; +durationSeconds = 90; + +% 2. Connection / Authentication, then create a headset session and subscribe to streams. +% Credentials are loaded from config/config.json. +cortex = cortexConnect(); +connectionCleanup = onCleanup(@() cortexDisconnect(cortex)); +if cortex.isConnected + cortex = cortexSession(cortex, headsetId); + cortex = cortexSubscribe(cortex, streams); +end + +% 3. Acquisition Loop: each cortexGetData call collects new samples into the buffer. +try + if cortex.isSubscribed + figs = struct(); + if ismember('eeg', cortex.streams) + figs.eeg = figure('Name', 'Live EEG', 'NumberTitle', 'off'); + end + if ismember('mot', cortex.streams) + figs.mot = figure('Name', 'Live Motion (IMU)', 'NumberTitle', 'off'); + end + if ismember('met', cortex.streams) + figs.met = figure('Name', 'Live Performance Metrics', 'NumberTitle', 'off'); + end + + startedAt = tic(); + while toc(startedAt) < durationSeconds && hasOpenFigure(figs) + if isfield(figs, 'eeg') && ishandle(figs.eeg) + [labels, data, time] = cortexGetData(cortex, 'eeg', 256); + if ~isempty(data) + plotEeg(figs.eeg, labels, data, time); + end + end + + if isfield(figs, 'mot') && ishandle(figs.mot) + [labels, data, time] = cortexGetData(cortex, 'mot', 160); + if ~isempty(data) + plotMotion(figs.mot, labels, data, time); + end + end + + if isfield(figs, 'met') && ishandle(figs.met) + [labels, data, time] = cortexGetData(cortex, 'met', 60); + if ~isempty(data) + plotPm(figs.met, labels, data, time); + end + end + + drawnow; + end + + for index = 1:numel(cortex.streams) + streamName = cortex.streams{index}; + [~, data] = cortexGetData(cortex, streamName); + fprintf('[subscribeAndPlot] %s: %d samples buffered.\n', streamName, size(data, 1)); + end + end +catch failure + fprintf('[subscribeAndPlot] ERROR %s: %s\n', failure.identifier, failure.message); +end + +% 4. Safe Teardown: unsubscribes and releases the socket, even after an error. +clear connectionCleanup; +fprintf('[subscribeAndPlot] Done.\n'); +end + +function open = hasOpenFigure(figs) +fields = fieldnames(figs); +open = false; +for i = 1:numel(fields) + if ishandle(figs.(fields{i})) + open = true; + return; + end +end +end + +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), return; end + +eeg = data(:, channels); +eeg = eeg - mean(eeg, 1, 'omitnan'); +eeg = max(min(eeg, 100), -100); + +numChannels = numel(channels); +offsets = (numChannels - 1:-1:0) * 200; +t = time - time(end); + +plot(t, bsxfun(@plus, eeg, offsets)); +ylim([-100, (numChannels - 1) * 200 + 100]); +set(gca, 'YTick', fliplr(offsets), 'YTickLabel', fliplr(labels(channels))); +title('EEG (+/-100 uV per trace, 200 uV spacing)'); +xlabel('Seconds'); +ylabel('Channel'); +end + +function plotMotion(fig, labels, data, time) +% plotMotion Plot 9-axis IMU motion stream: +% - Quaternions (Q0..Q3): [-1, 1] (or Gyroscope GYROX..GYROZ: [-100, 100] dps) +% - Accelerometer (ACCX..ACCZ): [-4, 4] g +% - Magnetometer (MAGX..MAGZ): [-4900, 4900] uT +figure(fig); +t = time - time(end); + +quatCols = find(ismember(labels, {'Q0', 'Q1', 'Q2', 'Q3'})); +gyroCols = find(ismember(labels, {'GYROX', 'GYROY', 'GYROZ'})); +accCols = find(ismember(labels, {'ACCX', 'ACCY', 'ACCZ'})); +magCols = find(ismember(labels, {'MAGX', 'MAGY', 'MAGZ'})); + +subplot(3, 1, 1); +if ~isempty(quatCols) + plot(t, data(:, quatCols)); + ylim([-1, 1]); + legend(labels(quatCols), 'Location', 'eastoutside'); + title('Quaternions ([-1, 1])'); + ylabel('Quaternion'); +elseif ~isempty(gyroCols) + plot(t, data(:, gyroCols)); + ylim([-100, 100]); + legend(labels(gyroCols), 'Location', 'eastoutside'); + title('Gyroscope ([-100, 100] dps)'); + ylabel('dps'); +end + +subplot(3, 1, 2); +if ~isempty(accCols) + plot(t, data(:, accCols)); + ylim([-4, 4]); + legend(labels(accCols), 'Location', 'eastoutside'); + title('Accelerometer ([-4, 4] g)'); + ylabel('g'); +end + +subplot(3, 1, 3); +if ~isempty(magCols) + plot(t, data(:, magCols)); + ylim([-4900, 4900]); + legend(labels(magCols), 'Location', 'eastoutside'); + title('Magnetometer ([-4900, 4900] uT)'); + ylabel('uT'); + xlabel('Seconds'); +end +end + +function plotPm(fig, labels, data, time) +% plotPm Plot normalized Performance Metrics (met) in the [0, 1] range. +figure(fig); +metricCols = find(cellfun(@isempty, regexp(labels, '\.isActive$'))); +if isempty(metricCols), return; end + +t = time - time(end); +plot(t, data(:, metricCols), '-o'); +ylim([0, 1]); +legend(labels(metricCols), 'Location', 'eastoutside'); +title('Performance Metrics ([0, 1])'); +xlabel('Seconds'); +ylabel('Normalized Score'); +end diff --git a/octave/functions/cortexConnect.m b/octave/functions/cortexConnect.m new file mode 100644 index 0000000..7639687 --- /dev/null +++ b/octave/functions/cortexConnect.m @@ -0,0 +1,51 @@ +function cortex = cortexConnect() +% cortexConnect Connect to Cortex over WSS and authorize this app. +% cortex = cortexConnect() loads clientId, clientSecret and the optional port (default 6868) +% from config/config.json +% and returns a struct with the fields: +% isConnected true when the Cortex link is open and the app is authorized +% token cortexToken to use in later Cortex requests ('' on failure) +% userInfo user details returned by Cortex ([] on failure) +% licenseInfo license details returned by Cortex ([] on failure) +% manager internal handle used by cortexDisconnect; do not modify +% isSubscribed, headsetId, sessionId, streams filled in by headset connection/subscription +% isRecording, recordId filled in by cortexRecord +% isProfileLoaded, profileName filled in by cortexProfile + +functionsDir = fileparts(mfilename('fullpath')); +addpath(fullfile(functionsDir, '..', 'internal')); + +[clientId, clientSecret, port] = cortexCredentials(); + +cortex = struct('isConnected', false, 'token', '', 'userInfo', [], 'licenseInfo', [], 'manager', [], ... + 'isSubscribed', false, 'isRecording', false, 'recordId', '', ... + 'isProfileLoaded', false, 'profileName', '', ... + 'headsetId', '', 'sessionId', '', 'streams', {{}}); +manager = CortexManager(clientId, clientSecret, 'localhost', port); +cortex.manager = manager; + +try + fprintf('[cortexConnect] Connecting to Cortex at wss://%s:%d...\n', manager.host, manager.port); + try + auth = manager.getAuth(); + catch connectFailure + fprintf(['Could not connect to Cortex at wss://%s:%d. ' ... + 'Make sure EMOTIV Launcher is running.\n'], manager.host, manager.port); + rethrow(connectFailure); + end + + fprintf('[cortexConnect] Checking user login and access right...\n'); + auth.init(); + auth.getUserInformation(); + auth.getLicenseInfo(); + + context = manager.getContext(); + cortex.token = context.token; + cortex.userInfo = context.userInfo; + cortex.licenseInfo = context.licenseInfo; + cortex.isConnected = true; + fprintf('[cortexConnect] Connected and authorized.\n'); +catch failure + fprintf('[cortexConnect] ERROR %s: %s\n', failure.identifier, failure.message); +end +end diff --git a/octave/functions/cortexDisconnect.m b/octave/functions/cortexDisconnect.m new file mode 100644 index 0000000..0e2521d --- /dev/null +++ b/octave/functions/cortexDisconnect.m @@ -0,0 +1,34 @@ +function cortex = cortexDisconnect(cortex) +% cortexDisconnect Close the Cortex connection opened by cortexConnect. +% cortex = cortexDisconnect(cortex) is safe to call even if cortexConnect failed. + +if isstruct(cortex) && isfield(cortex, 'manager') && ~isempty(cortex.manager) + try + if cortex.manager.getContext().isProfileLoaded + cortex.manager.getProfile().unload(); + end + catch failure + fprintf('[cortexDisconnect] Could not unload the profile: %s\n', failure.message); + end + fprintf('[cortexDisconnect] Closing Cortex connection...\n'); + try + cortex.manager.close(); + catch failure + fprintf('[cortexDisconnect] Could not close the Cortex connection cleanly: %s\n', failure.message); + end + cortex.manager = []; +end + +cortex.isConnected = false; +cortex.isSubscribed = false; +cortex.isRecording = false; +cortex.recordId = ''; +cortex.isProfileLoaded = false; +cortex.profileName = ''; +cortex.headsetId = ''; +cortex.sessionId = ''; +cortex.streams = {}; +cortex.token = ''; +cortex.userInfo = []; +cortex.licenseInfo = []; +end diff --git a/octave/functions/cortexFacialExpressionInfo.m b/octave/functions/cortexFacialExpressionInfo.m new file mode 100644 index 0000000..ff20379 --- /dev/null +++ b/octave/functions/cortexFacialExpressionInfo.m @@ -0,0 +1,21 @@ +function config = cortexFacialExpressionInfo(cortex) +% cortexFacialExpressionInfo Get the facial expression settings of the loaded profile. +% config = cortexFacialExpressionInfo(cortex) +% config fields: +% possibleActions cell array of every action Cortex supports for facial expression +% trainedActions cell array of structs with action, threshold (0 to 1000, [] for neutral) +% and trainingCount +% trainingDuration seconds a training lasts +% Requires cortexSession and cortexProfile(cortex, 'load', ...). + +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:facialExpressionFailed', 'Connect to Cortex before using facial expression operations.'); + end + config = cortex.manager.getFacialExpressionConfiguration().get(); +catch failure + if strcmp(failure.identifier, 'cortex:facialExpressionFailed'), rethrow(failure); end + error('cortex:facialExpressionFailed', 'Facial expression operation failed: %s', failure.message); +end +end diff --git a/octave/functions/cortexGetData.m b/octave/functions/cortexGetData.m new file mode 100644 index 0000000..f12f88b --- /dev/null +++ b/octave/functions/cortexGetData.m @@ -0,0 +1,33 @@ +function [labels, data, time, bciActions] = cortexGetData(cortex, stream, lastN) +% cortexGetData Read buffered samples of one subscribed stream (eeg, mot, dev, eq, pow, met, com or fac). +% [labels, data, time, bciActions] = cortexGetData(cortex, 'eeg', 256) first collects the data that has +% arrived (this can take up to about 1 second), then returns the newest 256 samples: +% labels cell array with one name per column of data +% data samples-by-columns matrix, oldest sample first (NaN where a value is empty) +% time sample times in seconds +% bciActions cell array with one action per sample for com and fac, '' for other streams +% For com, labels are {'act','pow'}: the act column of data is NaN and bciActions holds the action, +% while pow (0 to 1) is the action power. +% For fac, labels are {'eyeAct','uAct','uPow','lAct','lPow'}: the act columns of data are NaN and +% each element of bciActions is {eyeAct, uAct, lAct}; uPow and lPow (0 to 1) are the powers. +% Omit lastN to get everything in the buffer (the last 10000 samples per stream). + +if nargin < 3, lastN = []; end +labels = {}; +data = []; +time = []; +bciActions = {}; + +if ~isstruct(cortex) || ~isfield(cortex, 'isSubscribed') || ~cortex.isSubscribed + fprintf('[cortexGetData] No active subscription. Call cortexSubscribe first.\n'); + return; +end + +headset = cortex.manager.getHeadset(); +headset.update(); +if ~headset.isSubscribed + fprintf('[cortexGetData] No active subscription. Call cortexSubscribe first.\n'); + return; +end +[labels, data, time, bciActions] = cortex.manager.getContext().buffer.read(stream, lastN); +end diff --git a/octave/functions/cortexMarker.m b/octave/functions/cortexMarker.m new file mode 100644 index 0000000..5a78550 --- /dev/null +++ b/octave/functions/cortexMarker.m @@ -0,0 +1,58 @@ +function [cortex, result] = cortexMarker(cortex, action, varargin) +% cortexMarker Inject an instance marker or update it to an interval marker. +% [cortex, result] = cortexMarker(cortex, 'inject', label, value, ...) +% Optional inject name/value pairs: time (epoch milliseconds), port, extras. +% [cortex, result] = cortexMarker(cortex, 'update', markerId, endTime, ...) +% Optional update name/value pair: extras. Markers require an active record. + +result = []; +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'isRecording') || ~cortex.isRecording || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:markerFailed', 'Start a record before using marker operations.'); + end + if ~ischar(action) + error('cortex:markerFailed', 'action must be ''inject'' or ''update''.'); + end + + marker = cortex.manager.getMarker(); + switch lower(action) + case 'inject' + if numel(varargin) < 2 + error('cortex:markerFailed', 'Inject requires a label and value.'); + end + label = varargin{1}; + value = varargin{2}; + options = parseOptions(varargin(3:end), struct('time', [], 'port', 'Software', 'extras', struct())); + result = marker.inject(label, value, options.time, options.port, options.extras); + case 'update' + if numel(varargin) < 2 + error('cortex:markerFailed', 'Update requires a markerId and endTime.'); + end + markerId = varargin{1}; + endTime = varargin{2}; + options = parseOptions(varargin(3:end), struct('extras', struct())); + result = marker.update(markerId, endTime, options.extras); + otherwise + error('cortex:markerFailed', 'action must be ''inject'' or ''update''.'); + end +catch failure + if strcmp(failure.identifier, 'cortex:markerFailed'), rethrow(failure); end + error('cortex:markerFailed', 'Marker operation failed: %s', failure.message); +end +end + +function options = parseOptions(arguments, options) +if mod(numel(arguments), 2) ~= 0 + error('cortex:markerFailed', 'Marker options must be supplied as name/value pairs.'); +end +for index = 1:2:numel(arguments) + name = arguments{index}; + if ~ischar(name) || ~isfield(options, name) + error('cortex:markerFailed', 'Unknown marker option.'); + end + options.(name) = arguments{index + 1}; +end +end + diff --git a/octave/functions/cortexMentalCommandInfo.m b/octave/functions/cortexMentalCommandInfo.m new file mode 100644 index 0000000..3e1e023 --- /dev/null +++ b/octave/functions/cortexMentalCommandInfo.m @@ -0,0 +1,50 @@ +function config = cortexMentalCommandInfo(cortex, action, settings) +% cortexMentalCommandInfo Get or configure the mental command settings of the loaded profile. +% config = cortexMentalCommandInfo(cortex, 'get') +% config = cortexMentalCommandInfo(cortex, 'configure', settings) +% settings is a struct with any of these fields: +% activeActions cell array of actions to activate (at most 4 besides neutral) +% actionSensitivities up to 4 values from 1 to 10, in the order of the active actions +% config fields: currentTrainingThreshold, possibleActions, totalTrainingCount, +% trainingDuration and trainedActions (cell array of structs with action, active, +% sensitivity ([] when not applicable) and trainingCount). 'configure' saves the profile, +% then returns the configuration read back after the change. +% Requires cortexSession and cortexProfile(cortex, 'load', ...). + +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:mentalCommandFailed', 'Connect to Cortex before using mental command operations.'); + end + if ~ischar(action) + error('cortex:mentalCommandFailed', 'action must be ''get'' or ''configure''.'); + end + + mentalCommand = cortex.manager.getMentalCommandConfiguration(); + switch lower(action) + case 'get' + config = mentalCommand.get(); + case 'configure' + if nargin < 3 || ~isstruct(settings) + error('cortex:mentalCommandFailed', 'Configure requires a settings struct.'); + end + unknown = setdiff(fieldnames(settings), {'activeActions', 'actionSensitivities'}); + if ~isempty(unknown) + error('cortex:mentalCommandFailed', ... + 'Unknown setting "%s". Supported: activeActions, actionSensitivities.', unknown{1}); + end + activeActions = []; + sensitivities = []; + if isfield(settings, 'activeActions'), activeActions = settings.activeActions; end + if isfield(settings, 'actionSensitivities'), sensitivities = settings.actionSensitivities; end + mentalCommand.set(activeActions, sensitivities); + cortex.manager.getProfile().save(); + config = mentalCommand.get(); + otherwise + error('cortex:mentalCommandFailed', 'action must be ''get'' or ''configure''.'); + end +catch failure + if strcmp(failure.identifier, 'cortex:mentalCommandFailed'), rethrow(failure); end + error('cortex:mentalCommandFailed', 'Mental command operation failed: %s', failure.message); +end +end diff --git a/octave/functions/cortexProfile.m b/octave/functions/cortexProfile.m new file mode 100644 index 0000000..25d0273 --- /dev/null +++ b/octave/functions/cortexProfile.m @@ -0,0 +1,42 @@ +function [cortex, result] = cortexProfile(cortex, action, profileName) +% cortexProfile Load, save or unload a training profile for the active headset. +% [cortex, result] = cortexProfile(cortex, 'load', profileName) loads the profile and +% creates it first when it does not exist yet. +% [cortex, result] = cortexProfile(cortex, 'save') saves the loaded profile. +% [cortex, result] = cortexProfile(cortex, 'unload') unloads the loaded profile. +% result fields: name, uuid ('' when Cortex gives none), existed, created and isLoaded. +% cortex.isProfileLoaded and cortex.profileName are updated. Call cortexSession first. + +result = []; +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:profileFailed', 'Connect to Cortex before using profile operations.'); + end + if ~ischar(action) + error('cortex:profileFailed', 'action must be ''load'', ''save'' or ''unload''.'); + end + + profile = cortex.manager.getProfile(); + switch lower(action) + case 'load' + if nargin < 3 + error('cortex:profileFailed', 'Load requires a profile name.'); + end + result = profile.loadOrCreate(profileName); + case 'save' + result = profile.save(); + case 'unload' + result = profile.unload(); + otherwise + error('cortex:profileFailed', 'action must be ''load'', ''save'' or ''unload''.'); + end + + context = cortex.manager.getContext(); + cortex.isProfileLoaded = context.isProfileLoaded; + cortex.profileName = context.profileName; +catch failure + if strcmp(failure.identifier, 'cortex:profileFailed'), rethrow(failure); end + error('cortex:profileFailed', 'Profile operation failed: %s', failure.message); +end +end diff --git a/octave/functions/cortexRecord.m b/octave/functions/cortexRecord.m new file mode 100644 index 0000000..b42391f --- /dev/null +++ b/octave/functions/cortexRecord.m @@ -0,0 +1,47 @@ +function [cortex, result] = cortexRecord(cortex, action, varargin) +% cortexRecord Start or stop a record for the active Cortex session. +% [cortex, result] = cortexRecord(cortex, 'start', title, description, tags) +% [cortex, result] = cortexRecord(cortex, 'stop') +% Starting updates cortex.isRecording and cortex.recordId. The result is the +% Cortex result struct: record and sessionId. + +result = []; +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:recordFailed', 'Connect to Cortex before using record operations.'); + end + if ~ischar(action) + error('cortex:recordFailed', 'action must be ''start'' or ''stop''.'); + end + + record = cortex.manager.getRecord(); + switch lower(action) + case 'start' + if isempty(varargin) || numel(varargin) > 3 + error('cortex:recordFailed', 'Start requires title and accepts optional description and tags.'); + end + title = varargin{1}; + description = ''; + tags = {}; + if numel(varargin) >= 2, description = varargin{2}; end + if numel(varargin) >= 3, tags = varargin{3}; end + result = record.create(title, description, tags); + case 'stop' + if ~isempty(varargin) + error('cortex:recordFailed', 'Stop does not accept additional arguments.'); + end + result = record.stop(); + otherwise + error('cortex:recordFailed', 'action must be ''start'' or ''stop''.'); + end + + context = cortex.manager.getContext(); + cortex.isRecording = context.isRecording; + cortex.recordId = context.recordId; +catch failure + if strcmp(failure.identifier, 'cortex:recordFailed'), rethrow(failure); end + error('cortex:recordFailed', 'Record operation failed: %s', failure.message); +end +end + diff --git a/octave/functions/cortexSession.m b/octave/functions/cortexSession.m new file mode 100644 index 0000000..3fb52f6 --- /dev/null +++ b/octave/functions/cortexSession.m @@ -0,0 +1,75 @@ +function cortex = cortexSession(cortex, headsetId, varargin) +% cortexSession Connect a headset and create or reuse its active Cortex session. +% cortex = cortexSession(cortex, 'INSIGHT-XXXXXXXX') creates one session for the headset. +% 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). + +options = struct('autoRescan', true, 'queryInterval', 3, 'scanTimeout', 30); +if mod(numel(varargin), 2) ~= 0 + error('cortex:sessionFailed', 'Options must be supplied as name/value pairs.'); +end +for index = 1:2:numel(varargin) + name = varargin{index}; + if ~ischar(name) || ~isfield(options, name) + error('cortex:sessionFailed', 'Unknown headset session option.'); + end + options.(name) = varargin{index + 1}; +end + +if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:sessionFailed', 'Connect and authorize Cortex before creating a headset session.'); +end +if ~ischar(headsetId) || isempty(headsetId) + error('cortex:sessionFailed', 'headsetId must be a non-empty character vector.'); +end + +manager = cortex.manager; +context = manager.getContext(); +if ~isempty(context.sessionId) + if ~strcmp(context.headsetId, headsetId) + error('cortex:sessionFailed', ... + 'A session for headset %s is already active. Disconnect before selecting headset %s.', ... + context.headsetId, headsetId); + end + cortex = syncSessionState(cortex, context); + return; +end + +headset = []; +try + headset = manager.getHeadset(); + headset.scanHeadset(options.autoRescan, options.queryInterval); + + if ~headset.waitForHeadset(headsetId, options.scanTimeout) + error('CortexHeadset:notFound', 'Headset %s was not found within %g seconds.', ... + headsetId, options.scanTimeout); + end + + [ok, message] = headset.connectToHeadset(headsetId, {}); + if ~ok + error('CortexHeadset:connect', '%s', message); + end + + cortex = syncSessionState(cortex, manager.getContext()); +catch failure + if ~isempty(headset) + try + headset.stopScan(); + catch + end + end + error('cortex:sessionFailed', 'Could not create a headset session: %s', failure.message); +end +end + +function cortex = syncSessionState(cortex, context) +cortex.headsetId = context.headsetId; +cortex.sessionId = context.sessionId; +cortex.streams = context.subscribedStreams; +cortex.isSubscribed = ~isempty(context.subscribedStreams); +cortex.isRecording = context.isRecording; +cortex.recordId = context.recordId; +end diff --git a/octave/functions/cortexSubscribe.m b/octave/functions/cortexSubscribe.m new file mode 100644 index 0000000..fc6de71 --- /dev/null +++ b/octave/functions/cortexSubscribe.m @@ -0,0 +1,42 @@ +function cortex = cortexSubscribe(cortex, streams) +% cortexSubscribe Subscribe to streams on an active headset session. +% cortex = cortexSubscribe(cortex, {'eeg','mot','dev','eq','pow','met','com','fac','sys'}) +% com (mental command) and fac (facial expression) need a loaded profile; sys carries training events. +% Update the fields: +% isSubscribed true when the streams are being received +% streams the subscribed stream names +% Read the samples with cortexGetData. + +if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + fprintf('[cortexSubscribe] ERROR Call cortexConnect successfully first.\n'); + return; +end + +if ischar(streams), streams = {streams}; end +validStreams = {'eeg', 'mot', 'dev', 'eq', 'pow', 'met', 'com', 'fac', 'sys'}; +if ~iscellstr(streams) || isempty(streams) || ~all(ismember(streams, validStreams)) + fprintf('[cortexSubscribe] ERROR streams must be a non-empty list of: %s.\n', strjoin(validStreams, ', ')); + return; +end + +try + context = cortex.manager.getContext(); + if isempty(context.sessionId) + fprintf('[cortexSubscribe] ERROR Call cortexSession first to create an active session.\n'); + return; + end + + headset = cortex.manager.getHeadset(); + headset.subscribe(streams); + + context = cortex.manager.getContext(); + cortex.headsetId = context.headsetId; + cortex.sessionId = context.sessionId; + cortex.streams = context.subscribedStreams; + cortex.isSubscribed = ~isempty(context.subscribedStreams); + fprintf('[cortexSubscribe] Receiving data from %s.\n', context.headsetId); +catch failure + fprintf('[cortexSubscribe] ERROR %s: %s\n', failure.identifier, failure.message); +end +end diff --git a/octave/functions/cortexTraining.m b/octave/functions/cortexTraining.m new file mode 100644 index 0000000..f2b1234 --- /dev/null +++ b/octave/functions/cortexTraining.m @@ -0,0 +1,39 @@ +function result = cortexTraining(cortex, detection, action, status, varargin) +% cortexTraining Train an action of a detection on the loaded profile. +% result = cortexTraining(cortex, 'mentalCommand', 'push', 'start', 'wait', 30) +% result = cortexTraining(cortex, 'mentalCommand', 'push', 'accept', 'wait', 15) +% detection 'mentalCommand' ('facialExpression' uses the same call) +% action any action Cortex lists for the detection, for example neutral, push, left, right +% status start, accept, reject, reset or erase +% 'wait', seconds block until Cortex reports the outcome (needs the sys stream): +% start waits for MC_Succeeded or MC_Failed, accept waits for MC_Completed. +% Accepting a completed training also saves the profile. +% result fields: detection, action, status, event ('' without wait), isSucceeded, profileSaved. +% Requires cortexSession, cortexProfile(cortex, 'load', ...) and cortexSubscribe(cortex, {'sys'}). + +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:trainingFailed', 'Connect to Cortex before training.'); + end + if ~ischar(detection) || ~ischar(action) || ~ischar(status) + error('cortex:trainingFailed', 'detection, action and status must be character vectors.'); + end + if mod(numel(varargin), 2) ~= 0 + error('cortex:trainingFailed', 'Options must be supplied as name/value pairs.'); + end + + waitSeconds = 0; + for index = 1:2:numel(varargin) + if ~ischar(varargin{index}) || ~strcmp(varargin{index}, 'wait') + error('cortex:trainingFailed', 'Unknown training option. Supported: wait.'); + end + waitSeconds = varargin{index + 1}; + end + + result = cortex.manager.getTraining().train(detection, action, status, waitSeconds); +catch failure + if strcmp(failure.identifier, 'cortex:trainingFailed'), rethrow(failure); end + error('cortex:trainingFailed', 'Training operation failed: %s', failure.message); +end +end diff --git a/octave/internal/CortexAuth.m b/octave/internal/CortexAuth.m new file mode 100644 index 0000000..632f860 --- /dev/null +++ b/octave/internal/CortexAuth.m @@ -0,0 +1,159 @@ +classdef CortexAuth < handle + % CortexAuth Opens the Cortex WSS connection, checks login/access rights and holds the cortexToken. + + properties + license = '' + debit = 100 + end + + properties (SetAccess = private) + isUserLoggedIn = false + isAccessGranted = false + end + + properties + accessWaitTimeout = 180 + end + + properties (Access = private) + client + clientId + clientSecret + context + end + + methods + function obj = CortexAuth(clientId, clientSecret, host, port, context) + if nargin < 3, host = 'localhost'; end + if nargin < 4, port = 6868; end + if nargin < 5, context = CortexContext(); end + obj.clientId = clientId; + obj.clientSecret = clientSecret; + obj.context = context; + obj.client = CortexClient(host, port); + obj.client.onWarning(2, @(warning) obj.handleWarning(warning)); + obj.client.onWarning(3, @(warning) obj.handleWarning(warning)); + obj.client.onWarning(9, @(warning) obj.handleWarning(warning)); + end + + function init(obj) + % Verifies a user is logged in to EMOTIV Launcher and that this app has access. + logins = obj.getUserLogin(); + if isempty(logins) + error('CortexAuth:noUser', 'No user is logged in. Log in via EMOTIV Launcher and run again.'); + end + + if ~obj.hasAccessRight() + fprintf('[CortexAuth] Application access is not granted. Requesting approval from Cortex...\n'); + if ~obj.requestAccess() + fprintf(['[CortexAuth] Application access is not granted yet.\n' ... + '[CortexAuth] Open EMOTIV Launcher, sign in, and approve this application.\n' ... + '[CortexAuth] Waiting for approval for up to %d seconds...\n'], obj.accessWaitTimeout); + grantedWarning = obj.client.waitForWarning(9, obj.accessWaitTimeout); + if isempty(grantedWarning) + error('CortexAuth:accessDenied', ... + ['Application access was not approved within %d seconds. ' ... + 'Open EMOTIV Launcher, approve the application, and try again.'], ... + obj.accessWaitTimeout); + end + end + end + + if isempty(obj.context.token) + fprintf('[CortexAuth] Application access confirmed. Authorizing...\n'); + obj.authorize(); + end + end + + function logins = getUserLogin(obj) + response = obj.client.sendRequest('getUserLogin', struct()); + logins = response.result; + obj.isUserLoggedIn = ~isempty(logins); + end + + function granted = hasAccessRight(obj) + response = obj.client.sendRequest('hasAccessRight', obj.credentialParams()); + granted = isfield(response.result, 'accessGranted') && logical(response.result.accessGranted); + obj.isAccessGranted = granted; + end + + function granted = requestAccess(obj) + response = obj.client.sendRequest('requestAccess', obj.credentialParams()); + granted = isfield(response.result, 'accessGranted') && logical(response.result.accessGranted); + obj.isAccessGranted = granted; + end + + function token = authorize(obj) + params = obj.credentialParams(); + params.license = obj.license; + params.debit = obj.debit; + response = obj.client.sendRequest('authorize', params); + obj.context.token = response.result.cortexToken; + token = obj.context.token; + end + + function userInfo = getUserInformation(obj) + if isempty(obj.context.token) + error('CortexAuth:notAuthorized', 'Authorize before requesting user information.'); + end + + params = struct('cortexToken', obj.context.token); + response = obj.client.sendRequest('getUserInformation', params); + obj.context.userInfo = response.result; + userInfo = obj.context.userInfo; + end + + function licenseInfo = getLicenseInfo(obj) + if isempty(obj.context.token) + error('CortexAuth:notAuthorized', 'Authorize before requesting license information.'); + end + + params = struct('cortexToken', obj.context.token); + response = obj.client.sendRequest('getLicenseInfo', params); + if ~isfield(response.result, 'license') + error('CortexAuth:licenseInfo', 'Cortex returned no license information.'); + end + obj.context.licenseInfo = response.result.license; + licenseInfo = obj.context.licenseInfo; + end + + function client = getClient(obj) + client = obj.client; + end + + function context = getContext(obj) + context = obj.context; + end + + function close(obj) + obj.client.close(); + end + end + + methods (Access = private) + function handleWarning(obj, warning) + switch warning.code + case 2 + obj.isUserLoggedIn = true; + description = 'User logged in.'; + case 3 + obj.isUserLoggedIn = false; + obj.isAccessGranted = false; + obj.context.token = ''; + obj.context.userInfo = []; + obj.context.licenseInfo = []; + description = 'User logged out.'; + case 9 + obj.isAccessGranted = true; + description = 'Application access approved.'; + otherwise + description = 'Unhandled authentication warning.'; + end + fprintf('[CortexAuth] Warning %d: %s\n', warning.code, description); + end + + function params = credentialParams(obj) + params = struct('clientId', obj.clientId, 'clientSecret', obj.clientSecret); + end + end +end diff --git a/octave/internal/CortexClient.m b/octave/internal/CortexClient.m new file mode 100644 index 0000000..c3f3279 --- /dev/null +++ b/octave/internal/CortexClient.m @@ -0,0 +1,320 @@ +classdef CortexClient < handle + % CortexClient JSON-RPC client that connects straight to Cortex over WSS. + % Works in GNU Octave (with Java) and MATLAB via lib/cortex-ws-client.jar (nv-websocket-client). + + properties (Access = private) + ws + nextId = 1 + pendingResponses = {} + streamMessages = {} + warningMessages = {} + warningHandlers = {} + end + + properties (SetAccess = private) + lastWarning = [] + end + + properties + requestTimeout = 60 + end + + methods + function obj = CortexClient(host, port, requestTimeout) + if nargin < 1, host = 'localhost'; end + if nargin < 2, port = 6868; end + if nargin < 3, requestTimeout = 60; end + + obj.requestTimeout = requestTimeout; + obj.validateRequestTimeout(); + + internalDir = fileparts(mfilename('fullpath')); + libDir = fullfile(internalDir, '..', 'lib'); + CortexClient.addJars(libDir); + caPath = fullfile(internalDir, '..', '..', 'certificates', 'rootCA.pem'); + if ~exist(caPath, 'file') + error('CortexClient:certificate', ... + 'Required Cortex CA certificate not found: %s', caPath); + end + + url = sprintf('wss://%s:%d', host, port); + obj.ws = javaObject('cortex.CortexWsClient'); + obj.ws.connect(url, caPath, int32(10000)); + end + + function response = sendRequest(obj, method, params) + if nargin < 3, params = struct(); end + + obj.validateRequestTimeout(); + requestStartedAt = tic(); + id = obj.nextId; + obj.nextId = id + 1; + request = struct('jsonrpc', '2.0', 'id', id, 'method', method, 'params', params); + obj.ws.sendText(jsonencode(request)); + + queued = obj.takeResponse(id, method); + if ~isempty(queued) + response = queued; + return; + end + + while true + obj.checkRequestDeadline(requestStartedAt, method); + [messageType, msg] = obj.readMessage(); + obj.checkRequestDeadline(requestStartedAt, method); + if strcmp(messageType, 'timeout'), continue; end + + switch messageType + case 'result' + if obj.hasResponseId(msg, id) + response = msg; + return; + end + obj.pendingResponses{end + 1} = msg; + case 'error' + if obj.hasResponseId(msg, id) + obj.raiseRpcError(method, msg.error); + end + obj.pendingResponses{end + 1} = msg; + case 'warning' + obj.handleWarning(msg.warning); + case 'stream' + obj.streamMessages{end + 1} = msg; + otherwise + error('CortexClient:message', 'Unsupported Cortex message type: %s', messageType); + end + end + end + + function line = readLine(obj) + % Returns '' when no data arrives within the 1 s socket timeout. + line = obj.readSocketLine(); + end + + function stream = readStreamData(obj) + if ~isempty(obj.streamMessages) + stream = obj.streamMessages{1}; + obj.streamMessages(1) = []; + return; + end + + while true + [messageType, msg] = obj.readMessage(); + if strcmp(messageType, 'timeout') + stream = []; + return; + end + + switch messageType + case 'stream' + stream = msg; + return; + case 'warning' + obj.handleWarning(msg.warning); + case 'result' + obj.pendingResponses{end + 1} = msg; + case 'error' + obj.raiseRpcError('unsolicited message', msg.error); + otherwise + error('CortexClient:message', 'Unsupported Cortex message type: %s', messageType); + end + end + end + + function onWarning(obj, warningCode, handler) + if ~isnumeric(warningCode) || ~isscalar(warningCode) + error('CortexClient:warningHandler', 'Warning code must be a numeric scalar.'); + end + if ~isa(handler, 'function_handle') + error('CortexClient:warningHandler', 'Warning handler must be a function handle.'); + end + + registration = struct('code', warningCode, 'handler', handler); + obj.warningHandlers{end + 1} = registration; + end + + function warning = waitForWarning(obj, warningCode, timeoutSeconds) + if nargin < 3, timeoutSeconds = 60; end + if ~isnumeric(warningCode) || ~isscalar(warningCode) + error('CortexClient:warningWait', 'Warning code must be a numeric scalar.'); + end + if ~isnumeric(timeoutSeconds) || ~isscalar(timeoutSeconds) || timeoutSeconds < 0 + error('CortexClient:warningWait', 'Timeout must be a non-negative numeric scalar.'); + end + + warning = obj.takeWarning(warningCode); + if ~isempty(warning), return; end + + startedAt = tic(); + while toc(startedAt) < timeoutSeconds + [messageType, msg] = obj.readMessage(); + if strcmp(messageType, 'timeout'), continue; end + + switch messageType + case 'warning' + obj.handleWarning(msg.warning); + warning = obj.takeWarning(warningCode); + if ~isempty(warning), return; end + case 'stream' + obj.streamMessages{end + 1} = msg; + case 'result' + obj.pendingResponses{end + 1} = msg; + case 'error' + obj.raiseRpcError('unsolicited message', msg.error); + otherwise + error('CortexClient:message', 'Unsupported Cortex message type: %s', messageType); + end + end + warning = []; + end + + function close(obj) + if isempty(obj.ws), return; end + try + obj.ws.close(); + catch + end + obj.ws = []; + end + end + + methods (Static, Access = private) + function addJars(libDir) + loaded = javaclasspath('-all'); + [status, libInfo] = fileattrib(libDir); + if status + libDir = libInfo.Name; + end + for jarName = {'nv-websocket-client-2.14.jar', 'cortex-ws-client.jar'} + jarPath = fullfile(libDir, jarName{1}); + if ~exist(jarPath, 'file') + error('CortexClient:jar', 'Missing %s. Restore the lib folder from the repository.', jarPath); + end + if ~any(strcmp(loaded, jarPath)) + javaaddpath(jarPath); + end + end + end + end + + methods (Access = private) + function validateRequestTimeout(obj) + if ~isnumeric(obj.requestTimeout) || ~isscalar(obj.requestTimeout) || ... + ~isfinite(obj.requestTimeout) || obj.requestTimeout <= 0 + error('CortexClient:requestTimeoutConfig', ... + 'requestTimeout must be a finite, positive numeric scalar.'); + end + end + + function checkRequestDeadline(obj, requestStartedAt, method) + if toc(requestStartedAt) >= obj.requestTimeout + error('CortexClient:requestTimeout', ... + 'Timed out waiting for a response to "%s" after %.3g seconds.', ... + method, obj.requestTimeout); + end + end + + function [messageType, msg] = readMessage(obj) + line = obj.readSocketLine(); + if isempty(line) + messageType = 'timeout'; + msg = []; + return; + end + + msg = jsondecode(line); + messageType = obj.classifyMessage(msg); + end + + function messageType = classifyMessage(obj, msg) + if ~isstruct(msg) + error('CortexClient:message', 'Cortex returned a non-object JSON message.'); + elseif isfield(msg, 'sid') + messageType = 'stream'; + elseif isfield(msg, 'result') + messageType = 'result'; + elseif isfield(msg, 'error') + messageType = 'error'; + elseif isfield(msg, 'warning') + messageType = 'warning'; + else + error('CortexClient:message', 'Cortex returned an object with no sid, result, error, or warning field.'); + end + end + + function matched = hasResponseId(obj, msg, requestId) + matched = isfield(msg, 'id') && isequal(msg.id, requestId); + end + + function response = takeResponse(obj, requestId, method) + response = []; + for index = 1:numel(obj.pendingResponses) + candidate = obj.pendingResponses{index}; + if obj.hasResponseId(candidate, requestId) + response = candidate; + obj.pendingResponses(index) = []; + if strcmp(obj.classifyMessage(candidate), 'error') + obj.raiseRpcError(method, candidate.error); + end + return; + end + end + end + + function warning = takeWarning(obj, warningCode) + warning = []; + for index = 1:numel(obj.warningMessages) + candidate = obj.warningMessages{index}; + if isequal(candidate.code, warningCode) + warning = candidate; + obj.warningMessages(index) = []; + return; + end + end + end + + function raiseRpcError(obj, method, rpcError) + code = 'unknown'; + message = jsonencode(rpcError); + if isstruct(rpcError) + if isfield(rpcError, 'code') + code = num2str(rpcError.code); + end + if isfield(rpcError, 'message') + message = char(rpcError.message); + end + end + error('CortexClient:rpc', '%s failed (code %s): %s', method, code, message); + end + + function handleWarning(obj, warning) + if ~isstruct(warning) || ~isfield(warning, 'code') + error('CortexClient:warning', 'Cortex returned an invalid warning object.'); + end + + obj.lastWarning = warning; + obj.warningMessages{end + 1} = warning; + + for index = 1:numel(obj.warningHandlers) + registration = obj.warningHandlers{index}; + if isequal(registration.code, warning.code) + registration.handler(warning); + end + end + end + + function line = readSocketLine(obj) + % Java returns null (empty in Octave) on timeout; a closed link throws. + try + line = obj.ws.poll(int32(1000)); + catch err + error('CortexClient:closed', 'Connection to Cortex closed: %s', err.message); + end + if isempty(line) + line = ''; + else + line = char(line); + end + end + end +end diff --git a/octave/internal/CortexContext.m b/octave/internal/CortexContext.m new file mode 100644 index 0000000..fa86e95 --- /dev/null +++ b/octave/internal/CortexContext.m @@ -0,0 +1,22 @@ +classdef CortexContext < handle + % CortexContext Shared authentication data for one Cortex connection. + + properties + token = '' + userInfo = [] + licenseInfo = [] + + headsets = {} % cell array of headset structs from the last queryHeadsets + headsetId = '' + sessionId = '' + subscribedStreams = {} + isRecording = false + recordId = '' + profileName = '' + isProfileLoaded = false + detectionInfo = struct() % per detection: cell arrays actions, controls and events, set on profile load + trainingEvents = {} % structs with detection, event and time from the sys stream + streamLabels = struct() % one field per stream, each a cell array of column labels + buffer = [] % CortexDataBuffer holding the received samples + end +end diff --git a/octave/internal/CortexDataBuffer.m b/octave/internal/CortexDataBuffer.m new file mode 100644 index 0000000..9ca64c5 --- /dev/null +++ b/octave/internal/CortexDataBuffer.m @@ -0,0 +1,113 @@ +classdef CortexDataBuffer < handle + % CortexDataBuffer Fixed-size ring buffer that keeps the latest samples of each data stream. + % Rows are samples (oldest first when read) and columns follow the stream labels. + + properties (SetAccess = private) + capacity + end + + properties (Access = private) + names = {} + labels = {} + samples = {} + times = {} + bciActions = {} + nextRow = [] + count = [] + end + + methods + function obj = CortexDataBuffer(capacity) + if nargin < 1, capacity = 10000; end + if ~isnumeric(capacity) || ~isscalar(capacity) || capacity < 1 + error('CortexDataBuffer:capacity', 'Capacity must be a positive numeric scalar.'); + end + obj.capacity = floor(capacity); + end + + function configure(obj, stream, labels) + % Resets one stream and stores its column labels. + idx = obj.indexOf(stream); + obj.labels{idx} = labels; + obj.samples{idx} = []; + obj.times{idx} = []; + obj.bciActions{idx} = {}; + obj.nextRow(idx) = 1; + obj.count(idx) = 0; + end + + function append(obj, stream, row, time, bciAction) + % bciAction is optional: the mental command or facial expression action of a com or fac sample. + if nargin < 5, bciAction = ''; end + idx = obj.indexOf(stream); + width = numel(row); + if isempty(obj.samples{idx}) + obj.samples{idx} = NaN(obj.capacity, width); + obj.times{idx} = NaN(obj.capacity, 1); + obj.bciActions{idx} = cell(obj.capacity, 1); + end + + columns = size(obj.samples{idx}, 2); + if width < columns + row(end + 1:columns) = NaN; + elseif width > columns + row = row(1:columns); + end + + r = obj.nextRow(idx); + obj.samples{idx}(r, :) = row; + obj.times{idx}(r) = time; + obj.bciActions{idx}{r} = bciAction; + obj.nextRow(idx) = mod(r, obj.capacity) + 1; + obj.count(idx) = min(obj.count(idx) + 1, obj.capacity); + end + + function [labels, data, time, bciActions] = read(obj, stream, lastN) + % Returns the newest lastN samples (all buffered samples when lastN is omitted). + labels = {}; + data = []; + time = []; + bciActions = {}; + idx = find(strcmp(obj.names, stream), 1); + if isempty(idx), return; end + + labels = obj.labels{idx}; + n = obj.count(idx); + if nargin >= 3 && ~isempty(lastN) + n = min(n, lastN); + end + if n == 0, return; end + + newest = mod(obj.nextRow(idx) - 2, obj.capacity) + 1; + rows = mod((newest - n + 1:newest) - 1, obj.capacity) + 1; + data = obj.samples{idx}(rows, :); + time = obj.times{idx}(rows); + bciActions = obj.bciActions{idx}(rows); + end + + function n = numSamples(obj, stream) + idx = find(strcmp(obj.names, stream), 1); + if isempty(idx) + n = 0; + else + n = obj.count(idx); + end + end + end + + methods (Access = private) + function idx = indexOf(obj, stream) + idx = find(strcmp(obj.names, stream), 1); + if isempty(idx) + idx = numel(obj.names) + 1; + obj.names{idx} = stream; + obj.labels{idx} = {}; + obj.samples{idx} = []; + obj.times{idx} = []; + obj.bciActions{idx} = {}; + obj.nextRow(idx) = 1; + obj.count(idx) = 0; + end + end + end +end diff --git a/octave/internal/CortexFacialExpressionConfiguration.m b/octave/internal/CortexFacialExpressionConfiguration.m new file mode 100644 index 0000000..dadcc76 --- /dev/null +++ b/octave/internal/CortexFacialExpressionConfiguration.m @@ -0,0 +1,77 @@ +classdef CortexFacialExpressionConfiguration < handle + % CortexFacialExpressionConfiguration Reads the facial expression configuration of the loaded profile. + + properties (Access = private) + client + context + end + + methods + function obj = CortexFacialExpressionConfiguration(client, context) + obj.client = client; + obj.context = context; + end + + function config = get(obj) + if isempty(obj.context.sessionId) + error('CortexFacialExpressionConfiguration:noSession', 'Create a headset session first.'); + end + if ~obj.context.isProfileLoaded + error('CortexFacialExpressionConfiguration:noProfile', 'Load a profile first.'); + end + token = obj.context.token; + session = obj.context.sessionId; + detection = 'facialExpression'; + + info = obj.context.detectionInfo.(detection); + signature = obj.client.sendRequest('getTrainedSignatureActions', ... + struct('cortexToken', token, 'detection', detection, 'session', session)).result; + duration = obj.client.sendRequest('getTrainingTime', ... + struct('cortexToken', token, 'detection', detection, 'session', session)).result; + + trained = CortexFacialExpressionConfiguration.toCell( ... + CortexFacialExpressionConfiguration.field(signature, 'trainedActions', {})); + trainedActions = cell(1, numel(trained)); + for index = 1:numel(trained) + name = trained{index}.action; + % Neutral has no threshold. + value = []; + if ~strcmp(name, 'neutral') + thresholdResult = obj.client.sendRequest('facialExpressionThreshold', struct( ... + 'cortexToken', token, 'session', session, 'action', name, 'status', 'get')).result; + value = CortexFacialExpressionConfiguration.field(thresholdResult, 'value', thresholdResult); + if ~isnumeric(value) || isempty(value), value = []; end + end + trainedActions{index} = struct('action', name, 'threshold', value, ... + 'trainingCount', CortexFacialExpressionConfiguration.field(trained{index}, 'times', 0)); + end + + config = struct( ... + 'possibleActions', {info.actions}, ... + 'trainedActions', {trainedActions}, ... + 'trainingDuration', CortexFacialExpressionConfiguration.field(duration, 'time', [])); + end + end + + methods (Static, Access = private) + function items = toCell(value) + if iscell(value) + items = value(:)'; + elseif isstruct(value) + items = num2cell(value(:))'; + elseif ischar(value) + items = {value}; + else + items = {}; + end + end + + function value = field(source, name, default) + if isstruct(source) && isfield(source, name) + value = source.(name); + else + value = default; + end + end + end +end diff --git a/octave/internal/CortexHeadset.m b/octave/internal/CortexHeadset.m new file mode 100644 index 0000000..5bf39f4 --- /dev/null +++ b/octave/internal/CortexHeadset.m @@ -0,0 +1,296 @@ +classdef CortexHeadset < handle + % CortexHeadset Scans for headsets, connects one and opens a session, optionally subscribing to streams. + % The client is single-threaded, so the scan "timer" runs inside update(), which also reads + % the incoming data samples into the context buffer. + + properties + connectTimeout = 10 % seconds to wait for warning 104 (headset connected) + end + + properties (SetAccess = private) + isScanning = false + isSubscribed = false + autoRescan = true + queryInterval = 3 + end + + properties (Access = private) + client + context + scanFinished = false + lastQueryAt = [] + parser + end + + methods + function obj = CortexHeadset(client, context) + obj.client = client; + obj.context = context; + obj.parser = CortexStreamParser(); + if isempty(context.buffer) + context.buffer = CortexDataBuffer(10000); + end + obj.client.onWarning(1, @(warning) obj.onSessionClosed(warning)); + obj.client.onWarning(142, @(warning) obj.onScanFinished(warning)); + end + + function scanHeadset(obj, autoRescan, queryInterval) + % Starts a scan and queries the headset list every queryInterval seconds (see update()). + if nargin < 2, autoRescan = true; end + if nargin < 3, queryInterval = 3; end + if ~(islogical(autoRescan) || isnumeric(autoRescan)) || ~isscalar(autoRescan) + error('CortexHeadset:scanOptions', 'autoRescan must be true or false.'); + end + if ~isnumeric(queryInterval) || ~isscalar(queryInterval) || queryInterval <= 0 + error('CortexHeadset:scanOptions', 'queryInterval must be a positive number of seconds.'); + end + + obj.autoRescan = logical(autoRescan); + obj.queryInterval = double(queryInterval); + fprintf('[CortexHeadset] Scanning for headsets...\n'); + obj.refreshHeadsets(); + obj.isScanning = true; + obj.queryHeadsets(); + end + + function stopScan(obj) + obj.isScanning = false; + end + + function headsets = queryHeadsets(obj) + response = obj.client.sendRequest('queryHeadsets', struct()); + obj.context.headsets = CortexHeadset.toCell(response.result); + obj.lastQueryAt = tic(); + headsets = obj.context.headsets; + if isempty(headsets) + fprintf('[CortexHeadset] No headsets found.\n'); + else + fprintf('[CortexHeadset] Headsets (id | status):\n'); + for index = 1:numel(headsets) + fprintf(' %s | %s\n', CortexHeadset.textField(headsets{index}, 'id'), ... + CortexHeadset.textField(headsets{index}, 'status')); + end + end + end + + function headset = findHeadset(obj, headsetId) + headset = []; + for index = 1:numel(obj.context.headsets) + candidate = obj.context.headsets{index}; + if isfield(candidate, 'id') && strcmp(candidate.id, headsetId) + headset = candidate; + return; + end + end + end + + function found = waitForHeadset(obj, headsetId, timeoutSeconds) + % Keeps scanning until headsetId shows up in the list or the timeout expires. + startedAt = tic(); + found = false; + while true + if ~isempty(obj.findHeadset(headsetId)) + found = true; + return; + end + if toc(startedAt) >= timeoutSeconds, return; end + obj.update(0.5); + end + end + + function [ok, message] = connectToHeadset(obj, headsetId, streams) + % Connects the headset if needed, creates an active session, and subscribes when streams are provided. + if nargin < 3, streams = {}; end + ok = false; + message = ''; + + try + headset = obj.findHeadset(headsetId); + if isempty(headset) + message = sprintf('Headset %s is not in the scanned headset list.', headsetId); + return; + end + + 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)); + end + if isempty(obj.client.waitForWarning(104, obj.connectTimeout)) + message = sprintf(['Connection to %s was not successful: warning 104 ' ... + '(headset connected) was not received within %g seconds.'], ... + headsetId, obj.connectTimeout); + return; + end + end + + obj.isScanning = false; + obj.createSession(headsetId); + if ~isempty(streams) + obj.subscribe(streams); + end + ok = true; + catch failure + message = failure.message; + end + end + + function sessionId = createSession(obj, headsetId) + fprintf('[CortexHeadset] Creating an active session for %s...\n', headsetId); + params = struct('cortexToken', obj.context.token, 'status', 'active', 'headset', headsetId); + response = obj.client.sendRequest('createSession', params); + sessionId = response.result.id; + obj.context.sessionId = sessionId; + obj.context.headsetId = headsetId; + end + + function subscribe(obj, streams) + if isempty(obj.context.sessionId) + error('CortexHeadset:noSession', 'Create a session before subscribing.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'streams', {streams}); + response = obj.client.sendRequest('subscribe', params); + + failures = CortexHeadset.toCell(response.result.failure); + for index = 1:numel(failures) + item = failures{index}; + fprintf('[CortexHeadset] Subscribe failed for %s (code %s): %s\n', ... + CortexHeadset.textField(item, 'streamName'), ... + CortexHeadset.textField(item, 'code'), CortexHeadset.textField(item, 'message')); + end + + successes = CortexHeadset.toCell(response.result.success); + for index = 1:numel(successes) + item = successes{index}; + name = item.streamName; + labels = CortexStreamParser.flattenLabels(item.cols); + obj.parser.register(item.sid, name); + obj.context.streamLabels.(name) = labels; + obj.context.subscribedStreams{end + 1} = name; + obj.context.buffer.configure(name, labels); + fprintf('[CortexHeadset] Subscribed to %s (%d columns).\n', name, numel(labels)); + end + obj.isSubscribed = ~isempty(successes); + if ~obj.isSubscribed + error('CortexHeadset:subscribe', 'Cortex did not accept any data stream.'); + end + end + + function unsubscribe(obj) + if ~obj.isSubscribed, return; end + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'streams', {obj.context.subscribedStreams}); + obj.isSubscribed = false; + obj.parser.reset(); + obj.context.subscribedStreams = {}; + obj.client.sendRequest('unsubscribe', params); + end + + function update(obj, maxSeconds) + % Reads incoming messages into the buffer for about maxSeconds, then runs the scan timer. + % It can block up to 1 s when no data is arriving. + if nargin < 2, maxSeconds = 0.25; end + startedAt = tic(); + while true + stream = obj.client.readStreamData(); + if isempty(stream), break; end + obj.storeSample(stream); + if toc(startedAt) >= maxSeconds, break; end + end + obj.runScanTimer(); + end + end + + methods (Access = private) + function refreshHeadsets(obj) + % Cortex answers with warning 142 when the scan finishes. + obj.scanFinished = false; + obj.client.sendRequest('controlDevice', struct('command', 'refresh')); + end + + function onScanFinished(obj, warning) + obj.scanFinished = true; + if ~obj.autoRescan + fprintf(['[CortexHeadset] Headset scan finished (warning 142). ' ... + 'Call scanHeadset again to rescan.\n']); + end + end + + function onSessionClosed(obj, warning) + if ~isfield(warning, 'message') || ~isstruct(warning.message) || ... + ~isfield(warning.message, 'sessionId') || ... + ~strcmp(warning.message.sessionId, obj.context.sessionId) + return; + end + + obj.isScanning = false; + obj.isSubscribed = false; + obj.context.sessionId = ''; + obj.context.headsetId = ''; + obj.context.subscribedStreams = {}; + obj.context.isRecording = false; + obj.context.recordId = ''; + obj.context.profileName = ''; + obj.context.isProfileLoaded = false; + obj.parser.reset(); + fprintf('[CortexHeadset] Session %s was closed by Cortex.\n', warning.message.sessionId); + end + + function runScanTimer(obj) + if ~obj.isScanning, return; end + if obj.autoRescan && obj.scanFinished + obj.refreshHeadsets(); + end + if isempty(obj.lastQueryAt) || toc(obj.lastQueryAt) >= obj.queryInterval + obj.queryHeadsets(); + end + end + + function storeSample(obj, msg) + [stream, row, time, bciAction] = obj.parser.parse(msg); + if isempty(stream), return; end + if strcmp(stream, 'sys') + obj.storeSystemEvent(msg.sys, time); + return; + end + obj.context.buffer.append(stream, row, time, bciAction); + end + + function storeSystemEvent(obj, values, time) + % A sys sample is {detection, event}, for example {'mentalCommand', 'MC_Started'}. + names = CortexStreamParser.stringsOf(values); + if numel(names) < 2, return; end + obj.context.trainingEvents{end + 1} = ... + struct('detection', names{1}, 'event', names{2}, 'time', time); + end + end + + methods (Static, Access = private) + function items = toCell(value) + % jsondecode returns a struct array or a cell array depending on the content. + if isempty(value) + items = {}; + elseif iscell(value) + items = value(:)'; + elseif isstruct(value) + items = num2cell(value(:))'; + else + items = {value}; + end + end + end + + methods (Static, Access = private) + function text = textField(item, name) + text = '?'; + if isstruct(item) && isfield(item, name) + value = item.(name); + if isnumeric(value), value = num2str(value); end + text = char(value); + end + end + end +end diff --git a/octave/internal/CortexManager.m b/octave/internal/CortexManager.m new file mode 100644 index 0000000..d03d3cf --- /dev/null +++ b/octave/internal/CortexManager.m @@ -0,0 +1,124 @@ +classdef CortexManager < handle + % CortexManager Owns the Cortex objects and creates each one lazily on first use. + % The TCP connection (CortexClient) is opened by CortexAuth, so nothing connects until getAuth(). + + properties (SetAccess = private) + host + port + clientId + clientSecret + context + end + + properties (Access = private) + auth = [] + headset = [] + record = [] + marker = [] + profile = [] + training = [] + mentalCommand = [] + facialExpression = [] + end + + methods + function obj = CortexManager(clientId, clientSecret, host, port) + if nargin < 2 + [clientId, clientSecret, configPort] = cortexCredentials(); + else + configPort = 6868; + end + if nargin < 3, host = 'localhost'; end + if nargin < 4, port = configPort; end + obj.clientId = clientId; + obj.clientSecret = clientSecret; + obj.host = host; + obj.port = port; + obj.context = CortexContext(); + end + + function auth = getAuth(obj) + if isempty(obj.auth) + obj.auth = CortexAuth(obj.clientId, obj.clientSecret, obj.host, obj.port, obj.context); + end + auth = obj.auth; + end + + function context = getContext(obj) + context = obj.context; + end + + function client = getClient(obj) + client = obj.getAuth().getClient(); + end + + function headset = getHeadset(obj) + if isempty(obj.headset) + obj.headset = CortexHeadset(obj.getClient(), obj.context); + end + headset = obj.headset; + end + + function record = getRecord(obj) + if isempty(obj.record) + obj.record = CortexRecord(obj.getClient(), obj.context); + end + record = obj.record; + end + + function marker = getMarker(obj) + if isempty(obj.marker) + obj.marker = CortexMarker(obj.getClient(), obj.context); + end + marker = obj.marker; + end + + function profile = getProfile(obj) + if isempty(obj.profile) + obj.profile = CortexProfile(obj.getClient(), obj.context); + end + profile = obj.profile; + end + + function training = getTraining(obj) + if isempty(obj.training) + obj.training = CortexTraining(obj.getClient(), obj.context, obj.getHeadset(), obj.getProfile()); + end + training = obj.training; + end + + function mentalCommand = getMentalCommandConfiguration(obj) + if isempty(obj.mentalCommand) + obj.mentalCommand = CortexMentalCommandConfiguration(obj.getClient(), obj.context); + end + mentalCommand = obj.mentalCommand; + end + + function facialExpression = getFacialExpressionConfiguration(obj) + if isempty(obj.facialExpression) + obj.facialExpression = CortexFacialExpressionConfiguration(obj.getClient(), obj.context); + end + facialExpression = obj.facialExpression; + end + + function close(obj) + % Only closes what was actually created. + if ~isempty(obj.headset) + try + obj.headset.unsubscribe(); + catch + end + obj.headset = []; + end + if ~isempty(obj.auth) + obj.auth.close(); + end + obj.record = []; + obj.marker = []; + obj.profile = []; + obj.training = []; + obj.mentalCommand = []; + obj.facialExpression = []; + end + end +end diff --git a/octave/internal/CortexMarker.m b/octave/internal/CortexMarker.m new file mode 100644 index 0000000..4e79a78 --- /dev/null +++ b/octave/internal/CortexMarker.m @@ -0,0 +1,78 @@ +classdef CortexMarker < handle + % CortexMarker Injects instance markers and updates them to interval markers. + + properties (Access = private) + client + context + end + + methods + function obj = CortexMarker(client, context) + obj.client = client; + obj.context = context; + end + + function result = inject(obj, label, value, time, port, extras) + if nargin < 4 || isempty(time) + time = double(javaMethod('currentTimeMillis', 'java.lang.System')); + end + if nargin < 5 || isempty(port), port = 'Software'; end + if nargin < 6 || isempty(extras), extras = struct(); end + obj.validateRecording(); + if ~ischar(label) || isempty(label) + error('CortexMarker:label', 'label must be a non-empty character vector.'); + end + if ~(ischar(value) || (isnumeric(value) && isscalar(value) && isfinite(value))) + error('CortexMarker:value', 'value must be a character vector or finite numeric scalar.'); + end + if ~isnumeric(time) || ~isscalar(time) || ~isfinite(time) || time < 0 + error('CortexMarker:time', 'time must be a non-negative numeric epoch timestamp in milliseconds.'); + end + if ~ischar(port) || isempty(port) + error('CortexMarker:port', 'port must be a non-empty character vector.'); + end + if ~isstruct(extras) || numel(extras) ~= 1 + error('CortexMarker:extras', 'extras must be a scalar struct.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'time', double(time), 'value', value, 'label', label, 'port', port); + if ~isempty(fieldnames(extras)), params.extras = extras; end + + response = obj.client.sendRequest('injectMarker', params); + result = response.result; + end + + function result = update(obj, markerId, endTime, extras) + if nargin < 4 || isempty(extras), extras = struct(); end + obj.validateRecording(); + if ~ischar(markerId) || isempty(markerId) + error('CortexMarker:markerId', 'markerId must be a non-empty character vector.'); + end + if ~isnumeric(endTime) || ~isscalar(endTime) || ~isfinite(endTime) || endTime < 0 + error('CortexMarker:time', 'endTime must be a non-negative numeric epoch timestamp in milliseconds.'); + end + if ~isstruct(extras) || numel(extras) ~= 1 + error('CortexMarker:extras', 'extras must be a scalar struct.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'markerId', markerId, 'time', double(endTime)); + if ~isempty(fieldnames(extras)), params.extras = extras; end + + response = obj.client.sendRequest('updateMarker', params); + result = response.result; + end + end + + methods (Access = private) + function validateRecording(obj) + if isempty(obj.context.sessionId) + error('CortexMarker:noSession', 'Create an active session before using markers.'); + end + if ~obj.context.isRecording + error('CortexMarker:notRecording', 'Markers can only be used while a record is active.'); + end + end + end +end \ No newline at end of file diff --git a/octave/internal/CortexMentalCommandConfiguration.m b/octave/internal/CortexMentalCommandConfiguration.m new file mode 100644 index 0000000..c9a0bce --- /dev/null +++ b/octave/internal/CortexMentalCommandConfiguration.m @@ -0,0 +1,143 @@ +classdef CortexMentalCommandConfiguration < handle + % CortexMentalCommandConfiguration Reads and writes the mental command configuration of the loaded profile. + + properties (Access = private) + client + context + end + + methods + function obj = CortexMentalCommandConfiguration(client, context) + obj.client = client; + obj.context = context; + end + + function config = get(obj) + obj.requireSession(); + token = obj.context.token; + session = obj.context.sessionId; + detection = 'mentalCommand'; + + info = obj.context.detectionInfo.(detection); + signature = obj.client.sendRequest('getTrainedSignatureActions', ... + struct('cortexToken', token, 'detection', detection, 'session', session)).result; + active = obj.getActiveActions(); + sensitivity = obj.getSensitivity(); + threshold = obj.client.sendRequest('mentalCommandTrainingThreshold', ... + struct('cortexToken', token, 'session', session)).result; + duration = obj.client.sendRequest('getTrainingTime', ... + struct('cortexToken', token, 'detection', detection, 'session', session)).result; + + sensitiveActions = CortexMentalCommandConfiguration.sensitiveActions(active); + trained = CortexMentalCommandConfiguration.toCell(CortexMentalCommandConfiguration.field(signature, 'trainedActions', {})); + trainedActions = cell(1, numel(trained)); + for index = 1:numel(trained) + name = trained{index}.action; + value = []; + position = find(strcmp(sensitiveActions, name), 1); + if ~isempty(position) && position <= numel(sensitivity) + value = sensitivity(position); + end + trainedActions{index} = struct('action', name, ... + 'active', strcmp(name, 'neutral') || any(strcmp(active, name)), ... + 'sensitivity', value, ... + 'trainingCount', CortexMentalCommandConfiguration.field(trained{index}, 'times', 0)); + end + + config = struct( ... + 'currentTrainingThreshold', CortexMentalCommandConfiguration.field(threshold, 'currentThreshold', []), ... + 'possibleActions', {info.actions}, ... + 'totalTrainingCount', CortexMentalCommandConfiguration.field(signature, 'totalTimesTraining', 0), ... + 'trainedActions', {trainedActions}, ... + 'trainingDuration', CortexMentalCommandConfiguration.field(duration, 'time', [])); + end + + function set(obj, activeActions, sensitivity) + % Either argument may be [] to leave it unchanged. + obj.requireSession(); + token = obj.context.token; + session = obj.context.sessionId; + + if ~isempty(activeActions) + if ischar(activeActions), activeActions = {activeActions}; end + if ~iscellstr(activeActions) + error('CortexMentalCommandConfiguration:argument', 'activeActions must be a cell array of action names.'); + end + info = obj.context.detectionInfo.mentalCommand; + for index = 1:numel(activeActions) + if ~any(strcmp(info.actions, activeActions{index})) + error('CortexMentalCommandConfiguration:argument', 'Unsupported action "%s".', activeActions{index}); + end + end + if numel(setdiff(activeActions, {'neutral'})) > 4 + error('CortexMentalCommandConfiguration:argument', 'At most 4 actions (excluding neutral) can be active.'); + end + obj.client.sendRequest('mentalCommandActiveAction', struct('cortexToken', token, ... + 'session', session, 'status', 'set', 'actions', {activeActions(:)'})); + end + + if ~isempty(sensitivity) + if ~isnumeric(sensitivity) || numel(sensitivity) > 4 || any(sensitivity < 1 | sensitivity > 10) + error('CortexMentalCommandConfiguration:argument', ... + 'sensitivity must have up to 4 values between 1 and 10, in the order of the active actions.'); + end + values = obj.getSensitivity(); + values(1:numel(sensitivity)) = sensitivity(:)'; + obj.client.sendRequest('mentalCommandActionSensitivity', struct('cortexToken', token, ... + 'session', session, 'status', 'set', 'values', values(:)')); + end + end + end + + methods (Access = private) + function requireSession(obj) + if isempty(obj.context.sessionId) + error('CortexMentalCommandConfiguration:noSession', 'Create a headset session first.'); + end + if ~obj.context.isProfileLoaded + error('CortexMentalCommandConfiguration:noProfile', 'Load a profile first.'); + end + end + + function active = getActiveActions(obj) + response = obj.client.sendRequest('mentalCommandActiveAction', struct( ... + 'cortexToken', obj.context.token, 'session', obj.context.sessionId, 'status', 'get')); + active = CortexMentalCommandConfiguration.toCell(response.result); + end + + function values = getSensitivity(obj) + response = obj.client.sendRequest('mentalCommandActionSensitivity', struct( ... + 'cortexToken', obj.context.token, 'session', obj.context.sessionId, 'status', 'get')); + values = double(response.result(:)'); + values = [values, 5 * ones(1, max(0, 4 - numel(values)))]; + end + end + + methods (Static, Access = private) + function actions = sensitiveActions(active) + % Sensitivity values follow the active actions; neutral has none, and only 4 are kept. + actions = active(~strcmp(active, 'neutral')); + actions = actions(1:min(4, numel(actions))); + end + + function items = toCell(value) + if iscell(value) + items = value(:)'; + elseif isstruct(value) + items = num2cell(value(:))'; + elseif ischar(value) + items = {value}; + else + items = {}; + end + end + + function value = field(source, name, default) + if isstruct(source) && isfield(source, name) + value = source.(name); + else + value = default; + end + end + end +end diff --git a/octave/internal/CortexProfile.m b/octave/internal/CortexProfile.m new file mode 100644 index 0000000..f061692 --- /dev/null +++ b/octave/internal/CortexProfile.m @@ -0,0 +1,177 @@ +classdef CortexProfile < handle + % CortexProfile Queries, creates, loads, saves and unloads training profiles for the active headset. + + properties (Access = private) + client + context + end + + methods + function obj = CortexProfile(client, context) + obj.client = client; + obj.context = context; + end + + function profiles = query(obj) + params = struct('cortexToken', obj.context.token); + response = obj.client.sendRequest('queryProfile', params); + profiles = CortexProfile.toCell(response.result); + end + + function profile = findProfile(obj, profileName) + profile = []; + profiles = obj.query(); + for index = 1:numel(profiles) + item = profiles{index}; + if isstruct(item) && isfield(item, 'name') && strcmp(item.name, profileName) + profile = item; + return; + end + end + end + + function result = loadOrCreate(obj, profileName) + CortexProfile.validateName(profileName); + obj.requireHeadset(); + + if obj.context.isProfileLoaded + if strcmp(obj.context.profileName, profileName) + info = obj.context.detectionInfo; + if ~isstruct(info) || ~isfield(info, 'mentalCommand') || ~isfield(info, 'facialExpression') + obj.loadDetectionInfo(); + end + result = CortexProfile.makeResult(profileName, '', true, false, true); + return; + end + error('CortexProfile:otherLoaded', ... + 'Profile %s is already loaded. Unload it before loading %s.', ... + obj.context.profileName, profileName); + end + + existing = obj.findProfile(profileName); + created = isempty(existing); + uuid = ''; + if created + fprintf('[CortexProfile] Profile %s not found; creating it...\n', profileName); + createResult = obj.setup(profileName, 'create'); + uuid = CortexProfile.textField(createResult, 'uuid'); + else + uuid = CortexProfile.textField(existing, 'uuid'); + end + + fprintf('[CortexProfile] Loading profile %s...\n', profileName); + loadResult = obj.setup(profileName, 'load'); + if isempty(uuid), uuid = CortexProfile.textField(loadResult, 'uuid'); end + + obj.context.profileName = profileName; + obj.context.isProfileLoaded = true; + obj.loadDetectionInfo(); + result = CortexProfile.makeResult(profileName, uuid, ~created, created, true); + end + + function result = save(obj) + obj.requireLoaded(); + name = obj.context.profileName; + setupResult = obj.setup(name, 'save'); + result = CortexProfile.makeResult(name, CortexProfile.textField(setupResult, 'uuid'), ... + true, false, true); + end + + function result = unload(obj) + obj.requireLoaded(); + name = obj.context.profileName; + setupResult = obj.setup(name, 'unload'); + obj.context.profileName = ''; + obj.context.isProfileLoaded = false; + obj.context.detectionInfo = struct(); + result = CortexProfile.makeResult(name, CortexProfile.textField(setupResult, 'uuid'), ... + true, false, false); + end + end + + methods (Access = private) + function loadDetectionInfo(obj) + maxAttempts = 3; + for detection = {'mentalCommand', 'facialExpression'} + for attempt = 1:maxAttempts + try + response = obj.client.sendRequest('getDetectionInfo', struct('detection', detection{1})); + break; + catch err + if attempt == maxAttempts + rethrow(err); + end + end + end + result = response.result; + obj.context.detectionInfo.(detection{1}) = struct( ... + 'actions', {CortexProfile.toStrings(result, 'actions')}, ... + 'controls', {CortexProfile.toStrings(result, 'controls')}, ... + 'events', {CortexProfile.toStrings(result, 'events')}); + end + end + + function result = setup(obj, profileName, status) + params = struct('cortexToken', obj.context.token, 'headset', obj.context.headsetId, ... + 'profile', profileName, 'status', status); + response = obj.client.sendRequest('setupProfile', params); + result = response.result; + end + + function requireHeadset(obj) + if isempty(obj.context.headsetId) + error('CortexProfile:noSession', 'Create a headset session before using profiles.'); + end + end + + function requireLoaded(obj) + if ~obj.context.isProfileLoaded + error('CortexProfile:notLoaded', 'No profile is loaded.'); + end + end + end + + methods (Static, Access = private) + function validateName(profileName) + if ~ischar(profileName) || isempty(profileName) + error('CortexProfile:name', 'profileName must be a non-empty character vector.'); + end + end + + function result = makeResult(name, uuid, existed, created, isLoaded) + result = struct('name', name, 'uuid', uuid, 'existed', existed, ... + 'created', created, 'isLoaded', isLoaded); + end + + function text = textField(item, fieldName) + text = ''; + if isstruct(item) && isfield(item, fieldName) && ischar(item.(fieldName)) + text = item.(fieldName); + end + end + + function items = toStrings(result, fieldName) + items = {}; + if ~isstruct(result) || ~isfield(result, fieldName), return; end + value = result.(fieldName); + if ischar(value) + items = {value}; + elseif iscell(value) + items = value(:)'; + end + end + + function items = toCell(value) + % jsondecode returns a struct array or a cell array depending on the content. + if isempty(value) + items = {}; + elseif iscell(value) + items = value(:)'; + elseif isstruct(value) + items = num2cell(value(:))'; + else + items = {}; + end + end + end +end diff --git a/octave/internal/CortexRecord.m b/octave/internal/CortexRecord.m new file mode 100644 index 0000000..93f5a32 --- /dev/null +++ b/octave/internal/CortexRecord.m @@ -0,0 +1,60 @@ +classdef CortexRecord < handle + % CortexRecord Creates and stops records for the active Cortex session. + + properties (Access = private) + client + context + end + + methods + function obj = CortexRecord(client, context) + obj.client = client; + obj.context = context; + end + + function result = create(obj, title, description, tags) + if isempty(obj.context.sessionId) + error('CortexRecord:noSession', 'Create an active session before starting a record.'); + end + if obj.context.isRecording + error('CortexRecord:alreadyRecording', 'Stop the active record before starting another.'); + end + if ~ischar(title) || isempty(title) || numel(title) > 200 + error('CortexRecord:title', 'title must be a non-empty character vector of at most 200 characters.'); + end + if ~ischar(description) + error('CortexRecord:description', 'description must be a character vector.'); + end + if ischar(tags), tags = {tags}; end + if ~iscellstr(tags) + error('CortexRecord:tags', 'tags must be a character vector or a cell array of character vectors.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'title', title); + if ~isempty(description), params.description = description; end + if ~isempty(tags), params.tags = tags; end + + response = obj.client.sendRequest('createRecord', params); + result = response.result; + if ~isfield(result, 'record') || ~isfield(result.record, 'uuid') + error('CortexRecord:response', 'Cortex did not return the created record id.'); + end + + obj.context.recordId = char(result.record.uuid); + obj.context.isRecording = true; + end + + function result = stop(obj) + if ~obj.context.isRecording || isempty(obj.context.sessionId) + error('CortexRecord:notRecording', 'There is no active record to stop.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId); + response = obj.client.sendRequest('stopRecord', params); + result = response.result; + obj.context.isRecording = false; + obj.context.recordId = ''; + end + end +end \ No newline at end of file diff --git a/octave/internal/CortexStreamParser.m b/octave/internal/CortexStreamParser.m new file mode 100644 index 0000000..74d33fd --- /dev/null +++ b/octave/internal/CortexStreamParser.m @@ -0,0 +1,103 @@ +classdef CortexStreamParser < handle + % CortexStreamParser Turns decoded Cortex subscribe/stream messages into labels and numeric rows. + % It maps each subscription id (sid) to its stream name; storage is left to CortexDataBuffer. + + properties (Access = private) + sids = {} + streams = {} + end + + methods + function register(obj, sid, streamName) + obj.sids{end + 1} = sid; + obj.streams{end + 1} = streamName; + end + + function reset(obj) + obj.sids = {}; + obj.streams = {}; + end + + function [stream, row, time, bciAction] = parse(obj, msg) + % stream is '' when the message does not belong to a registered stream. + % bciAction is the action of a com sample, or {eyeAct, uAct, lAct} for fac ('' for other streams). + stream = ''; + row = []; + time = NaN; + bciAction = ''; + if isfield(msg, 'sid') && ischar(msg.sid) + % Streams of one session can share the same sid, so match the stream by its field name too. + candidates = find(strcmp(obj.sids, msg.sid)); + for index = candidates + if isfield(msg, obj.streams{index}) + stream = obj.streams{index}; + break; + end + end + end + if isempty(stream) || ~isfield(msg, stream) + stream = ''; + return; + end + + if isfield(msg, 'time') && isnumeric(msg.time) && ~isempty(msg.time) + time = double(msg.time); + end + row = CortexStreamParser.flattenSample(msg.(stream)); + names = CortexStreamParser.stringsOf(msg.(stream)); + if strcmp(stream, 'fac') + % fac carries three actions per sample: {eyeAct, uAct, lAct}. + bciAction = names; + elseif ~isempty(names) + bciAction = names{1}; + end + end + end + + methods (Static) + function names = stringsOf(values) + if ischar(values) + names = {values}; + elseif iscell(values) + names = values(cellfun(@ischar, values)); + names = names(:)'; + else + names = {}; + end + end + + function labels = flattenLabels(cols) + % The dev stream nests the contact-quality labels in a sub-array. + if ischar(cols) + labels = {cols}; + elseif iscell(cols) + labels = {}; + for index = 1:numel(cols) + labels = [labels, CortexStreamParser.flattenLabels(cols{index})]; %#ok + end + else + labels = {}; + end + end + + function row = flattenSample(values) + % Empty entries (null, no markers) become NaN so every row keeps the same width. + % jsondecode returns numeric, logical or cell values depending on the tool and content. + if isnumeric(values) || islogical(values) + if isempty(values) + row = NaN; + else + row = double(values(:))'; + end + elseif iscell(values) + row = []; + for index = 1:numel(values) + row = [row, CortexStreamParser.flattenSample(values{index})]; %#ok + end + if isempty(row), row = NaN; end + else + row = NaN; + end + end + end +end diff --git a/octave/internal/CortexTraining.m b/octave/internal/CortexTraining.m new file mode 100644 index 0000000..780bfc2 --- /dev/null +++ b/octave/internal/CortexTraining.m @@ -0,0 +1,125 @@ +classdef CortexTraining < handle + % CortexTraining Trains mental command or facial expression actions on the loaded profile. + % Training progress arrives as events on the "sys" stream, so subscribe to it to wait for results. + + properties (Access = private) + client + context + headset + profile + end + + methods + function obj = CortexTraining(client, context, headset, profile) + obj.client = client; + obj.context = context; + obj.headset = headset; + obj.profile = profile; + end + + function result = train(obj, detection, action, status, waitSeconds) + if nargin < 5, waitSeconds = 0; end + detection = CortexTraining.normalizeDetection(detection); + if isempty(obj.context.sessionId) + error('CortexTraining:noSession', 'Create a headset session before training.'); + end + if ~obj.context.isProfileLoaded + error('CortexTraining:noProfile', 'Load a profile before training.'); + end + if ~isnumeric(waitSeconds) || ~isscalar(waitSeconds) || waitSeconds < 0 + error('CortexTraining:wait', 'wait must be a non-negative number of seconds.'); + end + + info = obj.context.detectionInfo.(detection); + action = CortexTraining.canonical(info.actions, action, 'action', detection); + status = CortexTraining.canonical(info.controls, status, 'status', detection); + + finalEvents = {}; + switch status + case 'start' + finalEvents = {'Succeeded', 'Failed'}; + case 'accept' + finalEvents = {'Completed'}; + end + shouldWait = waitSeconds > 0 && ~isempty(finalEvents); + if shouldWait && ~any(strcmp(obj.context.subscribedStreams, 'sys')) + error('CortexTraining:noSysStream', 'Subscribe to the sys stream to wait for training events.'); + end + + obj.context.trainingEvents = {}; + params = struct('cortexToken', obj.context.token, 'detection', detection, ... + 'session', obj.context.sessionId, 'action', action, 'status', status); + obj.client.sendRequest('training', params); + + result = struct('detection', detection, 'action', action, 'status', status, ... + 'event', '', 'isSucceeded', false, 'profileSaved', false); + if ~shouldWait, return; end + + event = obj.waitForEvent(finalEvents, waitSeconds); + if isempty(event) + error('CortexTraining:timeout', 'No %s %s event within %g seconds.', ... + detection, strjoin(finalEvents, '/'), waitSeconds); + end + result.event = event; + result.isSucceeded = ~isempty(regexp(event, '_(Succeeded|Completed)$', 'once')); + + if strcmp(status, 'accept') && result.isSucceeded + try + obj.profile.save(); + result.profileSaved = true; + catch err + fprintf('[CortexTraining] Training completed but saving the profile failed: %s\n', err.message); + end + end + end + end + + methods (Access = private) + function event = waitForEvent(obj, suffixes, waitSeconds) + event = ''; + pattern = ['_(' strjoin(suffixes, '|') ')$']; + startedAt = tic(); + seen = 0; + while toc(startedAt) < waitSeconds + obj.headset.update(0.25); + events = obj.context.trainingEvents; + for index = seen + 1:numel(events) + if ~isempty(regexp(events{index}.event, pattern, 'once')) + event = events{index}.event; + return; + end + end + seen = numel(events); + end + end + end + + methods (Static, Access = private) + function detection = normalizeDetection(detection) + if ~ischar(detection) + error('CortexTraining:detection', 'detection must be ''mentalCommand'' or ''facialExpression''.'); + end + switch lower(detection) + case 'mentalcommand' + detection = 'mentalCommand'; + case 'facialexpression' + detection = 'facialExpression'; + otherwise + error('CortexTraining:detection', ... + 'detection must be ''mentalCommand'' or ''facialExpression''.'); + end + end + + function value = canonical(allowed, value, kind, detection) + if ~ischar(value) || isempty(value) + error('CortexTraining:argument', '%s must be a non-empty character vector.', kind); + end + index = find(strcmpi(allowed, value), 1); + if isempty(index) + error('CortexTraining:argument', 'Unsupported %s "%s" for %s. Supported: %s.', ... + kind, value, detection, strjoin(allowed, ', ')); + end + value = allowed{index}; + end + end +end diff --git a/octave/internal/cortexCredentials.m b/octave/internal/cortexCredentials.m new file mode 100644 index 0000000..e12d63b --- /dev/null +++ b/octave/internal/cortexCredentials.m @@ -0,0 +1,32 @@ +function [clientId, clientSecret, port] = cortexCredentials() +% cortexCredentials Load clientId, clientSecret and the optional port from config/config.json. +% port defaults to 6868 (production) when config.json has no "port" field. +% Internal: the dev environment uses port 7070; set "port": 7070 in config.json. + +configFile = fullfile(fileparts(mfilename('fullpath')), '..', 'config', 'config.json'); +if ~exist(configFile, 'file') + error('cortexCredentials:configNotFound', ... + ['Config file not found: %s. ' ... + 'Copy octave/config/config.example.json to octave/config/config.json ' ... + 'and set your clientId and clientSecret.'], configFile); +end + +config = jsondecode(fileread(configFile)); +if ~isfield(config, 'clientId') || ~isfield(config, 'clientSecret') || ... + isempty(config.clientId) || isempty(config.clientSecret) + error('cortexCredentials:invalidConfig', ... + 'octave/config/config.json must contain non-empty clientId and clientSecret fields.'); +end + +clientId = config.clientId; +clientSecret = config.clientSecret; + +port = 6868; +if isfield(config, 'port') && ~isempty(config.port) + port = config.port; + if ~isnumeric(port) || ~isscalar(port) || ~isfinite(port) || port ~= fix(port) || port < 1 || port > 65535 + error('cortexCredentials:invalidConfig', ... + 'octave/config/config.json "port" must be an integer between 1 and 65535.'); + end +end +end diff --git a/octave/java/cortex/CortexWsClient.java b/octave/java/cortex/CortexWsClient.java new file mode 100644 index 0000000..16204c6 --- /dev/null +++ b/octave/java/cortex/CortexWsClient.java @@ -0,0 +1,115 @@ +package cortex; + +import java.io.FileInputStream; +import java.io.IOException; +import java.io.InputStream; +import java.security.KeyStore; +import java.security.cert.Certificate; +import java.security.cert.CertificateFactory; +import java.util.Collection; +import java.util.concurrent.BlockingQueue; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.TimeUnit; + +import javax.net.ssl.SSLContext; +import javax.net.ssl.TrustManagerFactory; + +import com.neovisionaries.ws.client.WebSocket; +import com.neovisionaries.ws.client.WebSocketAdapter; +import com.neovisionaries.ws.client.WebSocketFactory; +import com.neovisionaries.ws.client.WebSocketFrame; +import com.neovisionaries.ws.client.WebSocketState; + +/** Polling WebSocket client for Octave/MATLAB, which cannot receive Java callbacks. */ +public class CortexWsClient { + private final BlockingQueue messages = new LinkedBlockingQueue(); + private volatile boolean closed = true; + private WebSocket socket; + + /** An empty caPath uses the JVM default trust store. */ + public void connect(String url, String caPath, int timeoutMs) throws Exception { + WebSocketFactory factory = new WebSocketFactory(); + factory.setConnectionTimeout(timeoutMs); + factory.setSocketTimeout(timeoutMs); + factory.setVerifyHostname(true); + if (caPath != null && !caPath.isEmpty()) { + factory.setSSLContext(sslContextFor(caPath)); + } + + socket = factory.createSocket(url); + socket.addListener(new WebSocketAdapter() { + @Override + public void onTextMessage(WebSocket ws, String text) { + messages.add(text); + } + + @Override + public void onStateChanged(WebSocket ws, WebSocketState newState) throws Exception { + // Runs before the reader thread starts, so idle reads must block again. + if (newState == WebSocketState.OPEN) { + ws.getSocket().setSoTimeout(0); + } + } + + @Override + public void onDisconnected(WebSocket ws, WebSocketFrame serverFrame, + WebSocketFrame clientFrame, boolean closedByServer) { + closed = true; + } + }); + + closed = false; + try { + socket.connect(); + } catch (Exception e) { + closed = true; + throw e; + } + } + + public void sendText(String text) { + if (closed) { + throw new IllegalStateException("Connection to Cortex closed."); + } + socket.sendText(text); + } + + /** Returns null on timeout; throws once the link is closed and the queue is drained. */ + public String poll(int timeoutMs) throws Exception { + String message = messages.poll(timeoutMs, TimeUnit.MILLISECONDS); + if (message == null && closed) { + throw new IOException("Connection to Cortex closed."); + } + return message; + } + + public boolean isOpen() { + return !closed; + } + + public void close() { + closed = true; + if (socket != null) { + socket.disconnect(); + } + } + + private static SSLContext sslContextFor(String caPath) throws Exception { + KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType()); + trustStore.load(null, null); + CertificateFactory certificateFactory = CertificateFactory.getInstance("X.509"); + try (InputStream in = new FileInputStream(caPath)) { + Collection certificates = certificateFactory.generateCertificates(in); + int index = 0; + for (Certificate certificate : certificates) { + trustStore.setCertificateEntry("ca" + index++, certificate); + } + } + + TrustManagerFactory trustManagers = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); + trustManagers.init(trustStore); + SSLContext context = SSLContext.getInstance("TLS"); + context.init(null, trustManagers.getTrustManagers(), null); + return context; + } +} diff --git a/octave/lib/cortex-ws-client.jar b/octave/lib/cortex-ws-client.jar new file mode 100644 index 0000000..261d6eb Binary files /dev/null and b/octave/lib/cortex-ws-client.jar differ diff --git a/octave/lib/nv-websocket-client-2.14.jar b/octave/lib/nv-websocket-client-2.14.jar new file mode 100644 index 0000000..69d6d9a Binary files /dev/null and b/octave/lib/nv-websocket-client-2.14.jar differ