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
)


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で設定後、生成されたコードが自動的に適用される。 以下のように設定する



ボーレートの確認
ボーレート = 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