Tuesday, September 16, 2014

Serial2tcp sharing a serial port on your computer to a remote device

There are dozens of ways to connect to remote devices from XTension but it occurred to me that there isn’t a simple way to just share one connected to another Mac. This little app will connect a local serial port on any Mac to a TCP port. Listen for a connection to the port and then forward data between the two. It can connect multiple serial ports and TCP ports with only one process. I’ve made no attempt to code for the opposite side of the equation, turning a TCP stream back into a virtual com port because thats not necessary for XTension. Anything XTension can connect to via a local port it can also connect to via a TCP stream.

download:  serial2tcp.zip

(since the code was fairly straightforward I was able to load the source into an older version of the compiler and create a fat binary with both Intel and PPC code for anyone wanting to recycle a really old machine. I’m not entirely sure how far back in OS versions this will run, but it would be worth trying on 10.4 intel or ppc machines.)

download ppc: serial2tcp_ppc.zip

download and unzip. I would recommend placing the serial2tcp folder inside the Applications folder. There is a folder of libraries inside it as well that must remain next to the application regardless where you put it. Then if you’re the kind of person who likes to run things from the command line you can make an alias to your /bin directory.

command line options:

--help   prints out the help
--list    prints out a list of available serial ports on your computer
--share [serial port name] [serial port baud] [tcp port number]

--share is the main entry point for getting it to do anything. Get the serial port name from the --list function, a standard baud rate and a TCP port above 1024 to run it on.

For example to share a CM11a on a remote machine you’d use something like:

/Applications/serial2tcp/serial2tcp --share usberial_FT5434 4800 2000

would connect to an FTDI based usb/serial adaptor with that name, open the port at 4800 baud and share it on port 2000.  If you wish to share more than one port you can use multiple --share parameters. But they must have unique serial port names and TCP port numbers.

The program will allow only 1 connection at a time for any given serial port but will re-listen if a connection goes away. So you should be able to reconnect to it without restarting it or any such thing. It also makes a valiant effort to reconnect to a lost serial port. If someone pulls the USB plug and plugs it back in on the remote machine it will work very hard to reconnect to that port and then reconnect it to the already open TCP stream. If you’re lucky you wont even miss any data. On 10.9 with the latest FTDI drivers I had no trouble with this apart from the garbage data being sent down the serial port making my CM11 freak out until being power cycled. On earlier OS versions though it was not uncommon to get a kernel panic if an open usb/serial adaptor was pulled while in use. So YMMV.

To use it then in XTension just select “remote tcp port” instead of a serial port from the available port popup. Enter the IP address of the computer doing the sharing and the port number you’ve chosen, in the above example 2000. The computer hosting the port should be configured with a static IP address or a reserved DHCP address so that it doesn’t change. If you want to share across the internet you’ll have to be able to create the proper NAT pass throughs to reach it. It’s a server listening for an incoming connection on the port not a client that can make an outgoing connection.

Thats all well and good, but the real value would be in having it launch at computer startup and run no matter who is logged in or if anybody is logged in to the computer. This is possible by setting up a system launchd configuration file for it. The following instructions are for OSX 10.9 and later, but it should work for the last few versions. Earlier than 10.7 and you should verify the proper launchd plist configuration because I believe it has changed since 10.6.

Inside the serial2tcp folder you’ll find a file called “com.sentman.serial2tcp.plist” this is a boilerplate launchd configuration file that you will need to edit for your own use. If you have apple’s dev tools installed then you can use the excellent plist editor, otherwise any text editor can do it but pay attention to the XML structure. Screenshots below are from the plist editor.


The “label” must be unique and should be the same name as the file but without the .plist at the end. You can leave it like it is unless you’re starting multiple instances.

the first program argument must be the link to the program you wish to run, in this case I put it in the Applications folder, but if you put it somewhere else then change that link.

The following parameters are the same as if you were adding them at the command line. In this example I’m sharing usbserial-FTG3LGPX at 57600 baud on port 2000. You’ll want to change those for your own settings. You can add more program arguments if you wish to share more than one port. Just repeat items 1 through 4 with the new info in them.

Once you’ve saved this back you’ll need to place a copy into the system launchd folder which is at /Library/LaunchAgents you can use the command line to get there or the “go to folder” option of the finders “Go” menu and enter that path. It will ask you to enter your password in the finder because this is a system protected folder and you need to run as an administrator to move files in and out of it. Once the file is there you’ll need to edit the owner of the file. It must be owned as root in order to be loaded while nobody is logged in. I could not get this to work from the finder’s file permissions panel and so it must be done from the command line.

Open a terminal window and type:

cd /Library/LaunchAgents

then

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

again it will ask you for your password to make sure you’re actually allowed to make a file owned as root.

You can test without rebooting by using the launchctl command from the same command line, type:

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

and you should just get the cursor again if no errors occurred. The program will log it’s output to the system log while running in the background so look there for connect/disconnect errors or other messages. If all went well you should now be able to see it running with the activity manager and connect to the port from XTension and share the device.

This article is cross posted at MacHomeAutomation.com

No comments:

Post a Comment

.code { background:#f5f8fa; background-repeat:no-repeat; border: solid #5C7B90; border-width: 1px 1px 1px 20px; color: #000000; font: 13px 'Courier New', Courier, monospace; line-height: 16px; margin: 10px 0 10px 10px; max-height: 200px; min-height: 16px; overflow: auto; padding: 28px 10px 10px; width: 90%; } .code:hover { background-repeat:no-repeat; }