# 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.

```bash
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.

```bash
# 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.

```bash
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:

```bash
# 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:
   ```bash
   sudo setcap 'cap_net_bind_service=+ep' ./.pio/build/linux_x86_64/program
   ```
2. Run the simulator normally:
   ```bash
   ./.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:
   ```bash
   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:
   ```bash
   ./.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:
```json
{
  "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](https://resources.sienci.com/view/gs-compile/).

### 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.

```bash
# 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
```bash
# 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:
```bash
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!