Skip to content

ARD + HHDM Integration

This guide walks you through connecting HHDM to ARD so you can run simulations directly from HHDM. No prior coding or terminal experience is required — every step is spelled out below.

What you'll end up with

A working connection between HHDM and ARD, so HHDM can trigger simulations on ARD and pull back results automatically.

Step 1 — Create your ARD API key

  1. Log in to ARD.
  2. Go to User Settings → API Access.
  3. Click Generate Key.
  4. Copy the key immediately — ARD only shows it once. If you lose it, you'll need to generate a new one.

Generate API Key

Step 2 — Add the key to HHDM

  1. Open HHDM and go to its ARD Simulation Settings page.
  2. Paste the API key into the API Key field.
  3. Save.

HHDM Settings

Keep your key private

Treat this key like a password. Don't paste it into emails, chat messages, or shared documents. If you think it's been exposed, go back to ARD and generate a new one — this instantly disables the old key.

Step 3 — Install Python using UV

HHDM needs a small Python "connector" script to talk to ARD. To run that script, your computer needs Python installed. We recommend installing it using UV, a simple installer that handles everything for you.

  1. Download and install UV from the official site: https://docs.astral.sh/uv/getting-started/installation/
  2. Follow the instructions for your operating system (Windows, Linux or Mac).
  3. Once installed, you'll use it to set up a project folder — a self-contained space that keeps this Python setup separate from anything else on your computer.

Create your project folder

  1. Create a new folder somewhere easy to find, e.g. Documents/ard-hhdm-connector.
  2. Open a terminal window in that folder:
  1. Open the folder in File Explorer.
  2. Click into the address bar at the top of the window (where the folder path is shown).
  3. Type cmd and press Enter — a terminal window opens, already inside your folder.
  1. Open Terminal (press Cmd + Space, type "Terminal", press Enter).
  2. Type cd (with a space after it) — don't press Enter yet.
  3. Drag your folder from Finder into the Terminal window. This automatically fills in the folder's path.
  4. Press Enter.
  1. In the terminal, run the following commands one at a time, pressing Enter after each:
    uv init

    uv add requests

These commands set up the Python environment and install the one extra piece of software (requests) the connector script needs to talk to ARD over the internet.

Add the connector script

  1. Ask your ARD contact for the main.py file.
  2. Place main.py directly inside the project folder you just created (the same one you ran uv init in).

Your folder should now contain at least:

ard-hhdm-connector/
├── main.py
├── pyproject.toml
├── .venv
└── (a few other files created by uv)

Step 4 — Point HHDM at the Python environment

  1. In HHDM, find the setting for the Python Executable Path.
  2. Select the Python interpreter that lives inside the project folder you just created (the one uv init set up — it will typically be in a subfolder called .venv inside your project folder).

HHDM Settings

Step 5 — Run the authentication check

Back in HHDM, run the Authentication Check action.

  • ✅ Success means HHDM was able to reach ARD using your API key and the connector script is working.
  • ❌ If it fails, double-check:
  • The API key was pasted correctly in Step 2
  • main.py is in the correct folder
  • The interpreter selected in Step 4 is the one from your project folder (not your computer's default Python, if it has one)

Auth Run

Step 6 — Run your first simulation

Once the health check passes, you're ready to run a real simulation from HHDM.

Build the JSON profile

Simulations are configured using a JSON Profile that maps HHDM's parameters to the matching items in ARD. Ask your ARD/HHDM contact for a demo JSON profile to use as a starting template — you'll customize it from there. The full schema is documented on the ARD External API docs page.

Every simulation, regardless of type, must specify:

  • Vehicle
  • Track
  • Ambient conditions
  • Sim config

Names must match exactly

Whatever you put for vehicle, track and ambient conditions must match the name of that item in ARD exactly — including capitalization and spacing. A mismatched name is the most common reason a simulation fails to submit.

Version numbers are optional

If you don't specify a version number for an item, ARD automatically uses the latest version. Only include a version number if you need to pin a simulation to a specific, older version.

Submit and check results

Once your JSON profile is filled in, run the simulation from HHDM.

  1. Submit the simulation to ARD by clicking the Simulate -> Run button
  2. Poll ARD until the simulation completes by clicking Get Simulation Status -> Run
  3. Pull the results back into HHDM by clicking Get Simulation Results -> Run

Troubleshooting checklist

Problem Likely cause
Health check fails Wrong/missing API key, wrong interpreter selected, or main.py missing from the folder
Simulation won't submit Vehicle/track/ambient/sim config missing or name doesn't exactly match ARD
"Command not found" running uv UV wasn't installed correctly — reinstall from the link in Step 3 and restart your terminal

Reference