Board - Getting Started

Ruff Board Description describes hardware interfaces (such as GPIO), and on-board devices (such as LED) that application can control. The board is a prerequisite condition for any Ruff app to run on a real board.

Here we introduce a basic structure, because the board description files is too big to fit in the web page. Please go to Ruff MBD V1 for more details of a real board description.


  • Please here here if you are not sure how to use Ruff to write apps.

  • Please upload device information to Rap Registry to demonstrate accurately on rap layout —visual.

    Refer to here to know how to add a device to Rap Registry.

  • Please read the datasheet to confirm the information of hardwares interface and on-board boards.

Step 1: Creating a Project

  • Create a new project folder (hello-ruff-board).

  • Change the directory of the folder just created in step 1 and use rap to initialize the board.

    Note: the argument here is board. It will generate some board related configuration.

    mkdir hello-ruff-board
    cd hello-ruff-board

    rap init board
  • Please fill in information as prompted. You can use default values for all fields. rap will initialize the project and generate files as follows:

    • package.json, package configuration
    • board.json, board description

Step 2: Declaring the Hardware Interface

board.json works as the board description in this project. The basic structure of board.json is listed as follow:

"version": "2.0",
"id": "foo",
"model": "foo",
"devices": [
"id": "gpio-0",
"driver": "sys-gpio",
"inputs": {
"pin": {
"type": "number",
"args": {
"pin": 0
"outputs": {
"gpio": {
"type": "gpio"
"outputs": {
"gpio-0": "gpio-0/gpio"

Here are some properties declared in board.json:

  • version - the schema version of board.json currently is 2.0.
  • id - for this board here, it is also the ID that you input during initialization.
  • model - We strongly recommend users to upload the device information of the hardware model to Rap Registry.
  • devices - the on-board hardware resource(interface or device).
  • outputs - the export hardware resource, and also can be used by other devices.

devicesand outputs are the most important parts of the board developers to verify.

Here is a case of GPIO Interface:

  • Many GPIO interfaces are located on the same board. So, we need to name it gpio-0.
  • The driver for this GPIO is sys-gpio, which is a Ruff OS built-in driver. (If yours is a plain driver, rap install --save first and then follow the steps here).
  • The driver requires a PIN number. Here, the argument pin is 0.
  • It will export a GPIO interface for other devices to use, naming it as gpio and the type is gpio. It will be matched with the type in the layout.

Once the hardware interface is defined, we will export a name in outputs:

  • gpio-0 - the inteface that gpio-0 exports and is named as gpio.

Step 3: Testing The Board

Now we are ready write an application to test the board. Please follow the instruction in Getting Started and Development Steps to write an application. When creating your application, you need to specify a local board project.

mkdir hello-ruff
cd hello-ruff

rap init --local-board /path/to/your_board_project

When you finish writing the application, you can start to deploy it to the board. Please refer to Ruff OS Porting Guide to port Ruff.

The most significant is to find out whether other devices are successfully supported by testing the layout. Please run the following commands:

rap layout

If it works, it means that the board is configured successfully.

Extension: Board Publishing

Your development is finished after coding and testing. If you would like to share it with others, you can publish it to the Registry. Please login to your account or apply for your account by clicking here.

Note: please upload your device information to Rap Registry, if you want rap layout —visual to work well.

Please run the following command to publish:

rap publish

Next Step

If you would like to know more about the board development, please go to Ruff Board Model.