4. FaultyCMD Installation

FaultyCMD Usage

Warning

If you are moving from previous FaultyCat firmware and tools, you will need to first upload a .uf2 file to the FaultyCat so FaultyCMD can recognise it.

Find the instructions here: How to update FaultyCat.

To start using FaultyCMD, you must:

For Windows users, run a new terminal session in the same path as where the file faultycmd_vx.x.x.x.exe is located. Learn more here: FaultyCMD installation - Windows
For Linux /macOS / Window-with-Python start the virtual environment where you installed the package. See more information here: FaultyCMD Installation-Linux /macOS / Window-with-Python

Then you can start using the tool by using the command:

faultycmd

Important

In this wiki, we will use the command-line installation method with Python as a reference. Windows users who are using the executable file (faultycmd_vx.x.x.x.exe) should replace the faultycmd command with the file name, for example:

.\faultycmd_v3.0.0.0.exe

You will see the main view of the CLI:

Usage: faultycmd [OPTIONS] COMMAND [ARGS]...

  faultycmd — host tool for FaultyCat v3.

Options:
  --version                  Show the version and exit.
  --ignore-version-mismatch  Bypass the firmware/host version parity check on
                             every connect. Unsafe — only use for development
                             against a hand-built UF2.
  --help                     Show this message and exit.

Commands:
  campaign  Run automated parameter sweeps.
  crowbar   Control the crowbar (voltage glitch on the target).
  emfi      Control the EMFI module (electromagnetic fault injection).
  info      List FaultyCat interfaces detected on this machine.
  scanner   Scan the target's SWD pinout.
  tui       Launch the interactive dashboard.

Available commands

The correct usage of faultycmd is the following:

faultycmd [OPTIONS] COMMAND [ARGS]

`[OPTIONS]`	Description
`--version`	Show the current version of faultycmd running
`--ignore-version-mismatch`	Bypass the firmware/host version parity check on every connect. Unsafe — only use for development against a hand-built UF2
`--help`	Show the available OPTIONS and COMMAND

`COMMAND`	Description
`campaign`	Run automated parameter sweeps
`crowbar`	Control the crowbar (voltage glitch on the target)
`emfi`	Control the EMFI module (electromagnetic fault injection)
`info`	List FaultyCat interfaces detected on this machine
`scanner`	Scan the target's SWD pinout
`tui`	Launch the interactive dashboard

Checking the connected devices

Before performing any operation, it is recommended to verify that the system correctly detects the FaultyCat. To do this, run the command:

faultycmd info

Important

If faultycmd is not able to see the FaultyCat connected, this may indicate there is a problem with the serial port permissions for your user.

Example of expected output when having a FaultyCat with the compatible firmware connected:

faultycmd vx.x.x.x (host)
   FaultyCat CDC interfaces
┏━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┓
┃   IF ┃ role        ┃ device ┃
┡━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━┩
│ 0x00 │ emfi        │ COMXX  │
│ 0x02 │ crowbar     │ COMXX  │
│ 0x04 │ scanner     │ COMXX  │
│ 0x06 │ target-uart │ COMXX  │
└──────┴─────────────┴────────┘
firmware: vx.x.x.x  (match)

Note

Ports are automatically assigned by the operating system.

Campaign

Instead of firing one individual shot at a time, Campaign mode automates a continuous search across an entire parameter space. Used for a parameter-space search during an actual fault-injection attack.

Usage:

faultycmd campaign [OPTION] COMMAND [ARGS]

`[OPTIONS]`	Description
`--engine`	Engine to run the sweep on; use `emfi` or `crowbar` (default:crowbar)
`--port`	Override the port
`--help`	Show the available OPTIONS and COMMAND

`COMMAND`	Description
`configure`	Define the sweep ranges
`drain`	Download the accumulated sweep results
`start`	Start the sweep
`status`	Show the state of the running sweep
`stop`	Stop the running sweep
`watch`	Follow the sweep live until it completes

`ARG`	Description
Configuration `[ARGS]`	-
`--delay`	Delay range in µs (START:END:STEP, or a fixed value). This argument is required
`--width`	Pulse width range (µs on EMFI, ns on crowbar). This argument is required
`--power`	Power range. On crowbar: 1=low, 2=high. Ignored on EMFI. This argument is required
`--settle-ms`	Settle time between shots in ms (default: 0). This argument is required
Drain `[ARGS]`	-
`--max`	Records per request (max 18). [default: 18]
Watch `[ARGS]`	-
`--every-ms`	Update interval in ms (default: 200)

Example:

faultycmd campaign configure --delay 1000:3000:1000 --width 200:300:100 --power 1
faultycmd campaign start
faultycmd campaign watch

Crowbar

The Crowbar technique forces the target chip to misbehave by briefly shorting its power supply (VCC to GND) using a power N-MOSFET.

This causes a sudden, momentary drop (a voltage dip) in the target chip's power.

The sudden drop violates the setup and hold time requirements of the target chip's flip-flops, causing internal bits to flip right as they try to latch.

The ultimate goal is to make the target chip skip an instruction or fail open during a crucial security check (like an authentication or a bootloader lifecycle gate).

Usage:

faultycmd crowbar [OPTION] COMMAND [ARGS]

`[OPTIONS]`	Description
`--port`	Override the crowbar port
`--help`	Show the available OPTIONS and COMMAND

`COMMAND`	Description
`arm`	Arm the crowbar
`configure`	Configure the parameters for the next glitch
`disarm`	Disarm the crowbar
`fire`	Wait for the trigger and fire the glitch
`ping`	Verify communication with the crowbar
`status`	Show the current state of the crowbar

`ARG`	Description
Configuration `[ARGS]`	-
`--trigger`	Options: immediate, ext_rising, ext_falling, ext_pulse_pos, ext_pulse_neg (default: immediate)
`--output`	Options: lp = low power, hp = high power (real glitch). Default: hp
`--delay-us`	Delay after the trigger in µs (default: 0)
`--width-ns`	Pulse width in ns (8 to 50000). Default:200
Fire `[ARGS]`	-
`--trigger-timeout-ms`	Max time to wait for the trigger in ms. Default: 60000

EMFI

The Electromagnetic Fault Injection (EMFI) unlike voltage glitching techniques that manipulate the power delivery network, EMFI operates remotely by utilizing localized magnetic fields to disrupt internal chip operations.

Usage:

faultycmd emfi  [OPTION] COMMAND [ARGS]

`[OPTIONS]`	Description
`--port`	Override the EMFI port
`--help`	Show the available OPTIONS and COMMAND

`COMMAND`	Description
`arm`	Arm the module (charge the high-voltage capacitor)
`capture`	Read the analog capture from the last fire
`configure`	Configure the parameters for the next EMFI fire
`disarm`	Disarm the EMFI module
`fire`	Wait for the trigger and fire the EMFI pulse
`ping`	Verify communication with the EMFI module
`status`	Show the current state of the EMFI module

`ARG`	Description
Capture `[ARGS]`	-
`--offset`	Start position within the buffer (default: 0)
`--length`	Bytes to read (max 512 per request). Default: 512
`--out`	Output file (if omitted, prints as hex)
Configuration `[ARGS]`	-
`--trigger`	Options: immediate, ext_rising, ext_falling, ext_pulse_pos, ext_pulse_neg (default: immediate)
`--delay-us`	Delay after the trigger in µs (default: 0)
`--width-us`	Pulse width in ns (1 to 50). Default:5
`--charge-timeout-ms`	Max armed time in ms (0 = 60 s default). Default: 0
Fire `[ARGS]`	-
`--trigger-timeout-ms`	Max time to wait for the trigger in ms. Default: 60000

Scanner

An automated hardware interrogation and bus-scanning utility. Scanner's primary role is to discover, map, and verify physical connection states on a target microcontroller before and after an attack window.

Usage:

faultycmd scanner  [OPTION] COMMAND [ARGS]

`[OPTIONS]`	Description
`--port`	Override the scanner port
`--help`	Show the available OPTIONS and COMMAND

`COMMAND`	Description
`scan-swd`	Detect the target's SWD pins

`ARG`	Description
SWD scanner `[ARGS]`	-
`--targetsel`	Optional hex value. Discovery sweeps the whole bus by default
`--timeout-s`	Max scan time ib seconds (default:30)

TUI

The Text User Interface (TUI) serves as the primary interactive, terminal-based visual dashboard for FaultyCat v3. It acts as an abstraction layer above the raw host Command Line Interface (CLI), allowing operators to configure parameters, fire pulses, and monitor hardware states in real time using keyboard-driven controls and modalsl.

In the TUI you can basically perform and configure the same things as when using the command line interface.

Usage:

faultycmd tui

The letters that open the modals (e, b, p, n) are mnemonics on the engine name: EMFI, crowBar, camPaign, scaN SWD.

Key	Action
`q`	quit (if a modal is open, closes it first)
`r`	reconnect (closes and reopens the 4 CDCs — handy after re-plugging the board)
`c`	clear the campaign live log
`s`	stop the running sweep (without opening a modal)
`e`	EMFI modal (configure / arm / fire / disarm / capture)
`b`	Crowbar modal (configure / arm / fire / disarm)
`p`	Campaign modal (sweep parameters + start / stop / drain)
`n`	Scan SWD modal (single button that fires `scan swd` over CDC2)

Scan SWD modal (`n`)

A single-button modal that runs scan swd over the CDC2 text shell (P(8,2)=56 permutations, 30 s timeout). While the scan is running the CDC2 diagnostic stream is paused so it doesn't contaminate the output, and it resumes when the scan finishes. The raw firmware lines (MATCH / NO_MATCH / ERR) appear on the modal's status line.

Supported platforms

System	Status	Notes
Linux	✓ verified	Ports under `/dev/ttyACM*`. If you hit `Permission denied` when opening them, add your user to the `dialout` group (`sudo usermod -aG dialout $USER`) and log out / back in. Install via wheel from a Release.
Windows 10/11	✓ verified (2026-05-25)	`COM` ports enumerated by `usbser.sys` (inbox driver). Requires firmware `v3.0-f11-0d` or later — earlier versions failed to enumerate because of bugs in the descriptor and in the init order. Easiest install path: download `faultycmd_vX.Y.Z.W.exe` from the Release — no Python install needed.* If you prefer pip, use a venv so `Scripts/` ends up on `PATH`; otherwise `python -m faultycmd ...` works without PATH changes.
macOS	⚠ not validated	The cross-platform logic (pyserial parsing) should be enough, but no hardware on hand to confirm. Install via wheel from a Release.

Subsequent sessions

cd /path/to/host/faultycmd-py
# Activate the venv for your shell (step 1 of Quick start)
faultycmd tui

To leave the venv: deactivate.

Trigger polarity (EMFI / Crowbar)

Both engines expose the same five trigger modes on the wire:

Trigger	Wire id	PIO program (WAITs)	Event that fires the glitch
`immediate`	0	(none)	starts immediately on `fire`
`ext_rising`	1	`WAIT 0, WAIT 1`	rising edge
`ext_falling`	2	`WAIT 1, WAIT 0`	falling edge
`ext_pulse_pos`	3	`WAIT 0, WAIT 1, WAIT 0`	falling edge at the end of a LOW→HIGH→LOW pulse
`ext_pulse_neg`	4	`WAIT 1, WAIT 0, WAIT 1`	rising edge at the end of a HIGH→LOW→HIGH pulse

Notes:

The idle level of the trigger line is set once when the firmware boots, in main.c (ext_trigger_init(EXT_TRIGGER_PULL_DOWN)): LOW-idle for the whole system. Services do not change it on every arm.
As a consequence, ext_falling and ext_pulse_neg require the external source to drive the line HIGH between events. Without that active stimulation, the internal pull-down and the v2 board's level-shifter keep the line LOW and the first WAIT 1 waits forever.
Latency from the trigger event to the crowbar/EMFI pin is the same in all four edge modes (~56 ns). If you measure from the start of the pulse instead of from the final edge that fires the glitch, you add the pulse width to the reading — that's the cursor position on your scope, not firmware overhead.
ext_pulse_pos and ext_pulse_neg are inverses. Pick the one that matches the idle level your source produces between events; otherwise the first WAIT hangs.

Trigger timeout (EMFI / Crowbar fire)

Every call to fire accepts a trigger_timeout_ms that bounds how long the firmware waits for the external trigger before cancelling with *_ERR_TRIGGER_TIMEOUT. The defaults and semantics are identical for EMFI and Crowbar:

Default: 60 000 ms (1 minute). Enough for manual triggers without having to go back to the CLI to adjust the value.
0 means wait forever. The firmware honours it in tick_waiting; a disarm cancels the wait, releases the PIO, and resets the state.

Where to configure it:

TUI (e / b): the modal form exposes a trigger-timeout-ms field. It is read on every fire, so it can be tweaked between shots without re-applying the configuration. The value is persisted alongside the rest of the form in last_config.json.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

4. FaultyCMD Installation

FaultyCMD Usage

Available commands

Checking the connected devices

Campaign

Crowbar

EMFI

Scanner

TUI

Scan SWD modal (`n`)

Supported platforms

Subsequent sessions

Trigger polarity (EMFI / Crowbar)

Trigger timeout (EMFI / Crowbar fire)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Faulty Cat

Understanding Faulty Cat

How to update FaultyCat

FaultyCMD

FAQs

Clone this wiki locally

4. FaultyCMD Installation

FaultyCMD Usage

Available commands

Checking the connected devices

Campaign

Crowbar

EMFI

Scanner

TUI

Scan SWD modal (n)

Supported platforms

Subsequent sessions

Trigger polarity (EMFI / Crowbar)

Trigger timeout (EMFI / Crowbar fire)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Faulty Cat

Understanding Faulty Cat

How to update FaultyCat

FaultyCMD

FAQs

Clone this wiki locally

Scan SWD modal (`n`)