# Quickstart

From an account to your firmware running on a twin. You need a firmware ELF built for one of the boards in the catalog; no hardware.

## 1\. Get an account

[Sign in](https://app.circuittwin.ai/sign-in) with your email address. We send you a 6-digit code; enter it and you are in. The Free plan costs nothing.

CircuitTwin is available in the United States only. The first time you sign in, the app asks where you are located.

## 2\. Run firmware in the browser

The fastest start: on **Projects**, choose **Try a development board**. It runs a Blink program on a NUCLEO-F767ZI, STM32F4-Discovery or NUCLEO-F103RB twin and shows the console live.

To run your own firmware:

1. Make a project with **New project**, then add a system with **New system** and pick its microcontroller. A system with one microcontroller is what you would call a board.
2. Open **Runs**, choose **New run**, pick the system and upload the ELF, HEX or BIN you would flash.
3. Set what counts as a pass, for example a line the console must print, and choose **Start run**.

The run page shows the console as it runs, then the verdict, each check and any issue the twins found.

## 3\. Install the CLI and sign in

> **Getting ct**
>
> On macOS (13 or later, Apple silicon or Intel) and Linux (x86\_64 or ARM64), the command below installs a signed build and checks its SHA-256 first. The macOS build leaves out the commands for real boards (`ct hw`). On Windows, email [support@circuittwin.ai](mailto:support@circuittwin.ai) and we send you the package: `ct.exe` and `install.ps1`.

macOS and Linux

```
curl -fsSL https://circuittwindownloads.blob.core.windows.net/cli/install.sh | sh
ct --version
```

Windows (PowerShell)

```
.install.ps1    # in the folder you unpacked
ct --version
```

Every `ct` command except `ct login` needs a signed-in account. Create an access token in the app under **Settings, Access tokens** (see [Access tokens](https://circuittwin.ai/docs/tokens)), then:

terminal

```
ct login --server https://app.circuittwin.ai
# paste the token when asked; ct checks it with the server before storing it
ct login --status
```

## 4\. Run firmware from your terminal

Run one image on a built-in board until a line appears on the console:

terminal

```
ct run --board nucleo-f767zi build/app.elf --until "READY"
```

Exit code `0` means the run reached its target (or ended within its budget without a fault), `1` that it did not, `4` that it completed on peripherals the twin does not model, so it is not a pass. Add sensors on a bus with `--device`, for example `--device INA226@I2C1:0x40`, and feed them a scripted world with `--scenario`.

> **No simulation build**
>
> Build for the real target exactly as you would for hardware. There is no simulation build configuration and no shim layer: the twin runs the same ELF.

## 5\. Generate a twin from documents

If your part is not in the catalog, generate it from the vendor’s documents, in the app on the **Datasheets** page or with `ct twin generate`. Companion documents (reference manual, errata, vendor headers) make the twin more complete. A new twin uses one generation credit; a part already in the catalog is reused for free.

terminal

```
ct twin generate stm32f767zi-datasheet.pdf --with rm0410.pdf --output twins/
```

## 6\. Turn the run into a test

A suite names the board, the firmware and what must happen. Run it locally first, then from your [CI](https://circuittwin.ai/docs/ci):

suite.yaml

```
schemaVersion: ct.test-suite/1
id: firmware-smoke
name: Firmware smoke test
defaults:
  board:
    id: nucleo-f767zi
cases:
  - id: boots
    name: Firmware boots and reports ready
    firmware:
      path: build/app.elf
    assertions:
      - kind: marker
        pass: READY
      - kind: no_fault
```

terminal

```
ct test run suite.yaml --junit report.xml
```

## Next steps

- [Put your system in a 3D world](https://circuittwin.ai/docs/proving-ground) and run it live
- [Debug in STM32CubeIDE or VS Code](https://circuittwin.ai/docs/ide)
- [Wire several microcontrollers together](https://circuittwin.ai/docs/scenes) on UART, SPI, I2C, CAN, RS-485 or Ethernet
- [Core concepts](https://circuittwin.ai/docs/concepts): what a twin models, and what the labels mean