|
LibMuse 6.0.3
|
|
|
LibMuse 6.0.3
|
|
Provides the client interface to a specific Muse Headband.
This class maps to a single Muse Headband, providing an API for receiving connection events and data packets, as well as the ability to inspect various properties of the headband it corresponds to. Users can initiate and halt a connection to the device, enable data transmission, find out the human-readable name of the headband, etc.
This class should never be constructed directly by a user; rather, references to it can be retrieved from MuseManager.
There are two main ways of interacting with a Muse:
If you call runAsynchronously(), you do not need to call connect() or execute() on your own. Everything is taken care of by LibMuse for the duration of the connection (i.e. until you receive a disconnected event).
If you call connect() on your own, you are responsible for calling execute() on your own as well. Execute performs small, non-blocking steps of work such as initiating a connection, streaming data or disconnecting. If execute() is not called, no work is performed. The Muse will not transition its connection state and you will not receive any data. If you are using this method of interacting with a Muse you need to continue calling execute() until you receive a DISCONNECTED event through a registered connection listener. It may take multiple execute calls to reach the DISCONNECTED after issuing the disconnect request. Failure to wait for the DISCONNECTED event can result in unanticipated consequences.
|
abstract |
Initiate a connection to a Muse headband.
This call is non-blocking and returns immediately. Since this returns before the connection is established, you should instead use a connection listener to implement any logic, such as updating a UI element, on successful connection. When the connection is successful you will receive a CONNECTED event. If the connection is unsuccessful you will receive a DISCONNECTED event.
Threading: method is thread-safe.
|
abstract |
|
abstract |
Starts/stops data transmission (but keep-alive packets will be still sent). If you're using low-level interface (connect + execute), you should still call execute() to continue sending keep-alive messages. If you're using runAsynchronously(), then it will take care about sending keep-alive packets.
Threading: method is thread-safe. You can call it in the middle of an execute operation. If method is called before connection is established, the right setting will be passed to device during connection routine.
| enable | true to start streaming data. false to pause the data stream. |
|
abstract |
Enable/disable libmuse to rethrow any exceptions caught in your app code from the various listeners. For example, if there is a bug in your data listener code that results in an exception. Libmuse will catch that and it can rethrow that to cause your app to crash if enabled. Or if disabled it will swallow that exception and prevent the app from crashing. It is useful to enable this in development to help track down any bugs in your code more easily. It is best to disable this in production code to prevent your app from crashing. If this method is not called, the default is disabled.
| enable | true to enable exception to be thrown. false to disable. |
|
abstract |
Runs a single, non-blocking step of processing.
Reads data from Bluetooth if there is any; updates the connection state; sends packets to listeners; etc. This should be called relatively frequently: max 250ms, ideally 20ms.
If you are listening for computed values (e.g. band powers) rather than just raw EEG samples, then be aware that this method may trigger some amount of processing in the foreground before it returns. If this has undesirable effects on app performance, then you may want to move it to a dedicated thread.
Also be aware that all packets will be received on the same thread as execute() is run.
Threading: This method is NOT thread safe. You must synchronize the Muse object on your own if you wish to call it concurrently from more than one thread.
|
abstract |
Returns current connection state.
Threading: method is thread-safe.
|
abstract |
Returns the time at which this device was most recently discovered.
Muse devices broadcast service information every few seconds, and this is the last time LibMuse has heard this broadcast info.
Only implemented on low-energy Muses. Returns NaN if called on non-low-energy Muses.
The value is in microseconds since some common start time (e.g. epoch, device start time, or app start time) that is guaranteed not to change within a running app process. The value may be used e.g. to determine which of two devices was discovered more recently than the other. It should not be used as an absolute time, nor should the common start time be assumed to be the same between any two running app instances.
|
abstract |
Returns Bluetooth MAC address of the Muse Headband.
Threading: method is thread-safe.
|
abstract |
Returns struct which contains all information about Muse configuration.
Threading: method is thread-safe.
null. null if the configuration is unknown.
|
abstract |
Returns all information about the version of the Muse.
Threading: method is thread-safe.
null. null if the version is unknown.
|
abstract |
Returns Bluetooth name of the Muse Headband.
Threading: method is thread-safe.
|
abstract |
Returns the RSSI of this device.
Only implemented on low-energy Muses. Returns NaN if called on non-low-energy Muses.
Threading: method is thread-safe.
|
abstract |
True if this device supports Bluetooth Low-Energy.
true if this Muse supports Bluetooth Low-Energy. false if it does not.
|
abstract |
Returns true if the Muse is paired with the OS, false otherwise. This will always return true for Muse 2014 ( MU_01 ). For Muse 2016 ( MU_02 ) headbands this will return false on Android and iOS. For Muse 2016 ( MU_02 ) headbands on Windows, this will return true if the headband is paired with the OS and false if it is not.
true if the Muse is paired with the OS, false otherwise.
|
abstract |
Registers a connection listener. The same listener cannot be registered twice. If the listener was already registered, then this method does nothing.
Threading: method is thread-safe.
| listener | The listener to register. |
|
abstract |
Registers a data listener. You can register the same listener to listen for different packet types - just call this method again. It's your responsibility to make sure that the listener handles all packet types correctly.
If this listener was already registered for this specific type then this method does nothing.
Threading: method is thread-safe.
| listener | The listener to register. |
| type | The type of data packet the listener will receive. |
|
abstract |
Registers an error listener.
Threading: method is thread-safe.
| listener | The listener to register. |
|
abstract |
Connect to a headband out of the main logic flow.
This method handles all the connection logic for a single connection to a headband (i.e. starting with issuing a "connecting" event and ending with issuing a "disconnected" event). It may run in a separate thread or an event loop on the main thread; the details are platform-specific.
If this method is used, then all packets are delivered on the main thread.
The lifetime of effect of this method ends on disconnection; if you want to initiate a new connection to a headband that has disconnected, you should call runAsynchronously() on it again.
If this method is called multiple times within the lifetime of a single connection, any subsequent calls will do nothing other than print a log message.
Note that there is currently a race condition if runAsynchronously() is called
This will be resolved in a future library release. For now, call runAsynchronously() on the same thread that sent the DISCONNECTED packet, or after some modest delay (say 1 second.)
Threading: This method is thread safe.
|
abstract |
Changes notch frequency (power line frequency).
Threading: method is thread-safe. You can call it in the middle of execute operation, but in this case be aware that this operation will interrupt data streaming to set new notch frequency. Data streaming will be restored after that. If method is called before a connection is established, the right setting will be passed to device during connection routine.
When combining a call setNotchFrequency with Muse.setPreset() setNotchFrequency can be called before or after the call to Muse.setPreset() The notch frequency will be applied to the preset after the preset is set.
| newFrequency | The new notch frequency. |
|
abstract |
When LibMuse tries connect to a Muse, it will by default try 3 times before giving up. This function allows you to change the number of tries from 3 to anything you want. num_tries must be a positive integer. This function only works for model MU-02 Muses, calling it on a MU-01 will do nothing. This function was added for internal testing purposes, and we do not anticipate that 3rd party clients of the LibMuse library will need to modify this value.
Threading: This method is thread safe.
| numTries | The number of times to try to connect before giving up. |
|
abstract |
Changes Muse Headband settings. Look at http://developer.choosemuse.com/hardware-firmware/headband-configuration-presets for details.
Threading: method is thread-safe. You can call it in the middle of execute operation, but in this case be aware that this operation will interrupt data streaming to set new preset. Data streaming will be restored after that. If method is called before connection is established, the right setting will be passed to device during connection routine.
| preset | The new preset. |
|
abstract |
Unregisters all registered connection listeners and data listeners.
Threading: method is thread-safe.
|
abstract |
Unregisters connection listeners.
Threading: method is thread-safe.
| listener | The listener to unregister. |
|
abstract |
Unregisters a data listener that was registered before.
If the listener was not registered before, then this method does nothing.
Threading: method is thread-safe.
| listener | The listener to unregister. |
| type | The type of data packet the listener will stop receiving. |
|
abstract |
Unregisters an info listener that was registered before.
If the listener was not registered before, then this method does nothing.
Threading: method is thread-safe.
| listener | The listener to unregister. |
1.8.12