Candle: a GRBL host with a G-code visualizer, and the GRBL versions it tracks

A host for GRBL machines, not a CNC controller

Candle is a GRBL controller application with a G-code visualizer written in Qt. The scope is narrow and deliberate: it is a host application for a machine that already runs GRBL firmware, and it does not do motion planning, toolpath calculation or machine design.

The supported functions are listed in the project documentation and they map onto the four things an operator does with such a machine. The first is controlling a GRBL based CNC machine via console commands, buttons on a form, and the numpad. The second is monitoring the machine state. The third is loading, editing, saving and sending G-code files to the machine. The fourth is visualising G-code files, which is where the G-code visualizer in the project's name comes from, along with the heightmap feature named in the repository topics.

The audience is therefore the owner of a GRBL machine: a hobbyist with a desktop router, a laser cutter on a self-built frame, a small CNC mill, or someone who has converted a commercial machine to GRBL. The person running it is often also the person who wrote the G-code, so the editing and visualisation features carry as much weight as the sending.

The project is written in C++ with Qt, licensed GPL-3.0, and the last push to the repository was on 2026-08-29.

Sending G-code is the easy part, seeing it is the point

The interesting part of Candle is not the transport. GRBL is spoken to over a serial console, and Candle can drive that connection from a console window, from form buttons or from the numpad, so an operator can jog the machine, run a cycle or send a program without touching the machine itself.

The interesting part is what happens before the send. The G-code visualizer renders the file so you can see the toolpath before it reaches the motors, and the heightmap topic in the repository suggests the visualisation includes surface information rather than only a flat drawing. For a machine where a wrong move can snap a bit, seeing the path is worth more than a faster send.

The editing part sits in the same loop. Files can be loaded, edited, saved and sent, so a job can be tweaked at the machine rather than regenerated on the computer, which is a normal workflow for small batch work where the tool changes between runs.

Monitoring is the third leg, and it exists because a GRBL machine has state that the operator needs to see, such as what it is doing now and whether it is in an alarm condition. The documentation lists it as a separate supported function, which is a hint that it is treated as a first class part of the application rather than a logging side effect.

Taken together, the three features answer a question the console-only workflow cannot: what is this file going to do to my machine, and what is the machine doing right now.

Three sets of downloads, split by GRBL firmware version

The download section is arranged by firmware version, and that is the first thing to understand.

There are the latest release versions, linked from the GitHub releases page, and there is a nightly build, published under the `nightly` tag, with a separate workflow badge for Windows x64. The release history lists tags for a nightly build, for version 11.2 and for version 10.12, so the project publishes both stable releases and a moving nightly channel.

Below that sit the previous versions, and here the split is by GRBL firmware rather than by Candle version alone. For GRBL v1.1 firmware there is a Windows zip and a Linux tar.gz, both at 1.1.7. For GRBL v0.9 and below there is a Windows zip and a Linux tar.gz, both at 1.0.11.

That organisation is a practical warning. GRBL changed significantly between v0.9 and v1.1, and a Candle build that speaks the right protocol for one is not automatically right for the other. Before you download, check which firmware your controller board is running, because the two archive sets are not interchangeable.

The system requirements are modest but specific: Windows, Linux on Ubuntu, macOS, or Raspberry Pi OS Trixie, a CPU with SSE2 instruction set support, a graphics card with OpenGL 2.0 support, and 120 MB of free storage space.

Building on Ubuntu, Raspberry Pi OS or Fedora with Qt5

The Linux build instructions are the most complete in the project documentation, covering Ubuntu, Raspberry Pi OS Trixie and Fedora 43. On Ubuntu and Raspberry Pi OS Trixie the packages come from apt:

sudo apt update
sudo apt install cmake build-essential qtbase5-dev libqt5serialport5-dev qtscript5-dev qttools5-dev libqt5websockets5-dev qtmultimedia5-dev

The package list tells you what Candle is actually made of. The serial port module is the link to GRBL, Qt Script is the scripting layer for the console, Qt WebSockets covers the network and remote control side, and Qt Multimedia covers camera and video preview, which is what a camera-equipped CNC wants for alignment.

Fedora uses dnf, with the equivalent package set:

sudo dnf update
sudo dnf group install development-tools
sudo dnf install cmake qt5-qtbase-devel qt5-qtserialport-devel qt5-qtscript-devel qt5-qttools-static qt5-qttools-devel qt5-qtwebsockets-devel qt5-qtmultimedia-devel

Then the source is fetched and built with CMake:

git clone https://github.com/Denvi/Candle.git
cd Candle

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX="~/programs/Candle"
cmake --build . --config=Release
cmake --install .

The executable ends up in the `~/programs/Candle` directory. Note that the dependency set is Qt 5, which is worth checking against your distribution before you start.

The Windows build goes through vcpkg

Windows is built on the vcpkg toolchain rather than a system package manager, and the instructions make that explicit.

You install cmake and vcpkg, and bootstrap vcpkg from its own repository:

git clone https://github.com/microsoft/vcpkg.git
vcpkg\bootstrap-vcpkg.bat

The dependency set is then declared in `vcpkg.json` and `vcpkg-configuration.json` at the repository root, and installed with:

vcpkg install

CMake has to be told where vcpkg is, through an environment variable:

CMAKE_TOOLCHAIN_FILE={PATH_TO_VCPKG}/scripts/buildsystems/vcpkg.cmake

Without that variable, CMake will not find the vcpkg-provided packages, and the build will fail on missing dependencies rather than on anything Candle specific. That is the single most common way this build goes wrong.

The build itself uses the same CMake sequence as the Linux instructions, with a Windows style install prefix:

mkdir build; cd build
cmake .. -DCMAKE_INSTALL_PREFIX="$(pwd)/Candle"
cmake --build . --config=Release
cmake --install .

and the executable lands in the `build/Candle` directory. The repository also carries `CMakePresets.json`, so the configuration is preset-driven for anyone who prefers that to passing flags by hand, and the `src/`, `triplets/`, `deploy/`, `help/` and `wiki/` directories cover the sources, the vcpkg triplets, packaging, the built in help and the documentation.

Where Candle is the wrong tool

The boundaries are clear and they are not going to move.

The first is firmware. Candle speaks to GRBL, and the project says so plainly before you open an issue: it works with CNC controlled by GRBL firmware, and many problems can be solved by using the proper version of GRBL and the proper configuration. The documentation points at the GRBL wiki for v0.9 and earlier and at the gnea fork wiki for v1.1, and asks you to read them before creating an issue. That is a reasonable stance and it also tells you where the project draws its line. A machine running LinuxCNC, Mach, or a proprietary controller is out of scope entirely.

The second is what Candle does not do for you. It is a host, not a CAM system, so it will not generate the toolpath. It will not do workholding maths, it will not manage a job queue across several machines, and it will not replace a proper CAM tool for anything complex. The G-code visualizer shows you what a file will do, which is a different job from producing the file.

The third limit is the Qt 5 dependency. The Linux instructions install qtbase5-dev and the Qt 5 modules, and the OpenGL 2.0 requirement means the application needs a reasonably capable graphics stack. On a headless server or a very old machine that is a real constraint, and a Raspberry Pi works but is listed only for the Trixie release.

The last point is about the licensing and the release rhythm. GPL-3.0 means a distributed modified build carries the same obligations, which for a personal tool is not a burden and for a commercial product is a question to settle. And the release tags are irregular, with a nightly tag, a 11.2 release and a 10.12 release appearing in the history, so if you need a specific version for a machine that must keep working, download and keep the archive rather than tracking the nightly channel.

Editorial conclusion

Candle fits a hobbyist or small shop running a GRBL controlled router, laser or mill that wants a graphical host with a G-code visualizer, and it fits a team that needs to load, edit and send G-code over a serial console without writing their own controller software. It does not fit a machine running firmware other than GRBL, and it is the wrong tool for a CNC that needs more than GRBL offers, since the project itself points users to the GRBL wiki for configuration problems. Before you download a build, pick the one that matches your firmware, since separate archives exist for GRBL v1.1 and for GRBL v0.9 and below, and check the GRBL wiki for your version before opening an issue.

Frequently asked questions

Official sources

1. Denvi/Candle on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases