LibMuse 6.0.2
com.choosemuse.libmuse.Muse Class Referenceabstract

Public Member Functions

abstract void connect ()
 
abstract void disconnect ()
 
abstract void execute ()
 
abstract void runAsynchronously ()
 
abstract ConnectionState getConnectionState ()
 
abstract String getMacAddress ()
 
abstract String getName ()
 
abstract double getRssi ()
 
abstract double getLastDiscoveredTime ()
 
abstract void setNumConnectTries (int numTries)
 
abstract MuseConfiguration getMuseConfiguration ()
 
abstract MuseVersion getMuseVersion ()
 
abstract void registerConnectionListener (MuseConnectionListener listener)
 
abstract void unregisterConnectionListener (MuseConnectionListener listener)
 
abstract void registerDataListener (MuseDataListener listener, MuseDataPacketType type)
 
abstract void unregisterDataListener (MuseDataListener listener, MuseDataPacketType type)
 
abstract void registerErrorListener (MuseErrorListener listener)
 
abstract void unregisterErrorListener (MuseErrorListener listener)
 
abstract void unregisterAllListeners ()
 
abstract void setPreset (MusePreset preset)
 
abstract void enableDataTransmission (boolean enable)
 
abstract void setNotchFrequency (NotchFrequency newFrequency)
 
abstract boolean isLowEnergy ()
 
abstract boolean isPaired ()
 
abstract void enableException (boolean enable)
 

Detailed Description

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:

  1. calling runAsynchronously()
  2. calling connect() on your own and then repeatedly calling execute().

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.

Member Function Documentation

§ connect()

abstract void com.choosemuse.libmuse.Muse.connect ( )
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.

§ disconnect()

abstract void com.choosemuse.libmuse.Muse.disconnect ( )
abstract

Disconnects your mobile device from Muse Headband.

If you are calling execute() on your own, remember to continue calling execute() until you receive the DISCONNECTED event.

Threading: method is thread-safe.

If you don't want to receive disconnection event, unregister listeners manually first.

§ enableDataTransmission()

abstract void com.choosemuse.libmuse.Muse.enableDataTransmission ( boolean  enable)
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.

Parameters
enabletrue to start streaming data. false to pause the data stream.

§ enableException()

abstract void com.choosemuse.libmuse.Muse.enableException ( boolean  enable)
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.

Parameters
enabletrue to enable exception to be thrown. false to disable.

§ execute()

abstract void com.choosemuse.libmuse.Muse.execute ( )
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.

§ getConnectionState()

abstract ConnectionState com.choosemuse.libmuse.Muse.getConnectionState ( )
abstract

Returns current connection state.

Threading: method is thread-safe.

Returns
The current connection state.

§ getLastDiscoveredTime()

abstract double com.choosemuse.libmuse.Muse.getLastDiscoveredTime ( )
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.

Returns
The time at which this device was most recently discovered.

§ getMacAddress()

abstract String com.choosemuse.libmuse.Muse.getMacAddress ( )
abstract

Returns Bluetooth MAC address of the Muse Headband.

Threading: method is thread-safe.

Returns
The MAC address of the Muse Headband.

§ getMuseConfiguration()

abstract MuseConfiguration com.choosemuse.libmuse.Muse.getMuseConfiguration ( )
abstract

Returns struct which contains all information about Muse configuration.

Threading: method is thread-safe.

Warning
The Muse Configuration object is only populated during connection routine or after headband settings (like preset or notch frequency) are changed. If this is called before the Muse is connected, the configuration will be null.
Returns
The configuration information of this Muse or null if the configuration is unknown.

§ getMuseVersion()

abstract MuseVersion com.choosemuse.libmuse.Muse.getMuseVersion ( )
abstract

Returns all information about the version of the Muse.

Threading: method is thread-safe.

Warning
The Muse Version is populated during connection routine only. If this is called before the Muse is connected, the version will be null.
Returns
The version of this Muse or null if the version is unknown.

§ getName()

abstract String com.choosemuse.libmuse.Muse.getName ( )
abstract

Returns Bluetooth name of the Muse Headband.

Threading: method is thread-safe.

Returns
The name of the Muse Headband.

§ getRssi()

abstract double com.choosemuse.libmuse.Muse.getRssi ( )
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.

Returns
The RSSI of a low-energy Muse or NaN if the Muse is not low-energy.

§ isLowEnergy()

abstract boolean com.choosemuse.libmuse.Muse.isLowEnergy ( )
abstract

True if this device supports Bluetooth Low-Energy.

Returns
true if this Muse supports Bluetooth Low-Energy. false if it does not.

§ isPaired()

abstract boolean com.choosemuse.libmuse.Muse.isPaired ( )
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.

Returns
true if the Muse is paired with the OS, false otherwise.

§ registerConnectionListener()

abstract void com.choosemuse.libmuse.Muse.registerConnectionListener ( MuseConnectionListener  listener)
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.

Parameters
listenerThe listener to register.

§ registerDataListener()

abstract void com.choosemuse.libmuse.Muse.registerDataListener ( MuseDataListener  listener,
MuseDataPacketType  type 
)
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.

Parameters
listenerThe listener to register.
typeThe type of data packet the listener will receive.

§ registerErrorListener()

abstract void com.choosemuse.libmuse.Muse.registerErrorListener ( MuseErrorListener  listener)
abstract

Registers an error listener.

Threading: method is thread-safe.

Parameters
listenerThe listener to register.

§ runAsynchronously()

abstract void com.choosemuse.libmuse.Muse.runAsynchronously ( )
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

  1. as a result of a DISCONNECTED packet, and
  2. on a different thread from the one that delivered the notification.

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.

§ setNotchFrequency()

abstract void com.choosemuse.libmuse.Muse.setNotchFrequency ( NotchFrequency  newFrequency)
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.

Warning
This is only supported on Muse 2014 ( MU_01 ) headbands and then only with presets:
MusePreset.PRESET_10 , MusePreset.PRESET_12 and MusePreset.PRESET_14 . Under those presets, the only valid frequencies are: NotchFrequency.NOTCH_50HZ NotchFrequency.NOTCH_60HZ
Calling this with NotchFrequency.NOTCH_NONE will do nothing.
This does nothing on Muse 2016 ( MU_02 ) headbands and on Muse 2014 ( MU_01 ) headbands with presets MusePreset.PRESET_AB or MusePreset.PRESET_AD
Parameters
newFrequencyThe new notch frequency.

§ setNumConnectTries()

abstract void com.choosemuse.libmuse.Muse.setNumConnectTries ( int  numTries)
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.

Parameters
numTriesThe number of times to try to connect before giving up.

§ setPreset()

abstract void com.choosemuse.libmuse.Muse.setPreset ( MusePreset  preset)
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.

Parameters
presetThe new preset.

§ unregisterAllListeners()

abstract void com.choosemuse.libmuse.Muse.unregisterAllListeners ( )
abstract

Unregisters all registered connection listeners and data listeners.

Threading: method is thread-safe.

§ unregisterConnectionListener()

abstract void com.choosemuse.libmuse.Muse.unregisterConnectionListener ( MuseConnectionListener  listener)
abstract

Unregisters connection listeners.

Threading: method is thread-safe.

Parameters
listenerThe listener to unregister.

§ unregisterDataListener()

abstract void com.choosemuse.libmuse.Muse.unregisterDataListener ( MuseDataListener  listener,
MuseDataPacketType  type 
)
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.

Parameters
listenerThe listener to unregister.
typeThe type of data packet the listener will stop receiving.

§ unregisterErrorListener()

abstract void com.choosemuse.libmuse.Muse.unregisterErrorListener ( MuseErrorListener  listener)
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.

Parameters
listenerThe listener to unregister.

The documentation for this class was generated from the following file: