Skip to main content
The pinout and properties of custom chips are defined in a Chip Definition JSON file. The file name should be <chip-name>.chip.json. For example, if your chip is called i2c-light-sensor, the file name should be i2c-light-sensor.chip.json. The JSON file should contain a single object with the following properties:
PropertyTypeDescription
namestringThe name of the chip. This name will be displayed in the diagram editor
authorstringThe name of the chip author
pinsarray of stringsThe list of pins for the chip
controlsarray of objectsThe list of controls for the chip (optional)
displayobjectConfiguration of an attached display (optional)

​
Complete Example

{
  "name": "My Custom Chip",
  "author": "Your Name",
  "pins": ["VCC", "GND", "SCL", "SDA", "OUT"],
  "controls": [
    {
      "id": "temperature",
      "label": "Temperature (°C)",
      "type": "range",
      "min": -40,
      "max": 125,
      "step": 0.1
    }
  ]
}

​
Pins

The pins array should contain the names of the pins for your chip, 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. For example: 
  "pins": ["VCC", "GND", "RST", "", "SCL", "SDA"],
The example above defines a chip with 5 pins, ordered as follows: 
       ___
 VCC -|⚬  |- SDA
 GND -|   |- SCL
 RST -|___|-

​
Controls

Controls provide a way for users to interact with your chip while the simulation is running. For example, a temperature sensor chip can have a control that lets the user set the current temperature. The controls property should contain an array of control objects. Each control object should have the following properties:
PropertyTypeDescriptionExample
idstringThe identifier for the control, please use camelCase (e.g. relativeHumidity)“relativeHumidity”
labelstringThe name of the control that will be displayed to the user”Relative Humidity”
typestringThe type of the control. Currently, the only valid value is “range”, which displays a slider”range”
minnumberThe minimum value for the control0
maxnumberThe maximum value for the control100
stepnumberThe step size for the slider1
For example: 
  "controls": [
    {
      "id": "relativeHumidity",
      "label": "Relative Humidity",
      "type": "range",
      "min": 0,
      "max": 100,
      "step": 1
    }
  ],
To read the value of the control from your chip code, use the Attributes API.

​
Display

The display property allows you to attach a display to your chip. Use the display to implement a custom LCD, OLED, or e-paper display, or to show the state of your chip (e.g. draw a graph of the temperature over time, or visually indicate the state of a blinds controller). The display property should contain an object with the following properties:
PropertyTypeDescriptionExample
widthnumberThe width of the display, in pixels128
heightnumberThe height of the display, in pixels64
For example: 
  "display": {
    "width": 128,
    "height": 64
  },
To draw on the display from your chip code, use the Framebuffer API.

​
JSON Schema

A JSON Schema for validating chip definition files is available in the wokwi-cli repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us