Skip to main content

Getting Started with the Wokwi Custom Chips C API

warning

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

Introduction​

The Custom Chips API allows you to create new simulation models and extend the functionality of Wokwi. You can create new sensors, displays, memories, testing instruments, and even simulate your own custom hardware.

Custom Chips are usually written in C, but you can use any language that compiles to WebAssembly (e.g. Rust, AssemblyScript, etc.). There is also an experimental support for writing custom chips in Verilog.

Tutorials​

Getting started​

Open any Wokwi project (or create a new one) and click on the blue "+" button in the diagram editor. Select "Custom Chip" from the list of options.

You'll see a dialog where you can enter the chip name, as well as the language you wish to use. We recommend using C for now. After typing a name for your chip, click on the "Create Chip" button.

This will add a copy of the chip to your diagram and create two files in your project:

  • a JSON file with the chip pinout and settings (name, author, etc.)
  • a C file with the chip code (or a rust/verilog file, depending on the language you selected).

The JSON file file defines a minimal set of pins ("VCC", "GND", "IN", "OUT"). Change the pin names and add more pins as needed.

The C file contains a minimal chip implementation. Add your code to the chip_init() function. This function is called for every instance of the chip in the diagram. You can use it to initialize the chip state, configure timers, and set up pin watches.

The example code also includes a chip_state_t struct, where you can store any state that your chip needs. You can use the user_data field of the i2c_config_t, timer_config_t, etc. to store a pointer to this struct.

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 debug messages will appear in a new "Chips Console" tab below the diagram view:

Chips Console

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​

Basics​

Communication​

  • SPI Chip - A basic ROT13 cipher over SPI
  • UART Chip - A basic ROT13 cipher over UART
  • I2C Chip - Simple counter with interrupt output
  • EEPROM Chip - Simple I2C memory with 256 kbits by Benny Meisels

Displays​

Sensors​

Complex chips​