Skip to main content

​
How It Works

​
Hardware Layout

Precharge is a predefined device type in the controller that automatically handles the precharge logic and the closing of contactors, based on a voltage measurement or setpoint. A precharge device controls up to three contactors on a DC bus connection. The main and auxiliary contactors are 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.
  • Auxiliary contactor: switches the precharge contactor, placed in series with a precharge resistor. It is used to limit inrush current during startup.
Precharge Layout

​
Voltage Source

The precharge logic requires a voltage measurement to determine when to start or stop the sequence. The voltage can come from two sources:
  • Setpoint (status.voltage): a value written directly to the precharge device, for example by another device or a control script.
  • Analog measurement (measure.voltage): a value forwarded from a connected analog measuring device via analogMeasurementAddressMap. When an analog address map is configured, this source takes priority over the voltage setpoint.

​
Precharge Sequence

The precharge device is always in one of the following states:
  1. Open: all contactors are open. The device monitors the voltage measurement or setpoint and waits for the conditions to start the precharge sequence. The sequence starts when the voltage rises above tresholdVoltage (and below maximumVoltage, if configured). If breakerFeedback is enabled, a valid breaker signal is also required.
  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 Precharging state).
  3. Precharging: the auxiliary contactor is closed, allowing current to flow through the precharge resistor. The device waits for prechargePeriodInSeconds to allow the DC link capacitance to charge.
  4. Closed with auxiliary: the main contactor is closed. The auxiliary contactor remains closed for holdAuxiliaryInSeconds to ensure a controlled transition before it is opened.
  5. Closed: the auxiliary contactor opens. The DC bus is now fully connected through the main and reference contactors.
The device returns to the Open state if the voltage drops below tresholdVoltage, exceeds maximumVoltage (if configured), the breaker signal is lost (if breakerFeedback is enabled), or the main or reference contactor feedback is lost (if the respective feedback options are enabled). If contactor feedback is enabled and a contactor does not reach its expected state within 15 seconds, the precharge sequence is aborted and restarted from the beginning. If maxFeedbackRetries is configured, the device counts each such retry. When the maximum number of retries is reached, the device enters a fault state and requires a control.reset command before it can resume normal operation.

​
Manual Control

For testing purposes (for example, to verify the precharge configuration and contactor wiring), the precharge sequence can be controlled manually by writing commands directly to the precharge device:
  • control.enable: manually starts the precharge sequence, regardless of the voltage measurement or setpoint.
  • control.disable: manually stops the precharge sequence and opens all contactors.
After using manual control, use control.reset to clear the manual enable/disable state and return to normal operation, where the precharge sequence is driven by the voltage measurement or setpoint.

​
Required Parameters

To add a precharge device, the following parameters are required.
​
id
string
required
A unique identifier for the device.Example: battery1_precharge
​
type
string
required
Indicates the type of device. For this type of device, it is always precharge.Example: precharge
​
addressMap
string
required
The name of the device’s address map on the controller.Example: battery1_precharge_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.
​
prechargePeriodInSeconds
int
required
The duration in seconds the device remains in the Precharging state, with the auxiliary contactor closed, before closing the main contactor.Example: 10
​
holdAuxiliaryInSeconds
int
required
The duration in seconds the auxiliary contactor remains closed after the main contactor has been closed.Example: 2
​
tresholdVoltage
int
required
The minimum voltage in volts required to start the precharge sequence. While in the Open state, the device waits until the voltage measurement or setpoint rises above this value before initiating the sequence. If the voltage drops below this value while in the Closed state, the device opens all contactors and returns to the Open state.Example: 700

​
Optional Parameters

The following parameters can be added to digital input or output devices; however, they are optional and not required. These parameters provide additional functionality to the device.
​
contactorFeedback
bool
Enables feedback for all three contactors (main, auxiliary, and reference) at once. When set to true, this is equivalent to setting mainContactorFeedback, auxiliaryContactorFeedback, and referenceContactorFeedback all 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.
​
auxiliaryContactorFeedback
bool
Indicates whether feedback is enabled for the auxiliary contactor. When enabled, the address map must contain a measure.contactor.auxiliary register.
​
referenceContactorFeedback
bool
Indicates whether feedback is enabled for the reference contactor. When enabled, the address map must contain a measure.contactor.reference register.
​
breakerFeedback
bool
Indicates whether the breaker feedback is enabled or not.
​
maximumVoltage
int
The maximum voltage in volts above which the precharge sequence will not start, or if already in the Closed state, will cause the device to open all contactors and return to the Open state.Example: 760
​
holdReferenceInSeconds
int
The duration in seconds the device remains in the Closed reference state, with the reference contactor closed, before engaging the auxiliary contactor. Defaults to 3 seconds if not specified.Example: 5
​
analogMeasurementAddressMap
string
Indicates the name of the device’s analog measurement address map on the controller.Example: battery1_analog_address_map
​
maxFeedbackRetries
int
The maximum number of times the precharge device may retry the precharge sequence when the contactor control and feedback do not match. When the limit is reached, the device enters a fault state and requires a control.reset command before it is released. Defaults to -1, which allows unlimited retries. A value of 0 means no retries are allowed.Example: 3

​
Example

The snippet below demonstrates a precharge device, highlighting both the required and optional parameters. 
{
  "id": "battery1_precharge",
  "type": "precharge",
  "addressMap": "battery1_precharge_address_map",
  "disabled": false,
  "holdReferenceInSeconds": 5,
  "prechargePeriodInSeconds": 10,
  "holdAuxiliaryInSeconds": 2,
  "tresholdVoltage": 700,
  "maximumVoltage": 760,
  "mainContactorFeedback": true,
  "auxiliaryContactorFeedback": false,
  "referenceContactorFeedback": true,
  "breakerFeedback": true,
  "maxFeedbackRetries": 3
}
When configuring a precharge device, ensure that all required parameters are correctly specified to avoid configuration errors. Optional parameters can provide additional functionality and control but are not necessary for basic operation. Always verify that the paths provided for addressMap are accurate and that the files exist in the specified locations.