Skip to content

Altair_library_for_CubeIDE

STM32CubeIDE (CMake プロジェクト) 向けライブラリです。

[!IMPORTANT] 最初に GitHub の README を読んでください。
このページは導入用の要約で、最新かつ詳細な説明は GitHub 側の README / readme フォルダの各ドキュメントにあります。
https://github.com/Altairu/Altair_library

含まれるライブラリ

ファイル 概要 詳細ドキュメント
can_lib CAN 通信 CAN 通信
encoder エンコーダ エンコーダー
gpio_lib GPIO / PWM GPIO/PWM
kinematics 運動学 運動学
motor_driver モータドライバ モータドライバ
pid PID 制御 PID 制御
serial_lib シリアル通信 シリアル通信
usart_lib USART ユーティリティ USARTユーティリティ

導入手順

1. リポジトリをダウンロード

https://github.com/Altairu/Altair_library よりダウンロードします。

ダウンロード

2. フォルダをコピー

Altair_library_for_CubeIDE フォルダを選択してコピーします。

フォルダ選択

3. プロジェクトに配置

STM32CubeIDE プロジェクトの Core/Inc 内に貼り付けます。

Core/
└── Inc/
    └── Altair_library_for_CubeIDE/   ← ここに配置
        ├── altair.h
        ├── can_lib.h / can_lib.c
        ├── encoder.h / encoder.c
        ├── gpio_lib.h / gpio_lib.c
        ├── kinematics.h / kinematics.c
        ├── motor_driver.h / motor_driver.c
        ├── pid.h / pid.c
        ├── serial_lib.h / serial_lib.c
        └── usart_lib.h / usart_lib.c

配置

4. CMakeLists.txt を編集

cmake/stm32cubemx/CMakeLists.txt を以下のように編集します。

# STM32CubeMX generated include paths
set(MX_Include_Dirs
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc/Altair_library_for_CubeIDE  # ← 追加
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Drivers/STM32F4xx_HAL_Driver/Inc
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Drivers/STM32F4xx_HAL_Driver/Inc/Legacy
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Drivers/CMSIS/Device/ST/STM32F4xx/Include
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Drivers/CMSIS/Include
)

# STM32CubeMX generated application sources
set(MX_Application_Src
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Src/main.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Src/stm32f4xx_it.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Src/stm32f4xx_hal_msp.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Src/sysmem.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Src/syscalls.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../startup_stm32f446xx.s
    # ↓ 使うライブラリの .c を追加
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc/Altair_library_for_CubeIDE/can_lib.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc/Altair_library_for_CubeIDE/encoder.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc/Altair_library_for_CubeIDE/gpio_lib.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc/Altair_library_for_CubeIDE/kinematics.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc/Altair_library_for_CubeIDE/motor_driver.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc/Altair_library_for_CubeIDE/pid.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc/Altair_library_for_CubeIDE/serial_lib.c
    ${CMAKE_CURRENT_SOURCE_DIR}/../../Core/Inc/Altair_library_for_CubeIDE/usart_lib.c
)

CMakeLists.txt

ビルド設定

5. main.c にインクルード

main.c の先頭に以下を追加するだけで全ライブラリが使用可能になります。

#include "Altair_library_for_CubeIDE/altair.h"

CAN 通信を使う場合の追加設定

CubeMX で以下を設定しないと通信が不安定になったり止まったりします。

パラメータ 推奨値
AutoRetransmission ENABLE
AutoBusOff ENABLE

ハードウェア注意事項

  • 終端抵抗: バスの両端に 120Ω が必要。ないとビットエラーが多発して通信が不安定になる。
  • ボーレート: 全ノードで一致していること。ボーレートの計算式は can_lib.md を参照。
  • ACK: バスに自分以外のノードが最低1つ存在しないと ACK エラーになり Bus-Off に至る。単体テスト時は CubeMX で Mode = CAN_MODE_LOOPBACK に設定する。

CAN通信

can_lib 使い方

CAN送受信をシンプルに扱えるライブラリ。
メールボックスの空き待ちなどの面倒な処理はライブラリ内部で完結している。

できること

  • CAN 初期化(フィルタ設定、開始、受信通知有効化)
  • 標準IDフレームの送信(メールボックス空き待ちつき)
  • 割り込み受信結果の共有構造体保持(g_can1_rx_data / g_can2_rx_data)

主要API

  • Can_DefaultInitConfig(CAN_HandleTypeDef *hcan)
    • CAN1/CAN2 に応じた初期フィルタバンクを返す
  • Can_Init(CAN_HandleTypeDef *hcan, const CanInitConfig *config)
    • フィルタ設定、HAL_CAN_Start、FIFO0受信通知有効化まで実施
  • Can_Transmit(CAN_HandleTypeDef *hcan, uint32_t std_id, uint8_t *pData, uint8_t size)
    • 最大 CAN_TX_TIMEOUT_MS 待機して送信

CubeMX 必須設定

以下の3つは CubeMX (MX_CAN1_Init) 側で設定すること。ライブラリでは触れない。

パラメータ 推奨値 理由
AutoRetransmission ENABLE エラー時に自動再送。フレームが黙って捨てられなくなる
AutoBusOff ENABLE Bus-Off 状態からハードウェアが自動復帰する

CubeMXで設定後、生成されたコードが自動的に適用される。 以下のように設定する

alt text

alt text

alt text

ボーレートの確認

ボーレート = APB1クロック ÷ (Prescaler × (1 + TimeSeg1 + TimeSeg2))

デフォルト設定例(HSI 168MHz、APB1 = 42MHz): - Prescaler=3, BS1=11TQ, BS2=2TQ → 1Mbps

相手ノードのボーレートと一致していること。

使い方

初期化
#include "Altair_library_for_CubeIDE/can_lib.h"

// MX_CAN1_Init() の後に呼ぶ
Can_Init(&hcan1, NULL);  // デフォルト設定

CAN1/CAN2 を同時に使う場合:

CanInitConfig can1_cfg = Can_DefaultInitConfig(&hcan1);
CanInitConfig can2_cfg = Can_DefaultInitConfig(&hcan2);

// 用途に応じて必要なら調整
// can1_cfg.filter_bank = 0;
// can2_cfg.filter_bank = 14;

Can_Init(&hcan1, &can1_cfg);
Can_Init(&hcan2, &can2_cfg);
送信
uint8_t data[8] = {1, 2, 3, 4, 5, 6, 7, 8};
Can_Transmit(&hcan1, 0x125, data, 8);
  • メールボックス満杯時は内部で CAN_TX_TIMEOUT_MS (デフォルト10ms) まで待機
  • タイムアウト時は古い送信要求を全メールボックス中断して新規送信を試みる
受信割り込みの流れ
  • HAL_CAN_RxFifo0MsgPendingCallback が上書き実装されている
  • 受信成功時に std_id / dlc / data[] を更新
  • 新規データ有無は new_data_flag で判定し、アプリ側で 0 クリアする
受信

受信は割り込みで更新される g_can1_rx_data / g_can2_rx_data を参照する。

extern CanRxData g_can1_rx_data;

if (g_can1_rx_data.new_data_flag) {
    g_can1_rx_data.new_data_flag = 0;
    uint32_t id = g_can1_rx_data.std_id;
    uint8_t dlc = g_can1_rx_data.dlc;
    // g_can1_rx_data.data[0] ~ [dlc-1]
}
デュアルCAN時の注意
  • SlaveStartFilterBank で CAN1/CAN2 のフィルタバンク領域を分割する
  • デフォルトは SlaveStartFilterBank = 14(CAN1: Bank0, CAN2: Bank14)
  • 現在の初期設定ではマスク0のため、全ID受信になっている

Encoder

encoder 使い方

Encoder_Init で初期化し、周期処理で Encoder_Interrupt を呼んで値を更新する。

できること

  • タイマをエンコーダモードで開始
  • カウント値から回転数、角度、移動距離、速度、rpsを計算
  • 長時間運用向けの簡易オーバーフロー対策(limit 加算方式)

主要API

  • Encoder_Init(Encoder *encoder, TIM_HandleTypeDef *htim, double diameter, int ppr, int period)
  • Encoder_Read(Encoder *encoder)
  • Encoder_Interrupt(Encoder *encoder, EncoderData *encoder_data)
  • Encoder_Reset(Encoder *encoder)
#include "Altair_library_for_CubeIDE/encoder.h"

Encoder encoder;
EncoderData encoder_data;

// 例: 直径100mm、PPR=8192、周期10ms
Encoder_Init(&encoder, &htim5, 100.0, 8192, 10);

while (1) {
    Encoder_Interrupt(&encoder, &encoder_data);
    // encoder_data.count / rot / deg / distance / velocity / rps
    HAL_Delay(10);
}

補足: - カウンタを初期化したい場合は Encoder_Reset(&encoder) - printf("%f") を使う場合は linker flags に -u _printf_float が必要 - 実装ではカウンタ中央(32767付近)を基準に読んでおり、±20000を超えたら limit を更新して再センタリングする

Kinematics

kinematics 使い方

ロボット速度(lx, ly, rx)から各輪速度を計算する。モードは OMNI_3 / OMNI_4 / MEKANUM に対応。

できること

  • ホイール配置モード別の逆運動学計算
  • 3輪時は speedBL を未使用(NULL可)
  • 入力 rx は内部で度→ラジアン変換して計算

主要API

  • Kinematics_GetTargetSpeeds(Kinematics *kinematics, float lx, float ly, float rx, float *speedFR, float *speedFL, float *speedBR, float *speedBL)

注: kinematics.h には Kinematics_Init 宣言があるが、現行 kinematics.c には実装がないため、構造体へ直接代入して初期化する。

#include "Altair_library_for_CubeIDE/kinematics.h"

Kinematics kinematics;
kinematics.robot_diameter = 150.0f;
kinematics.wheel_radius = 30.0f;
kinematics.mode = OMNI_4;

float speedFR, speedFL, speedBR, speedBL;
Kinematics_GetTargetSpeeds(&kinematics,
                           100.0f,   // lx
                           0.0f,     // ly
                           0.3f,     // rx
                           &speedFR, &speedFL, &speedBR, &speedBL);

Motor Driver

motor_driver 使い方

MotorDriver_Init 後に MotorDriver_setSpeed で -100〜100% を指定する。

できること

  • 正転/逆転の2ch PWM出力制御
  • 速度指令(-100〜100%)
  • ショートブレーキ停止
  • PWM周波数の自動設定/手動設定

主要API

  • MotorDriver_Init(...)
  • MotorDriver_setSpeed(MotorDriver *motor, int speed)
  • MotorDriver_Stop(MotorDriver *motor)
  • MotorDriver_setPwmFrequency(MotorDriver *motor, uint32_t frequency_hz)
#include "Altair_library_for_CubeIDE/motor_driver.h"

MotorDriver motor;
MotorDriver_Init(&motor, &htim13, TIM_CHANNEL_1, &htim14, TIM_CHANNEL_1);

MotorDriver_setSpeed(&motor, 50);   // 正転50%
HAL_Delay(1000);
MotorDriver_setSpeed(&motor, -50);  // 逆転50%
HAL_Delay(1000);
MotorDriver_Stop(&motor);           // ブレーキ停止

PWM 周波数の調整:

// 任意周波数へ変更
MotorDriver_setPwmFrequency(&motor, 980U);

自動周波数設定を無効化したい場合は、altair.h を読む前に MOTOR_DRIVER_DISABLE_DEFAULT_PWM を定義する。

補足: - デフォルト周波数は MOTOR_DRIVER_DEFAULT_PWM_HZ(既定 980Hz) - speed は内部で実質 -99〜99 にクリップされる実装 - 周波数計算は APB1/APB2 分周を考慮して PSC/ARR を再設定する

PID

pid 使い方

できること

  • P/I/D 制御計算
  • 微分フィルタ時定数の設定
  • 積分項アンチワインドアップ(上限クリップ)
  • 出力反転(正逆反転)

主要API

  • Pid_Init(Pid *pid)
  • Pid_setGain(...)
  • Pid_setGainWithLimit(...)
  • Pid_setInvert(Pid *pid, int invert)
  • Pid_control(...) / Pid_controlError(...)
  • Pid_reset(Pid *pid)
  • Pid_getControlValue(Pid *pid, ControlType control_type)
#include "Altair_library_for_CubeIDE/pid.h"

Pid pid;
Pid_Init(&pid);
Pid_setGainWithLimit(&pid, 1.0, 0.1, 0.01, 0.0, 100.0);
Pid_setInvert(&pid, 1);  // 必要なら -1

double u = Pid_control(&pid,
                       90.0,  // target
                       80.0,  // now
                       10);   // control_period[ms]

補足: - 誤差を直接入れる場合は Pid_controlError - リセットは Pid_reset - 成分確認は Pid_getControlValue(&pid, P/I/D) - control_period は ms 単位。0 を入れると積分更新や微分計算の一部がスキップされる

Serial

serial_lib 使い方

serial_lib は 2バイトヘッダ付き (0xA5, 0xA5) の int16_t 配列を送受信する。

できること

  • 可変長 int16_t 配列の送信
  • ヘッダ検証つき受信
  • ヒープ未使用(固定バッファ運用)

フレーム形式

  • 先頭2バイト: 0xA5 0xA5
  • 続くデータ: int16_t をビッグエンディアンで並べる

主要API

  • Serial_Init(USART_HandleTypeDef *huart)
  • Serial_SendData(USART_HandleTypeDef *huart, int16_t *data, uint8_t data_count)
  • Serial_ReceiveData(USART_HandleTypeDef *huart, int16_t *data, uint8_t data_count)
#include "Altair_library_for_CubeIDE/serial_lib.h"

Serial_Init(&husart2);

int16_t tx[3] = {100, 200, -150};
Serial_SendData(&husart2, tx, 3);

int16_t rx[3];
if (Serial_ReceiveData(&husart2, rx, 3)) {
    // rx に受信データ
}

注意: - data_count の最大は SERIAL_MAX_DATA_COUNT (16) - 実装は HAL_MAX_DELAY でブロッキング送受信する

GPIO / PWM

gpio_lib 使い方

GPIO 入出力のラッパと PWM duty 指定が使える。

できること

  • GPIO Output/Input/PullUp/PullDown 初期化
  • GPIO 書き込み、トグル、読み取り
  • PWM 開始と Duty 指定(0.0〜100.0%)

主要API

  • GpioLib_Init(...)
  • GpioLib_InitPwm(...)
  • GpioLib_Write(...) / GpioLib_Toggle(...) / GpioLib_Read(...)
  • GpioLib_WriteDuty(...)
#include "Altair_library_for_CubeIDE/gpio_lib.h"

GpioLib led;
GpioLib_Init(&led, GPIOC, GPIO_PIN_13, GPIO_LIB_MODE_OUTPUT);
GpioLib_Toggle(&led);

GpioLib pwm;
GpioLib_InitPwm(&pwm, GPIOA, GPIO_PIN_8, &htim1, TIM_CHANNEL_1);
GpioLib_WriteDuty(&pwm, 25.0f);  // 0.0〜100.0%

CubeMX 側で GPIO クロック、AF、PWM チャネル設定を済ませておくこと。

補足: - GpioLib_WriteDuty は Duty 範囲外入力を自動クリップする - PWM Duty 計算は都度 ARR を読み直して比較値を計算する

USART Utility

usart_lib 使い方

1バイト受信・タイムアウト管理・DMA受信開始を簡単に扱える。

できること

  • ポーリング送信
  • 1byte 受信 + タイムアウトフラグ管理
  • タイムアウト時の再初期化とエラーフラグクリア
  • DMA受信開始(USART1/2/3のデフォルトDMA割り当て)

主要API

  • UsartLib_Init(...)
  • UsartLib_Write(...)
  • UsartLib_ReadByte(...)
  • UsartLib_CheckTimeout(...) / UsartLib_ClearTimeout(...)
  • UsartLib_StartDmaRead(...)
#include "Altair_library_for_CubeIDE/usart_lib.h"

UsartLib usart;
UsartLib_Init(&usart, &husart2);

uint8_t b;
if (UsartLib_ReadByte(&usart, &b, 10) == HAL_OK) {
    UsartLib_Write(&usart, &b, 1, 10);
}

if (UsartLib_CheckTimeout(&usart)) {
    UsartLib_ClearTimeout(&usart);
}

DMA受信の例:

DMA_HandleTypeDef hdma_rx;
uint8_t rx_buffer[64];

UsartLib_StartDmaRead(&usart, &hdma_rx, rx_buffer, sizeof(rx_buffer));

DMAのNVIC設定は CubeMX 側で有効化が必要。

補足: - UsartLib_ReadByte が HAL_TIMEOUT のとき timeout_flag=1 になる - DMA 初期設定は USART1/2/3 以外では HAL_ERROR を返す

Note

著者:Shion Noguchi