Skip to main content

​
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:
  1. Open: all contactors are open. The device waits for a control.enable command to close the contactors.
  2. 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).
  3. 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.
​
id
string
required
A unique identifier for the device.Example: contactor1
​
type
string
required
Indicates the type of device. For this type of device, it is always contactor.Example: contactor
​
addressMap
string
required
The name of the device’s address map on the controller.Example: contactor1_address_map
​
disabled
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.

​
Optional Parameters

The following parameters are optional and provide additional functionality to the device.
​
holdReferenceInSeconds
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
​
contactorFeedback
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.
​
mainContactorFeedback
bool
Indicates whether feedback is enabled for the main contactor. When enabled, the address map must contain a measure.contactor.main register.
​
referenceContactorFeedback
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.

​
Example

The snippet below demonstrates a contactor device, highlighting both the required and optional parameters. 
{
  "id": "contactor1",
  "type": "contactor",
  "addressMap": "contactor1_address_map",
  "disabled": false,
  "holdReferenceInSeconds": 5,
  "contactorFeedback": true
}
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.