Dynam Labs VCU+ Plugin Reference Manual

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

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

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

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.

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

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

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).

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

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

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).

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

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

Retrieves the current value of the specified signal. This allows the plugin to access real-time data, such as temperature, speed, or pressure. Returns nil if the signal 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.

• signalId: Which signal to read, using one of the built-in constants (e.g. Temp1, BatteryVoltage); see the list below for all identifiers.

-- Read temperature signal 1
local temperature = getSignal(Temp1)
-- Read accelerator pedal and use it in logic
local pedal = getSignal(AcceleratorPedal)

-- Read temperature signal 1
local temperature = getSignal(Temp1)
-- Read accelerator pedal and use it in logic
local pedal = getSignal(AcceleratorPedal)

Deprecated alias for getSignal(). Retained for backwards compatibility with plugins written before firmware 2.0.14. Functionally identical to getSignal() — new code should prefer getSignal().

• signalId: Which signal to read, using one of the built-in constants (e.g. Temp1, BatteryVoltage); see the list below for all identifiers.

-- Equivalent to getSignal(Temp1)
local temperature = getSensor(Temp1)

-- Equivalent to getSignal(Temp1)
local temperature = getSensor(Temp1)

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.

• canBus: The physical bus to send the message on. (CAN2 or CAN3 only)
• canID: The identifier of the CAN message.
• data: The payload, a byte array of up to 8 bytes.

-- 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})

-- 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})

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.

• canBus: The physical bus to send the message on. (CAN1/CAN2/CAN3)
• canID: The identifier of the CAN message.
• handler: function that gets called when 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)

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

receiveCAN(CAN2, 0x123, handleMessage)

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

• p: Proportional gain
• i: Integral gain
• d: Derivative gain

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

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

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.

• target: The desired setpoint value.
• actual: The current measured value.

-- Create a PID controller
local pid = newPID(1.0, 0.5, 0.1)
-- Compute the control output
local targetTemp = 100 -- Target temperature
-- getSignal() requires firmware 2.0.14+
local actualTemp = getSignal(Temp1)
local controlOutput = pid:compute(targetTemp, actualTemp)

-- Create a PID controller
local pid = newPID(1.0, 0.5, 0.1)
-- Compute the control output
local targetTemp = 100 -- Target temperature
-- getSignal() requires firmware 2.0.14+
local actualTemp = getSignal(Temp1)
local controlOutput = pid:compute(targetTemp, actualTemp)

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

• channel: The PWM channel to configure (e.g., PWM1, PWM2).
• frequency: The desired frequency in Hertz.

setPWMFreq(PWM1, 750)

setPWMFreq(PWM1, 750)

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

• channel: The PWM channel to configure (e.g., PWM1, PWM2).
• duty: The desired duty cycle in percent.

setPWMDuty(PWM1, 25)

setPWMDuty(PWM1, 25)

Prints a message to the plugin log inside of Bolt.

• string: String to print

-- getSignal() requires firmware 2.0.14+
local ain3_val = getSignal(Ain3)
print("Ain3 Value: " .. ain3_val)

-- getSignal() requires firmware 2.0.14+
local ain3_val = getSignal(Ain3)
print("Ain3 Value: " .. ain3_val)

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

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

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

Writes a floating-point value into one of the VCU plugin log slots so it can be surfaced alongside other plugin telemetry. The VCU exposes 8 plugin log slots indexed from 1 to 8.

Note: If entry is outside the valid range or value is not a number, the call is rejected and an error is logged to the plugin console.

• entry: Plugin log slot index (integer between 1 and 8).
• value: Floating-point value to store in the slot.

-- Publish a derived signal to plugin log slot 1
local power = getSignal(BatteryVoltage) * getSignal(BatteryCurrent)
setLogEntry(1, power)

-- Publish a derived signal to plugin log slot 1
local power = getSignal(BatteryVoltage) * getSignal(BatteryCurrent)
setLogEntry(1, power)

Returns elapsed time in ms since the VCU booted.

if getTime() > 2500 then
  someFunction()
end

if getTime() > 2500 then
  someFunction()
end

Requests a new gear.

• gear: Requested Gear (GEAR_P, GEAR_R, GEAR_N, GEAR_D)

if someVar == 2500 then
  requestGear(GEAR_D)
end

if someVar == 2500 then
  requestGear(GEAR_D)
end

Sets a new drive-mode.

• mode: New drive mode (CHILL, NORMAL, SPORT, VALET)

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

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

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.

Required signals: When using a Custom (Plugin) BMS, the pack voltage (configureBmsVolt), discharge current limit (DCL) (configureBmsDisLim), and charge current limit (CCL) (configureBmsChgLim) must all be configured. Their CAN messages must be received at least every 500 ms, otherwise the BMS will be treated as offline. Pack current (configureBmsCurr) and state of charge (configureBmsSoc) are optional.

• bus: CAN bus to read the message from (CAN1, CAN2, or CAN3)
• canId: CAN ID containing the voltage signal
• startBit: start decoding data at this bit of the CAN frame
• length: number of bits to decode
• isSigned: decode value as a signed number
• scale: encoded data scaled by this factor
• offset: encoded data offset
• encoding: CAN_MOTOROLA or CAN_INTEL

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

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

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.

Required signals: When using a Custom (Plugin) BMS, the pack voltage (configureBmsVolt), discharge current limit (DCL) (configureBmsDisLim), and charge current limit (CCL) (configureBmsChgLim) must all be configured. Their CAN messages must be received at least every 500 ms, otherwise the BMS will be treated as offline. Pack current (configureBmsCurr) and state of charge (configureBmsSoc) are optional.

• bus: CAN bus to read the message from (CAN1, CAN2, or CAN3)
• canId: CAN ID containing the current signal
• startBit: start decoding data at this bit of the CAN frame
• length: number of bits to decode
• isSigned: decode value as a signed number
• scale: encoded data scaled by this factor
• offset: encoded data offset
• encoding: CAN_MOTOROLA or CAN_INTEL

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

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

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.

Required signals: When using a Custom (Plugin) BMS, the pack voltage (configureBmsVolt), discharge current limit (DCL) (configureBmsDisLim), and charge current limit (CCL) (configureBmsChgLim) must all be configured. Their CAN messages must be received at least every 500 ms, otherwise the BMS will be treated as offline. Pack current (configureBmsCurr) and state of charge (configureBmsSoc) are optional.

• bus: CAN bus to read the message from (CAN1, CAN2, or CAN3)
• canId: CAN ID containing the SOC signal
• startBit: start decoding data at this bit of the CAN frame
• length: number of bits to decode
• isSigned: decode value as a signed number
• scale: encoded data scaled by this factor
• offset: encoded data offset
• encoding: CAN_MOTOROLA or CAN_INTEL

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

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

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.

Required signals: When using a Custom (Plugin) BMS, the pack voltage (configureBmsVolt), discharge current limit (DCL) (configureBmsDisLim), and charge current limit (CCL) (configureBmsChgLim) must all be configured. Their CAN messages must be received at least every 500 ms, otherwise the BMS will be treated as offline. Pack current (configureBmsCurr) and state of charge (configureBmsSoc) are optional.

• bus: CAN bus to read the message from (CAN1, CAN2, or CAN3)
• canId: CAN ID containing the DCL signal
• startBit: start decoding data at this bit of the CAN frame
• length: number of bits to decode
• isSigned: decode value as a signed number
• scale: encoded data scaled by this factor
• offset: encoded data offset
• encoding: CAN_MOTOROLA or CAN_INTEL

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

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

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.

Required signals: When using a Custom (Plugin) BMS, the pack voltage (configureBmsVolt), discharge current limit (DCL) (configureBmsDisLim), and charge current limit (CCL) (configureBmsChgLim) must all be configured. Their CAN messages must be received at least every 500 ms, otherwise the BMS will be treated as offline. Pack current (configureBmsCurr) and state of charge (configureBmsSoc) are optional.

• bus: CAN bus to read the message from (CAN1, CAN2, or CAN3)
• canId: CAN ID containing the CCL signal
• startBit: start decoding data at this bit of the CAN frame
• length: number of bits to decode
• isSigned: decode value as a signed number
• scale: encoded data scaled by this factor
• offset: encoded data offset
• encoding: CAN_MOTOROLA or CAN_INTEL

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

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

Checks if a valid GPS fix has been acquired.

if GPSFixAcquired() then
  send_GPS_data()
end

if GPSFixAcquired() then
  send_GPS_data()
end

Fetches GPS data.

• data:

  GPS data requested. Supported types:

  • LATITUDE (deg)
  • LONGITUDE (deg)
  • ALTITUDE (m)
  • GROUNDSPEED (km/h)
  • HEADING (deg)
  • TIME (unix timestamp, seconds since epoch)

local heading = getGPSData(HEADING)

local heading = getGPSData(HEADING)

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

• payload: CAN message data (byte array to write into)
• data: Data to encode
• startBit: start encoding data at this bit of the CAN frame
• length: number of bits in the CAN frame
• scale (optional): scale data to be encoded
• offset (optional): value offset for the encoded data
• encoding (optional): CAN_MOTOROLA or CAN_INTEL

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)

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)

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

• payload: CAN data (byte array)
• startBit: start decoding data at this bit of the CAN frame
• length: number of bits to decode
• isSigned (optional): decode as a signed number
• scale (optional): encoded data scaled by this factor
• offset (optional): value offset for the encoded data
• encoding (optional): CAN_MOTOROLA or CAN_INTEL

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)

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)

Retrieves the current state of the pre-charge sequence.

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

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

Manually marks the pre-charge sequence as complete.

-- If custom conditions are met, mark precharge as done
-- getSignal() requires firmware 2.0.14+
if getSignal(BatteryVoltage) > 300 then
  setPrechargeDone()
end

-- If custom conditions are met, mark precharge as done
-- getSignal() requires firmware 2.0.14+
if getSignal(BatteryVoltage) > 300 then
  setPrechargeDone()
end

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.

• channel: Analog output channel (AOUT1 or AOUT2).
• voltage: Output voltage in Volts (0.0-5.0 V). Values outside this range are clamped.

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

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