first commit
This commit is contained in:
+149
@@ -0,0 +1,149 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user