> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crucihil.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> CruciHiL — bulletproof Hardware-in-the-Loop testing for firmware teams

CruciHiL is a Hardware-in-the-Loop (HiL) testing platform that catches firmware regressions before they reach the field. Write tests in Python, run them against virtual simulation before hardware exists, then run the same tests against real hardware — with zero code changes.

## What CruciHiL solves

Firmware teams waste enormous time on two problems:

**Test authoring friction.** Figuring out which signals a firmware component actually reads and writes takes days of reading code, tracing AUTOSAR RTE wrappers, and asking around. CruciHiL's `crucihil analyze` command does this with static analysis and AI in minutes.

**Hardware dependency.** Tests can't run until hardware is built, so regressions are caught late and fixes are expensive. CruciHiL's virtual backend runs identical tests in CI with no hardware at all — on day one.

## How it works

```
Layer 6 — Interfaces      CLI · Web Dashboard · CI/CD webhooks
Layer 5 — AI Interface    MCP Server — connect Claude, Copilot, Cursor
Layer 4 — Cloud Control   FastAPI + PostgreSQL — orchestration and history
Layer 3 — Local Agent     Test runner · YAML executor · result reporter
Layer 2 — Rig HAL         rig.can / rig.sim / rig.fault / rig.ecu
Layer 1 — Hardware        CAN · Ethernet · GPIO · Power · ECUs
```

The key design invariant: **Layer 2 (the Rig HAL) is the only layer that knows about hardware.** Test code uses `rig.can.send(...)` and `rig.can.expect(...)` — never "socketcan" or "can0". When you swap from a virtual backend to a PEAK CAN adapter, only the TOML changes. The test file is identical.

## Key capabilities

<CardGroup cols={3}>
  <Card title="Virtual-first CI" icon="microchip">
    Every test runs against an in-process virtual backend before hardware exists. CI works on day one.
  </Card>

  <Card title="Zero test changes" icon="arrows-rotate">
    Switch virtual → real hardware by changing one line in a TOML file. Test code is hardware-agnostic by design.
  </Card>

  <Card title="AI signal mapping" icon="brain">
    `crucihil analyze` maps AUTOSAR RTE and COM identifiers to DBC signal names using static analysis and AI.
  </Card>

  <Card title="Python-native" icon="python">
    Tests are async Python functions. No proprietary scripting language. Use your existing editor and CI toolchain.
  </Card>

  <Card title="MCP-connected" icon="plug">
    Claude, Copilot, and Cursor can query rigs, run tests, and explain failures through the built-in MCP server.
  </Card>

  <Card title="Open core" icon="lock-open">
    Self-hosted free up to two rigs. No vendor lock-in. Bring your own AI key.
  </Card>
</CardGroup>

## Start here

<Card title="Installation →" icon="download" href="/installation">
  Install CruciHiL and run your first test in under five minutes.
</Card>