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

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.

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 the CAN2 bus
sendCAN(CAN2, 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

setChargeLimit(limit)(Requires firmware v1.1.7 or later)

Sets a new charge(= regen) limit.

if id == BMS_LIMIT then
  setChargeLimit(msg[2])
end

setDischargeLimit(limit)(Requires firmware v1.1.7 or later)

Sets a new discharge limit.

if id == BMS_LIMIT then
  setDischargeLimit(msg[3])
end

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)

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