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

# Logic Analyzer Guide

> Use the Wokwi Logic Analyzer to debug and visualize digital signals, record VCD files, and analyze protocols using PulseView or GTKWave.

The [Logic Analyzer](/parts/wokwi-logic-analyzer) records the values of digital signals in your project. It's a powerful debugging tool, and can help you diagnose issues in your circuit and code. It's also very useful as a learning aid.

## Use cases

Some use cases include:

* Observe the PWM signal generated by the [analogWrite() function](https://www.arduino.cc/reference/en/language/functions/analog-io/analogwrite/)
* Look at the [Servo](/parts/wokwi-servo) control signal
* Develop and debug PIO machines for the [Raspberry Pi Pico](/parts/wokwi-pi-pico)
* Learn about the I2C protocol by looking at the SCL/SDA signals

<img src="https://mintlify.s3.us-west-1.amazonaws.com/wokwi-wokwi-docs/guides/logic-analyzer-i2c-decoder.png" alt="Logic Analyzer: I2C protocol signals decoded in PulseView" />

## Features

The Wokwi Logic Analyzer has 8 digital channels, called D0 to D7. It has a sample rate of 1GHz, which should be more than enough for most applications.

* Each channel has an activity LED that turns green whenever there is activity on the channel
* The activity LEDs provide an easy way to see that the signals are connected correctly
* The logic analyzer has a small display showing the number of samples captured since the simulation started
* The [configurable trigger](#using-the-trigger) lets you record just part of the data

## Using the Logic Analyzer

<Steps>
  <Step title="Add the Logic Analyzer">
    Click the blue Plus button, then select "Logic Analyzer (8 channels)".
  </Step>

  <Step title="Connect signals">
    Connect the signals you want to record to the Logic Analyzer pins. For instance, if you want to record I2C communication between an Arduino Uno and a peripheral, connect pins A4/A5 (SDA/SCL) to pins D0/D1 of the Logic Analyzer.
  </Step>

  <Step title="Start simulation">
    Start the simulation. You should see the green activity LEDs blink as the signals are coming in, and the number of samples should go up.
  </Step>

  <Step title="Download capture">
    Stop the simulation. This will download a file called "wokwi-logic.vcd" to your computer in [Value Change Dump](https://en.wikipedia.org/wiki/Value_change_dump) format.
  </Step>

  <Step title="View the capture">
    Use software such as PulseView or GTKWave to open and view the capture files.
  </Step>
</Steps>

### Exporting VCD in VS Code

When using [Wokwi for VS Code](/vscode/getting-started), the VCD file is automatically saved when the simulation stops, provided your diagram includes a Logic Analyzer. By default, the file is saved as `wokwi.vcd` in your project root.

You can customize the output path by adding the `vcdFile` option to your [wokwi.toml](/vscode/project-config) file:

```toml theme={null}
[wokwi]
version = 1
firmware = 'your-firmware.hex'
vcdFile = 'logic-capture.vcd'
```

### Using the Trigger

By default, the logic analyzer records data for the entire duration of the simulation. The trigger allows you to control the recording of data, by setting the value of one of the digital analyzer's input pins (D7 by default).

Here are some examples for common use cases:

* [Start recording when a button is pressed](https://wokwi.com/projects/313698551063380544) - Set the `triggerMode` to "edge", and connect the trigger pin (D7) to ground through a pull-down resistor. Connect the other end of the button to the positive power supply (VCC/5V).
* [Record only while the button is pressed](https://wokwi.com/projects/313706149095408193) - Same setup as above, but the `triggerMode` is set to "level".
* [Start recording after 1.5 seconds](https://wokwi.com/projects/313706408220557888) - Set `triggerMode` to "edge", connect the trigger pin (D7) and change the pin level to high after 1.5 seconds.

<Tip>
  Use the `triggerPin` and `triggerLevel` attributes to configure the trigger pin and set the trigger level ("high" or "low"). Check out the [wokwi-logic-analyzer documentation](/parts/wokwi-logic-analyzer) for more information.
</Tip>

### Customizing the Channel Names

By default, the channel names are D0, D1, D2, etc. You can customize the channel names by setting the `channelNames` attribute. For example, to name the channels "SCL", "SDA", "RST", add the following attribute to the logic analyzer:

```json theme={null}
{ 
  "type": "wokwi-logic-analyzer", 
  "id": "logic1",
  "attrs": {
    "channelNames": "SCL,SDA,RST"
  }
}
```

<Note>
  The channel names only affect the VCD file output. The input pins of the logic analyzer are called D0, D1, etc., regardless of the `channelNames` attribute.
</Note>

### Viewing the data in PulseView

PulseView is an open source Logic Analyzer GUI. It runs on Linux, Windows, Mac OS X, and there's even an Android version. You can visit their [downloads page](https://sigrok.org/wiki/Downloads) to get the latest version.

<Tip>
  For ARM Mac (M1/M2) users, please follow the [PulseView on Mac M1/M2 guide](https://nishtahir.com/running-pulseview-on-an-m1-mac/).
</Tip>

<Steps>
  <Step title="Import VCD file">
    Load the recorded signal (VCD) file by clicking on the small arrow next to the "Open" button, and choosing: "Import Value Change Dump data..."

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/wokwi-wokwi-docs/guides/logic-analyzer-pulseview-1.png" alt="PulseView: Import Value Change Dump data" />
  </Step>

  <Step title="Configure import options">
    You'll see a dialog where you can choose the VCD file to import. Once you selected a file, there'll be another dialog with import options.

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/wokwi-wokwi-docs/guides/logic-analyzer-pulseview-2.png" alt="PulseView: Compress idle periods" />
  </Step>

  <Step title="Set downsampling factor">
    Set the **Downsampling factor** to reduce memory usage. A value of **50** should work for most use cases.
  </Step>
</Steps>

<Warning>
  The default options usually cause PulseView to consume a lot of RAM and become sluggish. Setting the downsampling factor helps prevent this.
</Warning>

The following table lists some common downsampling values:

| Downsampling factor | Sample rate | When to use?                                          |
| ------------------- | ----------- | ----------------------------------------------------- |
| 1000                | 1MHz        | Low frequency signals / long recordings (10+ minutes) |
| **50**              | **20MHz**   | Common signals (UART, I2C, LED PWM, WS2812, etc.)     |
| 10                  | 100MHz      | High speed signals (10MHz+)                           |
| 1                   | 1GHz        | Very high speed signals (50MHz+)                      |

After confirming the import options, you should see the imported signals on the screen. The signal names will be "logic.D0", "logic.D1", etc.

<Card title="PulseView User Manual" icon="book" href="https://sigrok.org/doc/pulseview/unstable/manual.html">
  Learn more about using PulseView
</Card>

#### Configuring Windows to open VCD files in PulseView

You can configure Windows to automatically open VCD files in PulseView. Open a command prompt (cmd) window **as administrator**, and type the following commands:

```bash theme={null}
ftype vcdfile="%ProgramFiles%\sigrok\PulseView\pulseview.exe" "-I" "vcd:downsample=50" "%1"
assoc .vcd=vcdfile
```

<Warning>
  These commands don't work in powershell. They only work in cmd with Administrator privileges. The command sets the Downsampling factor to 50, but you can choose a different value that fits your needs.
</Warning>

### Viewing the data in GTKWave

[GTKWave](http://gtkwave.sourceforge.net/) is an open source, cross-platform wave viewer software. GTKWave can open VCD files generated by the Wokwi Logic Analyzer.

<Card title="wokwi2gtkwave Python Script" icon="code" href="https://github.com/bvandepo/wokwi2gtkwave">
  Automate GTKWave usage with Wokwi - monitor downloads and auto-display signals
</Card>

The [wokwi2gtkwave Python script](https://github.com/bvandepo/wokwi2gtkwave) is a user-contributed automation project for using GTKWave with Wokwi: it can monitor your downloads directory and automatically open new files with GTKWave. The script also configures GTKWave to automatically display the signals from your VCD files and zoom them to fit your screen.