Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
S

serial-port-json-server

> 编程语言
Open source

A serial port JSON websocket server for Windows, Mac, Linux, Raspberry Pi, or BeagleBone Black that lets you communicate with your serial port from a web applic

361 stars0 likes1 views
WebsiteGitHub

About

A serial port JSON websocket server for Windows, Mac, Linux, Raspberry Pi, or BeagleBone Black that lets you communicate with your serial port from a web applic

Main location for this repo has been moved to https://github.com/chilipeppr/serial-port-json-server

serial-port-json-server

Version 1.87 (See https://github.com/chilipeppr/serial-port-json-server for latest version 1.88+)

A serial port JSON websocket & web server that runs from the command line on Windows, Mac, Linux, Raspberry Pi, or Beagle Bone that lets you communicate with your serial port from a web application. This enables web apps to be written that can communicate with your local serial device such as an Arduino, CNC controller, or any device that communicates over the serial port. Since version 1.82 you can now also program your Arduino by uploading a hex file.

The app is written in Go. It has an embedded web server and websocket server. The server runs on the standard port of localhost:8989. You can connect to it locally with your browser to interact by visiting http://localhost:8989. The websocket is technically running at ws://localhost/ws. You can of course connect to your websocket from any other computer to bind in remotely. For example, just connect to ws://192.168.1.10/ws if you are on a remote host where 192.168.1.10 is your devices actual IP address.

The app is one executable with everything you need and is available ready-to-go for every major platform. It is a multi-threaded app that uses all of the cool techniques available in Go including extensive use of channels (threads) to create a super-responsive app.

If you are a web developer and want to write a web application that connects to somebody's local or remote serial port server, then you simply need to create a websocket connection to the localhost or remote host and you will be directly interacting with that user's serial port.

For example, if you wanted to create a Gcode Sender web app to enable people to send 3D print or milling commands from your site, this would be a perfect use case. Or if you've created an oscilloscope web app that connects to an Arduino, it would be another great use case. Finally you can write web apps that interact with a user's local hardware.

Thanks go to gary.burd.info for the websocket example in Go. Thanks also go to tarm/goserial for the serial port base implementation. Thanks go to Jarret Luft at well for building the Grbl buffer and helping on global code changes to make everything better.

Example Use Case

Here is a screenshot of the Serial Port JSON Server being used inside the ChiliPeppr Serial Port web console app. http://chilipeppr.com/serialport

This is the Serial Port JSON Server being used inside the TinyG workspace in ChiliPeppr. http://chilipeppr.com/tinyg

There is also a JSFiddle you can fork to create your own interface to the Serial Port JSON Server for your own project. http://jsfiddle.net/chilipeppr/vetj5fvx/

Running

From the command line issue the following command:

  • Mac/Linux ./serial-port-json-server
  • Windows serial-port-json-server.exe

Verbose logging mode:

  • Mac/Linux ./serial-port-json-server -v
  • Windows serial-port-json-server.exe -v

Running on alternate port:

  • Mac/Linux ./serial-port-json-server -addr :8000
  • Windows serial-port-json-server.exe -addr :8000

Filter the serial port list so it has relevant ports in the list:

  • Mac/Linux ./serial-port-json-server -regex usb|acm
  • Windows serial-port-json-server.exe -regex com8|com9|com2[0-5]|tinyg

Garbage collect mode (deprecated):

  • Mac/Linux ./serial-port-json-server -gc std
  • Windows serial-port-json-server.exe -gc max

Override the default hostname:

  • Mac/Linux ./serial-port-json-server -hostname myMacSpjs
  • Windows serial-port-json-server.exe -hostname meWindowsBox

Here's a screenshot of a successful run on Windows x64. Make sure you allow the firewall to give access to Serial Port JSON Server or you'll wonder why it's not working.

Binaries for Download

Version 1.86 Build date: Oct 4, 2015 Latest TinyG buffer and firmware programmer.

  • Windows x32
  • Windows x64
  • Mac OS X x64
  • Linux x32
  • Linux x64
  • Raspberry Pi (Linux ARM)
  • Beagle Bone Black (Linux ARMv7)
  • Intel Edison (Linux x64)

Version 1.80 Build date: Mar 8, 2015 Build has new garbage collection, "broadcast" tag, and "hostname" tag support.

  • Windows x32
  • Windows x64
  • Mac OS X x64 (Thanks to Riley Porter)
  • Linux x32
  • Linux x64
  • Raspberry Pi 1 (Linux ARMv6)
  • Raspberry Pi 2 (Linux ARMv7)
  • Beagle Bone Black (Linux ARMv7)
  • Linux ARMv8 (AppliedMicro X-Gene)
  • Intel Edison (Linux x64)

Feed Rate Override

There is a new feature available as of version 1.83 which is Feed Rate Override. It can be triggered by sending in a command like the following:

fro COM4 0.5

This command asks SPJS to override the existing feed rate and reduce it by half. If you have a feedrate of 200 then the command above would bring it to 100 by multiplying 200 * 0.5 = 100. To turn off the feed rate override set it back to 0 with a command such as:

fro COM4 0.0

How to Build

You do not need to build this. Binaries are available above. However, if you still want to build...

Video tutorial of building SPJS on a Mac: https://www.youtube.com/watch?v=4Hou06bOuHc

  1. Install Go (http://golang.org/doc/install)
  2. If you're on a Mac, install Xcode from the Apple Store because you'll need gcc to compile the native code for a Mac. If you're on Windows, Linux, Raspberry Pi, or Beagle Bone you are all set.
  3. Get go into your path so you can run "go" from any directory: On Linux, Mac, Raspberry Pi, Beagle Bone Black export PATH=$PATH:/usr/local/go/bin On Windows, use the Environment Variables dialog by right-click My Computer
  4. Define your GOPATH variable and create the folder to match. This is your personal working folder for all yourGo code. This is important because you will be retrieving several projects from Github and Go needs to know where to download all the files and where to build the directory structure. On my Windows computer I created a folder called C:\Users\John\go and set GOPATH=C:\Users\John\go On Mac export GOPATH=/Users/john/go On Linux, Raspberry Pi, Beagle Bone Black, Intel Edison export GOPATH=/home/john/go On Windows, use the Environment Variables dialog by right-click My Computer to create GOPATH
  5. Change directory into your GOPATH
  6. Type "go get github.com/johnlauer/serial-port-json-server". This will retrieve this Github project and all dependent projects. It takes some time to run this.
  7. Then change direcory into src\github.com\johnlauer\serial-port-json-server.
  8. Type "go build" when you're inside that directory and it will create a binary called serial-port-json-server
  9. Run it by typing ./serial-port-json-server or on Windows run serial-port-json-server.exe
  10. If you have a firewall on the computer running the serial-port-json-server you must allow port 8989 in the firewall.

Supported Commands

Command Example Description
list Lists all available serial ports on your device
open portName baudRate [bufferAlgorithm] open /dev/ttyACM0 115200 tinyg Opens a serial port. The comPort should be the Name of the port inside the list response such as COM2 or /dev/ttyACM0. The baudrate should be a rate from the baudrates command or a typical baudrate such as 9600 or 115200. A bufferAlgorithm can be optionally specified such as "tinyg" (or in the future "grbl" if somebody writes it) or write your own.
sendjson {} {"P":"COM22","Data":[{"D":"!~\n","Id":"234"},{"D":"{"sr":""}\n","Id":"235"}]} See Wiki page at https://github.com/johnlauer/serial-port-json-server/wiki
send portName data send /dev/ttyACM0 G1 X10.5 Y2 F100\n Send your data to the serial port. Remember to send a newline in your data if your serial port expects it.
sendnobuf portName data send COM22 {"qv":0}\n Send your data and bypass the bufferFlowAlgorithm if you specified one.
close portName close COM1 Close out your serial port
bufferalgorithms List the available bufferAlgorithms on the server. You will get a list such as "default, tinyg"
baudrates List common baudrates such as 2400, 9600, 115200
restart Restart the serial port JSON server
exit Exit the serial port JSON server
fro fro COM 1.5 Multiplies the current feed rate by the value passed in for the specific serial port. (This is specific to Gcode, so if using SPJS for non-Gcode work this command won't mean much.)
memstats Send back data on the memory usage and garbage collection performance
broadcast string broadcast my data Send in this command and you will get a message reflected back to all connected endpoints. This is useful for communicating with all connected clients, i.e. in a CNC scenario is a pendant wants to ask the main workspace if there are any settings it should know about. For example send in "broadcast this is my custom cmd" and get this reflected back to all connected sockets {"Cmd":"Broadcast","Msg":"this is my custom cmd\n"}
version Get the software version of SPJS that is running
hostname Get the hostname of the current SPJS instance
program portName core:architecture:name $path/to/filename program com3 arduino:avr:uno c:\myfiles\grbl_9i.hex Send a hex file to your Arduino board to program it.
programfromurl portName core:architecture:name url programfromurl /dev/ttyACM0 arduino:sam:arduino_due_x http://synthetos.github.io/g2/binaries/TinyG2_Due-edge-078.03-default.bin Download a hex/bin file from a URL and then send it to your Arduino board to program it.

Programming Your Arduino from SPJS

The ability to program your board is now available within Serial Port JSON Server (SPJS). This feature was developed by the folks at Arduino because they are looking to use SPJS inside their upcoming Web IDE project. Therefore you can expect great support for this feature into the future as it will be the main way the IDE programs the boards. For folks using SPJS in other environments like ChiliPeppr, this means you'll be able to do firmware updates on your boards without much effort.

There are two new commands:

program [portName] [core:architecture:name] [$path/to/filename]
programfromurl [portName] [core:architecture:name] [url]

These commands are identical except for one parameter that specifies where the binary hex/bin file is. With the program command you specify a file path. With programfromurl you specify a public URL.

This example command will update your Arduino Due with the latest TinyG G2 firmware for your CNC machine. It will download the bin file from Github and flash it to an Arduino Due running on the ttyACM0 serial port on a Raspberry Pi 2.

programfromurl /dev/ttyACM0 arduino:sam:arduino_due_x http://synthetos.github.io/g2/binaries/TinyG2_Due-edge-078.03-default.bin

This example will update your Arduino Uno running on a Windows computer with the latest version of Grbl from a public URL.

programfromurl com12 arduino:avr:uno https://raw.githubusercontent.com/grbl/grbl-builds/master/builds/grbl_v0_9i_atmega328p_16mhz_115200.hex

The 2nd parameter of core:architecture:name specifies which board you're trying to program so that SPJS can figure out what programmer and parameters should be used to send the hex/bin file up to your device. The choices can be seen in the boards.txt file in the distribution, but here is a partial list for quick reference:

  • arduino:avr:uno
  • arduino:avr:yun
  • arduino:avr:diecimila
  • arduino:avr:nano
  • arduino:avr:mega
  • arduino:avr:megaADK
  • arduino:avr:leonardo
  • arduino:avr:micro
  • arduino:avr:esplora
  • arduino:avr:mini
  • arduino:avr:ethernet
  • arduino:avr:fio
  • arduino:avr:bt
  • arduino:avr:LilyPadUSB
  • arduino:avr:lilypad
  • arduino:avr:pro
  • arduino:avr:atmegang
  • arduino:avr:robotControl
  • arduino:avr:robotMotor
  • arduino:sam:arduino_due_x_dbg
  • arduino:sam:arduino_due_x
  • arduino:avr:tinyg (TinyG v7/v8. For G2 use due_x_dbg.)

Broadcast Command

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Go

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言