update refresh headset

Documentation/ReleaseNotes.md

@@ -1,5 +1,9 @@
 # <a id="release-notes"></a>Release Notes
 
+## Version 3.7 (November 2023)
+### Added
+- Support new headset refreshing flow where App need to to call ScanHeadsets() to start headset scanning.
+
 ## Version 2.7 2(10 July 2021)
 ### Added
 - Support injectMarker and updateMarker to EEG data stream.

README.md

@@ -22,8 +22,9 @@ In the previous version, there were 3 main classes DataStreamManager.cs will han
 
 1. Firstly, you need to initialize via Init(). You need to set clientId, clientSecret of your application and set isDataBufferUsing = false if you don't want to save subscribed data to DataBuffer before obtaining.
 2. Then call Start() to start connecting to Cortex and authorize the application.
-3. Connect to a headset and create and activate a session with the headset via CreateSessionWithHeadset(string headsetId). The headsetId has a format such as EPOCX-12345. If you set an empty string for the headsetId, unity-plugin will use the first headset in the headset list.
-4. After a session is activated successfully, You can create a record, subscribe data or load a profile for training.  
+3. From Emotiv Cortex 3.7, you need to call ScanHeadsets() at DataStreamManager.cs to start headset scanning. Otherwise your headsets might not appeared in the headset list return from queryHeadsets(). If IsHeadsetScanning = false, you need re-call the ScanHeadsets() if want to re-scan headsets again.
+4. Connect to your headset in the headset list via CreateSessionWithHeadset(string headsetId) method. It will connect, then create a working session with the headset. The headsetId has a format such as EPOCX-12345. If you set an empty string for the headsetId, unity-plugin will use the first headset in the headset list.
+5. After a session is activated successfully, You can create a record, subscribe data or load a profile for training.  
 	- **Start and Stop Record**: create a record via StartRecord(). The record title is a required parameter. You can stop the record via StopRecord().
 	- **Inject Marker**: You can inject an instance marker into the record via InjectMarker(). The markerValue and markerLabel are required parameters. You also can update the current instance marker via UpdateMarker() to make the marker to interval marker.  
 	- **Subscribe and UnSubscribe Data**: You can subscribe to one or more data streams via SubscribeData(list_data_streams). Currently, the unity-plugin support EEG(eeg), Motion (mot),Device Information (dev), Facial Expression(fac), Mental Command (com), Performance metrics(met), System Event (sys), Band power (pow) data streams. There are 2 choices for output data retrieving:

Src/Config.cs

@@ -78,6 +78,7 @@ public static class WarningCode
         public const int HeadsetDataTimeOut       = 103;
         public const int HeadsetConnected         = 104;
         public const int BTLEPermissionNotGranted = 31;
+        public const int HeadsetScanFinished      = 142;
     }
 
     public static class DevStreamParams

Src/CortexClient.cs

@@ -103,6 +103,7 @@ public class CortexClient
         public event EventHandler<string> StreamStopNotify;
         public event EventHandler<string> SessionClosedNotify;
         public event EventHandler<string> RefreshTokenOK;
+        public event EventHandler<string> HeadsetScanFinished;
 
         public event EventHandler<bool> BTLEPermissionGrantedNotify; // notify btle permision grant status
 
@@ -329,11 +330,7 @@ private void HandleResponse(string method, JToken data)
             else if (method == "controlDevice")
             {
                 string command = (string)data["command"];
-                if (command == "connect") 
-                {
-                    string message = (string)data["message"];
-                }
-                else if (command == "disconnect")
+                if (command == "disconnect")
                 {
                     HeadsetDisConnectedOK(this, true);
                 }
@@ -560,11 +557,6 @@ private void HandleWarning(int code, JToken messageData)
                 string message = messageData.ToString();
                 UserLogoutNotify(this, message);
             }
-            else if (code == WarningCode.UserLogout)
-            {
-                string message = messageData.ToString();
-                UserLogoutNotify(this, message);
-            }
             else if (code == WarningCode.HeadsetConnected) {
                 string headsetId = messageData["headsetId"].ToString();
                 string message = messageData["behavior"].ToString();
@@ -583,6 +575,11 @@ private void HandleWarning(int code, JToken messageData)
                 // the current profile is unloaded automatically
                 UnloadProfileDone(this, true);
             }
+            else if (code == WarningCode.HeadsetScanFinished)
+            {
+                string message = messageData["behavior"].ToString();
+                HeadsetScanFinished(this, message);
+            }
         }
 
         /// <summary>

Src/DataStreamManager.cs

@@ -48,6 +48,8 @@ public class DataStreamManager
         bool _isDataBufferUsing = true; // use data buffer to store subscribed data for eeg, pm, cq, eq, pow, motion
         List<Headset>  _detectedHeadsets = new List<Headset>(); // list of detected headsets
 
+        private bool _isHeadsetScanning = false;
+
         public event EventHandler<string> SessionActivatedOK;
         public event EventHandler<string> HeadsetConnectFail;
         public event EventHandler<DateTime> LicenseValidTo;
@@ -69,6 +71,8 @@ public event EventHandler<bool> BTLEPermissionGrantedNotify
         public event EventHandler<MentalCommandEventArgs> MentalCommandReceived;     // mental command
         public event EventHandler<SysEventArgs> SysEventsReceived;  // System events for training
 
+        public event EventHandler<string> HeadsetScanFinished;
+
         private DataStreamManager()
         {
             Init();
@@ -81,6 +85,8 @@ private DataStreamManager()
         public bool IsDataBufferUsing { get => _isDataBufferUsing; set => _isDataBufferUsing = value; }
         public bool IsSessionCreated {get => _isSessActivated;}
 
+        public bool IsHeadsetScanning { get => _isHeadsetScanning;}
+
         private void Init()
         {
             _dsProcess.ProcessInit();
@@ -94,6 +100,7 @@ private void Init()
             _dsProcess.QueryHeadsetOK           += OnQueryHeadsetOK;
             _dsProcess.UserLogoutNotify         += OnUserLogoutNotify;
             _dsProcess.SessionClosedNotify      += OnSessionClosedNotify;
+            _dsProcess.HeadsetScanFinished      += OnHeadsetScanFinished;
         }
 
         /// <summary>
@@ -202,7 +209,6 @@ private void OnSessionActivedOK(object sender, SessionEventArgs sessionInfo)
                 if (sessionInfo.HeadsetId == _wantedHeadsetId) {
                     _isSessActivated    = true;
                     _readyCreateSession = false;
-
                     SessionActivatedOK(this, _wantedHeadsetId);
                     // subscribe data
                     _dsProcess.SubscribeData();
@@ -485,6 +491,13 @@ private void CloseSession()
             }
         }
 
+        private void OnHeadsetScanFinished(object sender, string message)
+        {
+            UnityEngine.Debug.Log(message);
+            // Reset _isHeadsetScanning when get headset scan finished
+            _isHeadsetScanning = false;
+        }
+
         /// <summary>
         /// Start authorizing process.
         /// </summary>
@@ -936,5 +949,14 @@ public string GetWantedHeadset() {
                 return _wantedHeadsetId;
             }
         }
+
+        /// <summary>
+        /// ScanHeadsets to trigger scan headsets from Cortex
+        /// </summary>
+        public void ScanHeadsets() {
+            UnityEngine.Debug.Log("Start scanning headset.");
+            _isHeadsetScanning = true;
+            _dsProcess.RefreshHeadset();
+        }
     }
 }

Src/DataStreamProcess.cs

@@ -65,6 +65,11 @@ public event EventHandler<bool> BTLEPermissionGrantedNotify
             add { _ctxClient.BTLEPermissionGrantedNotify += value; }
             remove { _ctxClient.BTLEPermissionGrantedNotify -= value; }
         }
+        public event EventHandler<string> HeadsetScanFinished
+        {
+            add { _ctxClient.HeadsetScanFinished += value; }
+            remove { _ctxClient.HeadsetScanFinished -= value; }
+        }
 
         /// <summary>
         /// Gets states when work with cortex.
@@ -129,6 +134,7 @@ private void OnLicenseExpired(object sender, License lic)
         private void OnGetLicenseInfoDone(object sender, License lic)
         {
             LicenseValidTo(this, lic.validTo);
+            // auto scan headset
             _headsetFinder.FinderInit();
         }
 
@@ -439,5 +445,12 @@ public void ForceCloseWebsocket()
         {
             _ctxClient.ForceCloseWSC();
         }
+
+        /// <summary>
+        /// Refresh headset to trigger scan btle devices from Cortex
+        /// </summary>
+        public void RefreshHeadset() {
+            _headsetFinder.RefreshHeadset();
+        }
     }
 }

Src/HeadsetFinder.cs

@@ -13,7 +13,6 @@ namespace EmotivUnityPlugin
     public class HeadsetFinder
     {
         private CortexClient _ctxClient = CortexClient.Instance;
-
 
         /// <summary>
         /// Timer for querying headsets
@@ -57,6 +56,9 @@ public void StopQueryHeadset() {
                 _aTimer.Stop();
             }
         }
+        public void RefreshHeadset() {
+            _ctxClient.ControlDevice("refresh", "", null);
+        }
 
         /// <summary>
         /// Setup query headset timer