Disclaimer: This is an independent resource site.
Not affiliated with the Voron project or its development team.
<article class="guide-article">
<header>
<h1>Voron Klipper Board Migration Guide</h1>
<p class="lead">Step-by-step guide to safely migrate your Voron from one mainboard to another without losing your tuned configuration.</p>
</header>
<section>
<h2>Overview</h2>
<p>
Migrating from one control board to another is a common Voron upgrade path. Whether you are moving from an SKR v1.4 Turbo to an Octopus, or from an Octopus to a Manta M8P, the process follows a consistent workflow. This guide covers every step physically and in software.
</p>
<p>
<strong>Common migration scenarios:</strong>
</p>
<ul>
<li>SKR v1.4 Turbo to BTT Octopus v1.1 (adding more Z motors)</li>
<li>Fysetc Spider v2.2 to BTT Octopus v1.1 (more drivers and fans)</li>
<li>BTT Octopus v1.1 to BTT Manta M8P (integrated compute module)</li>
<li>Any board to any board when the original board fails</li>
</ul>
</section>
<section>
<h2>Prerequisites</h2>
<p>Before starting, gather the following:</p>
<ul>
<li>Your existing printer.cfg file (backed up) and the Voron reference config for the new board.</li>
<li>Pinout diagram for both the old and new boards.</li>
<li>Klipper firmware binary for the new board (or the build environment to compile one).</li>
<li>A multimeter for continuity testing.</li>
<li>A USB cable for initial firmware flashing (if the new board does not have an integrated compute module).</li>
<li>Ferrule crimps, heat shrink, and basic wiring tools.</li>
</ul>
</section>
<section>
<h2>Step 1: Backup Your Current Configuration</h2>
<p>
Before touching any hardware, create a complete backup of your working configuration.
</p>
<ol>
<li>Copy the entire <code>~/printer_data/config/</code> directory:</li>
</ol>
<pre>cp -r ~/printer_data/config ~/printer_data/config-backup-$(date +%Y%m%d)</pre>
<ol start="2">
<li>Save tuning values: record your <code>pressure_advance</code>, <code>max_accel</code>, PID values, and input shaper settings. These will transfer to any board.</li>
<li>Save your <code>SAVED_CONFIG</code> directory (contains probe and Z offset calibration).</li>
</ol>
</section>
<section>
<h2>Step 2: Build Firmware for the New Board</h2>
<p>
Compile Klipper firmware for the new board before removing the old one. That way you can flash immediately after wiring.
</p>
<ol>
<li>SSH into your Raspberry Pi or SBC.</li>
<li>Navigate to the Klipper directory:</li>
</ol>
<pre>cd ~/klipper
make menuconfig</pre>
<ol start="3">
<li>Set the correct options for your target board:</li>
</ol>
<table>
<thead>
<tr>
<th>Board</th>
<th>Microcontroller</th>
<th>Processor Model</th>
<th>Bootloader Offset</th>
<th>Communication</th>
</tr>
</thead>
<tbody>
<tr>
<td>Octopus v1.1</td>
<td>STM32F446</td>
<td>STM32F446</td>
<td>32KiB boot</td>
<td>USART1 PA10/PA9</td>
</tr>
<tr>
<td>SKR v1.4 Turbo</td>
<td>LPC1769</td>
<td>LPC1769</td>
<td>P0.17 jumper</td>
<td>USB</td>
</tr>
<tr>
<td>Spider v2.2</td>
<td>STM32F446</td>
<td>STM32F446</td>
<td>32KiB boot</td>
<td>USART3 PB11/PB10</td>
</tr>
<tr>
<td>Manta M8P (CB1)</td>
<td>STM32F407</td>
<td>STM32F407</td>
<td>128KiB boot</td>
<td>USB</td>
</tr>
</tbody>
</table>
<ol start="4">
<li>Exit and save, then compile:</li>
</ol>
<pre>make clean
make</pre>
<ol start="5">
<li>The firmware binary will be at <code>~/klipper/out/klipper.bin</code> (or <code>out/klipper.uf2</code> for some boards). Rename it as required by your board (e.g., <code>firmware.bin</code> for Octopus).</li>
</ol>
</section>
<section>
<h2>Step 3: Create a New Config From the Voron Reference</h2>
<p>
Do not try to edit your old config in place. Instead, start from the official Voron reference config for the new board and merge your tuned values.
</p>
<ol>
<li>Find the reference configs in the Voron GitHub repository under <code>Voron-Stealthburner/Voron2_4/config/</code> (or your specific model).</li>
<li>Copy the reference to your config directory:</li>
</ol>
<pre>cp reference-config.cfg ~/printer_data/config/printer.cfg</pre>
<ol start="3">
<li>Transfer these tuned values from your backup config:</li>
</ol>
<ul>
<li><code>rotation_distance</code> for all axes (if you calibrated them)</li>
<li><code>pressure_advance</code> and <code>pressure_advance_smooth_time</code></li>
<li>Input shaper settings (<code>[input_shaper]</code> section)</li>
<li>PID values from <code>SAVED_CONFIG</code></li>
<li>Probe Z offset and <code>z_offset</code> settings</li>
<li>Bed mesh profile (save the <code>SAVED_CONFIG</code> file)</li>
<li>Your custom macros (<code>[gcode_macro START_PRINT]</code>, etc.)</li>
</ul>
</section>
<section>
<h2>Step 4: Pin Mapping — Convert Pins from Old to New Board</h2>
<p>
This is the most critical step. Each pin in your old config must be mapped to the equivalent pin on the new board.
</p>
<p>
<strong>Example: SKR v1.4 Turbo to Octopus v1.1 conversion</strong>
</p>
<table>
<thead>
<tr>
<th>Function</th>
<th>SKR v1.4 Pin</th>
<th>Octopus v1.1 Pin</th>
</tr>
</thead>
<tbody>
<tr>
<td>X Step</td>
<td>P2.1</td>
<td>PF13</td>
</tr>
<tr>
<td>X Dir</td>
<td>P2.2</td>
<td>PF12</td>
</tr>
<tr>
<td>X Enable</td>
<td>P2.8</td>
<td>PF14</td>
</tr>
<tr>
<td>Y Step</td>
<td>P2.3</td>
<td>PF9</td>
</tr>
<tr>
<td>Y Dir</td>
<td>P2.4</td>
<td>PF8</td>
</tr>
<tr>
<td>Y Enable</td>
<td>P2.9</td>
<td>PF10</td>
</tr>
<tr>
<td>Z Step</td>
<td>P0.9</td>
<td>PF5</td>
</tr>
<tr>
<td>Z Dir</td>
<td>P0.8</td>
<td>PF4</td>
</tr>
<tr>
<td>Z Enable</td>
<td>P0.10</td>
<td>PF6</td>
</tr>
<tr>
<td>E0 Step</td>
<td>P0.7</td>
<td>PD6</td>
</tr>
<tr>
<td>E0 Dir</td>
<td>P0.6</td>
<td>PD5</td>
</tr>
<tr>
<td>E0 Enable</td>
<td>P0.5</td>
<td>PD7</td>
</tr>
<tr>
<td>X Endstop</td>
<td>P1.29</td>
<td>PG6</td>
</tr>
<tr>
<td>Y Endstop</td>
<td>P1.28</td>
<td>PG9</td>
</tr>
<tr>
<td>Z Endstop</td>
<td>P1.27</td>
<td>PG10</td>
</tr>
<tr>
<td>Probe</td>
<td>P1.26</td>
<td>PG12</td>
</tr>
<tr>
<td>Hotend Heater</td>
<td>P2.7</td>
<td>PA0</td>
</tr>
<tr>
<td>Hotend Thermistor</td>
<td>P0.24</td>
<td>PC4 (T0)</td>
</tr>
<tr>
<td>Bed Heater</td>
<td>P2.5</td>
<td>PB5</td>
</tr>
<tr>
<td>Bed Thermistor</td>
<td>P0.25</td>
<td>PC5 (T1)</td>
</tr>
</tbody>
</table>
</section>
<section>
<h2>Step 5: Physical Wiring and Installation</h2>
<p>
With the printer powered off and unplugged, replace the board.
</p>
<ol>
<li>Remove all wiring from the old board, labeling each connector with tape or a label maker. Take photos before disconnecting — they are invaluable.</li>
<li>Mount the new board in the electronics bay. Some boards (e.g., Octopus) are larger than SKR boards and may require rethinking the mounting location.</li>
<li>Wire stepper motors first. Use the Voron wiring guide for your specific board — stepper wire order is often different between board brands.</li>
<li>Wire endstops and probe. Verify continuity with a multimeter before connecting.</li>
<li>Wire heaters and thermistors. <strong>Double-check thermistor polarity</strong> — some boards are sensitive to swapped thermistor wires.</li>
<li>Wire fans. The Octopus uses 24V fan outputs by default — do not connect 5V fans without a buck converter.</li>
<li>Connect USB (for standalone boards) or install the compute module (for Manta-style boards).</li>
<li>Perform a visual inspection of all connections before applying power.</li>
</ol>
</section>
<section>
<h2>Step 6: Flash and Test</h2>
<ol>
<li>Copy the firmware binary to an SD card (for SD card flashing) or place in the correct location for DFU flashing.</li>
<li>For STM32 boards (Octopus, Spider, Manta), hold the boot button while connecting USB or power, then release. The board appears as a mass storage device. Copy the <code>firmware.bin</code> file.</li>
<li>For LPC1769 boards (SKR), place the <code>firmware.bin</code> on an SD card, insert it, and power on.</li>
<li>Connect via SSH and check that the MCU is detected:</li>
</ol>
<pre>ls /dev/serial/by-id/*</pre>
<ol start="5">
<li>Update the <code>serial:</code> path in printer.cfg to match the detected device ID.</li>
<li>Start Klipper:</li>
</ol>
<pre>sudo systemctl restart klipper</pre>
<ol start="7">
<li>Check the logs:</li>
</ol>
<pre>tail -n 50 ~/printer_data/logs/klippy.log</pre>
<ol start="8">
<li>Run the following test sequence:</li>
</ol>
<ul>
<li><code>STATUS</code> — confirms Klipper is connected.</li>
<li><code>QUERY_ENDSTOPS</code> — verify all endstops read correctly when triggered manually.</li>
<li><code>STEPPER_BUZZ STEPPER=stepper_x</code> — test each stepper motor moves in the correct direction.</li>
<li><code>PID_CALIBRATE HEATER=extruder TARGET=245</code> — run PID calibration for the hotend.</li>
<li><code>PID_CALIBRATE HEATER=heater_bed TARGET=100</code> — run PID calibration for the bed.</li>
</ul>
</section>
<section>
<h2>Step 7: Recalibration</h2>
<p>
After confirming basic function, re-run all calibration routines. Even if you transferred values, the new board's electrical characteristics may differ slightly.
</p>
<ol>
<li><code>PROBE_CALIBRATE</code> — recalibrate probe Z offset with hot bed and nozzle.</li>
<li><code>BED_MESH_CALIBRATE</code> — generate a fresh bed mesh.</li>
<li><code>Z_TILT_ADJUST</code> (for V2.4/Trident) — redo Z tilt calibration.</li>
<li><code>INPUT_SHAPER_CALIBRATE</code> — input shaping values can change due to different driver electrical characteristics.</li>
<li>Print a calibration cube to verify dimensional accuracy.</li>
</ol>
</section>
<section>
<h2>Common Migration Issues</h2>
<h3>Stepper Motors Move in the Wrong Direction</h3>
<p>
This is the most common issue. Add or remove the <code>!</code> character before the <code>dir_pin</code> value to invert the direction.
</p>
<p>
Example: <code>dir_pin: PF12</code> becomes <code>dir_pin: !PF12</code> if the motor moves backward.
</p>
<h3>Thermistor Reading Incorrect</h3>
<p>
If the thermistor reads wildly different values (e.g., room temperature shows as 300°C or -20°C), check the <code>sensor_type</code> and the <code>sensor_pin</code>. Some boards use different ADC pins for thermistor inputs — verify against the new board's pinout.
</p>
<h3>Probe Fails to Trigger</h3>
<p>
If the probe does not trigger, the pin inversion may be wrong. The Voron standard is NC (normally-closed) probe wiring. In Klipper, this means the pin should be <code>!PG12</code> (with the ! inversion character) if the probe outputs a low signal when triggered. Test with <code>QUERY_PROBE</code>.
</p>
<h3>Fan Not Spinning or Spinning at Full Speed</h3>
<p>
Check that the fan is the correct voltage (24V for Voron builds). If using the reference config, verify the <code>hardware_pwm:</code> setting. Some boards require PWM on specific timer channels.
</p>
</section>
<section>
<h2>Migration Checklist</h2>
<table>
<thead>
<tr>
<th>#</th>
<th>Task</th>
<th>Done?</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>Backup printer.cfg and SAVED_CONFIG</td>
<td></td>
</tr>
<tr>
<td>2</td>
<td>Compile Klipper firmware for new board</td>
<td></td>
</tr>
<tr>
<td>3</td>
<td>Get Voron reference config for new board</td>
<td></td>
</tr>
<tr>
<td>4</td>
<td>Map all pins from old board to new board</td>
<td></td>
</tr>
<tr>
<td>5</td>
<td>Transfer tuned values to new config</td>
<td></td>
</tr>
<tr>
<td>6</td>
<td>Label and photograph old wiring</td>
<td></td>
</tr>
<tr>
<td>7</td>
<td>Install new board and connect all wiring</td>
<td></td>
</tr>
<tr>
<td>8</td>
<td>Visual inspection of all connections</td>
<td></td>
</tr>
<tr>
<td>9</td>
<td>Flash firmware to new board</td>
<td></td>
</tr>
<tr>
<td>10</td>
<td>Verify serial device detection</td>
<td></td>
</tr>
<tr>
<td>11</td>
<td>Restart Klipper and check logs</td>
<td></td>
</tr>
<tr>
<td>12</td>
<td>Test endstops with QUERY_ENDSTOPS</td>
<td></td>
</tr>
<tr>
<td>13</td>
<td>Test stepper direction with STEPPER_BUZZ</td>
<td></td>
</tr>
<tr>
<td>14</td>
<td>Run PID calibration (hotend + bed)</td>
<td></td>
</tr>
<tr>
<td>15</td>
<td>Recalibrate probe Z offset</td>
<td></td>
</tr>
<tr>
<td>16</td>
<td>Run Z_TILT_ADJUST</td>
<td></td>
</tr>
<tr>
<td>17</td>
<td>Generate bed mesh</td>
<td></td>
</tr>
<tr>
<td>18</td>
<td>Recalibrate input shaper</td>
<td></td>
</tr>
<tr>
<td>19</td>
<td>Print test cube and verify quality</td>
<td></td>
</tr>
</tbody>
</table>
</section>
<section>
<h2>Troubleshooting After Migration</h2>
<p>
If you encounter issues after migration, check these in order:
</p>
<ol>
<li><strong>Klipper does not start:</strong> Check <code>klippy.log</code> for config validation errors. The most common cause is a pin name mismatch.</li>
<li><strong>Klipper starts but MCU errors:</strong> The serial path in <code>printer.cfg</code> does not match the actual device. Use <code>ls /dev/serial/by-id/*</code> to find the correct path.</li>
<li><strong>Heater errors:</strong> Check heater pin assignments. Many boards map heaters differently — verify your specific board's pinout.</li>
<li><strong>Thermistor reads 0 or max:</strong> Swap the thermistor wires at the board connector. Some boards are polarity-sensitive.</li>
<li><strong>Inconsistent first layer:</strong> Re-run <code>PROBE_CALIBRATE</code> and <code>BED_MESH_CALIBRATE</code> — the new ADC may give slightly different readings.</li>
</ol>
</section>
</article>