bCNC for GRBL and grblHAL: Installation, Configuration, and Limits

bCNC's Role at the GRBL Controller Boundary

bCNC addresses the operator-side gap between preparing a CNC program and commanding a GRBL-compatible controller. It combines a G-code sender and editor with autoleveling, digitizing, CAM functions, and controller configuration. The intended audience is therefore broader than someone who only needs a terminal for jogging axes. It is aimed at owners of GRBL or grblHAL machines who work on Windows, Linux, or macOS and prefer a Python application that can also be run from a source checkout.

The documented controller boundary matters. bCNC is not itself a CNC firmware package and does not replace the GRBL configuration stored by the controller. The README specifically discusses GRBL settings such as `$10` for reported position mode and `$13` for work units. Firmware, CAD settings, and bCNC must agree on coordinates and units. A G-code editor that opens a file successfully can still send unsafe or incorrect motion if those surrounding settings are wrong.

The project also targets older or slower hardware, including Raspberry Pi systems. That goal does not turn bCNC into a general-purpose CNC controller. Its documented scope is tied to GRBL and grblHAL, and the README describes original GRBL as reaching the end of its life because of limitations in 8-bit microcontrollers. Newer machine builds are advised to use a 32-bit controller with FluidNC, while grblHAL remains the named focus for the sender.

Installing bCNC Through pip and Launching the GUI

The README recommends installation with pip. The setup file requires Python 3.8 or newer, so the interpreter must satisfy that requirement before the package can be installed. The documented package command installs or upgrades bCNC together with its declared dependencies.

python -m pip install --upgrade bCNC

The package includes a console entry point named `bCNC`, but the README gives module execution as the launch method:

python -m bCNC

That command opens the graphical application when Tkinter is available. The README warns that pip may not install Tkinter in some cases. On Linux, the required package may be named `tkinter`, `python3-tkinter`, or `python-tk`, depending on the Python and operating system installation.

A first session should not begin with an untested production program. Connect the controller, confirm its settings, inspect the configuration page, and use the editor to load a known G-code file before sending work. The README does not document a separate connection command, a controller port flag, or a headless startup mode, so connection and machine operation remain interactive GUI actions.

Source Install and Windows Executable Choices

For development, the README gives an alternative that installs the current checkout rather than the PyPI release:

pip install .

The launch command remains:

python -m bCNC

When this command is run from the repository root, the README says it launches the Git version. It also says developers should use this method to ensure their code works after packaging. The repository contains `bCNC.py`, the `bCNC/` package directory, `setup.py`, and platform launcher files such as `bCNC.bat` and `bCNC.sh`, so a source checkout is the appropriate starting point when the code itself is being changed.

Windows users can build a single executable with PyInstaller. The documented command includes the project icon and imports from `lib;plugins;controllers`.

pip install pyinstaller
pyinstaller --onefile --distpath . --hidden-import tkinter --paths lib;plugins;controllers --icon bCNC.ico --name bCNC __main__.py

The README says this creates `bCNC.exe` and leaves a large `build` directory for caching. That directory should be deleted before redistribution. It also cautions that precompiled executables on the releases page may not be current. Users who need a particular source revision should therefore distinguish an executable built locally from an older release artifact.

Controller Settings That Can Prevent a Safe First Job

bCNC exposes most controller parameters through the `CAM -> Config/Controller` page. Changes are stored as differences from the default configuration in `${HOME}/.bCNC` or `~/.bCNC`. The default configuration is `bCNC.ini` in the installation directory. The README explicitly warns not to edit that installation file because upgrades overwrite it.

For GRBL, the README says to use `MPos` rather than `Wpos`, with `$10` set to an odd number. It recommends `$10=3` for GRBL 1.1 and gives `$10=1` as a failsafe value if communication problems occur. The README also says to set `$13=0` when CAD, bCNC, and GRBL should use millimeters by default.

These are controller settings, not bCNC command-line flags. They must be entered according to the controller's own interface or supported serial workflow. If the CAD and bCNC configuration uses inches instead, the unit choice must be reconciled rather than copied blindly.

The README also points out that grblHAL has compatibility-level settings established during firmware compilation. Those settings cannot be corrected by editing a bCNC preference alone. A connection problem may therefore originate in firmware configuration, not in the sender. The first check should be the controller's actual settings and its official GRBL or grblHAL documentation.

G-code, Autoleveling, and Optional Media Dependencies

The project combines G-code editing with autoleveling, digitizing, CAM, and related CNC operations. The optional dependencies show where the feature surface extends beyond basic controller communication. PIL libraries are used for the autolevel height map, OpenCV is used for webcam streaming on the web pendant, and SciPy is described as enabling faster 3D mesh slicing.

The setup file declares `numpy>=1.12`, `svgelements>=1,<2`, `shxparser>=0.0.2`, `Pillow>=4.0`, and `tkinter-gl>=1.0`. On macOS it also declares `pyobjc`, `pyobjc-core`, and `pyobjc-framework-Quartz`. On non-ARM platforms it declares `opencv-python==4.5.5.64`; the setup comment explains that no PyPI OpenCV packages are available for ARM, including Raspberry Pi and Orange Pi systems.

That packaging decision has consequences. A Raspberry Pi installation may need the application and its available dependencies assembled differently from a standard desktop installation. A desktop installation may fail early if Tkinter is missing, while optional capabilities may fail only when the related feature is opened. The README does not document a feature-by-feature dependency check or a rollback procedure. A successful launcher therefore does not prove that every optional workflow is available on every platform.

The README also warns that macOS appears broken in the new release work and asks macOS users to contact the project through issue 591. A platform being listed as supported is not the same as a currently validated installation.

GRBL Senders Versus Broader CNC Workflows

bCNC should be compared by controller scope rather than by the number of controls in its interface. It is designed to work with GRBL and grblHAL, including configuration of a connected controller. A full CAM package may generate toolpaths and manage machining operations, while bCNC's documented identity centers on sending and handling G-code for a compatible controller. The README's references to CAM and digitizing do not provide enough detail to claim parity with a separately documented CAM product.

A practical distinction is packaging. bCNC is primarily a Python application with a GUI and declared platform-specific dependencies. It can be built as `bCNC.exe`, but the README warns that release executables may be stale and recommends checking direct Python execution before reporting an executable-specific bug. A native controller interface distributed for one operating system may simplify packaging for that environment, although the available documentation does not identify a specific alternative product or establish its feature set.

The closer practical comparison is between bCNC and a basic GRBL terminal. A terminal can expose controller communication, while bCNC adds editing, autoleveling, digitizing, CAM, and configuration pages. The tradeoff is dependency and platform exposure: bCNC offers more operator functions, but Tkinter, Python package compatibility, firmware settings, and the macOS warning become part of the installation decision. The README's recommendation to use FluidNC on a 32-bit controller for new builds is a separate firmware choice from selecting bCNC as the sender.

Maintenance, Releases, and Upgrade Cost

The repository is not archived. Its last push was on 2026-04-15. The available release history is older and mixed: a PyPI release dated 2025-03-27, an initial `.exe` build dated 2018-11-21, and `0.9.11` dated 2017-10-02. The setup file reports version `0.9.16`, while the release list does not establish that this version was published through PyPI. Repository activity and package release freshness should therefore be checked separately.

Upgrading through pip is the least ambiguous documented route because the README explicitly says it installs or upgrades bCNC along with required packages. A local Git install is useful when testing source changes, but it places dependency and packaging responsibility on the development environment. A Windows executable build introduces PyInstaller, cached build output, and the need to check whether a bug also occurs without the executable wrapper.

The license is `GPL-2.0` according to the repository description, while the repository also contains `LICENSE.BSD3` and `LICENSE.MIT`. The setup metadata identifies `GPLv2`. The exact obligations for a particular distribution or modification require reviewing the applicable license text. bCNC is distributed under GPLv2 metadata, and the README does not state a separate commercial support policy or a compatibility promise for third-party firmware and hardware.

Editorial conclusion

Adopt bCNC when the machine uses GRBL or grblHAL, the operator wants a Python-based desktop sender, and the controller can be configured consistently with bCNC. Do not select it for a macOS installation that must work without further investigation, or when a machine cannot be aligned with the documented MPos and unit requirements. Check Python 3.8 or newer, Tkinter availability, controller firmware settings, and the `CAM -> Config/Controller` page before loading production G-code.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. vlachoudis/bCNC on GitHub