Boardswarm服务器

Boardswarm是一个gRPC服务器，它公开了与开发板交互的有用API。名称中的swarm部分来源于服务器连接到其他boardswarm实例的能力，以透明的方式为最终用户提供功能和功能的共享与分发。

有关Boardswarm设计的更多信息，请参阅设计文档

运行boardswarm

要运行boardswarm，需要将yaml配置文件作为参数传递。作为起点，可以使用文档化的示例配置。

身份验证

Boardswarm始终验证JWT载体令牌的身份验证；令牌可以验证OIDC服务器或本地静态jwks文件。

基于OIDC的身份验证

对于基于OIDC的身份验证，需要配置OIDC发行者的uri和客户端id。虽然boardswarm本身仅使用uri获取服务器的JWKS密钥，但它们与描述一起暴露给客户端，以便通过OAuth 2.0设备授权授予检索令牌。

server:
  authentication:
    - type: oidc
      # This description can be show to users for selecting which method to
      # use
      description: "Example OIDC"
      # uri to the oidc issuer
      uri: "https://issuer.example.com/"
      # The client identifier to be used by the client to be included in the
      # device authorization request
      client: "boardswarm"
...

在客户端端，运行以下命令以设置此类服务器并按照说明进行身份验证

$ boardswarm-cli  --instance <instance name> configure --new  -u <instance url>

基于静态JWKS的身份验证

对于静态JWKS令牌，需要为boardswarm生成JWKS以验证令牌，而客户端需要由私钥签名的JWT令牌。一种简单的方法是使用rnbyc工具。

要使用EdDSA密钥生成jwks，可以使用以下命令

$ rnbyc -j -g  Ed25519  -x   -o private.jwks -p auth.jwks

private.jwks应保持私密并用于签名客户端身份验证令牌。auth.jwks文件可以在boardswarm中配置以验证令牌，如下所示

server:
  authentication:
    # Authentication against a static Json Web Key Set.
    - type: jwks
      # Path to jwks file to authenticate against
      path: auth.jwks
...

对于用户令牌，当前仅验证标准过期字段；要创建用户令牌（有效期至2025年1月1日），可以使用以下命令。

$ rnbyc  -s '{"exp": 1735686000 }' -K private.jwks -o token.jwt

在客户端端，运行以下命令以设置此类服务器并按照说明进行身份验证

$ boardswarm-cli  --instance <instance name> configure --new -u <instance url> --token-file <path to token file>

提供商

提供商在boardswarm中提供控制台、存储卷和执行器。每个提供商都在配置文件的providers部分进行配置，使用以下通用设置

providers:
  - name: myprovider # The name of the provider
    provider: provider # The provider to use
    # Optional device specific parameters
    parameters:
      <provider specific>

对于每个由提供者创建的项目，boardswarm.provider.name 属性被设置为配置的名称，而 boardswarm.provider 属性被设置为所使用的提供者。

串行提供者

串行提供者从本地串行端口创建控制台。不需要提供者特定的参数，并且通常只有一个此类提供者。

由该提供者提供的控制台的配置参数目前仅为 rate，其数值与控制台的波特率相匹配。

示例配置

provider:
  - name: serial
    provider: serial

设备固件更新提供者 (dfu)

支持 (DFU 1.1)dfu 类规范。DFU 设备通过 udev 自动检测并作为卷曝光。不需要提供者特定的参数，且只能存在一个此类提供者。

目前仅支持对 DFU 目标进行写操作。提交这些卷将执行 USB 断开连接后重置。

示例配置

provider:
  - name: dfu
    provider: dfu

Rock USB 提供者 (rockusb)

支持 rockchip USB 协议。rockusb 设备通过 udev 自动检测并作为卷曝光。不需要提供者特定的参数，且只能存在一个此类提供者。

当 rockusb 设备处于 maskrom 模式时，存在两个目标（471、472）与 sram 和 ddr 上传匹配。这些目标只能写入。可以通过 rock 命令（download-boot 子命令）上传 rockchip 加载器 .bin 文件到这些目标。

当处于加载器模式时，存在一个与闪存 ID 匹配的目标。这支持读取、写入和搜索。请注意，rockchip 加载器固件在读取时并不总是可靠的，尤其是在较大的偏移量处。

示例配置

provider:
  - name: rockusb
    provider: rockusb

pdudaemon 提供者

支持 pdudaemon，将其 pdus 和端口作为执行器曝光。对于 pdudaemon 参数，需要配置 pdudaemon uri 以及每个 pdu 和其端口（由于 pdudaemon 不支持自省）。

pdudaemon 提供的执行器接受一个 mode 参数，可以是 on 或 off（与 pdudaemon 动作匹配）。

由该提供者创建的每个项目都将具有以下属性

• pdudaemon.pdu：受控 pdu 的名称
• pdudaemon.port：使用 pdu 的端口

示例配置

provider:
  - name: pdu
    provider: pdudaemon
    # Configuration parameters for this provider
    parameters:
      # Uri of the pdudaemon server
      uri: http://localhost:16421/
      pdus:
        # pdu name (pdu hostname in pdudaemon terminology)
        - name: pdu-0
          # Number of ports; Will expose an actuator for port 1 to N as per
          # pdudaemon convention for numbered ports
          ports: 4
        - name: pdu-1
          # List of port names, for pdus that use named rather then numbered
          # ports
          ports:
            - "left"
            - "right"

gpio 提供者

支持使用 Linux GPIO 字符设备将 gpio 线作为执行器曝光。提供者特定的参数应包含一个匹配部分，以匹配应使用的 gpiochip 以及要作为执行器曝光的该芯片的线路列表。线路可以通过线路名称或线路编号进行识别（请参阅 gpioinfo 命令的输出以确定线路/名称）。

提供的执行器具有一个 value 参数，它接受一个布尔值来将 gpio 线设置为高或低。

由该提供者创建的每个项目都将具有以下属性

• gpio.chip_label：使用的 GPIO 芯片的标签
• gpio.line_number：使用的 gpio 线的编号
• gpio.line_name：如果可用，使用的 gpio 线的名称

示例配置

providers:
  - name: "rpi header gpio"
    provider: gpio
    parameters:
      # the match has a list of udev properties to match against in similar
      # syntax as the eventual expose item. The example below matches the
      # GPIO's on an RPI 4's extension header
      match:
        udev.OF_FULLNAME: "/soc/gpio@7e200000"
      # A list of lines to expose as actuators; Lines can either be defined by
      # either lines name or the line number
      lines:
        - line_name: "GPIO23"
          name: "maskrom"
        - line_number: 24
          name: "gpio24"

Boardswarm 客户端提供者

此提供者作为远程 boardswarm 服务的客户端，并将所有项目本地（重）曝光。这意味着所有远程项目都可以像本地项目一样使用。对于远程 boardswarm 的身份验证，仅支持静态 jwt 令牌。

提供的所有项目都将具有其 boardswarm.instance 属性设置为提供者实例名称。

示例配置

providers:
  # The boardswarm provider connects to a remote boardswarm instance as a
  # client and exposes all remote items as local ones.
  - name: remote
    provider: boardswarm
    parameters:
        # The uri of the remote server
        uri: http://remote.example.net:6683
        # Path to the jwt token to use to connect to the remote server
        token: remote.token

设备

设备是将一切联系起来的东西。设备包含

• 控制台：连接到设备的控制台列表
• 卷：与设备关联的卷列表
• 模式：设备可以操作的模式列表

要将设备与其他项目链接，可以使用配置中的match键来使用匹配，该键包含一个用于匹配的项目属性字典。远程实例上的项目只有在显式配置了boardswarm.instance属性时才会匹配，否则只有本地项目会被匹配。

设备控制台

与该设备链接的控制台列表。每个控制台都有一个名称、控制台特定参数和一个用于匹配控制台的匹配项。按照惯例，列表中的第一个控制台应在客户端被视为默认控制台。

匹配后，将使用它们的特定参数配置控制台。

一个配置示例，用于配置一个控制台，该控制台来自串行提供者，波特率为1.5mbit/s

devices:
  - name: device
    consoles:
      - name: main
        parameters:
          rate: 1500000
        match:
            udev.ID_SERIAL: "12345"

设备音量

与该设备链接的音量列表。每个音量都有一个名称和一个匹配部分。

基于连接的USB端口配置的设备单个音量的示例配置

devices:
  - name: device
    volumes:
      - name: volume
        match:
          udev.ID_PATH: "pci-0000:00:14.0-usb-0:12.3"

设备模式

模式指的是设备的操作模式。按照惯例，设备通常至少有两种模式“开”和“关”。“开”通常应指设备正常操作所期望的，而“关”应指设备完全关闭电源。其他模式可以配置为例如反映设备被打开，但配置为通过USB加载软件。

对于每种模式，应配置一系列步骤来切换设备到该模式。在每个步骤之后，可以配置一个stabilisation周期来等待下一个步骤执行（或标记切换为完成）。

模式可以依赖于设备首先处于特定模式。这有助于简化序列，因为可以假设设备处于已知状态（通常是关闭），而不是必须定义每个序列，使其可以从任何模式进入。

devices:
  - name: device
    modes:
      # Name of the mode, on/off are by convention the expected "normal"
      # powered on and powered off states
      - name: on
        # Mode the device needs to be on to ensure the expected mode is reached
        depends: off
        # The sequence of actuator actions to take the establish this mode
        sequence:
          # Each sequence item should have a match to match the actuator to use
          # and actuator specific parameters to apply
          # As the configuration is a yaml document anchors can be used to
          # avoid duplication.
          - match: &pdu
              boardswarm.name: pdu.pdu-1.port-1
            parameters:
              mode: on
      - name: maskrom
        depends: off
        sequence:
          - match: &maskrom
              boardswarm.name: maskrom
              # Items from remote instances have an instance property set with
              # the remote instance name
              boardswarm.instance: remote
            parameters:
              value: true
            # stabilisation provides a time period to wait after apply actuator
            # action. E.g. to wait for power to stablelise before doing next
            # actions
            stabilisation: 500ms
          - match: *pdu
            parameters:
              mode: on
            stabilisation: 1s
          - match: *maskrom
            parameters:
              value: false
      - name: off
        sequence:
          - match: *maskrom
            parameters:
              value: false
          - match: *pdu
            parameters:
              mode: off
            stabilisation: 2s