3DプリンターをKlipperファームウェアで動かすとき、避けて通れないのが「printer.cfg」という設定ファイルです。
このファイルには、モーターの動きや温度制御、ベッドレベリングなど、プリンターを正しく動かすための情報がすべて詰まっています。
しかし初めて触れると、
- 「いきなり編集しようとしたけど、どこを触ればいいのか分からない」
- 「間違えて3Dプリンターが動かなくなった」
とトラブルや不安になる方も多いと思います。
この記事ではprinter.cfgの“読み方”を身につけることをゴールに、基本構造・各セクションの役割・設定方法を初心者にも分かるように解説します。
- printer.cfgの基本構造
- 各セクションの主要設定と意味
- 1. [printer]（全体設定）
- 2. [mcu]（ボードとの接続）
- 3. [stepper_x / y / z]（軸モーター）
- 4. [extruder]（押し出し）
- 5. [heater_bed]（ベッドヒーター）
- 6. [bed_screws]（手動レベリング補助）
- 7. [bed_mesh]（ベッド面の歪み補正）
- 8. [probe]（オートレベリング）
- 9. [bltouch]（BLTouch専用設定）
- 10. [safe_z_home]（安全なZ原点出し）
- 11. [fan] / [heater_fan]（ファン制御）
- 12. [firmware_retraction]（ファームウェア側リトラクト）
- 13. [input_shaper] / [adxl345]（共振低減）
- 14. [temperature_sensor]（追加温度センサー）
- 15. [filament_switch_sensor]（フィラメント切れ検知）
- 16. [filament_motion_sensor]（フィラメント動き検知）
- 17. [tmc2209]（TMC2209ドライバー設定）
- 18. [virtual_sdcard]（仮想SDカード）
- 19. [idle_timeout]（アイドルタイムアウト）
- 20. [display]（LCD/タッチパネル）
- include機能
- 3Dプリンタータイプごとの違い
- printer.cfgの設定値を決めるヒント
- 編集後の確認手順
- まとめ
printer.cfgの基本構造
printer.cfgの基本構造は「セクション」と「パラメータ」でできています。セクションは[section_name]のように角括弧で始まり、その中にkey: value形式でパラメータを書きます。
セクションとパラメータの関係
セクションとパラメータの関係は「セクション([ ]で囲まれたブロック)」ごとに、設定パラメータを並べて書く形式です。
#例
[stepper_x] #←セクション名
step_pin: PB9 #←パラメータ（設定項目）
dir_pin: !PB8
enable_pin: !PC2
rotation_distance: 40
position_endstop: 0
position_max: 235[stepper_x]→ セクション名step_pinなどがパラメータ(設定項目)
コメントは ; または # で始めるとコメントアウト、つまり無視されます。
同じパラメータを複数回書くと、最後に書いた値が有効になる点も覚えておきましょう。
主なセクション
まず理解したい主要セクションは次のとおりです。
- [printer]: プリンター全体の動作設定
- [mcu]: メインボード（マイコン）の接続情報
- [stepper_x], [stepper_y], [stepper_z]: 各軸のモーター
- [extruder]: フィラメント押し出し機構
- [heater_bed]: ベッドヒーター
- その他: ファン・センサー・マクロなど拡張用
👉 詳細なパラメータや具体例は「3. 各セクションの主要設定と意味」で解説します。ここでは「どんな項目があるか」をざっくり理解しておけばOKです。
オプションのセクション
拡張機能を使う場合に追加するセクションがあります。
- [bed_screws]：ベッドのネジ位置を定義(手動レベリング補助)
- [bed_mesh]：ベッド面の高さをグリッド計測して、印刷中に高さ差を補正
- [probe]：オートレベリング用のセンサー
- [bltouch]：BLTouch/3DTouch専用の制御・エラーハンドリング(ピン出し入れ等)
- [safe_z_home]：指定座標(例: 中央)へ移動してからZホームして安全に原点出し
- [fan], [heater_fan]：ファンの回転制御(パーツ冷却/ホットエンド冷却)。heater_fanは温度で自動ON
- [firmware_retraction]:ファームウェア側のリトラクト設定
- [input_shaper] / [adxl345]：加速度センサーで共振を測り、振動打消し(シェイパ)を適用
- [temperature_sensor]：周囲/ケース内/ボードなど追加温度の監視センサー
- [filament_switch_sensor]: フィラメントの有無を検知するスイッチセンサー
- [filament_motion_sensor]: フィラメントの動きを検知するセンサー
- [tmc2209]: TMC2209ステッパードライバーの設定
- [virtual_sdcard]: 仮想SDカード機能
- [idle_timeout]: アイドル時のタイムアウト設定
- [display]：LCDコントローラーやタッチパネルの設定(コントローラIC・接続方式)
各セクションは「必要になったら足す」で十分です。まずは手動で大まかに水平を出すなら[bed_screws]、その後の微小な面差は[bed_mesh]で補正します。プローブを使う場合は [probe](BLTouch系は [bltouch] も併用)で必ずz_offsetを運用温度で合わせ、原点出しは[safe_z_home]で中央付近に移動してから行うと衝突を避けやすくなります。
冷却は通常のパーツファンを [fan]、ホットエンド冷却は温度連動の [heater_fan] が便利です。高速化や振動低減を狙うときのみ[input_shaper] / [adxl345]を導入し、測定→設定の順で反映します。環境監視が必要なら[temperature_sensor]を追加し、必要に応じて温度連動ファンと組み合わせます。
導入の順番の目安は:
- 最小構成で動作確認 → 手動レベリング（[bed_screws]）→ メッシュ（[bed_mesh]）→ プローブ/安全ホーム（[probe]/[bltouch] + [safe_z_home]）
- 必要に応じてファン連動・表示・共振対策（[heater_fan]/[display]/[input_shaper]）
ポイント: 基礎段階では、まず「動く最小構成」に集中し、拡張セクションは後回しでOK。
各セクションの主要設定と意味
ここでは、代表的なセクションと主要パラメータを紹介します。数字の意味や単位をしっかり把握しておくと、トラブルを避けやすいです。実際の値は使用ボード・機種に合わせてください。
1. [printer]（全体設定）
機構(kinematics)と全体の上限(max_velocity, max_accel, square_corner_velocity)。コーナーで止まらずに曲がる度合いはsquare_corner_velocityが鍵です。値を大きくすると時間短縮、小さくすると角がシャープになります。
kinematics: 機構タイプ(cartesian / corexy / delta など)max_velocity: 移動速度の上限(mm/s)max_accel: 加速度の上限(mm/s²)square_corner_velocity: コーナーを止まらず滑らかに曲がる速度
[printer]
kinematics: cartesian # 機構タイプ
max_velocity: 150 # 最大速度（mm/s）
max_accel: 2000 # 最大加速度（mm/s²）
square_corner_velocity: 5 # コーナー抜け速度（mm/s）初期値の目安:
max_velocity: 150, max_accel: 2000, square_corner_velocity: 5
Tips:
最初は控えめな数値で始め、印刷の様子を見ながら少しずつ上げていくのが安全です。
2. [mcu]（ボードとの接続）
接続先(serial)と再起動方法(restart_method: command が一般的)。CAN環境ならcanbus_uuid、Raspberry PiをMCU化する場合は[mcu rpi]など、構成によりバリエーションがあります。
serial:/dev/serial/by-id/...のようなデバイス名restart_method: 通常はcommand
[mcu]
serial: /dev/serial/by-id/usb-... # シリアルポート（Linux推奨）
restart_method: command # 再起動方法（通常はcommand）[mcu my_extra_mcu]:
追加のマイコン(例：Raspberry PiをMCU化)の設定です。
[mcu rpi]
serial: /tmp/klipper_host_mcu使用例:
- Raspberry PiをMCUとして使用
- 複数のマイコンで分散制御
- 専用ボードとの連携
複数USB機器があるときは by-id を使うと安定します。
接続できない場合はケーブルやボード設定を再確認しましょう。
3. [stepper_x / y / z]（軸モーター）
信号ピン(step_pin, dir_pin, enable_pin)、動く量の基準(rotation_distance)、エンドストップ(endstop_pin と ! で反転、^ でプルアップ)、可動範囲(position_endstop, position_max)。初期の衝突を避けるには、homing_speed や homing_retract_dist を控えめにするのが安全です。
step_pin,dir_pin,enable_pin: モーター信号のピンrotation_distance: 1回転あたりの移動距離endstop_pin: エンドストップのピン。!で論理反転、^でプルアップ指定position_endstop: ホーム位置position_max: 可動範囲の最大値
[stepper_x]
step_pin: PB9 # ステップ信号ピン
dir_pin: !PB8 # 方向信号ピン（!で反転）
enable_pin: !PC2 # イネーブル信号ピン
rotation_distance: 40 # 1回転あたりの移動距離（mm）
endstop_pin: ^PC1 # エンドストップピン（^でプルアップ）
position_endstop: 0 # ホーム位置
position_max: 235 # 可動範囲の最大値Tips:
Klipperでは「steps/mm」を直接使いません。
回転距離(rotation_distance)を基準に調整するのが基本です。
4. [extruder]（押し出し）
フィラメントを溶かして押し出すユニットの設定です。まずは「どれだけ送るか(rotation_distance)」と、ノズル径・フィラメント径、ヒーター/センサーを決めます。
ヒーター暴走検出の調整用にverify_heaterも覚えておくと安心です。
rotation_distance: ギア1回転で送る距離nozzle_diameter: ノズル径filament_diameter: フィラメント径heater_pin,sensor_type: ヒーター・センサー情報min_temp/max_temp: 温度範囲の安全制限- verify_heater: 昇温が遅すぎる/速すぎる等を検出する監視のしきい値(後で調整)
ギア式について:
エクストルーダーにギア減速がある場合は、gear_ratioを併用すると設定が素直になります(例: BMGは 50:17 ≈ 2.95:1、Hemera/LGXは 3:1)。ギア無し(1:1)の場合はgear_ratioは不要です。
設定例(ギア無し)
[extruder]
step_pin: PA6 # ステップ信号ピン
dir_pin: !PA5 # 方向信号ピン
enable_pin: !PA4 # イネーブル信号ピン
rotation_distance: 7.0 # 1回転で送る距離（mm）
nozzle_diameter: 0.4 # ノズル径（mm）
filament_diameter: 1.75 # フィラメント径（mm）
heater_pin: PB1 # ヒーターピン
sensor_type: ATC Semitec 104GT-2 # 温度センサー種別
sensor_pin: PA7 # センサーピン
min_temp: 0 # 最低温度（℃）
max_temp: 285 # 最高温度（℃）設定例(ギア付き・BMG)
[extruder]
gear_ratio: 50:17
rotation_distance: 7.50
nozzle_diameter: 0.4
filament_diameter: 1.75
heater_pin: ...
sensor_type: ...
min_temp: 0
max_temp: 280
min_extrude_temp: 170Tips:
押し出し量はスライサーの「フロー」で微調整する前に、必ずrotation_distanceを正しく合わせましょう。
補足: rotation_distance は「フィードギアが1回転したときに実際にフィラメントが送られる距離(mm)」を入れる項目です。一方でgear_ratioは「モーターの回転数」と「フィードギアの回転数」の比（減速倍率）をそのまま伝える設定です。
つまり、モーターが何回転するとフィードギアが何回転するかをgear_ratioで表し、そのフィードギアが1回転したときに何mm送るかをrotation_distanceで決めます。どちらか一方でも誤ると押し出し量が大きくズレるため、両者をセットで正しく指定することが重要です。
かんたんに言えば、gear_ratioは「モーター:ギアの減速比」、rotation_distance は「ギア1回転あたりの送り量(ギア外周×食い込み係数の実測で合わせる)」という役割分担になります。
5. [heater_bed]（ベッドヒーター）
ベッドの加熱と温度計測を担当します。まずは正しいセンサー種別とピン配線を決め、必要に応じて安全関連(min_temp/verify_heater)も整えます。ベッド材質やシート、材料(PLA/ABS/PA等)によって適温や立ち上がり特性が違うため、上限温度は環境に合わせて見直してください。加熱テストは低温から始め、表示温度と実測の乖離が大きい場合はセンサー種別や配置を再確認します。安定後にPID自動調整(ベッドはバンバン制御でも可)を検討すると温度波形が落ち着きます。
- heater_pin: ヒーターを接続するピン(配線ミスは発熱しない/常時ONの原因)
- sensor_type: サーミスタ/ICの種類(例: NTC 100K B3950, 3950-ATC など)
- max_temp: 上限温度(一般に110〜120℃。PEI＋ABS等で見直し)
- min_temp: 最低許容温度(センサー断線検出の一助)
- sensor_pin: センサー入力ピン(極性・コネクタの差し間違いに注意)
- control: pid/bang-bang(既定で問題なければそのまま)
- pid_Kp/Ki/Kd: 必要に応じてPID手動設定(自動チューニング後の定着)
- verify_heater: 昇温異常/停滞の検知しきい値(安全性向上に有効)
[heater_bed]
heater_pin: PB0 # ヒーターピン
sensor_type: NTC 100K B3950 # 温度センサー種別
sensor_pin: PA0 # センサーピン
min_temp: 0 # 最低温度（℃）
max_temp: 120 # 最高温度（℃）安全設定:
verify_heater: heater=heater_bed max_error=120 hysteresis=5Tips:
厚いガラスや磁気シートは熱容量が大きく立ち上がりが遅いです。verify_heaterを厳しすぎる値にすると誤検知になりやすいので、まず既定で観察→必要なら緩めに調整をしてください。
6. [bed_screws]（手動レベリング補助）
ノズル(またはプローブ)とベッドのギャップを、ベッドのネジを回して物理的に揃えるための案内機能です。スクリュー位置をXY座標で定義すると、指示どおりに移動してくれるので、紙一枚の抵抗で各点を合わせる“紙方式”が安全・確実です。まずは印刷可能範囲内に測定点が入り、ノズルやクリップと干渉しないことを確認しましょう。加熱の有無でベッドの反りが変わるため、「最初は常温で手順確認→運用温度で再調整」という段取りが失敗しにくいです。
- screw1(〜screw4): 各ネジの座標(x, y)。四隅＋中央(任意)で精度が安定
- speed: 計測点への移動速度(mm/s)。最初は控えめに(例: 100以下)
- horizontal_move_z: 点間移動でのZリフト量(mm)。クリップ回避に十分な高さを
- probe_height: ノズル接触ではなくプローブで当てる場合の補正(必要時のみ)
- screw_thread/adjust: 回す向きや何回転程度かを案内したい場合に利用(対応機能)
- retries: 計測と案内を何巡か繰り返して平面を詰める
[bed_screws]
screw1: 100, 50 # ネジ1の座標（x, y）
screw2: 200, 50 # ネジ2の座標（x, y）
screw3: 200, 200 # ネジ3の座標（x, y）
screw4: 100, 200 # ネジ4の座標（x, y）
speed: 50 # 移動速度（mm/s）
horizontal_move_z: 5 # 測定点間のZリフト（mm）Tips:
- 調整順は対角線上に交互→最後に中央で確認が定番です。
- screws_tilt_adjustを併用すると、どのネジをどれだけ回すかの“量”までガイドしてくれます。
- 物理レベリングで大域的な歪みを取ってから、必要に応じて[bed_mesh]で微小な面差を電気的に補正すると、初層の安定度が一気に上がります。
7. [bed_mesh]（ベッド面の歪み補正）
ベッド表面の高低差をグリッド状に計測し、その差分を印刷中に補正します。まずは計測範囲と密度を適切に設定し、実運用では「補正をどの高さまで残すか」を決めると安定します。プローブがない場合はノズル接触での計測も可能ですが、初回は加熱前の低温で試し、熱変形を見たいときは印刷温度で再計測します。
- mesh_min / mesh_max: 計測範囲のXY(mm)
- probe_count: グリッド密度(例: 3,3 / 5,5)
- algorithm: 補間方式(lagrange / bicubic)
- fade_start / fade_end: 補正の薄め開始/終了Z(mm)
- speed / horizontal_move_z: 計測時の移動速度とZリフト量
[bed_mesh]
mesh_min: 10, 10 # 計測範囲の最小XY（mm）
mesh_max: 200, 200 # 計測範囲の最大XY（mm）
probe_count: 5, 5 # グリッド密度
algorithm: lagrange # 補間方式
fade_start: 1.0 # 補正を薄め始めるZ高さ（mm）
fade_end: 10.0 # 補正を終えるZ高さ（mm）Tips:
最初はprobe_countの密度を控えめ(3×3)にして流れを確認→必要なら5×5以上に。
8. [probe]（オートレベリング）
BLTouchなどのプローブでベッド面高さを計測し、初層の安定性を底上げします。要は「ノズル基準でプローブがどれだけズレているか（x/y/z オフセット）」を正しく伝えるのが肝心です。特にz_offsetは印刷開始高さに直結するため、ベッド・ノズルを運用温度まで加熱し、熱伸びを含めた状態で校正すると安定します。安全のため、[safe_z_home]と組み合わせて中央付近でホーム→メッシュ計測という流れがおすすめです。
- pin: センサートリガーピン(論理反転 ! やプルアップ ^ が必要な場合あり)
- x_offset / y_offset: ノズルからのXYオフセット(mm)。プローブ先端の物理位置を正確に
- z_offset: ノズルからのZオフセット(mm)。PROBE_CALIBRATE→紙テスト→SAVE_CONFIG が基本手順
- speed / lift_speed: 計測下降/上昇の速度(mm/s)。まずは保守的に
- sample_retract_dist: 連続測定のたびに持ち上げる量(mm)。誤タッチ防止に有効
- samples: 1点あたりの測定回数。初期は2〜3回で十分
- samples_tolerance: サンプル間の許容差(mm)。ブレが大きい場合は配線/固定を再確認
- samples_tolerance_retries: 許容差を超えたときの再試行回数
- activate_gcode / deactivate_gcode: 計測前後のG-code。ファン停止や待機などを挿む場合に便利
[probe]
pin: ^PC1 # プローブ信号ピン
x_offset: 0 # ノズルからのXオフセット（mm）
y_offset: 0 # ノズルからのYオフセット（mm）
z_offset: 0 # ノズルからのZオフセット（mm）
speed: 5 # 計測速度（mm/s）
samples: 3 # 1点あたりの測定回数
samples_tolerance: 0.1 # サンプル間の許容差（mm）Tips:
- BLTouch/3DTouch 等は専用の [bltouch] セクションも併用します(ピンの出し入れやエラー復帰など固有動作はそちらで設定)
- 計測順序は「温度安定→G28（必要なら [safe_z_home]）→BED_MESH_CALIBRATE」が定石。結果は保存して再利用(BED_MESH_PROFILE save=…/BED_MESH_PROFILE load=…)すると運用が楽です
- 測定結果が点ごとにブレる場合は、プローブの固定剛性、配線ノイズ、Z 反転/マイクロステップ設定、ベッドのたわみ(支持点)を疑ってください
- ノズル接触型(タップ/クリック)を使う場合は、ベッド表面の汚れやフィラメント残りが誤差源になります。必ず清掃後に実施しましょう。
9. [bltouch]（BLTouch専用設定）
BLTouch/3DTouch系の可動ピン式プローブを制御します。ピンの上下や自己診断、エラー状態の復帰など、BLTouch固有の動作を扱います。測定点の精度は Z オフセットの正確さに依存するため、加熱済みの実稼働状態でz_offsetを詰めると安定します。
- sensor_pin / control_pin: センサー/制御ピン
- x_offset / y_offset / z_offset: ノズル基準のオフセット(mm)
- stow_on_each_sample: 計測ごとにピン格納
- probe_with_touch_mode: タッチモードでの計測を有効化
- pin_up_reports_not_triggered / pin_up_touch_mode_reports_triggered: 状態整合の設定
- set_output_mode: 出力方式(OD/PP など、機種に応じて)
[bltouch]
sensor_pin: ^PC1 # センサー信号ピン
control_pin: PA0 # 制御信号ピン
x_offset: 0 # ノズルからのXオフセット（mm）
y_offset: 0 # ノズルからのYオフセット（mm）
z_offset: 0 # ノズルからのZオフセット（mm）
stow_on_each_sample: True # 計測ごとにピン格納
probe_with_touch_mode: True # タッチモードでの計測コツ: 先に[probe]の一般項目で運用を固定し、BLTouch特有の挙動は本セクションで補正。
10. [safe_z_home]（安全なZ原点出し）
Zホームを行う前に、指定したXY(ベッド中央など)へ移動してから原点出しを行います。クリップやフレームに当たるリスクを避けられ、プローブ使用時の安定性が大きく向上します。ホーム直前/直後にノズルを持ち上げる「Zホップ」も設定でき、治具や突起を跨いで安全に動作できます。
- home_xy_position: Zホーム前に移動するXY(mm)
- speed: 移動速度(mm/s)
- z_hop / z_hop_speed: 事前/事後の持ち上げ量と速度
- move_to_previous: 終了後に元の位置へ戻すか
[safe_z_home]
home_xy_position: 150, 150 # Zホーム前の移動先XY（mm）
speed: 50 # 移動速度（mm/s）
z_hop: 10 # 事前のZリフト（mm）
z_hop_speed: 5 # Zリフト速度（mm/s）Tips:
home_xy_positionはプローブのオフセット込みでベッド範囲内に収めること。
11. [fan] / [heater_fan]（ファン制御）
「fan」は手動/スライサー制御のパーツ冷却、「heater_fan」は温度に応じて自動で回るホットエンド冷却が主用途です。
- pin: 出力ピン
- max_power: 出力上限（0.0〜1.0）
- kick_start_time: 低速起動補助の通電時間（秒）
- off_below: 指定以下のデューティを 0 とみなす閾値
- heater（heater_fan）: 監視対象ヒーター(例: extruder)
- heater_temp（heater_fan）: 自動ON する温度(℃)
[fan]
pin: PA0 # ファン制御ピン
max_power: 1.0 # 最大出力（0.0-1.0）
kick_start_time: 0.5 # 起動補助時間（秒）
off_below: 0.0 # 停止閾値[heater_fan hotend_fan]
pin: PA1 # ファン制御ピン
heater: extruder # 監視対象ヒーター
heater_temp: 50.0 # 自動ON温度（℃）
fan_speed: 1.0 # ファン速度（0.0-1.0）Tips:
ファンは複数登録可能。[heater_fan] を使えば温度に応じて自動制御できる。
12. [firmware_retraction]（ファームウェア側リトラクト）
スライサーと独立してファームウェア側でリトラクトを制御します。材料切替や細かい調整に有効で、G10/G11コマンドで直接制御できます。リトラクト長と速度のバランスで糸引きと角の品質を調整します。
- retract_length: リトラクトする長さ(mm)
- retract_speed: リトラクト速度(mm/s)
- unretract_extra_length: 押し出し時の追加長(mm)
- unretract_speed: 押し出し速度(mm/s)
[firmware_retraction]
retract_length: 2.0 # リトラクト長（mm）
retract_speed: 20 # リトラクト速度（mm/s）
unretract_extra_length: 0 # 追加押し出し長（mm）
unretract_speed: 10 # 押し出し速度（mm/s）Tips:
フィラメント素材によってリトラクション設定が変わるので、必ずリトラクトテストをしてください。ここではあくまで参考値を書いています。
さらに、スライサー側で「Firmware Retraction」を有効にしておく必要あります。
13. [input_shaper] / [adxl345]（共振低減）
加速度センサー(ADXL345 等)で筐体の共振周波数を計測し、その周波数帯を打ち消すシェイパを適用します。高速印刷時のゴーストリング低減に効果的です。まずはセンサー配線(SPI)と取り付け剛性を確保し、計測後に各軸の周波数とシェイパ種別を反映します。
- [input_shaper] shaper_type: シェイパの種類(ei / mzv / zv / zvdd など)
- shaper_freq_x / shaper_freq_y: 各軸の共振周波数(Hz)
- damping_ratio: 減衰率(一般に 0.1〜0.2 付近から調整)
- [adxl345] spi_bus / cs_pin: センサー接続(SPIバス/CSピン)
[input_shaper]
shaper_type: mzv # シェイパタイプ
shaper_freq_x: 40 # X軸の共振周波数（Hz）
shaper_freq_y: 40 # Y軸の共振周波数（Hz）
damping_ratio_x: 0.1 # X軸の減衰率
damping_ratio_y: 0.1 # Y軸の減衰率シェイパタイプ:
- ei – 最も効果的だが遅延が大きい
- mzv – バランスが良い（推奨）
- zv – 遅延が小さい
- zvdd – 最も遅延が小さい
[adxl345]
cs_pin: spi1cs1 # CSピン
spi_speed: 5000000 # SPI速度（Hz）
spi_bus: spi1 # SPIバスTips:
取り付けが緩いと測定値がブレます。まずは固定と配線長を最適化。
14. [temperature_sensor]（追加温度センサー）
周囲温度、エンクロージャ内、ボード上の温度などを別途監視するためのセンサーです。記録や温度連動ファンのトリガとして利用でき、安全判断にも役立ちます。使用する素子の仕様(サーミスタ定数やIC名)に合わせて種類と配線を正しく指定します。
- sensor_type: 種別(例: NTC 100K B3950, ATC Semitec 104GT-2, MAX31865 等)
- sensor_pin: 入力ピン
- pullup_resistor: 必要に応じたプルアップ値(Ω)
- min_temp / max_temp: 読み取りの安全範囲(℃)
[temperature_fan chamber_fan]
pin: PA2 # ファン制御ピン
sensor_type: ATC Semitec 104GT-2 # 温度センサー種別
sensor_pin: PA3 # センサーピン
min_temp: 0 # 最低温度（℃）
max_temp: 100 # 最高温度（℃）
target_temp: 40 # 目標温度（℃）
max_speed: 1.0 # 最大速度（0.0-1.0）
min_speed: 0.3 # 最小速度（0.0-1.0）Tips:
追加センサーはtemperature_fanやcontroller_fanと組み合わせると、温度に応じた自動制御が実用的になります。
15. [filament_switch_sensor]（フィラメント切れ検知）
フィラメントの有無を検知するスイッチセンサーです。フィラメントが切れたり詰まったりしたときに自動で印刷を一時停止し、材料の無駄を防ぎます。スイッチが押されているかどうかで判定します。
- switch_pin: スイッチの信号ピン
- pause_on_runout: 切れ時にポーズするかどうか
- runout_gcode: 切れ時に実行するG-Code
[filament_switch_sensor filament_sensor]
switch_pin: ^PA0 # スイッチピン（^でプルアップ）
pause_on_runout: True # 切れ時にポーズする
runout_gcode:
PAUSE # 印刷を一時停止
M117 フィラメント切れ # エラーメッセージ表示Tips:
- スイッチはフィラメントが通る位置に正確に取り付ける
- ^でプルアップを有効にすると安定動作する
- フィラメントの太さに合わせてスイッチの感度を調整
- 誤検知を防ぐため、振動やノイズの少ない場所に設置
16. [filament_motion_sensor]（フィラメント動き検知）
フィラメントの動きを検知するセンサーです。フィラメントが動いているかどうかを監視し、停止した場合に印刷を一時停止します。スイッチセンサーより高精度で、詰まりの早期発見に有効です。
- detection_length: 検知する長さ(mm)
- extruder: 監視対象のエクストルーダ
- switch_pin: センサーの信号ピン
- pause_on_runout: 停止時にポーズするかどうか
[filament_motion_sensor filament_sensor]
detection_length: 7.0 # 検知長（mm）
extruder: extruder # 監視対象エクストルーダ
switch_pin: ^PA0 # センサーピン（^でプルアップ）
pause_on_runout: True # 停止時にポーズするTips:
- detection_lengthはフィラメントの直径の2-3倍程度に設定
- センサーはフィラメントが確実に通る位置に固定
- フィラメントの種類(PLA/ABS等)で感度が変わる場合がある
- 配線は短く、ノイズの影響を受けにくい場所に配置
17. [tmc2209]（TMC2209ドライバー設定）
TMC2209ステッパードライバーの設定です。静音性と高精度を両立し、センサレスホーミングにも対応します。UART通信でリアルタイムに電流やマイクロステップを調整できます。
- uart_pin: UART通信のピン
- microsteps: マイクロステップ数
- run_current: 運転時の電流(A)
- hold_current: 停止時の電流(A)
- stealthchop_threshold: ステルスチョップの速度閾値
[tmc2209 stepper_x]
uart_pin: PC4 # UART通信ピン
microsteps: 16 # マイクロステップ数
run_current: 0.8 # 運転電流（A）
hold_current: 0.5 # 保持電流（A）
stealthchop_threshold: 500 # ステルスチョップ閾値Tips:
- run_currentはモーター定格の60-80%から開始して調整
- hold_currentはrun_currentの50-70%程度に設定
- 脱調する場合は電流を上げ、発熱が激しい場合は下げる
- stealthchop_thresholdは静音性と性能のバランスで調整
- センサレスホーミングを使う場合はdiag_pinも設定
18. [virtual_sdcard]（仮想SDカード）
仮想SDカード機能です。Raspberry Piなどのホストコンピューター上でG-Codeファイルを管理し、物理的なSDカードを使わずに印刷できます。ファイルのアップロードや管理がWebインターフェースから簡単に行えます。
- path: G-Codeファイルの保存場所
- on_error_gcode: エラー時に実行するG-Code
[virtual_sdcard]
path: ~/gcode_files # G-Codeファイルの保存場所
on_error_gcode:
M117 SDカードエラー # エラーメッセージ表示Tips:
- パスは「絶対パス」で指定し、アクセス権限を確認
- ファイル名に日本語や特殊文字は避ける
- 大きなファイルは転送に時間がかかる場合がある
- バックアップを定期的に取ることを推奨
- ディスク容量不足にならないよう注意
19. [idle_timeout]（アイドルタイムアウト）
アイドル時のタイムアウト設定です。一定時間操作がないと自動でモーターやヒーターを停止し、安全と省エネを実現します。放置による事故や火災を防ぐ重要な安全機能です。
- timeout: タイムアウト時間(秒)
- gcode: タイムアウト時に実行するG-Code
[idle_timeout]
timeout: 600 # タイムアウト時間（秒）
gcode:
M84 # モーターをOFF
M106 S0 # ファンをOFF
M117 アイドルタイムアウト # メッセージ表示Tips:
- timeoutは印刷時間を考慮して設定(短すぎると印刷中に停止)
- 長時間印刷の場合は600秒(10分)以上に設定
- ヒーターの停止は火災リスクを考慮して慎重に判断
- 印刷中はタイムアウトしないよう注意
- 緊急時の復帰手順を事前に確認しておく
20. [display]（LCD/タッチパネル）
表示モジュールは「コントローラICの種類」と「接続方式（SPI/I2C/並列）」で設定が大きく変わります。まずは基板シルクや販売ページの仕様からIC名(例: ST7920, UC1701, ST7567)と接続方式を特定しましょう。ノイズや配線長の影響を受けやすいので、初回は短い配線・適切なGND共有で確認し、映らないときはコントラストやバックライトの設定も見直すと解決が早いです。クリック付きエンコーダは回転方向の論理が逆になることがあり、encoder_pins の極性を入れ替えて整えます。
- lcd_type / controller: コントローラ種別(例: ST7920, UC1701など)。モジュール固有のドライバを選択
- 接続ピン: SPI/I2C/並列の各ピン(例: cs, sclk, mosi, miso, a0/dc, rst)。配線長は短く、GND共通を確実に
- encoder_pins / click_pin: エンコーダ左右回転のピン割当と押下ボタン。回転方向が逆なら配線/極性を見直す
- buzzer_pin / contrast / backlight: ブザー・コントラスト・バックライトの調整。表示が薄い/潰れる時は contrast を段階的に調整
- kill_pin / reset_pin（任意）: 物理キルスイッチやモジュールリセット。誤配線で常時リセットにならないよう注意
[display]
lcd_type: st7920 # ディスプレイタイプ
cs_pin: PA4 # CSピン
sclk_pin: PA5 # クロックピン
sid_pin: PA6 # データピン
encoder_pins: ^PA2,^PA3 # エンコーダピン
click_pin: ^PA1 # クリックピンTips:
- ST7920 はノイズ耐性が低めです。モータ線から離し、フェライトや短配線を心がけると安定します。
- フルグラフィックLCDは描画負荷が高く、更新レートが落ちることがあります。必要な表示だけに絞ると見やすさと反応が改善します。
- タッチパネル系は別途 [display] の他に専用モジュールやファーム連携が必要な場合があります。導入手順をベンダ資料で確認してください。
include機能
includeは、printer.cfgの中から「別の設定ファイルを読み込んで、その内容をそこに書いたかのように合成する」機能です。設定内容が増えると、1つのprinter.cfgに全て書くのは大変です。そんなときに便利なのがinclude機能です。設定ファイルを分割し、見やすく整理できます。
- 目的: 長いprinter.cfgを用途ごと(マクロ、ベッドメッシュ、機種別など)に分け、見通しと再利用性を上げる
- 使い方: 読み込みたい位置に1行ずつ書く(後から書いたほうが優先＝後勝ち)
includeの使い方:
- 別ファイルを作成(例: macros.cfg / bed_mesh.cfg)
- printer.cfgの先頭か末尾に記述：
[include macros.cfg] [include bed_mesh.cfg] - 保存 → RESTART(またはFIRMWARE_RESTART)
設定が少ないうちは1つの printer.cfg にまとめても大丈夫です。
大きくなってきたら「マクロ」「ベッドメッシュ」などを分割し、include で読み込むと整理しやすくなります。
[include macros.cfg]
[include bed_mesh.cfg]読み込む順番が優先順位になります。この場合、[include macros.cfg]が先に読み込まれます。
スペルミスやパス間違いは起動エラーの原因になるので注意が必要です。
printer.cfgのマクロについて
マクロとは、複数のコマンドを1つにまとめた「便利なショートカット」です。例えば、印刷開始時に毎回同じ作業をする場合、それを1つのコマンドで実行できるようになります。
マクロって何？:
例：印刷開始の手順
- ホーム(G28)
- ベッドを60℃に加熱(M140 S60)
- ノズルを200℃に加熱(M104 S200)
- 温度が上がるまで待つ(M190 S60, M109 S200)
基本的な書き方:
[gcode_macro マクロ名]
gcode:
# ここに実行したいコマンドを書く
G28 # ホーム
M104 S200 # ノズル加熱
M140 S60 # ベッド加熱ポイント：
- [gcode_macro マクロ名] でマクロを定義
- gcode: の下にコマンドを書く
- #の後はコメント(説明)
これを毎回手動でやるのは大変ですよね？マクロを使えば、START_PRINTと入力するだけで全部自動でやってくれます。
3Dプリンタータイプごとの違い
機構が違うと、使うセクション名や初期調整のポイントが少し変わります。まず自分の機種のタイプを確認し、そのタイプに合う最小構成から始めましょう。
Cartesian / CoreXY / Delta
Cartesian（カーテシアン）:
X・Y・Z がそれぞれ独立して動く最も一般的な構造です。[printer].kinematics: cartesian、軸は [stepper_x] [stepper_y] [stepper_z]を使います。物理レベリング([bed_screws])で大まかに平面を出し、必要なら[bed_mesh]で微調整を加えます。
例: Creality Ender-3 / Ender-3 V2 / Ender-3 S1、Prusa i3 MK3S+、Anycubic i3 Mega
カーテシアンには「ベッドスリンガー」と「カンチレバー」の2種類あります。
ベッドスリンガーはいわゆるCreality Ender-3系で、もっとも一般的な3Dプリンターで、そのシンプルさ、信頼性、使いやすさで知られていますよね。一方、カンチレバーはBambu Lab A1 miniなどが有名です。片持ちフレーム形状が独特だと思います。
CoreXY(コアXY):
X/Yの動きを2つのモーターで合成する機構です。[printer].kinematics: corexyを指定します。rotation_distance の考え方はベルト軸として Cartesian と同じですが、ベルトの張り・経路の精度が仕上がりに強く影響します。高速化しやすいため、安定後に[input_shaper]を適用すると効果が出やすいです。
例: Voron 2.4 / Voron Trident、Creality K1 / K1 Max、Bambu Lab X1 / P1
Delta（デルタ）:
3本のタワーでヘッド位置を決める構造です。ステッパーは[stepper_a] [stepper_b] [stepper_c]を使い、上部エンドストップでホームします。初期は DELTA_CALIBRATE(またはプローブ＋[bed_mesh])で幾何学を合わせ、中心〜周辺の高さ差が小さくなるよう詰めます。Zオフセットは印刷温度で再確認すると安定します。
例: Anycubic Kossel、FLSUN SR / V400、SeeMeCNC Rostock
マルチエクストルーダー / IDEX
ノズルが2本以上の構成です。2本目以降は[extruder1]のように番号付きで追加します。送りモーターだけを増やすなら[extruder_stepper]を使います。IDEX(左右独立)では、左右のホーム/パーク位置や干渉回避をマクロで切り替え、ツールごとに温度・押し出し量・補正値(例: pressure_advance)を分けて管理します。(本記事は基礎が対象なので、詳細の調整は割愛)
例: Raise3D E2、Snapmaker J1、Tenlog TL-D3 Pro、BCN3D Sigma 系
printer.cfgの設定値を決めるヒント
設定の多くは「機体の物理仕様」から素直に導けます。最初に配線・機構タイプを確定し、次に“動作の基準”になる値(rotation_distance、オフセット、温度センサー種別など)を計算または実測で決めましょう。Klipperはsteps/mm を直接使わず、1回転でどれだけ進むか(rotation_distance)を基準にします。ギアがある場合はgear_ratioを併用すると見通しが良くなります。
ハードウェア情報を調べる
まずは「何で動いているか」を把握します。ここが曖昧だと、以降の調整がすべて不安定になります。
- モーター型番 → ステップ角度
一般的に 1.8°(200ステップ/回転)か 0.9°(400ステップ/回転)。Klipperでは通常この差はrotation_distanceには直接関与しませんが、異常な動きがあれば型番・配線・ドライバ設定(例: TMCのinterpolate等)も確認。
- メインボードのピン配置 → 各pinの位置
メーカー配布のピンマップ/回路図を参照。step_pin/dir_pin/enable_pin、endstop_pin、heater_pin/sensor_pin が確実に合っているかを最優先で確認。
- サーミスタ仕様 → sensor_type選定
代表例はNTC 100K B3950、ATC Semitec 104GT-2など。表示温度が室温から大きくズレる場合は型番・配線・プルアップ抵抗を再確認。
- 機構と伝達要素 → ベルトピッチ/プーリー歯数、リードスクリューのリード、エクストルーダのギア比
ここがrotation_distance の“元ネタ”になります。販売ページや実測で確認していきましょう。
Tips:
- 最初は低速・低温でテストし、正転/逆転やエンドストップの論理(! 反転、^ プルアップ)を安全に確認
- 動かない/逆回転は配線・ピン・論理反転のどれかが誤りであることが多いです。焦らず順番に切り分け
rotation_distance(Eステップ)の計算例
rotation_distanceは「モーター1回転で軸（またはフィラメント）が進む距離」です。steps/mm と違い、マイクロステップ設定に依存しないため、物理仕様が分かれば“まずの値”をすぐ置けます。
- ベルト軸(例: GT2, 20T プーリー)
ベルトピッチ 2mm × 歯数 20 = 40mm → rotation_distance: 40目安: 16Tなら 32mm、20Tなら 40mm、 idler 交換やプーリー歯数変更時はここだけ更新。
- リードスクリュー(例: リード 8mm)
1回転で 8mm 進む → rotation_distance: 8
注意: “ピッチ”と“スタート数（条数）”の混同に注意。
公称 8mmリードは「ピッチ × 条数」で 8mm になっている場合があります。必ず“1回転で進む実距離＝リード”を使う。
- エクストルーダ（ギア式/直結どちらでも可）
まずは公称値で開始。印刷温度で「100mm 押し出し」を指令し、実測長をノギスで測って補正します。
- 計算式: 新 rotation_distance = 旧値 × 指令長(mm) / 実測長(mm)
- 例: 100mm 指令 → 98mm 実測 → 旧値 × (100/98)
ギア式なら、可能なら gear_ratio（例: 50:17）を併用すると、rotation_distance を“ホブ1回転あたりの送り”基準で考えられ、メンテ時の再計算が楽になります。
rotation_distanceは「フィードギア（フィラメントを噛むギア）が1回転したときに送られる距離（mm）」です。モーター側の回転はgear_ratioで表します。
ギア式でgear_ratioを書く場合(推奨):
- 計算式: rotation_distance = π × 有効直径（フィードギア）
- 例: 有効直径7.0mmなら、rotation_distance ≈ 3.1416 × 7.0 ≈ 21.99mm
gear_ratio: 50:17 ; motor:gear（BMG）
rotation_distance: 21.99ギア式だがgear_ratioを書かない場合(減速を内包する):
- 計算式: rotation_distance = (π × 有効直径) × (ギア比の逆数)
- ギア比の逆数 = フィードギア:モーター = B:A(gear_ratioがA:Bのとき)
つまり rotation_distance = π × D × (B / A) - 例(BMG 50:17, D=7.0mm): 21.99 × (17/50) ≈ 7.48mm
; gear_ratio を書かない場合
rotation_distance: 7.48補足と落とし穴:
- CoreXY でも各ベルトの rotation_distance 自体は Cartesian と同じ考え方です（運動学は [printer].kinematics で表現）。
- マイクロステップやステップドライバの設定は、Klipperの rotation_distance とは独立です。ここを混同しないと調整がシンプルになります。
- エクストルーダ校正は必ず“運用温度”で。冷間や極端な速度で測ると、溶融圧・スリップでズレます。フィラメントの湿気・硬さでも結果が変わるため、代表的な条件で1回決め、スライサーのフローは微調整に留めると安定します。
- ベルト軸は“ベルト張力・プーリー固定”で実距離が微妙に変わることがあります。最初の印刷で寸法がズレる場合は、メカ側（固定ねじ、ベルトたるみ）と rotation_distance の両面で再確認を。
よくある設定ミス（原因と対処のヒントつき）
最初に起きやすいのは「配線・論理の食い違い」「原点や可動範囲の誤解」「温度センサー種別の不一致」です。症状だけ追うより、“どこを見れば原因にたどり着けるか”を意識すると早く解決できます。
ピン間違い・論理反転(! / ^):
- 症状: モーターが動かない／逆回転／ガタつく
- 主因: step_pin/dir_pin/enable_pinの取り違え、dir_pinの反転不足(!)、enable_pinの論理違い、モーター配線の相対入れ替え
確認/対処:
- STEPPER_BUZZ STEPPER=stepper_xで1軸ずつ生存確認(少しだけ前後に動けばOK)
- 逆なら dir_pin に ! を付け外し
- 無反応は enable_pinの論理(! 有無)や配線を見直し
endstop と position_endstop の不整合:
- 症状: ホーム後に突っ込む／離れる／端で止まらない
- 主因: endstop_pinの極性(! 反転)の不一致、原点がベッド最小側か最大側かの取り違え、position_endstopと実機のゼロがズレている
確認/対処:
- QUERY_ENDSTOPS実行→手でスイッチを押して状態が変わるか確認(逆なら !)
- 原点が最小側ならposition_endstop: 0、最大側なら「可動最大値」を入れる
- homing_retract_distを小さめにして安全にテスト
可動範囲(position_max/min)の設定抜け:
- 症状: 端まで行かない／動かそうとするとエラー
- 対処: 実測ストロークに合わせて position_max(必要なら position_min)を設定
rotation_distance / gear_ratio のミス:
- 症状: 寸法が全体に大きい/小さい、円がいびつ
対処:
- ベルト軸は「ベルトピッチ×プーリー歯数」で初期値(GT2×20T→40)
- エクストルーダは 100mm 押し出し実測で補正(旧値×指令長/実測長)
- ギア式はgear_ratioを併用すると再計算が楽
sensor_type 違い（温度系）:
- 症状: 0℃固定／加熱直後にエラー／表示が極端にズレる
対処:
- 実機のサーミスタ型番に合わせてsensor_typeを正しく選ぶ
- min_temp/max_tempと配線(断線・短絡)を確認
- 立ち上がりが遅いベッドはverify_heaterを厳しくしすぎない
単位混同(mm/s と mm/min):
- 症状: 想定より激遅／激速で動く
- 対処: Klipperは基本 mm/s。スライサーやMarlin資料のmm/minをそのまま入れない
TMC ドライバ設定（任意）:
- 症状: 脱調しやすい／センサレスが常時ヒット
- 対処: run_current をモーター定格の6〜8割で開始、diag_pin の配線/無効化を確認(センサレスは後で)
include の順序/重複:
- 症状: 直したはずの値が反映されない
- 対処: 後勝ちを理解し、同じパラメータは最終読み込み側で一元管理
スペル・型ミス:
- 症状: RESTART でエラー、起動不可
- 対処: コンソールのエラーメッセージ(セクション名・行番号)に従い、キー名の綴り・数値/文字列の型を修正
編集後の確認手順
保存と再起動:
変更 → 保存 → RESTART(またはFIRMWARE_RESTART)で反映。
エラーが出たらコンソールのログ(行番号・セクション名)を見て綴り・値の型を再確認。
メモ:
- RESTARTはKlipperサービス再起動、FIRMWARE_RESTARTはMCU側の再初期化も含む再起動。エラー時は後者が有効なことが多い。
動作テスト（最初の順序）:
- 室温表示が妥当か(ヒーターOFFで)
- 低温でヒーターテスト(例: ノズル150℃、ベッド50℃)
- 軸を小刻みに手動移動(衝突がないこと)
- G28でホーム(エンドストップが正常に動作するか)
- パーツファン/ホットエンドファンのON/OFF確認
コツ: 一度に大きく変えず、小さく変更→テストを繰り返すとトラブルを防げます。
まとめ
以上で説明を終わりになります。printer.cfgはKlipperの「頭脳」です。内容を理解すれば、自分のプリンターを思い通りにチューニングできます。– セクションごとの役割を知る – 設定値の意味(単位・依存関係)を把握する – 小さな変更からテストしながら進めることで設定作業はぐっと楽になります。
最初は難しく見えても、「どの設定が何を制御しているか」を意識して読むだけで理解が深まります。安全に配慮しながら、少しずつカスタマイズを楽しんでください。
