Open the editorEditor

Custom chips

A custom chip is a chip whose behavior is code: a sensor Mokxi has no part for, a display driver or a memory. Chips written for Wokwi's chip API run as is.

These are different from the chips you make from parts. Those are a circuit folded into a box. A custom chip is a program.

Bring a chip over from Wokwi

A chip comes with the project it is in. Import the project the usual way and its chips come along as parts, with their pins and their wires:

  • A Wokwi for VS Code or Wokwi CLI project has each chip already built: the chip.wasm its wokwi.toml names, next to a chip.json. Mokxi runs that file.
  • A project from wokwi.com has each chip as two files, <name>.chip.json and <name>.chip.c. Bring both in.
  • A chip the project names under dependencies in its diagram.json, such as "chip-pwm": "github:Dlloydev/Wokwi-Chip-PWM@1.0.6", is downloaded from that release on GitHub, as Wokwi does.

The import report says which chips came over, and what was missing from any that did not. A chip whose files were not in the upload is a note on the canvas where it stood.

Write your own

Open the More menu and choose New custom chip. Name it, and the chip goes on the canvas, starting as an inverter. It is also in the part panel under Chips in this project, so you can place as many as you need.

The chip's two files open in the code panel, picked like a board's files from the list at its top:

  • <name>.chip.json names its pins, in order from pin 1, and can add sliders (controls) and a display. A pin's place in the list is where it is on the chip: down the left side, then up the right.
  • <name>.chip.c is what it does, in C, with Wokwi's chip API: pin_init, pin_watch, pin_write, timer_start, attr_read, i2c_init, spi_init, uart_init and the rest.

Press Run and Mokxi builds the chip's code first, in your browser. A mistake in the code shows in the build panel, and clicking it goes to the line. A chip written in Mokxi is a Wokwi chip too: the same two files work there.

Run it

Press Run. Each chip runs its own code next to the circuit, at the speed of the simulation: a chip timer of one millisecond fires after one simulated millisecond.

  • What the chip prints with printf shows in the serial monitor, under the chip's id.
  • A chip with a display draws on its body.
  • A chip with controls (a temperature, a light level) has a slider for each one in its panel. Click the chip and move a slider while the circuit runs; the chip reads the new value right away.

A chip's other settings are its properties, as in Wokwi's diagram.json.

Safe to run

A chip's code runs in a box of its own. It cannot reach the page, your files, the network or any other part of the circuit except through its own pins. It gets 16 MB of memory at most. If its code gets stuck in a loop that never ends, Mokxi stops that one chip, says so in the serial monitor, and the rest of the circuit keeps running.

How it differs from Wokwi

Mokxi simulates voltages and Wokwi does not, so a chip pin reads high above 2.5 V. A circuit that only worked on Wokwi because levels are perfect there may need a resistor here, as it would on a real bench. A chip's outputs drive at the voltage on its VCC pin, so a chip on a 3.3 V board drives 3.3 V.

Wokwi's experimental functions for reading the microcontroller's memory do nothing in Mokxi yet; a chip that uses them says so in the serial monitor.