Getting Started with Smoothieboard

So you got your Smoothieboard and you want to get it running. Good news: it’s not that complicated. Bad news: you still need to read stuff and do things in order.

This guide will walk you through the whole process from plugging in the USB cable for the first time, to actually making your machine do things.

Expected time: 2-4 hours depending on how complicated your machine is and how many times you have to re-read things.

Already know what you’re doing? Jump ahead:

How it works

Before you start plugging wires everywhere, here’s the basic idea of how this whole thing works:

You want to make a physical object. Here’s the chain:

  1. Design your thing in CAD software (OpenSCAD, Fusion360, Inkscape, whatever)
  2. Generate G-code using a slicer/CAM program (Slic3r, CamBam, LightBurn, etc.)
  3. Send commands to Smoothieboard using host software (Pronterface, Octoprint, bCNC, etc.)
  4. Smoothieboard receives G-code via USB/Ethernet/SD card
  5. Smoothie firmware executes the commands by moving motors and controlling tools
  6. Your machine makes the thing

The parts of the system:

  • Smoothie = The firmware (software) that runs on the board
  • Smoothieboard = The actual physical board (hardware)
  • G-code = The language that tells machines what to do
  • Config file = A text file on the SD card that tells Smoothie how to behave

If you want more details on all this, read Smoothie Basics.

Versions
There are two versions of Smoothieboard: v1 (LPC1769, widely used, stable) and v2 (STM32H745, more powerful, newer). Most of this documentation applies to both. Check Smoothieboard hardware if you want the details.

Choose your machine guide

Different machines need different setup instructions. Pick yours:

3D Printer

3D Printer

Extruders, hotends, heated beds

Setup Guide
Laser

Laser Cutter

Laser power, focusing, safety

Setup Guide
CNC Mill

CNC Mill

Spindles, tool changes, feeds

Setup Guide
Pick and Place

Pick and Place

Vacuum, rotation, placement

Setup Guide
Read the whole guide first
Seriously. Read your machine guide from start to finish before you plug anything in. You'll save yourself time and avoid breaking things. People who don't do this always regret it.

The process

Here’s what setting up a Smoothieboard looks like. Each machine guide gives you the details, but this is the general flow:

Before anything else

You need:

  • Basic electrical knowledge (voltage, current, polarity - see Electricity Basics if you need a refresher)
  • Screwdrivers, wire strippers, multimeter
  • A power supply appropriate for your machine
  • USB cable (usually USB-A to USB-B)
  • Ability to crimp or solder wires (depending on your setup)
  • Patience

Windows users: You’ll need to install Windows Drivers for the board to show up properly.

Time estimate:

  • Software setup: 15-30 minutes
  • Wiring everything: 1-2 hours
  • Configuration: 1-2 hours
  • Testing and calibration: 30 minutes to 1 hour

Step 1: Software setup (15-30 minutes)

1. Install drivers (Windows only)

If you’re on Windows, go install the Windows drivers now. Linux and Mac have drivers built in.

2. Get host software

You need software on your computer to talk to the board. Pick one:

  • Smoopi - Recommended, runs on Raspberry Pi with touchscreen
  • Pronterface - Popular for 3D printers, simple and reliable
  • Octoprint - Web-based 3D printer control, very nice
  • bCNC - Good for CNC mills

See Software for the full list.

3. Download configuration file

You’ll need a config file for your machine type:

Save this somewhere, you’ll need it later.

4. Read your machine guide

Go read the entire guide for your machine type now. Not kidding. Do it.

Step 2: First connection (15 minutes)

Plug in USB

Connect the USB cable from your computer to the Smoothieboard. The board should power on (you’ll see LEDs light up).

Your computer should recognize it as:

  • A USB serial device
  • A USB mass storage device (the SD card shows up like a USB stick)

Talk to it

Open your host software, connect to the serial port, and try some commands:

version       (shows firmware version)
help          (lists available commands)
G0 X10        (tries to move X axis - won't work yet, no motors)

If you get responses, you’re good. If not, check your drivers (Windows) or try a different USB cable.

See Console Commands for what you can type.

The SD card

The SD card appears as a drive on your computer. You can copy files to it like any USB stick. Important:

  • The config file goes here
  • G-code files go here
  • Always “safely eject” before doing anything
Never edit the SD card while the machine is running
Concurrent access corrupts SD cards. Always unmount/eject in your OS before operations. "Unmount" means clicking "safely eject" in your file manager, not physically removing the card.

Step 3: Wiring (1-2 hours)

Power off!
Always disconnect power before wiring. Never connect or disconnect anything with power on. Seriously.

Your machine guide has the detailed wiring instructions. General order:

  1. Power supply - Wire AC power to your PSU, then PSU outputs to the board power inputs (see Main Power Input)
  2. Stepper motors - Connect each motor to a driver output (see Stepper Motors)
  3. Endstops - Wire limit switches to endstop inputs (see Endstops)
  4. Sensors - Thermistors for 3D printers (see Temperature Control)
  5. Tools - Heaters, lasers, spindles, whatever your machine uses

Test each component as you go. Wire something, test it, then move on. If you wire everything at once and it doesn’t work, you’ll waste hours troubleshooting.

Step 4: Configuration (1-2 hours)

Configuration is just editing a text file. No compiling, no fancy tools.

Copy config to SD card

  1. Plug in your USB cable (board should be powered)
  2. The SD card appears as a drive
  3. Copy your downloaded config file to it
  4. Name it config or config.txt
  5. Safely eject the drive
  6. Reset the board (press reset button or power cycle)
  1. Plug in your USB cable (board should be powered)
  2. The SD card appears as a drive
  3. Copy your downloaded config.ini file to it
  4. The file MUST be named exactly config.ini (V2 uses INI format, not plain text)
  5. Safely eject the drive
  6. Reset the board (press reset button or power cycle)

Edit for your machine

You’ll need to change values for your specific setup. Open the config file in any text editor and look for:

  • Steps per mm for your motors
  • Max speeds and accelerations
  • Endstop pin assignments
  • Temperature sensor types
  • Tool configurations

See Configuring Smoothie for complete documentation.
  • Steps per mm for your motors (in INI sections like [actuator.alpha])
  • Max speeds and accelerations
  • Endstop pin assignments
  • Temperature sensor types
  • Tool configurations

V2 uses INI-style configuration (like Windows config files) instead of V1’s key-value format. See Configuring Smoothie for complete documentation.

 Always unmount, then reset
After editing config, safely eject the SD card, then reset the board. Changes only take effect after reset.

Test everything

  • Motors: Try G0 X10 G0 Y10 etc.
  • Endstops: Try homing with G28
  • Temperature: Check readings (3D printers)
  • Tools: Test heaters/lasers/spindles carefully

Step 5: Calibration (30 mins - 1 hour)

Motors

Measure actual distances vs commanded distances, adjust steps_per_mm in config until accurate.

Acceleration

Start with conservative values, increase gradually until you see problems (ringing, skipping), then back off.

Tools

  • 3D printers: E-steps calibration, PID tuning
  • Lasers: Power calibration, focus
  • CNCs: Feed rates, spindle speeds

Your machine guide has the specifics.

Step 6: First run

Make something simple:

  • 3D printer: Small calibration cube
  • Laser: Simple square
  • CNC: Shallow engraving

Start slow, watch closely, be ready to hit the emergency stop.

If it works: congratulations, you’re done!

If it doesn’t work: see below.

When things go wrong

Board not recognized

  • Windows: Install Windows drivers
  • Try different USB cable
  • Try different USB port
  • Check for LED activity on board

Motors not moving

  • Check wiring
  • Check motor current in config
  • Try simple commands like G0 X10
  • Use M119 to check endstops aren’t triggered

Endstops not working

  • Check wiring and polarity
  • Verify normally-open vs normally-closed in config
  • Test with M119 command

Temperature wrong

  • Check thermistor type in config
  • Verify wiring
  • Look for shorts

For more help, see Troubleshooting.

Getting help

When you’re stuck:

First:

  1. Read the Troubleshooting page
  2. Search this documentation
  3. Check your wiring
  4. Double-check your config file

Then ask the community:

When asking for help, include:

  • Firmware version (run version command)
  • Your config file (use pastebin.com)
  • Photos of your setup
  • Exact error messages
  • What you’ve already tried

What’s next

Must read:

Useful stuff:

Want to help?

Now go make something cool.

This is a wiki! If you'd like to improve this page, you can edit it on GitHub.