*** GUIDE *** Passthrough Onboard Serial Port to Mac OSX High Sierra

2 posts in this topic Last Reply

Recommended Posts

High Sierra 10.13.2 unRAID version in use at the time of this writing (6.4.0_rc18f)


I'm really enjoying unRAID, so I thought I would give something back to the community.


I have an application that I had written in Java and I needed to dial-up satellite modems using the old technology called a modem to retrieve data from remote locations.


Yes, I could use a USB to Serial adapter like the excellent Keyspan USA-19HS adapter from, but I have a Supermicro MB and I really wanted to use the onboard serial port instead.


Dealing with the Cable - Always stop your array and power down your unRAID server whenever connecting or removing components and unplug the unit.


So the first thing you need to do is pickup a 9 pin serial male to IDC 10 pin female motherboard header adapter.  My local store had the StarTech PLATE9M in stock so I picked that one up.


This however will not work with my Supermicro motherboard and the reason for this is the fact that there are two different IDC10 header standards i.e. AT/Everex and DTK/Intel.  Turns out that Supermicro uses the latter DTK/Intel.  So to fix this, you either need to buy a different header in the first place or disassemble the DB9 connector from the plate and unsolder and re-solder the wires to their correct positions.  All the wires are in the wrong locations except Pin 1.  Also to note pin 1 on a ribbon cable is usually denoted by a red wire.




So to fix this, unsolder all the wires from the DB9 except for pin 1.  As mentioned earlier the red wire is pin 1, so if you bought the AT / EVEREX motherboard header connector then re-solder the pins as follows:




Now that we have that out of the way, we can re-assemble our cable and attach it to the header and computer chassis.


Test the Connection with unRAID


At this point we need to make sure the serial port is enabled in the Bios.  In my case I am using a modem with unRAID, so I will test as follows:


Either use the new >_ Terminal menu in unRAID, or ssh into your unRAID server.


At the command prompt issue the following command --> dmesg | grep tty


The computer should respond with something like this:


[    0.000000] console [tty0] enabled
[    6.339412] 00:01: ttyS0 at I/O 0x3f8 (irq = 4, base_baud = 115200) is a 16550A


From this we know that our serial port is assigned as ttyS0.


You can use screen with unRAID to test your modem, but you need to install the Nerd Tools plugin and then go to Settings and select Nerd Pack and then find screen in the list and install it.


You would then test your modem by issuing the following command --> screen /dev/ttyS0 115200


To exit screen, DO NOT use CTRL-c, instead use --> CTRL-a and then k and press y for yes.


Edit High Sierra KVM xml Settings


Now with our computer started, and before we launch our High Sierra KVM (see gridrunner's excellent videos), we need to edit the XML file.


Now according to this documentation from Consoles, serial, parallel & channel devices and I will restate it here:




Now it's important to note that in the third paragraph we see that the console element in the xml file is tied to the first serial device in the same file.


So we must edit our xml file as follows:

Pro Tip:  It's a good idea to copy the xml file settings to a text editor like BBEdit or Sublime so if something goes wrong, we can paste those settings back in.


Change this:


    <serial type='pty'>
      <target port='0'/>
    <console type='pty'>
      <target type='serial' port='0'/>


To this:


    <serial type='pty'>
      <target port='0'/>
    <serial type='dev'>
      <source path='/dev/ttyS0'/>
      <target port='0'/>

    <console type='pty'>
      <target type='serial' port='0'/>

Note, we need to add our ttyS0 port in that we saw earlier when we issued the following command --> dmesg | grep tty


Okay, now we need to Update our settings and then it's a good idea to look at the xml file again to make sure it hasn't been set back to something else.  Believe me when I say this happens.  Especially if you do not put the extra serial device in the correct place in the xml.


Now we can launch our High Sierra KVM.  If everything goes well we should be at the desktop.


Check that the Serial port has been passed through to High Sierra


Next we need to launch the terminal window.


Issue the following command --> ls -l /dev/tty.serial*


You should get back the following:


crw-rw-rw-  1 root  wheel   19,   0 11 Jan 14:08 /dev/tty.serial1
crw-rw-rw-  1 root  wheel   19,   2 12 Jan 08:36 /dev/tty.serial2 <-- This is the ttyS0 that we are passing through.


At this point if we have a modem connected, we can use the built in screen command to communicate with the modem.


So we type --> screen /dev/tty.serial2 115200


And we can then issue commands to the modem and see results back.


To exit screen, DO NOT use CTRL-c, instead use --> CTRL-a and then k and press y for yes.


Possible Port in Use Issues with OSX


Now her are some final notes.  In my case as I stated in the start of this, I needed to use a Java program that I had written to retrieve data from remote satellite modems.  I use a library for this called RXTX from RXTX wiki.  But sometimes programs will complain that the serial port that we just setup is in use.  So in High Sierra, we have to issue the following commands to eliminate this problem.


First make sure the lock directory is in place using this command:


sudo mkdir /var/lock


Next we need to set the appropriate permissions with the following commands:


sudo dscl . -append /groups/_uucp GroupMembership username <-- this is your mac username.

sudo chgrp uucp /var/lock

sudo chmod 775 /var/lock


That's all :)




Edited by Limy

Share this post

Link to post

nice job nerd!

Share this post

Link to post

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Copyright © 2005-2018 Lime Technology, Inc.
unRAID® is a registered trademark of Lime Technology, Inc.