vision-alignment/Development.md

Developing and Simulating on Linux

When developing custom CNC plugins—especially those manipulating Work Coordinate Systems (WCS)—testing on physical hardware can result in dangerous and costly crashes.

Fortunately, FluidNC provides a native PC port that can run directly on Linux. By pairing your local instance of gSender Edge with this virtual controller, you can rapidly test UI changes, G-code injection, and coordinate transformations in a 100% safe environment.

Prerequisites

Ensure your Linux environment has the required build tools and dependencies. You will need Git, Python, socat (for the virtual serial cable), and picocom (for testing). To compile gSender locally, you will also need the C++ build chain, curl, and some specific UI libraries.

sudo apt-get update
sudo apt-get install git python3 python3-venv socat picocom build-essential libudev-dev libgtk-3-dev curl

---

Step 1: Set Up PlatformIO and Compile FluidNC

FluidNC uses PlatformIO for its build system. Before compiling, you need to create a Python virtual environment and install the PlatformIO CLI.

# Create and activate a Python virtual environment
python3 -m venv pio_env
source pio_env/bin/activate

# Install PlatformIO
pip install platformio

With PlatformIO active, clone the FluidNC repository and compile the native Linux 64-bit simulator.

git clone https://github.com/bdring/FluidNC.git
cd FluidNC
pio run -e linux_x86_64

(This will download the necessary toolchains and output the compiled program to ./.pio/build/linux_x86_64/program)

Step 2: Initialize Virtual Filesystem & Configuration

The Linux simulator expects a local folder named native_localfs to act as flash storage. Create the folder and copy in the standard test-drive configuration:

# From the root of the FluidNC directory:
mkdir native_localfs
cp ./FluidNC/data/config.yaml ./native_localfs/

---

Step 3: Connect gSender (Choose Method A or B)

You can connect gSender to the simulator using either a Virtual Serial Port or a local Network Socket (Ethernet). The Ethernet method is faster, but the Serial method (see Method B) mimics physical hardware more closely.

Method A: The Ethernet Shortcut (Recommended)

FluidNC natively simulates the ESP32's network stack by opening a Telnet server on port 23.

1. Grant the simulator permission to bind to privileged network ports:

   sudo setcap 'cap_net_bind_service=+ep' ./.pio/build/linux_x86_64/program
   

2. Run the simulator normally:

   ./.pio/build/linux_x86_64/program
   

3. In gSender, select the Ethernet connection option and connect to 127.0.0.1 on port 23.
4. WAKE THE GUI: Because Telnet connections do not trigger a hardware reset, FluidNC will not automatically send its welcome string, leaving gSender's UI disabled. Open the Console tab in gSender, type ?, and press Enter. The controller will respond, and the UI will unlock into the Idle state.

---

Method B: Virtual Serial Port (socat)

If you need to test standard serial behavior, use socat to create a virtual null-modem cable. We name the gSender side ttyCNC to trick gSender's strict hardware filters into listing the port.

1. Open Terminal A and create the virtual cable:

   sudo socat -d -d \
     pty,link=/dev/ttyCNC,raw,echo=0,b115200,mode=666 \
     pty,link=/dev/ttyVIRT,raw,echo=0,b115200,mode=666
   

2. Open Terminal B and run the simulator, piping its input/output directly into the virtual cable:

   ./.pio/build/linux_x86_64/program < /dev/ttyVIRT > /dev/ttyVIRT
   

   (Note: This terminal will appear to freeze. This is correct! All output is being routed into the virtual cable.)
3. Add ports section into ~/.sender_rc. It should look like this:

{
  "ports": [
    {
      "path": "/dev/ttyCNC",
      "manufacturer": "Virtual CNC",
      "vendorId": "0403",
      "productId": "6001"
    }
  ],
  "events": {},
  // other definitions
}

4. Open gSender, select Serial, choose ttyCNC from the Ports list, (make sure the baudrate is set to 115200 in the Config->Basic->Baud rate), and click Connect.

---

Step 4: Test Your Plugin

Your fully functional virtual CNC machine is now running!

---

Step 5: Run gSender for Development

If you're actively developing custom CNC plugins or modifying gSender's UI, it is highly recommended to run gSender from its source code. This enables hot-reloading for faster iteration. The following instructions are adapted from the official Sienci Compile gSender guide.

1. Install Node.js and Yarn

gSender is a Node.js/Electron application. We will use Node Version Manager (NVM) to install the necessary Node.js version.

# Install Node Version Manager (NVM)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source "$HOME/.nvm/nvm.sh"

# Install Node.js (v24.x is currently recommended)
nvm install 24

# Enable Yarn package manager
corepack enable yarn

2. Clone gSender and Install Dependencies

# Clone the gSender repository
git clone https://github.com/Sienci-Labs/gsender.git
cd gsender

# Install all required packages (this may take some time to compile native modules)
yarn install

3. Launch Development Mode

To start gSender in development mode with hot-reloading enabled:

yarn dev

(This launches the local development server. You can open gSender in your browser at http://localhost:8000, or via the automatically launched Electron window. Any changes you make to the source code will automatically reload.)

Once running, you can connect this development instance of gSender directly to your FluidNC simulator using either the Ethernet or Virtual Serial method outlined in Step 3!