# Headset object

Some methods of the API return one or more headset objects, for example [queryHeadsets](queryheadsets). A [session object](../session/session-object) also includes a headset object.

## Description

A headset object include these fields:

| Name             | Type               | Description                                                                                                                                                                                                                                                                                                                          |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id               | `string`           | The id of this headset.                                                                                                                                                                                                                                                                                                              |
| status           | `string`           | Can be "discovered", "connecting", or "connected".                                                                                                                                                                                                                                                                                   |
| connectedBy      | `string`           | Can be "bluetooth", "dongle", "usb cable", or "extender".                                                                                                                                                                                                                                                                            |
| dongle           | `string`           | The version of the dongle firmware.                                                                                                                                                                                                                                                                                                  |
| firmware         | `string`           | The version of the headset firmware.                                                                                                                                                                                                                                                                                                 |
| motionSensors    | `array of strings` | The names of the motion sensors of this headset.                                                                                                                                                                                                                                                                                     |
| sensors          | `array of strings` | The names of the EEG sensors of this headset. Use the international 10-20 system.                                                                                                                                                                                                                                                    |
| settings         | `object`           | An object containing the configuration of the EEG and motion data of this headset.                                                                                                                                                                                                                                                   |
| flexMappings     | `object`           | If the headset is an EPOC Flex, then this field is an object containing information about the mapping of the EEG channels.                                                                                                                                                                                                           |
| headbandPosition | `string`           | <p>If the headset is an EPOC X, then this field tells you the position of the headband of this headset. Can be "back" or "top".<br>If the headset is not an EPOC X, then this field is null.<br>See <a href="updateheadsetcustominfo">updateHeadsetCustomInfo</a> for details.</p><p><em>This field was added in Cortex 2.4</em></p> |
| customName       | `string`           | <p>The custom name of the headset. The user can set it in EMOTIV App.</p><p><em>This field was added in Cortex 2.4</em></p>                                                                                                                                                                                                          |

### Status

When you want to work with a headset, it is important to check its status.&#x20;

| Status     | Description                                                                                                                                                                                                                                                       |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| discovered | <p>Cortex has detected the headset, but it is not connected. You cannot create a session for a discovered headset.<br>You can call <a href="controldevice">controlDevice</a> to connect the headset.</p>                                                          |
| connecting | Cortex is trying to connect to this headset. This can take a few seconds.                                                                                                                                                                                         |
| connected  | <p>Cortex is connected to and receives data from this headset. You can call <a href="../session/createsession">createSession</a> and start working with this headset.</p><p>You can call <a href="controldevice">controlDevice</a> to disconnect the headset.</p> |

### Settings

The **settings** object include these fields:

| Name     | Type     | Description                              |
| -------- | -------- | ---------------------------------------- |
| mode     | `string` | Can be "EPOC", "EPOCPLUS", or "EPOCFLEX" |
| eegRate  | `number` | The EEG sample rate, in hertz.           |
| eegRes   | `number` | The EEG resolution, in bits.             |
| memsRate | `number` | The motion data sample rate, in hertz.   |
| memsRes  | `number` | The motion data resolution, in bits.     |

For an Epoc+ headset, the mode can be "EPOC" or "EPOCPLUS", depending on its configuration. See [updateHeadset](updateheadset) for details.\
For an Insight or Epoc headset, the mode is always "EPOC".\
For an Epoc Flex headset, the mode is always "EPOCFLEX".

{% hint style="info" %}
A motion rate of zero means that the motion sensors are disabled.
{% endhint %}

### Flex Mapping

Currently, the **flexMappings** object contains a single field. It may include more fields in the future.

| Name     | Type     | Description                                                                                                                                                                                                                                                             |
| -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mappings | `object` | <p>Describe which EEG channel is mapped to which physical connector of EPOC Flex device. The keys are the names of the connectors, the values are the names of the EEG channels.</p><p>Example: { "CMS": "TP8", "DRL": "P6", "RM": "TP10", "RN": "P4", "RO": "P8" }</p> |

## Examples

### Insight

```javascript
{
  "id": "INSIGHT-AAAA0000",
  "status": "connected",
  "connectedBy": "dongle",
  "customName": "",
  "dongle": "6ff",
  "firmware": "930",
  "motionSensors": [
    "Q0",
    "Q1",
    "Q2",
    "Q3",
    "ACCX",
    "ACCY",
    "ACCZ",
    "MAGX",
    "MAGY",
    "MAGZ"
  ],
  "sensors": [
    "AF3",
    "T7",
    "Pz",
    "T8",
    "AF4"
  ],
  "settings": {
    "eegRate": 128,
    "eegRes": 14,
    "memsRate": 64,
    "memsRes": 14,
    "mode": "INSIGHT"
  }
}
```

### Epoc+

```javascript
{
    "id": "EPOCPLUS-3B9AXXXX",
    "status": "connected",
    "connectedBy": "dongle",
    "customName": "",
    "dongle": "6ff",
    "firmware": "625",
    "motionSensors": [
        "GYROX",
        "GYROY",
        "GYROZ",
        "ACCX",
        "ACCY",
        "ACCZ",
        "MAGX",
        "MAGY",
        "MAGZ"
    ],
    "sensors": [
        "AF3",
        "F7",
        "F3",
        "FC5",
        "T7",
        "P7",
        "O1",
        "O2",
        "P8",
        "T8",
        "FC6",
        "F4",
        "F8",
        "AF4"
    ],
    "settings": {
        "eegRate": 256,
        "eegRes": 16,
        "memsRate": 64,
        "memsRes": 16,
        "mode": "EPOCPLUS"
    }
}
```
