板卡描述,描述了具体的硬件板卡上存在哪些硬件接口(比如,GPIO接口),以及应用可以操作的内置设备(比如,LED)。板卡描述是 Ruff APP 运行在具体板卡上的基石。
请参考 Ruff MBD V1 ,了解一个具体的板卡描述文件如何编写。
前提条件
- 如果还没有了解如何使用 Ruff 编写应用,可以阅读这里。
- 如果还没有了解如何创建板卡项目,可以阅读这里。
- 如果你希望在
rap layout --visual
能够正确进行图形化展示,请在软件仓库上传并配置设备信息。参考这里了解如何在软件仓库添加设备。 - 请查看板卡对应的技术手册,确定板卡上的接口类型和内置设备,以及相应的参数。
板卡描述文件的基本结构
board.json
是板卡工程的主要文件,用以描述板卡信息。其基本结构如下:{
"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"
}
}
板卡声明包括如下内容:
version
,这个版本号是board.json
的模式(schema)版本号,当前版本为2.0。id
,该板卡描述的 ID,它是你在创建工程的时候输入的工程名。model
,该板卡的所支持硬件的型号,建议在软件仓库上传设备信息后,将设备型号配置在这里。devices
,描述了板卡上所支持的硬件资源(接口或设备)。outputs
,描述了板卡对外导出的硬件资源,也就是其它外设可以使用的接口。
板卡资源配置
在板卡的配置过程中,最重要的是配置板卡上的各种资源,包括:
- 硬件接口
- 电源管脚(VCC)
- 接地管脚(GND)
- 板载设备
在配置过程中,如果需要的驱动不是 RuffOS 中内置的驱动,需要通过 rap install --save
安装后,才可以配置中引用。
硬件接口
硬件接口,是板卡上最重要的组成部分,只有对外提供了硬件接口,其它外设才能接入。
配置硬件接口,要配置两个部分:
devices
,配置接口的基本信息,包括驱动、PIN 等。outputs
,配置对外导出的接口,也就是其它外设用以接入的接口。
devices
部分包含如下字段:
id
,该设备对象的 ID。driver
,该设备对象使用的驱动inputs
,为该驱动配置的输入参数outputs
,该设备对象导出的接口,这是在程序中真实用到的接口对象。
下面是一个例子:"devices": [
...
{
"id": "gpio-0",
"driver": "sys-gpio",
"inputs": {
"pin": {
"type": "number",
"args": {
"pin": 0
}
}
},
"outputs": {
"gpio": {
"type": "gpio"
}
}
}
...
],
"outputs": {
...
"gpio-0": "gpio-0/gpio"
...
}
这里,我们声明了一个 GPIO 接口:
- 其 ID 命名为
gpio-0
- 驱动是
sys-gpio
,这是由 RuffOS 提供的一个内置驱动。 - 这个驱动要求指定 GPIO 对应的 PIN,其类型是一个数字,参数是
pin
为 0。 - 它会导出一个 GPIO 接口供其它外设使用,其名字为
gpio
,类型为gpio
,在硬件布局的过程中,会根据这个类型进行匹配。
我们在 outputs
里可以定义一个供外部使用的名字:
gpio-0
,它对应的就是gpio-0
导出的名为gpio
的接口。
更多配置细节,请参考硬件接口指南。
电源管脚(VCC)
电源管脚,是板卡上为外设提供的电源接口。
配置电源管脚,需要在 devices
部分声明一个 id 为 power
的配置。在板卡描述文件中,电源管脚是一个虚拟的配置,无需配置驱动,只要根据板卡的实际情况,声明对应的信息即可。具体的配置需要在 outputs
字段声明,每个电源管脚都要有一个参数:
voltage
,描述该电源管脚对应的电压。
下面是一个例子:"devices": [
...
{
"id": "power",
"outputs": {
"vdd-0": {
"type": "power",
"args": {
"voltage": "3.3v"
}
},
"vdd-1": {
"type": "power",
"args": {
"voltage": "5v"
}
}
}
},
...
]
其中声明了两个电源管脚:
- 名为
vdd-0
的电源管脚,电压为3.3v。 - 名为
vdd-1
的电源管脚,电压为5v。
接地管脚(GND)
接地管脚,是板卡上为外设提供的地线接口。
配置电源管脚,需要在 devices
部分声明一个 id 为 ground
的配置。在板卡描述文件中,接地管脚是一个虚拟的配置,无需配置驱动,只要根据板卡的实际情况,声明对应的信息即可。具体的配置需要在 outputs
字段声明。
下面是一个例子,声明了四个接地管脚。"devices": [
...
{
"id": "ground",
"outputs": {
"gnd-0": {
"type": "ground"
},
"gnd-1": {
"type": "ground"
},
"gnd-2": {
"type": "ground"
},
"gnd-3": {
"type": "ground"
}
}
}
...
]
板载设备
板载设备,是板卡上预置的设备,比如,LED、按钮等。应用程序可以通过板卡描述文件中声明的信息操控板载设备。
板载设备需要配置在 devices
中,通常要配置如下字段:
id
,设备 ID,应用程序可以通过$(‘#‘)访问该设备。 model
,可选字段,设备的型号driver
,该设备对应的驱动inputs
,输入信息,用于给驱动提供输入参数,根据驱动的不同,配置内容不同。
通常来说,板载设备的驱动是一个普通的驱动,需要通过 rap install --save
安装后,才可以在配置中引用。
下面是一个板载 LED 的描述:"devices": [
...
{
"id": "led-r",
"model": "ruff-led-gpio",
"driver": "led-gpio",
"inputs": {
"gpio": {
"type": "gpio",
"bind": "gpio-22/gpio",
"args": {
"direction": "out",
"level": "low"
}
}
}
}
...
]
上面的配置说明
- 该板载 LED 的 ID 为
led-r
,应用程序可以通过$(‘#led-r’)访问。 - 其型号为
ruff-led-gpio
- 其驱动为
led-gpio
- 在
inputs
字段中,具体的配置信息依赖于led-gpio
。这里声明了一个名为gpio
的配置,- 其接口类型为
gpio
- 绑定到
gpio-22/gpio
- 该配置有两个参数,分别是
direction
为out
,level
为low
- 其接口类型为
硬件接口指南
目前,Ruff 支持的硬件接口类型包括:
接口类型 | RuffOS 内置驱动 |
---|---|
GPIO | sys-gpio |
I²C | sys-i2c |
UART | sys-uart |
PWM | N |
ADC | N |
RuffOS 内置驱动
GPIO
RuffOS 内置的驱动为 sys-gpio:
- 以 PIN 作为输入参数
- 导出一个 GPIO 接口供使用
下面是一个例子:"devices": [
...
{
"id": "gpio-0",
"driver": "sys-gpio",
"inputs": {
"pin": {
"type": "number",
"args": {
"pin": 0
}
}
},
"outputs": {
"gpio": {
"type": "gpio"
}
}
}
...
],
"outputs": {
...
"gpio-0": "gpio-0/gpio"
...
}
I²C
RuffOS 内置的驱动为 sys-i2c
- 以 bus 作为输入参数
- 导出一个 I²C 接口供使用
下面是一个例子:"devices": [
...
{
"id": "i2c-0",
"model": "ruff-i2c",
"driver": "sys-i2c",
"inputs": {
"bus": {
"type": "number",
"args": {
"bus": 0
}
}
},
"outputs": {
"i2c": {
"type": "i2c"
}
}
}
...
],
"outputs": {
...
"i2c-0": "i2c-0/i2c"
...
}
UART
RuffOS 内置的驱动为 sys-uart
- 以路径作为输入参数
- 导出一个 UART 接口供使用
"devices": [ |
转换接口
在硬件接口开发中,将一个接口专为另外一种接口是一种常见的做法。
下面以 Ruff MBD V1 为例,介绍一些转换驱动。
I²C 转 PWM
在 Ruff MBD V1 中,采用 pca9685
将 I²C 转成了8路的 PWM,下面是一个例子:"devices": [
...
{
"id": "ruff-pwm",
"model": "ruff-pwm",
"driver": "pca9685",
"inputs": {
"i2c": {
"type": "i2c",
"args": {
"address": 85
}
}
},
"outputs": {
"pwm-0": {
"type": "pwm"
},
"pwm-1": {
"type": "pwm"
},
"pwm-2": {
"type": "pwm"
},
"pwm-3": {
"type": "pwm"
},
"pwm-4": {
"type": "pwm"
},
"pwm-5": {
"type": "pwm"
},
"pwm-6": {
"type": "pwm"
},
"pwm-7": {
"type": "pwm"
}
}
}
...
],
"outputs": {
...
"pwm-0": "ruff-pwm/pwm-0",
"pwm-1": "ruff-pwm/pwm-1",
"pwm-2": "ruff-pwm/pwm-2",
"pwm-3": "ruff-pwm/pwm-3",
"pwm-4": "ruff-pwm/pwm-4",
"pwm-5": "ruff-pwm/pwm-5",
"pwm-6": "ruff-pwm/pwm-6",
"pwm-7": "ruff-pwm/pwm-7",
...
}
I²C 转 ADC
在 Ruff MBD V1 中,采用 ltc2309
将 I²C 转成了8路的 ADC,下面是一个例子:"devices": [
...
{
"id": "ruff-adc",
"model": "ruff-adc",
"driver": "ltc2309",
"inputs": {
"i2c": {
"type": "i2c",
"args": {
"address": 8
}
}
},
"outputs": {
"an-0": {
"type": "adc"
},
"an-1": {
"type": "adc"
},
"an-2": {
"type": "adc"
},
"an-3": {
"type": "adc"
},
"an-4": {
"type": "adc"
},
"an-5": {
"type": "adc"
},
"an-6": {
"type": "adc"
},
"an-7": {
"type": "adc"
}
}
}
...
],
"outputs": {
...
"an-0": "ruff-adc/an-0",
"an-1": "ruff-adc/an-1",
"an-2": "ruff-adc/an-2",
"an-3": "ruff-adc/an-3",
"an-4": "ruff-adc/an-4",
"an-5": "ruff-adc/an-5",
"an-6": "ruff-adc/an-6",
"an-7": "ruff-adc/an-7",
...
}
I²C 转 GPIO
在 Ruff MBD V1 中,采用 mcp23017
将 I²C 转成了16路的 GPIO,下面是一个例子:"devices": [
...
{
"id": "gpio-plus",
"model": "ruff-gpio",
"driver": "mcp23017",
"inputs": {
"i2c": {
"type": "i2c",
"args": {
"address": 36
}
},
"gpio": {
"type": "gpio",
"bind": "gpio-0/gpio",
"args": {
"direction": "in",
"edge": "both"
}
}
},
"outputs": {
"io-0": {
"type": "gpio"
},
"io-1": {
"type": "gpio"
},
"io-2": {
"type": "gpio"
},
"io-3": {
"type": "gpio"
},
"io-4": {
"type": "gpio"
},
"io-5": {
"type": "gpio"
},
"io-6": {
"type": "gpio"
},
"io-7": {
"type": "gpio"
},
"io-8": {
"type": "gpio"
},
"io-9": {
"type": "gpio"
},
"io-10": {
"type": "gpio"
},
"io-11": {
"type": "gpio"
},
"io-12": {
"type": "gpio"
},
"io-13": {
"type": "gpio"
},
"io-14": {
"type": "gpio"
},
"io-15": {
"type": "gpio"
}
}
}
...
],
"outputs": {
...
"io-0": "gpio-plus/io-0",
"io-1": "gpio-plus/io-1",
"io-2": "gpio-plus/io-2",
"io-3": "gpio-plus/io-3",
"io-4": "gpio-plus/io-4",
"io-5": "gpio-plus/io-5",
"io-6": "gpio-plus/io-6",
"io-7": "gpio-plus/io-7",
"io-8": "gpio-plus/io-8",
"io-9": "gpio-plus/io-9",
"io-10": "gpio-plus/io-10",
"io-11": "gpio-plus/io-11",
"io-12": "gpio-plus/io-12",
"io-13": "gpio-plus/io-13",
"io-14": "gpio-plus/io-14",
"io-15": "gpio-plus/io-15"
...
}