150 lines
5.8 KiB
Markdown
150 lines
5.8 KiB
Markdown
# 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!
|