> ## Documentation Index
> Fetch the complete documentation index at: https://docs.directenergypartners.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contactor

## How It Works

### Hardware Layout

Contactor is a predefined device type in the controller that handles the closing and opening of contactors based on manual control commands.
A contactor device controls up to two contactors on a DC bus connection. The main contactor is required, the reference contactor is optional.

* **Main contactor**: switches the positive line of the DC connection.
* **Reference contactor** *(optional)*: switches the negative line of the DC connection.

### Control

The contactor device is always in one of the following states:

0. **Open**: all contactors are open. The device waits for a `control.enable` command to close the contactors.
1. **Closed reference**\*: the reference contactor is closed first. The device waits for `holdReferenceInSeconds` before continuing *(\*only if a reference contactor register is defined in the address map. If not, this state is skipped and the device immediately transitions to the Closed state)*.
2. **Closed**: the main contactor is closed. The DC bus is now fully connected through the main and reference contactors. The device returns to the `Open` state when a `control.disable` command is received, or if contactor feedback is enabled and a contactor is no longer in the expected state.

* **`control.enable`**: closes the contactors.
* **`control.disable`**: opens the contactors.

If contactor feedback is enabled and a contactor does not reach its expected state within 15 seconds, all contactors are opened and the device resets to the `Open` state.

## Required Parameters

To add a contactor device, the following parameters are required.

<ParamField path="id" type="string" required>
  A unique identifier for the device.

  **Example:** `contactor1`
</ParamField>

<ParamField path="type" type="string" required>
  Indicates the type of device. For this type of device, it is always `contactor`.

  **Example:** `contactor`
</ParamField>

<ParamField path="addressMap" type="string" required>
  The name of the device's address map on the controller.

  **Example:** `contactor1_address_map`
</ParamField>

<ParamField path="disabled" type="bool" required>
  Indicates whether the device is enabled or disabled. A value of true means the device is disabled, while false means the device is enabled.
</ParamField>

## Optional Parameters

The following parameters are optional and provide additional functionality to the device.

<ParamField path="holdReferenceInSeconds" type="int">
  The duration in seconds the device remains in the `Closed reference` state, with the reference contactor closed, before closing the main contactor. Defaults to `3` seconds if not specified.

  **Example:** `5`
</ParamField>

<ParamField path="contactorFeedback" type="bool">
  Enables feedback for both contactors (main and reference) at once. When set to `true`, this is equivalent to setting `mainContactorFeedback` and `referenceContactorFeedback` both to `true`.
</ParamField>

<ParamField path="mainContactorFeedback" type="bool">
  Indicates whether feedback is enabled for the main contactor. When enabled, the address map must contain a `measure.contactor.main` register.
</ParamField>

<ParamField path="referenceContactorFeedback" type="bool">
  Indicates whether feedback is enabled for the reference contactor. When enabled, the address map must contain both a `control.contactor.reference` and a `measure.contactor.reference` register.
</ParamField>

## Example

The snippet below demonstrates a contactor device, highlighting both the required and optional parameters.

```json icon="code" theme={null}
{
  "id": "contactor1",
  "type": "contactor",
  "addressMap": "contactor1_address_map",
  "disabled": false,
  "holdReferenceInSeconds": 5,
  "contactorFeedback": true
}
```

<Warning>
  When configuring a contactor device, ensure that all required parameters are correctly specified to avoid configuration errors.
  Always verify that the paths provided for addressMap are accurate and that the files exist in the specified locations.
</Warning>