Serial2CNC

Setup & operator guide

Serial2CNC

Send CNC program files over TCP or Serial. Run a Docker transfer server with a browser interface, or send directly from a Windows desktop.

Docker & browser

Run one container on an always-on computer and send over TCP/IP from a browser on your trusted network.

Set up the server →

Windows desktop

Install the EXE and send directly over TCP/IP or Serial, with an optional built-in web app for your local network.

Set up the desktop app →
01 / DOCKER SERVER

One container. Browser access.

The Docker server is a single application containing the browser interface and the transfer engine. It sends over TCP/IP only, for example to a USR-W610 converter; no serial devices, Windows services, or certificates are needed.

Docker transfer path A browser connects to the Serial2CNC container over HTTP. The container sends to a USR-W610 over TCP, which forwards to the CNC over serial. Browser Serial2CNC USR-W610 CNC HTTP Docker container TCP Serial
The program folder is a folder on the Docker host, mounted read-only into the container at /programs.

Run with Docker Compose

  1. Point Compose at your program folder. Clone the repository and set CNC_PROGRAMS_DIRECTORY to an existing folder, either in PowerShell or in a .env file next to docker-compose.yml:
    CNC_PROGRAMS_DIRECTORY='C:\CNCPrograms'

    Without it, Compose uses the repository's programs folder.

  2. Start the container.
    docker compose up --build -d
  3. Configure settings. Open http://<docker-host>:62899, expand Settings, set the working directory to /programs, enter the CNC/converter TCP host and port, and review framing and delay. Use an address reachable from the container, not localhost. Settings are kept in the settings volume across upgrades.
  4. Transfer. Select a file (paths are relative to the working directory), put the CNC into receive mode, and start the transfer. Monitor status and logs; use Cancel to stop an active send.

See the Docker guide for .env details, logs, and development mode.

02 / WINDOWS DESKTOP

Send directly from Windows

The WPF desktop application sends over TCP/IP or Serial/COM from your Windows session. It can also host the same browser interface on your local network while it is running.

  1. Install. Download Serial2CNC-<version>-win-x64.exe and its SHA-256 checksum from GitHub Releases and run it. It installs for the current user; administrator rights and a separate .NET runtime are not required.
  2. Launch the app. Open Serial2CNC from the Start menu. Settings are saved per user in %LOCALAPPDATA%\Serial2CNC and kept across restarts and upgrades.
  3. Choose the connection. Select TCP (USR-W610) or Serial / COM. Open Settings to enter the destination or serial parameters, delay between lines, and Okuma framing option.
  4. Select and send a program. Browse to the CNC file, check the program name if using Okuma framing, put the CNC into receive mode, and start the transfer. Keep the app open and monitor progress until it finishes.
  5. Optional: built-in web app. In Settings, choose a port (default 62899) and enable the built-in web application (LAN), then open http://<desktop-computer-name>:62899. It stops when the desktop app closes. The same trusted-network warning applies.

For unreleased builds, download an installer artifact from the Windows EXE workflow (GitHub sign-in required). Installers are unsigned; use trusted builds and compare the SHA-256 hash with the accompanying checksum.

Choose one sender per connection. Avoid sending from the desktop app and the Docker server to the same CNC at the same time. Uninstall older MSI versions before installing the EXE.

03 / CNC CONNECTION

Match the receiving machine

Both interfaces use the same transfer engine. Choose the transport that matches your wiring and the CNC's receive settings.

Connection What to configure
TCP / USR-W610 Enter the converter's reachable IP address and listening TCP port. Configure its serial side to match the CNC. Enable TCP XON/XOFF only when the receiving setup passes these flow-control characters through.
Serial / COM Choose the COM port on the sending computer and match baud rate, parity, data bits, stop bits, and handshake to the CNC. A virtual COM port can also be used when provided by your converter software. Serial is available in the desktop app and its built-in web app, not in Docker.

Files are sent as ASCII, one line at a time, with CRLF (\r\n) line endings. Check the CNC manual for supported program format, cabling, and receive procedure. A completed send is not confirmation that the CNC accepted or validated the program; verify it on the controller before use.

Device reference: USR-W610 serial-to-Wi-Fi/Ethernet converter.

04 / OKUMA FIRST & LAST ROW

What the framing option adds

Enable Okuma OSP7000L framing when the controller expects a program-name header and a closing percent marker. Serial2CNC wraps the file contents with two extra transmitted rows:

Row Sent text Purpose
First $PART01.MIL% Program-name header: a literal $, the resolved program name, then %.
Middle Your file's rows The existing program content, in its original order.
Last % Closing marker after the final file row.

How the program name is chosen

If you enter a program name, it is trimmed and converted to uppercase, then used as entered. Include .MIL yourself if needed; it is not added to a custom name. Leave the name blank to use the filename without its extension, followed by .MIL, in uppercase. For example, part01.nc becomes PART01.MIL.

$PART01.MIL%
G01 X10 Z-5
M02
%
Example transmitted payload for part01.nc containing two rows, with framing enabled and the program name left blank. Illustrative only, not a machining program.

Framing adds rows; it does not replace them. The source file is not modified. Existing headers or trailing % rows are not detected or removed, so enabling framing on an already framed file creates duplicate markers. Disable framing if the file already contains the required wrapper or if your controller uses a different format.

With framing disabled, only the file's rows are sent; the program-name field has no effect. ASCII encoding and CRLF line endings still apply.

05 / TRANSFER DELAY

A pause between lines, not characters

Delay between lines (ms) adds a fixed wait after sending each row, before sending the next one. It applies to TCP and Serial, including the Okuma header and closing marker when framing is enabled.

Send row 1→ 100 ms →Send row 2→ 100 ms →Last row
  • 0 ms: no extra software pause. Transfer speed still depends on the connection, serial baud rate, and flow control.
  • 100 ms: adds a tenth of a second between rows. There is no delay before the first row or after the final row.
  • Timing example: 102 transmitted rows (100 file rows plus 2 framing rows) have 101 gaps. At 100 ms, that adds about 10.1 seconds, on top of connection time, transmission time, and any flow-control waits.

A delay can give a slower controller time to process incoming lines. Use the machine's recommended value and increase it if the receiver loses data. It does not change baud rate, pace individual characters, or replace the correct handshake settings.

Delay and flow control do different jobs. A delay always waits the configured interval between rows. TCP XON/XOFF additionally pauses before sending a line after XOFF and resumes after XON; Serial uses the selected handshake mode. Either can make a transfer take longer than the delay calculation alone.

With Okuma framing enabled, the program-name header is always followed by a pause of at least 500 ms (or the line delay, if longer) so the controller can create the program. If the program already exists, the controller asks whether to overwrite it and sends XOFF; with XON/XOFF enabled, sending stays paused until the operator answers and the controller sends XON.