Dynam Labs VCU+ Plugin Reference Manual

onTick()

This function is called repeatedly by the VCU firmware. Implement your main control logic inside this function.

Continuously monitoring battery temperature and activating a cooling fan if it exceeds a threshold.

-- This function will be called on every tick of the plugin execution cycle
function onTick()
    local temp = getSensor(BatteryTemp)
    if temp > 80 then
        setOut(HS1) -- Turn on cooling fan
    else
        clearOut(HS1) -- Turn off cooling fan
    end
end

onSleep()

This optional callback is called by the VCU just before the device enters sleep mode. Use it to perform any necessary cleanup, save state, or send a final CAN message before power is removed. The VCU waits for this function to complete before proceeding with the sleep sequence.

Sending a final CAN message or saving state before the VCU goes to sleep.

function onSleep()
    sendCAN(CAN2, 0x7FF, {0x00}) -- notify other devices we're going to sleep
end

setOut(pin)

This function sets the specified output pin to its active state:

• High-Side Outputs: The pin transitions to a high state (voltage applied).
• Low-Side Outputs: The pin transitions to a low state (connected to ground).

Activating a high-side output pin to power a relay or a low-side output pin for devices requiring a ground-side switch.

-- Activate a high-side output 1
setOut(HS1)
-- Activate a low-side output 2
setOut(LS2)

clearOut(pin)

This function clears the specified output pin, setting it to its inactive state:

• High-Side Outputs: The pin transitions to a low state (voltage removed).
• Low-Side Outputs: The pin transitions to a high state (disconnected from ground).

Deactivating a relay or turning off a light connected to the VCU.

-- Deactivate the high-side output 1
clearOut(HS1)
-- Deactivate the low-side output 2
clearOut(LS2)

getSensor(sensorID)

Retrieves the current value of the specified sensor. This allows the plugin to access real-time data, such as temperature, a speed, or pressure. Returns nil if the sensor state is invalid. Always check the return value before performing arithmetic operations. The return value is always a floating point number, so it must be rounded or converted to an integer before using it in bitwise operations.

Reading a temperature sensor value for dynamic control logic.

List of available Sensors:

-- Retrieve the value from Temperature sensor 1
local temperature = getSensor(Temp1)
-- Retrieve Accelerator pedal value and use it in logic
local pedal = getSensor(AcceleratorPedal)

sendCAN(canBus, canID, data)

Sends a CAN message with the specified ID and data payload. Enables communication with other devices on the CAN bus.

Note: Only CAN2 and CAN3 are supported. Calls with CAN1 are silently ignored.

Sending commands to external controllers or reporting custom data.

-- Send a CAN message on CAN2 with ID 0x123 and data payload {0x01, 0x02, 0x03}
sendCAN(CAN2, 0x123, {0x01, 0x02, 0x03})
-- Example of sending a command to an external device on CAN3
sendCAN(CAN3, 0x200, {0xFF, 0xAA, 0x55})

receiveCAN(canBus, canID, handler)

Registers a CAN handler that gets called when a CAN message is received. Only gets called when a message on the bus with correct canID is received. This function only needs to be called once, from global scope. The message handler gets called at the loop rate - prior to the onTick() function, not at the exact moment the CAN message is received.

function handleMessage(data)
  local temp = (data[2] << 8) | data[1]
  print("Temp DLC: " .. #data .. " Temp: " .. temp)
end
 
receiveCAN(CAN2, 0x123, handleMessage)

newPID(p, i, d)

Creates a new PID controller instance with the specified tuning parameters.

Initializing a PID controller to maintain target speeds or stabilize temperatures.

-- Create a PID controller with P=1.0, I=0.5, D=0.1
local pid = newPID(1.0, 0.5, 0.1)

pid:compute(target, actual)

Computes the control output of an existing PID controller based on a target value and the actual measured value. This function is supposed to be called in a loop.

-- Create a PID controller
local pid = newPID(1.0, 0.5, 0.1)
-- Compute the control output
local targetTemp = 100 -- Target temperature
local actualTemp = getSensor(Temp1) -- Assume Temp1 provides actual temperature
local controlOutput = pid:compute(targetTemp, actualTemp)

setPWMFreq(channel, frequency)

Sets the frequency of the specified PWM (Pulse Width Modulation) channel in Hertz (Hz). This determines how many PWM cycles are generated per second.

setPWMFreq(PWM1, 750)

setPWMDuty(channel, duty)

Sets the duty cycle of the specified PWM (Pulse Width Modulation) a channel in percent (%).

setPWMDuty(PWM1, 25)

print(string)

Prints a message to the plugin log inside of Bolt.

local ain3_val = getSensor(Ain3)
print("Ain3 Value: " .. ain_val)

printStatistics()

Prints detailed memory usage and system statistics to the plugin log.

Useful for debugging memory leaks and monitoring performance.

-- Print memory and performance stats to the log
printStatistics()

getTime()

Returns elapsed time in ms since the VCU booted. Example Use Case: Handle timing operations

if getTime() > 2500 then
  someFunction()
end

requestGear(gear)(Requires firmware v1.1.6 or later)

Requests a new gear.

if someVar == 2500 then
  requestGear(GEAR_D)
end

setDrivemode(mode)(Requires firmware v1.1.7 or later)

Sets a new drive-mode.

if msg[1] == 100 then
  setDrivemode(SPORT)
end

configureBmsVolt(bus, canId, startBit, length, isSigned, scale, offset, encoding)

Configures decoding of the battery pack voltage from a CAN message. Once configured, the VCU will automatically decode the specified signal and use it as the BMS voltage input.

Note: The BMS type must be set to Custom (Plugin) for this function to take effect. This function can be global and does not have to be called repeatedly.

configureBmsVolt(CAN2, 0x301, 0, 16, false, 1, 0.0, CAN_INTEL)

configureBmsCurr(bus, canId, startBit, length, isSigned, scale, offset, encoding)

Configures decoding of the battery pack current from a CAN message. The decoded value will be used as the BMS current measurement within the VCU.

Note: The BMS type must be set to Custom (Plugin) for this function to take effect. This function can be global and does not have to be called repeatedly.

configureBmsCurr(CAN2, 0x302, 0, 16, true, 0.1, 0.0, CAN_INTEL)

configureBmsSoc(bus, canId, startBit, length, isSigned, scale, offset, encoding)

Configures decoding of the battery state of charge (SOC) from a CAN message. The decoded value will be used by the VCU for SOC display.

Note: The BMS type must be set to Custom (Plugin) for this function to take effect. This function can be global and does not have to be called repeatedly.

configureBmsSoc(CAN2, 0x303, 0, 8, false, 1.0, 0.0, CAN_INTEL)

configureBmsDisLim(bus, canId, startBit, length, isSigned, scale, offset, encoding)

Configures decoding of the battery discharge current limit (DCL) from a CAN message. The decoded value defines the maximum allowable discharge current reported by the BMS.

Note: The BMS type must be set to Custom (Plugin) for this function to take effect. This function can be global and does not have to be called repeatedly.

configureBmsDisLim(CAN2, 0x304, 0, 16, false, 0.1, 0.0, CAN_INTEL)

configureBmsChgLim(bus, canId, startBit, length, isSigned, scale, offset, encoding)

Configures decoding of the battery charge current limit (CCL) from a CAN message. The decoded value defines the maximum allowable charging current reported by the BMS.

Note: The BMS type must be set to Custom (Plugin) for this function to take effect. This function can be global and does not have to be called repeatedly.

configureBmsChgLim(CAN2, 0x304, 16, 16, false, 0.1, 0.0, CAN_INTEL)

GPSFixAcquired()(Requires firmware v1.1.7 or later)

Checks if a valid GPS fix has been acquired. Example Use Case: Custom CAN message implementations. Returns: True if a valid GPS fix has been acquired, false otherwise.

if GPSFixAcquired() then
  send_GPS_data()
end

getGPSData(data)(Requires firmware v1.1.7 or later)

Fetches GPS data.

Example Use Case: Custom CAN message implementations. Returns: Value of the data requested, nil if no valid GPS fix has been acquired.

local heading = getGPSData(HEADING)

canEncode(payload, data, startBit, length [, scale [, offset [, encoding]]])

Encodes data into a CAN message payload. The payload table is modified in-place. All parameters after length are optional.

local sensorPayload = {0, 0, 0, 0, 0, 0, 0, 0}
local rpm = 2500
canEncode(sensorPayload, rpm, 0, 16, 1.0, 0.0, CAN_INTEL)
sendCAN(CAN2, 0x123, sensorPayload)

canDecode(payload, startBit, length [, isSigned [, scale [, offset [, encoding]]]])

Decodes data from a CAN message. Should be called from a CAN receive callback. All parameters after length are optional.

Example Use Case: Custom CAN message implementations. Returns: Decoded value

local rpm = canDecode(canData, 0, 16, false, 1.0, 0.0, CAN_INTEL)
-- Minimal form — unsigned, scale 1.0, offset 0.0, Intel byte order
local soc = canDecode(canData, 0, 8)

getPrechargeState()(Requires firmware v1.1.8 or later)

Retrieves the current state of the pre-charge sequence.

Check if the pre-charge sequence is complete before closing contactors.

Returns: A number representing the pre-charge state (e.g., 0 for inactive, 1 for in-progress, 2 for complete).

if getPrechargeState() == 2 then
  -- Precharge is complete, ready to close contactors
  setOut(HS1)
end

setPrechargeDone()(Requires firmware v1.1.8 or later)

Manually marks the pre-charge sequence as complete.

Used in custom pre-charge logic where the completion criteria is determined by the plugin.

-- If custom conditions are met, mark precharge as done
if getSensor(BatteryVoltage) > 300 then
  setPrechargeDone()
end

setAnalogOut(channel, voltage)

Sets the output voltage on an analog output channel. The voltage is clamped to the 0–5 V range.

Note: This function is unavailable when:

• The drive inverter type is set to Tesla Large, Tesla Small, or Tesla 3 Rear (these inverter types require the analog outputs for their own operation).
• The pedal output type is set to Analog, Tesla S/X, or Tesla 3/Y.

In either case, the call is rejected with an error logged to the plugin console.

Driving an analog gauge or an external controller that accepts a 0–5 V signal.

-- Set AOUT1 to 2.5 V
setAnalogOut(AOUT1, 2.5)