Skip to main content

Getting Started with the Wokwi Custom Chips C API

caution

The Chips API is currently in beta. Please share your experiments and provide feedback in the #custom-chips channel on the Discord chat.

Getting started​

Open the Custom Chip Playground, go to the code editor, press F1 and select Create a custom C chip (beta).

This will create a new file called i2c-counter.chip.c. This file contains an example of a simple I2C device with an 8-bit counter that increments for every byte that you read. Writing to the device will override the value.

The device also provides an INT pin that goes low when the counter is greater than 127. Otherwise, the INT pin is in input (high impedance) state.

Start the simulation to observe the behavior of the custom chip: the Arduino code should read the counter value, and the LED will light up when the counter goes over 127.

Adding your custom chip to the simulation​

The Custom Chip Playground already has the chip wired in, but you can follow the instructions below to connect a custom chip to a different project.

Add the following snippet to your diagram.json:

{ "type": "chip-i2c-counter", "id": "chip1", "top": 0, "left": 0, "attrs": {} },

Wokwi automatically generates a breakout board for your chip. Edit i2c-counter.chip.json to define the pins for your part. The pins array should contain the names of your chip's pins, starting from pin number 1. If you wish to skip some pins (e.g. you want the breakout board to only have pins on its left side), use an empty string ("") for the pin name.

Using the API​

First, make sure to #include "wokwi-api.h". The chip should declare a chip_init method. This method will be called for every new instance of the chip. If the chip has some internal state, chip_init should allocate memory for the internal state, and save a pointer to this memory in the void *user_data field of the device configuration structures (e.g. i2c_config_t, timer_config_t, etc.).

Here's an example of a minimal chip file:

#include "wokwi-api.h"

void chip_init() {
  /*
    This method runs when the simulation starts. It's called once for each instance of the chip.
    You'd usually allocate some memory to store the chip state, initialize a bunch of pins with pin_init(),
    and configure pin watches, timers, and protocols such as UART, I2C, and SPI.
  */
}

Debugging your custom chip​

You can print debugging messages using the standard C printf() function. Make sure to also #include <stdio.h> in your program. The debugging messages will appear in the browser's developer console (to view it in Chrome: Ctrl+Shift+J or Option+⌘+J).

The debug messages from your chip will be printed in green color:

Chip debug messages displayed in green

In addition, you can use the Wokwi Logic Analyzer to debug the communication with your custom chip.

tip

Make sure to include a newline ("\n") at the end of your printf() messages. The simulator shows the messages only when it reaches a newline character.

Chips API reference 📖​

Chip examples​