Network Interface
Smoothieboard has an RJ45 connector, which can be used to connect the board to your local Ethernet network and communicate with it over TCP/IP.
This works similarly to how you would access your 2D printer or other network devices.
Settings
Smoothie supports Ethernet access, which must be enabled in the configuration file.
To enable the network, set true.
The IP address can be set statically or set to use DHCP.
However, due to buffer size limitations, some DHCP servers are not supported.
Here is an example of a setup using DHCP (meaning that the router automatically assigns an IP address to the Smoothieboard):
V1 Configuration (flat namespace):
# network settings
network.enable true # enable the ethernet network services
network.webserver.enable false # enable the webserver
network.telnet.enable false # enable the telnet server
network.plan9.enable true # enable the plan9 network filesystem
network.ip_address auto # use dhcp to get ip address
V2 Configuration (INI sections):
[network]
enable = true # enable the ethernet network services
webserver_enable = false # enable the webserver
shell_enable = false # enable the telnet server (renamed from telnet.enable)
ftp_enable = false # enable standard FTP on port 21
ntp_enable = true # set the real-time clock from NTP at network startup
ip_address = auto # use dhcp to get ip address
And an example of how to set up with a static IP:
V1 Configuration (flat namespace):
# network settings
network.enable true # enable the ethernet network services
network.webserver.enable false # enable the webserver
network.telnet.enable false # enable the telnet server
network.plan9.enable true # enable the plan9 network filesystem
network.ip_address 192.168.3.222 # the IP address
network.ip_mask 255.255.255.0 # the ip mask
network.ip_gateway 192.168.3.1 # the gateway address
V2 Configuration (INI sections):
[network]
enable = true # enable the ethernet network services
webserver_enable = false # enable the webserver
shell_enable = false # enable the telnet server (renamed from telnet.enable)
ftp_enable = false # enable standard FTP on port 21
ntp_enable = true # set the real-time clock from NTP at network startup
ip_address = 192.168.3.222 # the IP address
ip_mask = 255.255.255.0 # the ip mask
ip_gateway = 192.168.3.1 # the gateway address
The basic network configuration options appear in the V1 configuration sample and the V2 CNC sample.
If your configuration file does not contain the network section, it probably means the version of Smoothie that shipped with your board is too old.
You need to use the latest edge firmware and use the latest configuration file.
See Flashing Smoothie Firmware and Configuring Smoothie.
All Options
| Option | Example Value | Explanation | | —— | ————- | ———– |
| V1 Setting | V2 Setting | Description |
|---|---|---|
|
Master enable switch for the entire Ethernet network functionality. When disabled, the network module is completely unloaded to free system resources (approximately 8KB RAM). Must be set to |
||
|
If set to The service itself does not provide authentication or encryption. Restrict it to a trusted network. |
||
|
If set to The protocol is unencrypted and has no authentication. Use it only on a trusted network. |
||
|
If set to Provides direct filesystem access similar to NFS or SMB. |
||
|
Configures the IP address assignment method for the Smoothieboard. Set to When using a static IP, you must also configure |
||
|
Defines the subnet mask for static IP configuration — the netmask determines which portion of the IP address identifies the network and which portion identifies the host. Only used when With DHCP, this setting is ignored and the subnet mask is provided automatically by the DHCP server. |
||
|
Specifies the default gateway (router) IP address for static IP configuration — used for routing traffic outside the local network. Only used when With DHCP, the gateway is provided automatically by the DHCP server. |
||
|
Allows manual override of the Ethernet MAC (Media Access Control) address. By default, Smoothieboard auto-generates a unique MAC address based on the CPU's serial number, using a cryptographic hash. Only set this if you experience MAC address conflicts on your network, or need to preserve a specific MAC address after hardware replacement. |
||
|
Sets a hostname that is sent to the DHCP server during IP address requests. Some DHCP servers register this hostname in local DNS, letting you access the Smoothieboard by name (e.g., Only used when |
||
|
Uses the DHCP-provided DNS server when set to DNS is required when |
||
|
Enables the Smoothieware V2 FTP server on TCP port 21. This is unencrypted standard FTP. It is neither SFTP nor the V1 Simple File Transfer Protocol service on port 115. |
||
|
Requests the time from an NTP server when the V2 network starts and writes it to the real-time clock. The network and DNS configuration must work before hostname-based NTP servers can resolve. |
||
|
Sets the hostname of the NTP server used by Smoothieware V2. |
||
|
Applies a fixed integer offset in hours to the NTP result before setting the V2 real-time clock. It does not implement daylight-saving rules or fractional-hour time zones. Use zero to keep the clock on UTC. |
Wiring
To access your Smoothieboard, you need to connect it to your network by plugging an Ethernet cable into the Smoothieboard at one end and into your Ethernet router at the other end.
Please note that you can’t connect a Smoothieboard directly to your computer unless you use a special type of cable and configuration on your computer.
You want to use a router for this.
Once configured and plugged in, reset the Smoothieboard and wait for it to connect to the network.
Accessing Smoothie
To access Smoothie over the network, you first need to know its IP address. If you are not sure what IP address Smoothie has been assigned, you can use one of the following methods:
- If you have a panel connected to the Smoothieboard, the panel should display the IP address.
- If you have access to your network’s main router’s administration interface, it should tell you the IP address of all peripherals connected to it.
- If you are connected to the board via USB, you can use a program like Pronterface to send the
@netcommand, which gives you the current IP address. - If you are running Linux, you can use a command like
nmap -sn 192.168.0.0/24to find all accessible peripherals on the network. - NOTE: If the IP address shows
173.222.239.190, then it means that DHCP did not get an IP address assigned. (Try a static IP instead).
V2 network services
Smoothieware V2 uses the FreeRTOS+TCP stack and controls each service from [network]:
[network]
enable = true
shell_enable = true
ftp_enable = true
webserver_enable = true
ntp_enable = true
ntp_server = pool.ntp.org
timezone = 1
ip_address = auto
dns_server = auto
| Service | Port | Setting | Purpose |
|---|---|---|---|
| Network shell | TCP 23 | shell_enable |
Run G-code and console commands over a raw terminal connection |
| FTP | TCP 21 | ftp_enable |
Transfer files with an FTP client such as FileZilla |
| HTTP and WebSocket | TCP 80 | webserver_enable |
Serve files from /sd/www and provide WebSocket command and upload endpoints |
| NTP client | UDP 123 outbound | ntp_enable |
Set the real-time clock from ntp_server when the network starts |
These services provide no encryption. Keep the board on a trusted machine network and do not expose its ports to the public Internet.
V2 network shell
The shell listens on TCP port 23 and accepts the same G-code and console commands as a serial console. Connect with a Telnet or raw TCP client:
telnet ip_of_smoothie 23
The server accepts up to three shell clients. It behaves like a command stream, not a full Unix login shell.
V2 FTP server
Enable ftp_enable and connect an FTP client to port 21. This is standard FTP, not SFTP and not V1’s Simple File Transfer Protocol on port 115. FTP sends commands and file data without encryption.
V2 HTTP and WebSocket server
The HTTP server serves /sd/www/index.html at / and other files relative to /sd/www. It accepts WebSocket upgrades on two paths:
| WebSocket path | Purpose |
|---|---|
/command |
Send command lines and receive their output |
/upload |
Upload a named file using the V2 web interface protocol |
The current WebSocket implementation requires each incoming frame to set the FIN bit; fragmented messages are rejected. The command receive buffer is 132 bytes and the upload receive buffer is 1024 bytes, so clients must split their application data into complete frames that fit those buffers.
V2 NTP clock setup
With ntp_enable = true, Smoothie resolves ntp_server, sends one request when the network starts, applies the integer timezone offset in hours, and sets the real-time clock. The default server is pool.ntp.org and the default timezone is 0.
The timezone setting does not apply daylight-saving rules or half-hour offsets. Set it to the required fixed UTC offset and update it when local civil time changes, or keep the clock on UTC with timezone = 0. The ntp console command requests another synchronization.
V1 network services
Smoothieware V1 provides a different network stack and service set:
- Telnet (port 23) to run commands, stream G-code to Smoothie, or connect from Pronterface (see below)
- HTTP web server (port 80) allows control from your web browser
- Simple File Transfer Protocol (port 115) allows uploading files with a compatible client. It is not SSH File Transfer Protocol.
- (NOT SUPPORTED needs to be enabled and compiled) Plan9 (9P/Styx) (port 564) provides remote access to the file system from compatible clients (typically Linux)
V1 Telnet (port 23)
You can use a terminal to connect to your board via telnet by typing in a terminal:
telnet ip_of_smoothie:23
Pronterface can also connect to Smoothie over the network by using telnet - just enter ip_of_smoothie:23 instead of the serial port before clicking ‘Connect’. Where ip_of_smoothie is the IP address of your Smoothie. You must check the box under Settings Menu that says TCP streaming mode.
Raw telnet provides console access to run console commands or G-code, useful network commands here are net and netstat. See the smoothie-stream.py example for streaming.
V1 Web Server (port 80)
You can access the default user interface by going to this address in your web browser:
http://ip_of_smoothie/
Custom web pages can be accessed from the SD card, for example:
http://ip_of_smoothie/sd/webif/index.html
The web interface allows you to control the machine over the network
V1 Simple File Transfer Protocol (port 115)
Note: Simple File Transfer Protocol (NOT secure file transfer!) allows uploading of files. See the smoothie-upload.py example.
V1 Plan9 Network Filesystem (port 564)
NOTE: Plan9 is not built into Smoothie by default. To include it, rebuild Smoothie with make PLAN9=1. See Compiling Smoothie.
The Plan9 network file system can be used on Linux to directly mount the Smoothieboard over the network. First, activate the option
mount -t 9p 192.168.2.120 -o dfltuid=1000,dfltgid=1000 /mnt/smoothie
Now you can access the SD card of the Smoothieboard like a normal filesystem!
The dfltuid/dfltgid are the uid/gid of the user which owns the files in the mount. It is recommended to set these to the uid/gid of the user who will write to the filesystem.
If you want, you can also add the filesystem to your /etc/fstab as follows:
# /etc/fstab
# <file system> <mount point> <type> <options> <dump> <pass>
... your other stuff ...
192.168.1.6 /mnt/smoothie 9p user,noauto,dfltuid=1000,dfltgid=1000 0 0
Using a Hosts File
If IP addresses are getting you down, you can address your Smoothie by name if you add a line to your computer’s hosts file. For example, assuming your Smoothie’s address is 192.168.2.120, you could add:
192.168.2.120 smoothie
And then simply use smoothie:23 in the Port field of Pronterface, and simply http://smoothie in your web browser.
This only works from the computer you edit the hosts file on and requires Smoothie to have a constant IP address, either through configuring Smoothie as a static IP or by configuring your DHCP server to always assign Smoothie the same IP address.
Hardware Requirements
To use the network capabilities of the Smoothieboard (4X and 5X, note the 3X board does not have Ethernet capabilities), an RJ45 Magnetic Modular Jacks aka RJ45 network transformer like the Hanrun HR911105A needs to be soldered onto the board.
They are available from various electronics suppliers (search for “HR911105A” or “RJ45 magnetic modular jack”).
Hostname
You can configure a hostname for the DHCP server as such:
V1 Configuration:
network.ip_address auto # use dhcp to get IP address
network.hostname smoothie1 # optionally set this hostname for dhcp
V2 Configuration:
[network]
ip_address = auto # use dhcp to get IP address
hostname = smoothie1 # optionally set this hostname for dhcp
Note the
Net Command
If your network interface doesn’t work as it should, you can get some debugging information (such as the current IP) by sending the net command (@net from Pronterface) via the console (USB or UART).
IP Addr: 192.168.1.100
IP GW: 192.168.1.254
IP mask: 255.255.255.0
MAC Address: 00:1F:11:02:04:C9
V1 HTTP API
Creating a custom interface, a script that talks to a Smoothieboard, or helping with Smoothie’s web interface (please do!)?
Here’s the API you can expect the board to answer to over HTTP.
GET /sd/file
Retrieves the content of a file from the SD card. You can use this to retrieve the configuration file, but make sure to try both “/sd/config” and “/sd/config.txt” as both are valid filenames.
GET /query
Returns the same as the “?” command over serial, or the “get status” command over any interface.
Example output:
<Idle|MPos:-700.0000,0.0000,360.0000,0.0000|WPos:-700.0000,0.0000,360.0000|F:4000.0000|T:163.5,0.0|B:178.4,0.0>
Much faster than sending “get status” using /command.
POST /command
Parameter: The command you want to execute as the POST data/parameter.
Returns: Whatever the command returned.
POST /command_silent
Parameter: The command you want to execute as the POST data/parameter.
Returns: Nothing. Faster than /command, prefer whenever possible.