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.

tip

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.

note

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

Services​

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.

Contributing​

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 https://github.com/microsoft/devicescript and attach the .JSON file. The file will be reviewed and integrate into the built-in list.