User Tools

Site Tools



(this info is cross posted by my blog Serial2TCP is an app that lets you share a serial port to a network port. What this means is that you can use any Mac as a remote serial adaptor for your XTension devices. Need another W800 in the back half of the house and dont feel like running wires through the attic? Just connect it to your office machine over there, or the kids machine or any other Mac you have handy. It also works across the internet if you dont mind the fact that your connection would go down if the internet or cable modem got disconnected.


since the code was fairly straightforward and not dealing with constantly changing interface conventions I was able to load the same source into an older version of the compiler and make a fat binary for pre 10.7 OSX on both Intel and PPC processors. I dont really know how far back this will run, but 10.5 or maybe 10.4?

download pre-10.7 and ppc

download and unzip, I would recommend placing the folder inside the Applications folder. Dont just put the app there without it’s folder as it needs to have the folder of libraries next to it in order to run and that gets confusing and messy in your app folder. If you wish to run it manually from the command line you can then create an alias to it in /bin or something. If you’re just going to set it up to run in the background that isn’t necessary.


command line options: (NOTE that all the switches are preceded by a double dash, NOT the em dash that modern browsers insist on converting a typed double dash into when editing a wiki page.)

--help  (prints out these instructions)

--list  (prints out a list of available serial ports on the computer right now, you need this name for the next step)

--share [serial port name] [serial port baud rate] [tcp port]

you can use multiple –share name 57600 2000 combinations to share multiple ports.

for example:

/Applications/serial2tcp/serial2tcp --share usbserial-FT54454 4800 2000

might be the command you would use to share a CM11 or XTB-232 on a remote machine. It shares an FTDI based serial adaptor named usbserial-FT54454 opens it at 4800 baud and shares it to port 2000.

The program will only allow 1 connection at a time to any given share point but will relisten automatically if the connection is dropped from the TCP side, so no restarting necessary to get it back up again if the other side drops. It will also make valiant efforts to reconnect with a disconnected serial port. If the port returns it will reconnect to the proper stream and conversation can continue. However data may be lost and other errors may occur since yanking an in use usb/serial adaptor can cause all sorts of garbage to get sent to both sides as the driver unloads. In my testing on 10.9 and with the latest FTDI drivers I was able to reconnect with only some garbage data when pulling the adaptor. But in previous OSX versions and with other brands of adaptors I’ve seen kernel panics when an in use adaptor was accidentally disconnected. so YMMV.

To connect to it in XTension the remote computer will need a static IP address, or at least a DHCP reservation so that it will always be at the same address. If you’re connecting over the internet then you’ll also need to setup NAT passthroughs for the port you’ve selected so that XTension can reach the machine. This is a server and listens for a connection to come in, it wont make an outgoing connection.

As useful as running it from the command line might be, the real value is in setting this up to run automatically in the background no matter who, if anyone, is logged into the mac. This requires some work at the command line to get setup.

background operation

These instructions are for OSX 10.9 and later, I believe they should work as far back as 10.7.

Inside the serial2tcp folder you’ll also find a file called “com.sentman.serial2tcp.plist” this is a starting point for a launch agent configuration file so that OSX will run it in the background. If you have the OSX developer tools installed this will open in the plist editor, if you dont you can use any text editor but pay attention to the XML structure of the file so you dont introduce parsing errors.

The “Label” must be unique and should be the same name as the file.

The first program argument must be a link to where you’ve put the file. If you put the folder in Applications then this should be correct.

the rest of the program arguments are just what would be passed to the program if you ran it from the command line. IN this case I’m sharing a usb/serial adaptor at 57600 baud and sharing it on TCP port 2000. This was for a remote xBee network. You can change these values for your system. If you wish to share more ports then create another set of lines 1 through 4 but put in the new information. You can make as many shares as you like.

Once you save the file you’ll need to put a copy into the /Library/LaunchAgents folder. To get there in the finder use the “go to folder..” menu item from the “go” menu. Copy and Paste the file into that folder, the finder will ask you to authenticate with your admin password as this is a protected system folder.

Next you’ll need to change the owner of the file to root. I couldn’t get this to work through the Finders file permission dialog so we’ll have to do it from the command line. Open a terminal window and go to that folder by typing:

cd /Library/LaunchAgents

and then

sudo chown root ./com.sentman.serial2tcp.plist

again it will ask you to authenticate.

now we should be able to test it, you could just restart but you can load it manually also by entering:

sudo launchctl load ./com.sentman.serial2tcp.plist

if no errors are returned then you’re probably sharing the port. Use the activity viewer utility to see if it’s running and then try to connect to it via XTension and verify that everything else is working. Your mac is now acting as a very expensive usb/serial/ethernet adaptor and the connection should survive any user logging in and out.

tutorials/serial2tcp.txt · Last modified: 2023/02/13 14:52 by