Skip to main content

Quick Start

Anvil is easy to add to your driver. Install the agent, add the client library and configure your driver in under 5 minutes to start seeing real time information about your driver.

Prerequisites​

  • Control4 OS 3.3.1 or newer on the controller running your driver
  • The Anvil Agent installed and authenticated on your controller (setup guide)
  • A project created in Anvil
Older controllers

On anything below OS 3.3.1 the SDK disables itself at load and your driver runs exactly as it would with no SDK vendored at all. Nothing breaks; you just get no telemetry. See SDK installation for what that looks like.

1. Download the Driverforge SDK​

Download the latest Driverforge SDK and place the contents in your driver's vendor/ directory.

Download Anvil SDK

2. Add vendor directory to your .c4zproj manifest​

Make sure the vendor directory is included in your manifest:

<Item type="dir" c4zDir="vendor" name="vendor" recurse="true" exclude="false"/>
Using Squish?

If your project uses a squishy file, you can bundle the SDK into your squished driver instead of shipping the vendor directory:

Module "vendor.driverforge-sdk" "vendor/driverforge-sdk.lua"

The require('vendor.driverforge-sdk') call in the next step is the same either way: squish satisfies it from the bundle; otherwise Director resolves the vendored file from your packaged driver.

3. Initialize Anvil in OnDriverInit​

Update your OnDriverInit function to load the SDK and initialize it with your project's project token (in Anvil, open Settings > Projects, click the gear icon on your project, and copy the token from Project Token):

function OnDriverInit(strDIR)
    require('vendor.driverforge-sdk')

    Driverforge:Init("YOUR_API_KEY")

    Anvil:OnDriverInit(function(strDIR)
        -- Your existing OnDriverInit code goes here
    end, strDIR)
end
info

OnDriverInit is a special case: it runs before the SDK can auto-instrument, so it needs the explicit Anvil:OnDriverInit wrapper. All other lifecycle methods (OnDriverLateInit, OnPropertyChanged, etc.) are automatically instrumented; just write them normally.

4. Build and deploy​

Build your driver and load it onto your controller. Events will start streaming to Anvil immediately.

5. View your data in Anvil​

Open your project in Anvil to see data flowing in real time. The Events page shows every handler call as it happens, Logs shows your driver's log output, and Errors surfaces any exceptions with full stack traces. Interact with your driver in a navigator or Composer to see events appear instantly.

Next Steps​