Getting Started with the Wokwi Custom Chips C API
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:

In addition, you can use the Wokwi Logic Analyzer to debug the communication with your custom chip.
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 📖
- GPIO pins API
- Analog API
- Time simulation API
- UART API
- I2C Device API
- SPI Device API
- Attributes
- Framebuffer API
Chip examples
- Digital Inverter
- XOR gate
- SPI Chip - Implements a basic ROT13 cipher
- I2C Chip - Simple counter interrupt output
- UART Chip - Implements a basic ROT13 cipher
- Timer Chip - Showing how to use the Timer API
- LM75A Chip - I2C digital temperature sensor
- Framebuffer Chip - Shows how to implement a custom display driver chip
- IL9163 Display Driver - 128x128 color LCD display chip
- I2C Keypad Driver Example (by Yewolf)
- CD4051B Multiplexer Example (by Chris Schmidt)
- EEPROM Chip (by Benny Meisels)
- PCA9685 Chip (by Bonny Rais)
- DS18B20 Chip (by Bonny Rais) - Dallas Semi DS18B20 Temperature Sensor over OneWire