Skip to main content

Add Board

In DeviceScript, we commonly refere a Device Configuration as a board. You can see examples of configuration in each device page (like this one)

If your device is already using a supported system-on-a-chip (SoC) or MCU (ESP32, RP2040, ...), you can create a new board configuration in your project to support it in DeviceScript. You do not need to build a new firmware.

If you want to add a new system-on-a-chip (SoC), follow the add Soc guide.


If you just need to reconfigure a couple pins, you can also use the configureHardware function and skip the creation of a new board.

How to create a new board configuration

Create the new board.json file

You will need three pieces of information to start a new board: (1) the existing configuration you will fork, (2) a name and (3) an identifier.

In Visual Studio Code, select DeviceScript: Add Board... from the command palette.

Using the Command Line, use the add board command and follow the instructions.

devs add board

After this process, you wil have a new JSON under /boards/. The command line and Visual Studio Code will automatically integrate any configuration files in the /boards folder.

Editing the generated Device configuration (.json) file

The new configuration file is a schematized JSON file. In Visual Studio Code, you will get tooltip, completion, syntax errors and auto-completion.


The product identifier is used to identify devices in the Jacdac device catalog which is leveraged by the simulator dashboard.

  • configure the status light LED. DeviceScript supports monochrome LEDs, RGB LEDs, WS2812B, APA102, SK9822 and more (refer to the schema information).
    "led": {
"pin": 7,
"isMono": true
  • configure the system logging pin
    "log": {
"baud": 115200,
"pinTX": 0
  • configure I2C pins, add $connector only if there is a standardized connector
    "i2c": {
"pinSCL": 5,
"pinSDA": 4,
  • Update the pin map
    "pins": {
"P1": 1,
"P11": 11,
"P13": 13,
"P14": 14,
  • Update the board description
  • If available, provide a URL where the board can be purchased

Build the project to test the board definition.

npm run build


Note that there is two ways of defining services in the .board.json file. The ones listed under "$services": [ ... ] will generate startFoo() functions, which need to be called for the service to be started. The ones under "services": [ ... ] are always started; this is typically only used for power service.

    "$services": [
"service": "buzzer",
"pin": 20,
"name": "buzzer"

Flash the new configuration

The command line and Visual Studio will automatically integrate any configuration file in the boards/ folder. The first time you deploy a program with a new hardware configuration, it will reset the device.


If you have successfully crafted a configuration for your Device and you would like to share it with other users, you can open a GitHub Issue at and attach the .JSON file. The file will be reviewed and integrate into the built-in list.