# updateHeadset

This method lets you change the settings of an EPOC+ or EPOC X headset.

You can configure the EEG sample rate, EEG resolution, motion data sample rate, and motion data resolution. You can check the current settings of a headset using the method [queryHeadsets](/cortex-api/headset/queryheadsets.md).

This method is for EPOC+ and EPOC X headsets only. There are no configuration settings for other EMOTIV headsets.

Please note that updating the configuration of a headset can take a few seconds.

{% hint style="info" %}
The user must connect the headset to the computer by using a USB cable before calling this method. You can't configure the headset through a wireless connection. You can use [queryHeadsets](/cortex-api/headset/queryheadsets.md) to check how the headset is connected.
{% endhint %}

## Parameters

| Name        | Type     | Required | Description                                                                     |
| ----------- | -------- | -------- | ------------------------------------------------------------------------------- |
| cortexToken | `string` | yes      | A token returned by [authorize](/cortex-api/authentication/authorize.md).       |
| headset     | `string` | yes      | A headset id returned by [queryHeadsets](/cortex-api/headset/queryheadsets.md). |
| setting     | `object` | yes      | An object containing the setting to apply. See below.                           |

The **setting** parameter must be an object with these fields:

| Name     | Type     | Required | Description                                                                                                                                                                          |
| -------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mode     | `string` | yes      | <p>Must be "EPOC" or "EPOCPLUS".</p><p>In "EPOC" mode, the EEG resolution is 14 bits.</p><p>In "EPOCPLUS" mode, the EEG and motion resolutions are 16 bits.</p>                      |
| eegRate  | `number` | yes      | <p>The EEG sample rate, in hertz.<br>If the mode is "EPOC", then the EEG rate must be 128.</p><p>If the mode is "EPOCPLUS", then the EEG rate can be 128 or 256.</p>                 |
| memsRate | `number` | yes      | <p>The motion sample rate, in hertz.</p><p>If the mode is "EPOC", then the motion rate must be 0.</p><p>If the mode is "EPOCPLUS", then the motion rate can be 0, 32, 64 or 128.</p> |

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

## Result

The result is an object containing these fields:

| Name      | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| headsetId | `string` | The headset id you set in the parameters. |
| message   | `string` | A success message.                        |

In Cortex 2.3.0 and earlier, you just need to check the result of the method. If the method doesn't return any error, then it means that the update is successful.

However, since Cortex 2.4.0, the result of the method just tells you that the update is in progress. You must wait for a warning object with [code 110 or 111](/cortex-api/warning-objects.md#110-headset-update-successful) to know if the update is successful or not.

If your configuration is not compatible with a Bluetooth connection then you will receive a warning with [code 112](/cortex-api/warning-objects.md#112-headset-configuration-cannot-work-with-bluetooth). Your configuration will work fine with a USB dongle. To use the headset with a Bluetooth connection, you must set the EEG rate to 128Hz and disable the motion sensors.

## Examples

Set the EEG rate to 256 hertz (16 bits) and the motion rate to 64 hertz (16bits)

{% tabs %}
{% tab title="Request" %}

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "updateHeadset",
    "params": {
        "cortexToken": "xxx",
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "setting": {
            "mode": "EPOCPLUS",
            "eegRate": 256,
            "memsRate": 64
        }
    }
}
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "message": "..."
    }
}
```

{% endtab %}
{% endtabs %}

Set the EPOC+ headset in EPOC mode, EEG rate at 128 hertz (14 bits) and disable the motion sensors.

{% tabs %}
{% tab title="Request" %}

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "updateHeadset",
    "params": {
        "cortexToken": "xxx",
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "setting": {
            "mode": "EPOC",
            "eegRate": 128,
            "memsRate": 0
        }
    }
}
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "message": "..."
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://emotiv.gitbook.io/cortex-api/headset/updateheadset.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.