メタデータファイル

Firmixのプロジェクトの各属性値はテキストベースのメタデータファイルによって管理しています。

基本となるメタデータファイルの例

以下は基本的なメタデータファイルの例です。こちらのXiao RP2040のボード動作確認のプロジェクトのファイルを例に解説を行います。

{
  "projectGuid": "b7452e0c-c88f-4aa7-a006-f506cf7f0fcb",
  "projectName": "Xiao RP2040 ボード動作確認",
  "introductionLines": [
    "ボードの動作確認用のプログラムです。",
    "ボード上のLEDを点滅させます。"
  ],
  "targetMcu": "RP2040",
  "targetBoardLabel": "Seeed Xiao RP2040",
  "repositoryUrl": "https://github.com/yahiro07/firmix_projects/tree/main/firmix/blink_xiao_rp2040",
  "tags": ["RP2040", "サンプル"],
  "firmwareSpec": { "path": ".pio/build/generic/firmware.uf2" }
}

この例を見ながら、各フィールドについて解説します。

各フィールドの詳細

`projectGuid`

FirmixではプロジェクトをGUIDで識別しています。プロジェクト毎にユニークな値を指定してください。新しい値の生成には以下のジェネレータをご利用ください。

プロジェクトのGUIDは、既存のプロジェクトを更新する際に、対象のプロジェクトを識別するために使われます。投稿時に自分が所有しているプロジェクトで同じGUIDのプロジェクトがあるときは新しい内容で既存の投稿を上書きする動作になります。同じGUIDのプロジェクトがあり、他の人がそのプロジェクトを所有している場合にはエラーとなり上書きできないようになっています。

`projectName`

プロジェクトの名前です。タイトルとして表示されます。最大 32 文字です。

`introductionLines`

プロジェクト一覧画面に表示されるカードの説明文として表示されます。文字列の配列で指定します。表示上では文字列の値ごとに改行で区切られます。

`targetMcu`

対象MCUの識別名です。現在サポートされている値は以下のとおりです。

RP2040
SAMD21
SAMD51
nRF52840
ESP32S3

上のリスト以外の値を指定するとエラーとなり投稿できません。
主に表示上の識別のためにこの値を使用しています。ファームウェアの管理の実装上ではマイコンの品種毎に固有の処理などはなくどのMCUでも同様に扱っています。

`targetBoardLabel`

プロジェクトがターゲットとしているボード名を書き込みます。任意の文字列で32文字までです。
プロジェクトの詳細画面で、ファームウェアダウンロードボタンのそばに表示されます。誤ったボードにファームウェアを書き込んでしまうのを防ぐための表示です。

`repositoryUrl` (オプション)

Githubでプロジェクトのソースコードを管理している場合、そのページのURLをここに書きます。プロジェクトの詳細画面にこのURLへのリンクが配置されます。

`tags`

タグを複数指定できます。各タグは32文字までです。

`firmwareSpec`

ファームウェアを読み込む際のパスを指定します。読み込ませるファームウェアのファイル形式によって指定の仕方に違いがあります。

UF2ファイルを指定する場合

PlatformIOでarduino-picoを使ってRP2040のビルドをする構成など、ビルドプロセスでUF2ファイルが生成される環境では、FirmixにはビルドされたUF2ファイルのパスを指定して、これをそのまま読み込ませます。

(例)RP2040の場合

   "firmwareSpec": { "path": ".pio/build/generic/firmware.uf2" }

binやhexから変換する場合

PlatformIOでSAMD21やnRF52840のプロジェクトをビルドした際にはbinファイルやhexファイルが生成されますが、UF2ファイルは出力されません。Firmixにはファームウェアの読み込み時にbinファイルやhexファイルを読み込んで内部でUF2形式に変換する機能があるため、そのための指定を追加します。

uf2gen_optionsというフィールドにUF2形式に変換する際のオプションを指定します。内部的にはuf2genというパッケージを利用しており、オプションの形式もこれに従っています。
binファイルからの変換の際には、ブートローダのベースアドレスを指定する必要があります。

以下に各MCUごとのオプションの設定例を示します。

(例)ATSAMD21の場合

  "firmwareSpec": {
    "path": ".pio/build/xiao/firmware.bin",
    "uf2gen_options": { "family": "SAMD21", "base": "0x2000" }
  }

ATSAMD21やATSAMD51の場合、ベースアドレスに0x2000を指定します。

(例)ESP32S3の場合

  "firmwareSpec": {
    "path": ".pio/build/xiao_esp32s3/firmware.bin",
    "uf2gen_options": { "family": "ESP32S3", "base": "0x00" }
  }

EPS32の場合はベースアドレスに0x00を指定します。

(例)nRF52840の場合

  "firmwareSpec": {
    "path": ".pio/build/xiao_ble/firmware.hex",
    "uf2gen_options": { "family": "NRF52840" }
  }

hexファイルからUF2ファイルに変換する場合、ベースアドレスはhexファイルから読み込まれて自動で決まります。値を指定する必要はありません。

派生元プロジェクトの設定

Firmixには派生プロジェクトの機能があり、既存のプロジェクトを派生させて独自の機能を追加したものを公開する際にこの機能を利用できます。派生先のプロジェクトは派生元のプロジェクトからたどって表示することができますが、プロジェクト一覧には表示されないという扱いになっています。
プロジェクトの派生バージョンを作った場合に、概要やコンテンツが同じような複数のプロジェクトが一覧画面に表示されて違いがわかりにくい、という問題を改善するためにこの仕様を導入しました。

{
  ...その他のフィールド,
  "parentProjectGuid": "b7452e0c-c88f-4aa7-a006-f506cf7f0fcb",
}

実際のファイルの例はこちらを参照してください。

`parentProjectId` (オプション)

派生元プロジェクト(親プロジェクト)のGUIDを指定します。親プロジェクトがさらに親を持っている場合には、投稿時にエラーとなります。

メタデータファイル

基本となるメタデータファイルの例​

各フィールドの詳細​

projectGuid​

projectName​

introductionLines​

targetMcu​

targetBoardLabel​

repositoryUrl (オプション)​

tags​

firmwareSpec​

UF2ファイルを指定する場合​

binやhexから変換する場合​

派生元プロジェクトの設定​

parentProjectId (オプション)​