Wokwi

https://github.com/wokwi/wokwi-docs
Admin
Wokwi is an online simulator and development environment for microcontrollers and embedded systems,...
Tokens:102,842
Snippets:908
Trust Score:8.9
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### libraries.txt example with version pinning

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/guides/libraries.md

Example of a libraries.txt file that installs the latest versions of Servo and FastLED, and version 2.3.0 of MySensors. Lines starting with '#' are comments, and '@' followed by a version selects a specific library version.

```text
# Sample libraries.txt file:
Servo
FastLED

# Install a specific version of a library:
MySensors@2.3.0
```

--------------------------------

### GDB tbreak setup and continue

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/gdb-debugging.md

Example GDB session: set a temporary breakpoint at setup() with 'tbreak setup', continue with 'c', and stop at the beginning of setup(). The output shows the breakpoint location and the source line.

```gdb
(gdb) tbreak setup
Temporary breakpoint 1 at 0x2ca: file sketch.ino, line 28.
(gdb) c
Continuing.

Temporary breakpoint 1, setup () at sketch.ino:28
28        pinMode(LED_BUILTIN, OUTPUT);
(gdb)
```

--------------------------------

### Start local development server with npm start

Source: https://github.com/wokwi/wokwi-docs/blob/main/README.md

Start the local development server. This opens a browser window with the docs site, and most changes are reflected live without restarting the server.

```console
npm start
```

--------------------------------

### Install Wokwi CLI on Unix-like systems

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/cli-installation.md

Run this command in a terminal to install the Wokwi CLI on Linux or macOS. It downloads and executes the installation script from wokwi.com.

```bash
curl -L https://wokwi.com/ci/install.sh | sh
```

--------------------------------

### Wire placement instructions example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/diagram-format.md

Example of wire placement instructions using 'v' and 'h' commands with '*' separating source and target instructions.

```json
["v10", "h5", "*", "v-15", "h10"]
```

--------------------------------

### requirements.txt for Adafruit libraries

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/guides/circuitpython.md

Example requirements.txt file to install Adafruit libraries. Lines starting with '#' are comments. Wokwi downloads libraries and dependencies into the 'lib' folder.

```text
# requirements.txt example
adafruit_display_text
adafruit_dht
```

--------------------------------

### Install Wokwi CLI on Windows PowerShell

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/cli-installation.md

Use this command in PowerShell on Windows to install the Wokwi CLI. It downloads and executes the installation script from wokwi.com.

```powershell
iwr https://wokwi.com/ci/install.ps1 -useb | iex
```

--------------------------------

### Install idf-wokwi extension for ESP-IDF

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/cli-installation.md

Run this command to install the idf-wokwi extension, which allows you to access Wokwi simulations from the ESP-IDF toolchain's idf.py command.

```bash
pip install idf-wokwi
```

--------------------------------

### Display configuration example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/chip-json.md

Attaches a display with a width of 128 and height of 64 pixels.

```json
  "display": {
    "width": 128,
    "height": 64
  },
```

--------------------------------

### Install dependencies with npm install

Source: https://github.com/wokwi/wokwi-docs/blob/main/README.md

Install the project dependencies. Requires node.js and npm to be installed on your computer.

```console
npm install
```

--------------------------------

### Install ssd1306 library with mpremote

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/vscode-micropython.md

Installs the ssd1306 library from the MicroPython mip package repository onto the simulator.

```bash
mpremote connect port:rfc2217://localhost:4000 mip install ssd1306
```

--------------------------------

### SPI Configuration Example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/spi.md

Initializes an SPI device with specified pins, mode, and done callback. The 'done' callback must be called from chip_init().

```cpp
const spi_config_t spi1 = {
  .sck = pin_init("SCK", INPUT),
  .mosi = pin_init("MOSI", INPUT),
  .miso = pin_init("MISO", INPUT),
  .mode = 0,
  .done = chip_spi_done, // See the example below
  .user_data = chip,
};
```

--------------------------------

### Start interactive Docker session for chip compilation

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/guides/custom-chips-to-wasm.md

Starts an interactive Docker session with the wokwi/builder-clang-wasm image, mounting the current directory to /src. Use this to manually run build commands inside the container.

```bash
docker run --rm -it -u 1000:1000 -v ${PWD}:/src wokwi/builder-clang-wasm:latest
```

--------------------------------

### Arduino code example for wokwi-led-ring

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-led-ring.md

Arduino example for driving a wokwi-led-ring with the Adafruit_NeoPixel library. Sets all pixels to green and keeps the sketch running with a short delay.

```cpp
#include <Adafruit_NeoPixel.h>

#define RING_PIN 2
#define NUM_PIXELS 16

Adafruit_NeoPixel ring(NUM_PIXELS, RING_PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  ring.begin();
  for (int i = 0; i < NUM_PIXELS; i++) {
    ring.setPixelColor(i, ring.Color(0, 150, 0)); // Green
  }
  ring.show();
}

void loop() {
  delay(10);
}
```

--------------------------------

### UART configuration example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/uart.md

Shows how to define a uart_config_t struct with RX/TX pins, baud rate, and callbacks. The callbacks are optional and receive user_data as the first argument.

```cpp
static void on_uart_rx_data(void *user_data, uint8_t byte) {
  // `byte` is the byte received on the "RX" pin
}

static uint8_t on_uart_write_done(void *user_data) {
  // You can write the chunk of data to transmit here (by calling uart_write).
}

// ...

const uart_config_t uart1 = {
  .tx = pin_init("TX", INPUT_PULLUP),
  .rx = pin_init("RX", INPUT),
  .baud_rate = 115200,
  .rx_data = on_uart_rx_data,
  .write_done = on_uart_write_done,
  .user_data = chip,
};
```

--------------------------------

### Connection array example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/diagram-format.md

Shows a connection array connecting the A pin of led1 to pin 13 of the uno part with a green wire and no placement instructions.

```json
  ["led1:A", "uno:13", "green", []],
```

--------------------------------

### Run a simulation with wokwi-cli

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/cli-usage.md

Starts the simulation and displays serial output. The CLI automatically exits after 30 seconds by default.

```bash
wokwi-cli <your-project-directory>
```

--------------------------------

### Arduino code example for wokwi-neopixel

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-neopixel.md

Arduino example for the wokwi-neopixel part. Initializes a single WS2812 LED on pin 6, sets it to red, and shows the color. The loop just delays, so the LED stays red.

```cpp
#include <Adafruit_NeoPixel.h>

#define LED_PIN 6

Adafruit_NeoPixel pixel(1, LED_PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  pixel.begin();
  pixel.setPixelColor(0, pixel.Color(150, 0, 0)); // Red
  pixel.show();
}

void loop() {
  delay(100);
}

```

--------------------------------

### Arduino code example for wokwi-led-strip

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-led-strip.md

Arduino sketch using Adafruit_NeoPixel to control an 8-pixel WS2812 LED strip on pin 2. Sets all pixels to red in setup() and keeps the loop running with a delay.

```cpp
#include <Adafruit_NeoPixel.h>

#define STRIP_PIN 2
#define NUM_PIXELS 8

Adafruit_NeoPixel strip(NUM_PIXELS, STRIP_PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  strip.begin();
  for (int i = 0; i < NUM_PIXELS; i++) {
    strip.setPixelColor(i, strip.Color(150, 0, 0)); // Red
  }
  strip.show();
}

void loop() {
  delay(10);
}

```

--------------------------------

### Example usage of idf.py wokwi

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/idf-wokwi-usage.md

Shows setting the WOKWI_CI_TOKEN environment variable, building the project, running a simulation, and using the --timeout and --expect-text options for CI mode.

```bash
export WOKWI_CI_TOKEN="your-token-here"

# Build and simulate
idf.py build
idf.py wokwi

# CI mode: exit when expected text appears
idf.py wokwi --timeout 10000 --expect-text "Hello world!"
```

--------------------------------

### Run Wokwi scenario test for wokwi-dht22

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/automation-scenarios.md

Commands to clone the wokwi-part-tests repository, navigate to the dht22-esp32 example, build the firmware with PlatformIO, and run the Wokwi scenario test. Requires PlatformIO Core, Wokwi CLI, and the WOKWI_CLI_TOKEN environment variable.

```bash
git clone https://github.com/wokwi/wokwi-part-tests
```

```bash
cd wokwi-dht22/dht22-esp32
```

```bash
pio run
```

```bash
wokwi-cli . --scenario dht22.test.yaml
```

--------------------------------

### Touch coordinate mapping example (Arduino)

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/automation-scenarios.md

Shows how to map touch controller coordinates to display coordinates. The touch controller's origin is at the bottom-right of the display, not the top-left. This example uses the Adafruit FT6206 library on a 240x320 ILI9341 display.

```cpp
TS_Point p = ts.getPoint();
// Flip to match display coordinates
p.x = map(p.x, 0, 240, 240, 0);
p.y = map(p.y, 0, 320, 320, 0);
```

--------------------------------

### Install matching mpremote version with pip

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/vscode-micropython.md

Install mpremote version 1.23 to match the default firmware version in the project repository. Use this command to avoid compatibility issues.

```bash
pip install mpremote==1.23
```

--------------------------------

### ASCII art of pin layout for skipped pin example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/chip-json.md

Visual representation of the chip pinout for the example with a skipped pin.

```text
       ___
 VCC -|⚬  |- SDA
 GND -|   |- SCL
 RST -|___|-
```

--------------------------------

### Successful Wokwi CLI test output

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/automation-scenarios.md

Example output from a successful Wokwi CLI test run for the dht22-esp32 scenario. Shows the simulation startup, expected text matches, and the final 'Scenario completed successfully' message.

```text
Wokwi CLI v0.18.3 (786fa8e49d9c)
Connected to Wokwi Simulation API 1.0.0-20251028-g60747fe2
Starting simulation...
ets Jul 29 2019 12:21:46
[DHT22 Sensor Test (ESP32)] Expected text matched: "ets Jul 29 2019 12:21:46"

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0030,len:1156
load:0x40078000,len:11456
ho 0 tail 12 room 4
load:0x40080400,len:2972
entry 0x400805dc
DHT22 test!
[DHT22 Sensor Test (ESP32)] Expected text matched: "DHT22 test!"
Humidity: 45.80%  Temperature: 23.50°C
[DHT22 Sensor Test (ESP32)] Expected text matched: "Humidity: 45.80%  Temperature: 23.50°C"
Humidity: 45.80%  Temperature: 23.50°C
[DHT22 Sensor Test (ESP32)] Expected text matched: "Humidity: 45.80%  Temperature: 23.50°C"
Humidity: 66.90%  Temperature: 21.50°C
[DHT22 Sensor Test (ESP32)] Expected text matched: "Humidity: 66.90%  Temperature: 21.50°C"
[DHT22 Sensor Test (ESP32)] Scenario completed successfully
```

--------------------------------

### touch-release command example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/automation-scenarios.md

Releases the touch. The part-id is the target part.

```yaml
touch-release:
  part-id: esp32s3box
```

--------------------------------

### Arduino code example for wokwi-led-matrix

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-led-matrix.md

Arduino sketch using the Adafruit_NeoPixel library to control a wokwi-led-matrix. It initializes the matrix, sets all pixels to blue, and displays them. The loop just delays, so the display remains static.

```cpp
#include <Adafruit_NeoPixel.h>

#define MATRIX_PIN 2
#define ROWS 8
#define COLS 8
#define NUM_PIXELS (ROWS * COLS)

Adafruit_NeoPixel matrix(NUM_PIXELS, MATRIX_PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  matrix.begin();
  for (int i = 0; i < NUM_PIXELS; i++) {
    matrix.setPixelColor(i, matrix.Color(0, 0, 150)); // Blue
  }
  matrix.show();
}

void loop() {
  delay(10);
}
```

--------------------------------

### Arduino code example using Keypad library

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-membrane-keypad.md

Arduino sketch that reads key presses from a 4x4 keypad using the Keypad library. The keys array defines the values returned by keypad.getKey(), which must be single ASCII characters. The example uses pins 9,8,7,6 for rows and 5,4,3,2 for columns, and prints the pressed key to the serial monitor.

```cpp
#include <Keypad.h>

const uint8_t ROWS = 4;
const uint8_t COLS = 4;
char keys[ROWS][COLS] = {
  { '1', '2', '3', 'A' },
  { '4', '5', '6', 'B' },
  { '7', '8', '9', 'C' },
  { '*', '0', '#', 'D' }
};

uint8_t colPins[COLS] = { 5, 4, 3, 2 }; // Pins connected to C1, C2, C3, C4
uint8_t rowPins[ROWS] = { 9, 8, 7, 6 }; // Pins connected to R1, R2, R3, R4

Keypad keypad = Keypad(makeKeymap(keys), rowPins, colPins, ROWS, COLS);

void setup() {
  Serial.begin(9600);
}

void loop() {
  char key = keypad.getKey();

  if (key != NO_KEY) {
    Serial.println(key);
  }
}
```

--------------------------------

### Wait for USB Serial Monitor connection

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-pi-pico.md

Waits for the USB Serial Monitor connection before printing. Use this in setup() to avoid losing messages printed during USB setup time.

```cpp
void setup() {
  Serial.begin(115200);
  while (!Serial) {
    delay(10); // wait for serial port to connect. Needed for native USB
  }
  // Now you can safely print message:
  Serial.println("Hello, Serial Monitor!");
}
```

--------------------------------

### Arduino code example for standard configuration

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-lcd1602.md

Initializes the LiquidCrystal library with pin numbers matching the standard configuration table. Use this when connecting the LCD in 4-bit parallel mode with pins RS=12, E=11, D4=10, D5=9, D6=8, D7=7.

```cpp
#include <LiquidCrystal.h>

LiquidCrystal lcd(12, 11, 10, 9, 8, 7);

void setup() {
  lcd.begin(16, 2);
  // you can now interact with the LCD, e.g.:
  lcd.print("Hello World!");
}

void loop() {
  // ...
}
```

--------------------------------

### Configure Wokwi GDB server port in wokwi.toml

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/debugging.md

Add this line to the [wokwi] section of your wokwi.toml file to enable the GDB server on port 3333. This is required before starting the debugger.

```toml
gdbServerPort=3333
```

--------------------------------

### TinyDebug: Print debug messages with Debug.println()

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-attiny85.md

Include TinyDebug.h and call Debug.begin() in setup, then use Debug.println() to send messages to Wokwi's Serial Monitor. Requires a libraries.txt file containing 'TinyDebug'.

```cpp
#include <TinyDebug.h>

void setup() {
  Debug.begin();
  Debug.println(F("Hello, TinyDebug!"));
}

void loop() {
  /* Sprinkle some magic code here */
}
```

--------------------------------

### Configure wokwi-wifi-ap attributes (JSON)

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-wifi-ap.md

Example attributes for configuring a wokwi-wifi-ap part. The first creates an open network, the second a WPA2-secured network, and the third a local-only network without internet access.

```json
{ "ssid": "FreeWiFi" }
```

```json
{ "ssid": "HomeNet", "password": "secret123" }
```

```json
{ "ssid": "LocalOnly", "internet": "0" }
```

--------------------------------

### Drag gesture example combining touch commands

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/automation-scenarios.md

Simulates a drag gesture by combining touch-press, delay, touch-move, delay, and touch-release commands in a sequence.

```yaml
- touch-press:
    part-id: esp32s3box
    x: 50
    y: 100
- delay: 50ms
- touch-move:
    part-id: esp32s3box
    x: 150
    y: 100
- delay: 50ms
- touch-release:
    part-id: esp32s3box
```

--------------------------------

### Defining an LED with position and attributes

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/diagram-format.md

Shows how to define a part in the 'parts' section. Example defines a red LED with id 'led1', type 'wokwi-led', at position (100, 50), and sets its color attribute to red. Each part must have a unique 'id'.

```json
{
  "id": "led1",
  "type": "wokwi-led",
  "left": 100,
  "top": 50,
  "attrs": {
    "color": "red"
  }
}
```

--------------------------------

### touch-press command example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/automation-scenarios.md

Sends a press event at the given coordinates. Pair with touch-release to complete the gesture. The part-id is the target part, and x/y are in touch controller coordinates.

```yaml
touch-press:
  part-id: esp32s3box
  x: 120
  y: 160
```

--------------------------------

### Controls array example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/chip-json.md

Defines a control with an id, label, type, min, max, and step.

```json
  "controls": [
    {
      "id": "relativeHumidity",
      "label": "Relative Humidity",
      "type": "range",
      "min": 0,
      "max": 100,
      "step": 1
    }
  ],
```

--------------------------------

### Configure wokwi.toml with [[chip]] key

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/guides/custom-chips-to-wasm.md

Example excerpt from wokwi.toml. The [[chip]] key specifies the name and binary used by the custom chip. The name is used in diagram.json as a part type with the prefix 'chip-'. The binary path points to the WASM file.

```toml
[[chip]]
name = 'inverter' # To use the chip in diagram.json, add a part with "chip-inverter" type.
binary = 'chips/inverter.chip.wasm'

```

--------------------------------

### void spi_start(spi_dev_t spi, uint8_t *buffer, uint32_t count)

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/spi.md

Starts an SPI transaction, sending and receiving `count` bytes to/from the given `buffer`. You will usually listen for the CS (chip select) pin with `pin_watch` and call this when the CS pin goes low.

```APIDOC
## void spi_start(spi_dev_t spi, uint8_t *buffer, uint32_t count)

### Description
Starts an SPI transaction, sending and receiving `count` bytes to/from the given `buffer`.

### Parameters
- `spi` (spi_dev_t) - The SPI device handle returned by `spi_init`.
- `buffer` (uint8_t*) - Pointer to the buffer for data to be sent and received.
- `count` (uint32_t) - Number of bytes to transfer.

### Notes
- You will usually listen for the CS (chip select) pin with `pin_watch`. Call `spi_start()` when the CS pin goes low, and `spi_stop()` when the CS pin goes high.
- When creating a device that transfers large amounts of data (e.g. an LCD display), it's recommended to use a large buffer size (few kilobytes). The simulator can use the larger buffer to optimize DMA-controlled SPI transfer and speed up the simulation.
- For simple devices that transfer small amounts of data, you can use a single-byte buffer, and process each byte as it arrives in the `done` callback.
```

--------------------------------

### touch-move command example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/automation-scenarios.md

Sends a move (drag) event to new coordinates. Use between touch-press and touch-release. The part-id is the target part, and x/y are in touch controller coordinates.

```yaml
touch-move:
  part-id: esp32s3box
  x: 150
  y: 200
```

--------------------------------

### Arduino code example for BMP180 with Adafruit BMP085 library

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/board-bmp180.md

Arduino example using the Adafruit BMP085 library (compatible with BMP180) to read temperature, pressure, and altitude. On Arduino Uno, connect SDA to A4 and SCL to A5. The code prints readings to the serial monitor every second.

```cpp
#include <Wire.h>
#include <Adafruit_BMP085.h>

Adafruit_BMP085 bmp;

void setup() {
  Serial.begin(115200);

  if (!bmp.begin()) {
    Serial.println("BMP180 not found!");
    while (1);
  }

  Serial.println("BMP180 ready!");
}

void loop() {
  float temperature = bmp.readTemperature();
  int32_t pressure = bmp.readPressure();
  float altitude = bmp.readAltitude();

  Serial.print("Temperature: ");
  Serial.print(temperature);
  Serial.println(" C");

  Serial.print("Pressure: ");
  Serial.print(pressure);
  Serial.println(" Pa");

  Serial.print("Altitude: ");
  Serial.print(altitude);
  Serial.println(" m");

  Serial.println();
  delay(1000);
}
```

--------------------------------

### Arduino code example for wokwi-hx711

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-hx711.md

Arduino sketch that initializes the HX711 scale on pins A1 (DT) and A0 (SCK), then prints the weight in units every second. Uses the HX711 library's begin(), get_units(), and delay() functions.

```cpp
#include "HX711.h"

HX711 scale;

void setup() {
  Serial.begin(9600);
  Serial.println("Initializing the scale");
  scale.begin(A1, A0);
}

void loop() {
  Serial.println(scale.get_units(), 1);
  delay(1000);
}

```

--------------------------------

### Read MPU6050 acceleration with Adafruit library

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-mpu6050.md

Arduino example using the Adafruit MPU6050 library to read and display acceleration values. On Arduino Uno, connect SDA to A4 and SCL to A5. The loop prints X, Y, Z acceleration in m/s^2 every 500 ms.

```cpp
#include <Adafruit_MPU6050.h>
#include <Adafruit_Sensor.h>
#include <Wire.h>

Adafruit_MPU6050 mpu;

void setup(void) {
  Serial.begin(115200);

  while (!mpu.begin()) {
    Serial.println("MPU6050 not connected!");
    delay(1000);
  }
  Serial.println("MPU6050 ready!");
}

sensors_event_t event;

void loop() {
  mpu.getAccelerometerSensor()->getEvent(&event);

  Serial.print("[");
  Serial.print(millis());
  Serial.print("] X: ");
  Serial.print(event.acceleration.x);
  Serial.print(", Y: ");
  Serial.print(event.acceleration.y);
  Serial.print(", Z: ");
  Serial.print(event.acceleration.z);
  Serial.println(" m/s^2");
  delay(500);
}
```

--------------------------------

### Blink the onboard LED using LED_BUILTIN

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/board-st-nucleo-c031c6.md

Use in Arduino sketches to configure the built-in LED pin as an output and drive it high to turn on the LED. Place in setup() and loop() as needed.

```cpp
pinMode(LED_BUILTIN, OUTPUT);
digitalWrite(LED_BUILTIN, HIGH);
```

--------------------------------

### Arduino tone() example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-buzzer.md

Plays a 262Hz tone for 0.25 seconds on pin 8. Connect buzzer pin 1 to GND and pin 2 to Arduino pin 8.

```cpp
tone(8, 262, 250); // Plays 262Hz tone for 0.250 seconds
```

--------------------------------

### SPI Done Callback Example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/spi.md

Signature for the done callback. It processes received data and schedules the next transaction if the CS pin is still low.

```cpp
static void chip_spi_done(void *user_data, uint8_t *buffer, uint32_t count) {
  // 1. process the received data (optional)
  // 2. if the CS pin is still low, schedule the next SPI transaction using `spi_start`
}
```

--------------------------------

### Connect to serial port with PySerial

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/project-config.md

Python example using PySerial's RFC2217 support to connect to the serial port. Ensure the simulator tab is visible in VS Code, otherwise the simulation may pause and no serial output will be received.

```python
import serial

ser = serial.serial_for_url('rfc2217://localhost:4000', baudrate=115200)
ser.write(b'hello')

```

--------------------------------

### Arduino shiftOut example for wokwi-74hc595

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-74hc595.md

Arduino code that shifts out an 8-bit pattern to the 74HC595, assuming DS on pin 2, SHCP on pin 3, and STCP on pin 4. The pattern inverts every 500 ms.

```cpp
const int dataPin = 2;   /* DS */
const int clockPin = 3;  /* SHCP */
const int latchPin = 4;  /* STCP */

void setup() {
  pinMode(dataPin, OUTPUT);
  pinMode(clockPin, OUTPUT);
  pinMode(latchPin, OUTPUT);
}

int pattern = 0b10101010;
void loop() {
  digitalWrite(latchPin, LOW);
  shiftOut(dataPin, clockPin, LSBFIRST, pattern);
  digitalWrite(latchPin, HIGH);
  delay(500);
  pattern = ~pattern; // Invert the pattern
}
```

--------------------------------

### Initialize a project with wokwi-cli init

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/cli-usage.md

Run in the project's root directory to configure the project for Wokwi. It asks a few questions and automatically generates wokwi.toml and diagram.json files.

```bash
wokwi-cli init
```

--------------------------------

### Adafruit_ILI9341 basic usage

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-ili9341.md

Basic usage of the Adafruit_ILI9341 library with the wokwi-ili9341 display. Uses the pin connections from the table above: TFT_DC on pin 9 and TFT_CS on pin 10. The example prints colored text on the display.

```cpp
#include "SPI.h"
#include "Adafruit_GFX.h"
#include "Adafruit_ILI9341.h"

#define TFT_DC 9
#define TFT_CS 10
Adafruit_ILI9341 tft = Adafruit_ILI9341(TFT_CS, TFT_DC);

void setup() {
  tft.begin();

  tft.setCursor(26, 120);
  tft.setTextColor(ILI9341_RED);
  tft.setTextSize(3);
  tft.println("Hello, TFT!");

  tft.setCursor(20, 160);
  tft.setTextColor(ILI9341_GREEN);
  tft.setTextSize(2);
  tft.println("I can has colors?");
}

void loop() { }
```

--------------------------------

### TinyDebug: Read serial input with Debug.read()

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-attiny85.md

Use the Debug object to read input from the Simulator's serial monitor. The example checks if the read character is 'c' and then performs an action.

```cpp
if (Debug.read() == 'c') {
  // Do something, e.g. toggle an LED
}
```

--------------------------------

### Zephyr workspace directory tree

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/migrating.md

Default workspace tree for Zephyr. The tree is not complete; follow the Zephyr getting started guide and application development documentation for project preparation.

```text
├── bootloader
│   └── mcuboot
├── modules
│   ├── bsim_hw_models
│   ├── crypto
│   ├── debug
│   ├── fs
│   ├── hal
│   ├── lib
│   └── tee
├── tools
│   ├── edtt
│   └── net-tools
├── .west
│   └── config
└── zephyr
    ├── arch
    ├── boards
    ...
    ├── zephyr-env.cmd
    └── zephyr-env.sh
```

--------------------------------

### Arduino: Read potentiometer value with analogRead()

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-potentiometer.md

Connect SIG to an analog input pin (e.g., A0) and use analogRead() to read the current value. This example prints the value every 100 ms over Serial.

```cpp
void setup() {
  Serial.begin(115200);
  pinMode(A0, INPUT);
}

void loop() {
  int value = analogRead(A0);
  Serial.println(value);
  delay(100);
}
```

--------------------------------

### Serial port forwarding configuration

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/project-config.md

Enable serial port forwarding via an RFC2217 TCP server. This starts an RFC2217 server on port 4000, allowing connection via Serial Monitor extension, PuTTY, or PySerial's RFC2217 support.

```toml
rfc2217ServerPort = 4000

```

--------------------------------

### Animate a custom character by modifying it in loop()

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-lcd1602.md

Animates the custom heart character by gradually revealing it line-by-line. Replaces the loop() from the previous example; uses the same heart array and lcd.createChar() to update the character at runtime.

```cpp
void loop() {
  uint8_t heart2[8] = {0};
  for (int i = 0; i < 8; i++) {
    heart2[i] = heart[i];
    lcd.createChar(3, heart2);
    delay(100);
  }
  delay(500);
}
```

--------------------------------

### Arduino TVout circle drawing example

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-tv.md

Arduino code using the TVout library to draw a circle on the Wokwi TV. Connect SYNC to Arduino pin 9 and IN to pin 7. Initializes PAL mode with 120x96 resolution, clears the screen, and draws a circle at (60,48) with radius 32 in white.

```cpp
// Connect SYNC to Arduino pin 9, IN to Arduino pin 7

#include <TVout.h>

TVout TV;

void setup() {
  TV.begin(PAL, 120, 96);
  TV.clear_screen();
  TV.draw_circle(60, 48, 32, WHITE);
}

void loop() {
}
```

--------------------------------

### Create mpremote shortcut for Wokwi

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/vscode-micropython.md

Creates a config file so you can connect to the simulator with `mpremote wokwi`. Run these commands in a Unix shell.

```bash
mkdir -p ~/.config/mpremote
echo 'config={"wokwi": "connect port:rfc2217://localhost:4000"}' > ~/.config/mpremote/config.py
```

--------------------------------

### Arduino code example for DS18B20

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-ds18b20.md

Arduino sketch using OneWire and DallasTemperature libraries to read temperature from a DS18B20 sensor on pin 2. Prints temperature in Celsius to serial every second. Note: DallasTemperature library cannot read exactly -55°C due to a limitation; use OneWire directly for that.

```cpp
#include <OneWire.h>
#include <DallasTemperature.h>

#define ONE_WIRE_BUS 2

OneWire oneWire(ONE_WIRE_BUS);
DallasTemperature sensors(&oneWire);

void setup() {
  Serial.begin(115200);
  sensors.begin();
}

void loop() {
  sensors.requestTemperatures();
  float tempC = sensors.getTempCByIndex(0);
  Serial.print("Temperature: ");
  Serial.print(tempC);
  Serial.println(" °C");
  delay(1000);
}
```

--------------------------------

### Connect to Wokwi-GUEST from Arduino (WiFi.begin)

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/guides/esp32-wifi.md

Connects an ESP32 to the virtual Wokwi-GUEST access point from Arduino. Specifies WiFi channel 6 to skip scanning and save about 4 seconds. Prints dots until connected.

```cpp
#include <WiFi.h>

void setup() {
  Serial.begin(9600);
  Serial.print("Connecting to WiFi");
  WiFi.begin("Wokwi-GUEST", "", 6);
  while (WiFi.status() != WL_CONNECTED) {
    delay(100);
    Serial.print(".");
  }
  Serial.println(" Connected!");
}

void loop() {
  delay(100); // TODO: Build something amazing!
}

```

--------------------------------

### void timer_start_ns(timer_t timer_id, uint64_t nanos, bool repeat)

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/time.md

Similar to timer_start but specifies the duration in nanoseconds. Prefer timer_start when possible for better performance.

```APIDOC
## void timer_start_ns(timer_t timer_id, uint64_t nanos, bool repeat)

### Description
Similar to `timer_start`, but specifies the duration of the timer in nanoseconds instead of microseconds. Prefer `timer_start()` when possible to improve performance.

### Method
Function call

### Parameters
- **timer_id** (timer_t) - Required - The identifier of the timer to start.
- **nanos** (uint64_t) - Required - Duration in nanoseconds until the timer fires.
- **repeat** (bool) - Required - Whether the timer repeats.

### Returns
- void
```

--------------------------------

### Basic wokwi.toml configuration

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/project-config.md

Basic wokwi.toml configuration. Replace the firmware path with the location of the compiled firmware, relative to the wokwi.toml file. The elf field is optional but can speed up simulation. Avoid backslashes in paths; use forward slashes.

```toml
[wokwi]
version = 1
firmware = 'path-to-your-firmware.hex'
elf = 'path-to-your-firmware.elf'

```

--------------------------------

### Upload main.py with mpremote

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/vscode-micropython.md

Uploads the main.py file to the simulator's filesystem. Requires the simulation to be running and the serial port configured.

```bash
mpremote connect port:rfc2217://localhost:4000 fs cp main.py :main.py 
```

--------------------------------

### VS Code launch configuration for Wokwi GDB

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/debugging.md

Template for .vscode/launch.json. Uses the cppdbg type (requires the C/C++ extension). Replace the program path with your firmware's ELF file and miDebuggerPath with a GDB executable that supports your project's architecture (e.g., avr-gdb for AVR).

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Wokwi GDB",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/your-firmware.elf",
      "cwd": "${workspaceFolder}",
      "MIMode": "gdb",
      "miDebuggerPath": "/usr/local/bin/xtensa-esp32-elf-gdb",
      "miDebuggerServerAddress": "localhost:3333"
    }
  ]
}
```

--------------------------------

### Basic automation scenario file structure

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/automation-scenarios.md

Shows the required top-level fields (name, version, author) and a steps list containing set-control, delay, and wait-serial actions. Use as a template for any automation scenario file loaded with the --scenario CLI option.

```yaml
name: 'Your scenario name'
version: 1
author: 'Your name'

steps:
  # List of steps:
  - set-control:
      part-id: btn1
      control: pressed
      value: 1
  - delay: 500ms
  - wait-serial: 'Button 1 pressed'
```

--------------------------------

### uart_init

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/uart.md

Initializes a UART device with the given configuration, including pins, baud rate, and callbacks.

```APIDOC
## uart_init

### Description
Initializes a UART device with the specified configuration, including RX/TX pins, baud rate, and optional callbacks for received data and transmission completion.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
#### Parameters
- **config** (const uart_config_t*) - Required - Pointer to a configuration struct with the following fields:
  - **rx** (pin_t) - The RX pin, or `NO_PIN` to disable RX.
  - **tx** (pin_t) - The TX pin, or `NO_PIN` to disable TX.
  - **baud_rate** (uint32_t) - The baud rate (e.g., 115200).
  - **rx_data** (callback) - Optional - Called for each byte received on the RX pin.
  - **write_done** (callback) - Optional - Called when data transmission on the TX pin has finished.
  - **user_data** (void*) - Data passed as the first argument to the callbacks.

### Request Example
```cpp
static void on_uart_rx_data(void *user_data, uint8_t byte) {
  // `byte` is the byte received on the "RX" pin
}

static uint8_t on_uart_write_done(void *user_data) {
  // You can write the chunk of data to transmit here (by calling uart_write).
}

const uart_config_t uart1 = {
  .tx = pin_init("TX", INPUT_PULLUP),
  .rx = pin_init("RX", INPUT),
  .baud_rate = 115200,
  .rx_data = on_uart_rx_data,
  .write_done = on_uart_write_done,
  .user_data = chip,
};

uart_dev_t uart = uart_init(&uart1);
```

### Response
#### Success Response
- **uart_dev_t** - The initialized UART device handle.

#### Response Example
```cpp
uart_dev_t uart = uart_init(&uart1);
```

### Error Handling
No explicit error handling is documented.
```

--------------------------------

### Compile chip with Docker using wokwi/builder-clang-wasm

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/guides/custom-chips-to-wasm.md

Runs the project's Makefile inside a Docker container using the prebuilt wokwi/builder-clang-wasm image. The -u 1000:1000 flag is required to avoid permission issues; adjust the UID/GID if your host user ID differs.

```bash
docker run --rm -u 1000:1000 -v ${PWD}:/src wokwi/builder-clang-wasm:latest make
```

--------------------------------

### Control a part step (set-control)

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/wokwi-ci/automation-scenarios.md

Sets a controllable aspect of a component to a specified value. The control name depends on the part's documentation; for example, temperature or humidity on a DHT sensor.

```yaml
set-control:
  part-id: dht
  control: humidity
  value: 39
```

--------------------------------

### Setting up a pin watch

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/gpio.md

Configures a pin watch with FALLING edge, the chip_pin_change callback, and user_data, then calls pin_watch.

```cpp
const pin_watch_config_t watch_config = {
  .edge = FALLING,
  .pin_change = chip_pin_change,
  .user_data = chip,
};
pin_watch(pin, &watch_config);
```

--------------------------------

### Connect to Wokwi-GUEST from Rust (esp-idf-svc)

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/guides/esp32-wifi.md

Connects an ESP32 to Wokwi-GUEST using Rust with esp-idf-svc. Requires setting auth_method to None in ClientConfiguration. Uses esp-idf-hal and esp-idf-svc crates.

```rust
use embedded_svc::wifi::{AuthMethod, ClientConfiguration, Configuration};
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::wifi::EspWifi;
use esp_idf_sys::EspError;
fn main() -> Result<(), EspError> {
    esp_idf_sys::link_patches();

    let peripherals = Peripherals::take().unwrap();
    let sysloop = EspSystemEventLoop::take()?;
    let nvs_default_partition = EspDefaultNvsPartition::take()?;

    let mut wifi = EspWifi::new(
        peripherals.modem,
        sysloop.clone(),
        Some(nvs_default_partition.clone()),
    )?;

    wifi.set_configuration(&Configuration::Client(ClientConfiguration {
        ssid: "Wokwi-GUEST".into(),
        password: "".into(),
        auth_method: AuthMethod::None,
        ..Default::default()
    }))?;

    wifi.start()?;
    wifi.connect()?;

    Ok(())
}

```

--------------------------------

### PlatformIO project directory tree

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/migrating.md

Default directory structure for a new PlatformIO Arduino project. Replace /src/main.cpp with the .ino file from the downloaded project.

```text
├── .gitignore
├── include
│   └── README
├── lib
│   └── README
├── platformio.ini
├── src
│   └── main.cpp
└── test
    └── README
```

--------------------------------

### Define Pi Pico part with id "pico"

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-pi-pico.md

Defines the Pi Pico part with id "pico" in diagram.json, as required by the UART Serial Monitor connections example.

```json
  "parts": [
    {
      "type": "wokwi-pi-pico",
      "id": "pico",
      …
    },
    …
  ]
```

--------------------------------

### List uploaded files with mpremote

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/vscode/vscode-micropython.md

Lists the files currently uploaded to the simulator's filesystem.

```bash
 mpremote connect port:rfc2217://localhost:4000 ls
```

--------------------------------

### Initialize I2C device with callbacks using i2c_init

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/chips-api/i2c.md

Defines the optional I2C callbacks and initializes an I2C device with address 0x22 on SCL/SDA pins. The connect callback returns true for ACK, false for NACK; read returns the byte to send; write returns ACK/NACK; disconnect is optional. i2c_init must be called from chip_init() only.

```cpp
bool on_i2c_connect(void *user_data, uint32_t address, bool read) {
  // `address` parameter contains the 7-bit address that was received on the I2C bus.
  // `read` indicates whether this is a read request (true) or write request (false).
  return true; // true means ACK, false NACK
}

uint8_t on_i2c_read(void *user_data) {
  return 0; // The byte to be returned to the microcontroller
}

bool on_i2c_write(void *user_data, uint8_t data) {
  // `data` is the byte received from the microcontroller
  return true; // true means ACK, false NACK
}

void on_i2c_disconnect(void *user_data) {
  // This method is optional. Useful if you need to know when the I2C transaction has concluded.
}

static const i2c_config_t i2c1 {
  .address = 0x22,
  .scl = pin_init("SCL", INPUT_PULLUP),
  .sda = pin_init("SDA", INPUT_PULLUP),
  .connect = on_i2c_connect,
  .read = on_i2c_read,
  .write = on_i2c_write,
  .disconnect = on_i2c_disconnect,
  .user_data = chip,
};
```

--------------------------------

### Arduino code example for HC-SR04

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/parts/wokwi-hc-sr04.md

Arduino sketch that triggers a measurement on the HC-SR04 and reads the ECHO pulse length to calculate distance in centimeters and inches. It uses digitalWrite and pulseIn to measure the pulse, and prints the results to the serial monitor.

```cpp
#define PIN_TRIG 3
#define PIN_ECHO 2

void setup() {
  Serial.begin(115200);
  pinMode(PIN_TRIG, OUTPUT);
  pinMode(PIN_ECHO, INPUT);
}

void loop() {
  // Start a new measurement:
  digitalWrite(PIN_TRIG, HIGH);
  delayMicroseconds(10);
  digitalWrite(PIN_TRIG, LOW);

  // Read the result:
  int duration = pulseIn(PIN_ECHO, HIGH);
  Serial.print("Distance in CM: ");
  Serial.println(duration / 58);
  Serial.print("Distance in inches: ");
  Serial.println(duration / 148);

  delay(1000);
}

```

--------------------------------

### Connect to Wokwi-GUEST from MicroPython (network.WLAN)

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/guides/esp32-wifi.md

Connects a MicroPython ESP32 to the Wokwi-GUEST access point. After connecting, you can use the urequests library for HTTP/HTTPS and umqtt for MQTT.

```python
import network
import time

print("Connecting to WiFi", end="")
sta_if = network.WLAN(network.STA_IF)
sta_if.active(True)
sta_if.connect('Wokwi-GUEST', '')
while not sta_if.isconnected():
  print(".", end="")
  time.sleep(0.1)
print(" Connected!")

```

--------------------------------

### List files in flash filesystem

Source: https://github.com/wokwi/wokwi-docs/blob/main/docs/guides/circuitpython.md

Lists all files in the flash filesystem root. Useful for verifying project files are copied to the Pico's flash.

```python
import os
print(os.listdir('/'))
```
Tokens:
Raw