RogiStandard-hal
STM32 向けサークル共通ライブラリ
読み取り中…
検索中…
一致する文字列を見つけられません
RogiStandard-hal

STM32(CubeMX + CMake)向けのサークル共通ライブラリです。 ライブラリごとに独立した CMake ターゲットになっており、**リンクしたライブラリだけがビルドされます**。 使わないペリフェラルに依存するライブラリが原因でコンパイルエラーになることはありません。

使い方

CubeMX が生成したプロジェクトのトップ CMakeLists.txt に追記します。 add_subdirectory(cmake/stm32cubemx) より後に書いてください。

include(cmake/CPM.cmake)
CPMAddPackage(
NAME RogiStandard-hal
GIT_REPOSITORY git@github.com:5C6F2F/RogiStandard-hal.git
GIT_TAG main
SOURCE_SUBDIR Lib
)
target_link_libraries(${CMAKE_PROJECT_NAME}
stm32cubemx
# 使うライブラリだけを書く
rogi::DCMotor
rogi::Servo
)

VSCode(CMake Tools)で再構成すると、ライブラリが自動で取得されます。 コードからは各ライブラリのヘッダをそのまま #include します(例: #include "DCMotor.hpp")。

cmake/CPM.cmake が無い場合は CPM.cmake の get_cpm.cmake を cmake/CPM.cmake として保存してください。

ライブラリを開発するとき

利用側プロジェクトで、取得したものの代わりに手元の clone を使えます。

cmake --preset Debug -DCPM_RogiStandard-hal_SOURCE=/path/to/RogiStandard-hal

ディレクトリ構成

Lib/
├── CMakeLists.txt # 入口。rogi::hal と rogi_add_library() を定義
├── tests/ # ホストテストの入口。rogi_add_test() を定義
└── <カテゴリ>/
├── CMakeLists.txt # add_subdirectory(<ライブラリ>) を並べる
└── <ライブラリ>/
├── CMakeLists.txt # rogi::<ライブラリ> ターゲット
├── README.md
├── Inc/
├── Src/
└── tests/ # このライブラリのテスト (ホスト PC で実行)

ライブラリの追加

  1. Lib/<カテゴリ>/<ライブラリ>/ に Inc/・Src/・README.md・CMakeLists.txt を作る
  2. CMakeLists.txt に1行書く。これで rogi::Foo としてリンクできるようになる

    # Foo: (何をするライブラリか)
    # 必要なペリフェラル: (例: TIM, GPIO)
    rogi_add_library(Foo)

    Src/ 以下の .c / .cpp は自動でビルド対象になります。 ソースが無い場合(Src/ を作らない場合)はヘッダーオンリーのライブラリになります。 HAL のコールバック(HAL_xxx_Callback)を定義するライブラリは、定義を必ず Src/ の .cpp に書いてください。ヘッダに書くと呼ばれなくなることがあります。 他のライブラリに依存する場合は rogi_add_library(Foo DEPENDS rogi::DCMotor) のように書きます。 ソースを個別に指定したい場合は SOURCES Src/Foo.cpp を付けます。

  3. カテゴリの CMakeLists.txt に add_subdirectory(<ライブラリ>) を1行足す
  4. ヘッダの先頭で必要なペリフェラルを確認する

    #include "main.h"
    #ifndef HAL_TIM_MODULE_ENABLED
    #error "Foo には TIM が必要です。CubeMX で TIM を有効にしてコードを再生成してください。"
    #endif

テスト

テストは PC 上で実行します。ファームウェアと同じ rogi::<名前> のターゲットを使うので、Eigen や units もファームウェアと同じバージョンでテストされます。

cmake -S Lib/tests -B build/tests
cmake --build build/tests
ctest --test-dir build/tests --output-on-failure

テストを追加するときは、ライブラリ(またはカテゴリ)の下に tests/ を作り、CMakeLists.txt に1行書きます。Lib/tests/CMakeLists.txt の追記は不要です。

rogi_add_test(foo_tests DEPENDS rogi::Foo)
  • tests/ 以下の .cpp は自動でビルド対象になります
  • main 関数は不要です。テストのソースには #include <doctest/doctest.h> と TEST_CASE だけを書きます
  • ctest には TEST_CASE ごとに foo_tests/<TEST_CASE 名> として登録されます
  • AddressSanitizer / UndefinedBehaviorSanitizer が有効です。無効にするときは -DROGI_TEST_SANITIZERS=OFF を付けます
  • エディタ(clangd)は build/tests/compile_commands.json を使ってテストのファイルを解析します。テストのファイルを開く前に、上の configure を一度実行してください

ドキュメント

ヘッダのコメントと各ライブラリの README から、Doxygen で HTML のドキュメントを生成します。

doxygen docs/Doxyfile # リポジトリ直下で実行

生成には doxygen・graphviz・python3 が必要です。見るときは、簡易サーバーを立ててブラウザで http://localhost:8000 を開きます(終わったら Ctrl+C)。

python3 -m http.server -d build/docs 8000

build/docs/index.html を直接開いても読めますが、Flatpak 版のブラウザではファイルへのアクセスが制限され、スタイルが当たらないことがあります。

クラスや関数は、左のツリーの「ライブラリ一覧」からカテゴリ → ライブラリの順に辿れます。各ライブラリのページには、リンクするターゲット(target_link_libraries)と #include するヘッダ、そのライブラリの README.md が載ります。この分類はディレクトリ構造から自動で付くので、ヘッダや README に書く必要はありません(docs/doxygen_group_filter.py)。

main に push すると、Actions がドキュメントを生成して https://rogi-docs.5c6f2f.com に公開します。開くとログイン画面が出るので、@keio.jp のメールアドレスを入力し、届いたコードを入れてください。公開の設定と管理は docs/README.md にまとめています。

公開先を開けないときは、Actions の実行結果のページ下部にある Artifacts の docs-html から zip でダウンロードし、展開した index.html を開いても読めます。

見た目はテーマ doxygen-awesome-css の上に、サークルのサイトに合わせた配色(docs/rogi-theme.css)を重ねています。

コメントの書き方

最低限、次のものに Doxygen 形式のコメントを書きます。見本は Lib/Actuator/DCMotor/Inc/DCMotor.hpp と Lib/Control/OmniWheelController/Inc/OmniWheelController.hpp です。

  • ヘッダの先頭: @file と @brief(何をするライブラリか、必要なペリフェラル)
  • 公開しているクラス・関数: @brief、引数があれば @param、戻り値があれば @return
void setDuty(float duty);
Eigen::Matrix< float, N, 3 > getWheelMatrix(const std::array< WheelPositions, static_cast< std::size_t >(N)> &wheel_positions)

データの流れなど、文章では伝わりにくいものは @dot 〜 @enddot に Graphviz の図を書けます(OmniWheelController.hpp を参照)。