Polisy HW How-To: Serial Console

[mwester]

Connecting to the Polisy Serial Console Port - Hardware

When things go all wrong... or when you think something you're about to do has a chance to go all wrong... then you might need access to the Polisy serial console port in order to recover.  This post and thread is all about connecting the hardware in order to gain access to that port.

(Note: PLEASE start a NEW THREAD for your questions and issues, this thread is reserved for HOW-TO information, not debugging, troubleshooting, or questions!)

 

 

(1) Acquire the USB to TTL Serial Cable

First things first -- you'll need a USB to TTL Serial Cable to connect your PC or Mac to the Polisy serial console port.  You want THIS ONE.  While there's nothing special about the Polisy's internal serial console port (it uses the pretty-much standard 3.3 volt TTL RX and TX signals), a potential pitfall is the lack of standardization of the USB-to-TTL serial cables themselves -- they often use different chipsets internally, and different color coding, and different device drivers.  (The end result being that if you can't get a prompt, it's fiendishly difficult to determine if the problem is the terminal program you're using, the driver for the cable you've got, the pin connections you've guessed at, or perhaps the Polisy hardware is in a state where it's not talking to you...)  So, once again, you want the Adafruit USB to TTL Serial Cable, product #954:

     https://www.adafruit.com/product/954

(Note: If you choose NOT to use that product - start a NEW THREAD for your questions and problems -- this thread is reserved for HOW-TO information using that, and only that cable!)

Next, install the software you'll need.  Follow the instructions on the Adafruit product page (use the links above) to install the device driver, and other software, as appropriate for your computer.  Note that the Adafruit pages will take you to a topic that is all about connecting to a Raspberry Pi's serial port -- that's fine, since the Polisy's serial port is electrically identical.  So just follow the guide to configure your Windows, Mac, or Linux host, and you'll be all set.

The details of what to do, and how to use the serial console are NOT the subject of this thread -- this thread is about connecting the hardware, and nothing else!  So please, please, start another thread to discuss your issues, questions, concerns, or anything else about the terminal software and everything else associated with using the serial console once it's connected!

 

(2) Gain Access to the Polisy Serial Console Connector

The console connector is a white 5-pin connector inside the Polisy, right up front on the circuit board.

Start by opening up your Polisy -- power off your Polisy, remove the screws holding the top cover on, and gently lift the cover off.

Identify the connector -- it's the one circled in red in the photo:

 

 

 

(3) Tape or Tie Back the USB to TTL Serial Cable's Power Pin

Play it safe -- tie the extra, unused power pin (the one on the red wire) on the Adafruit USB to TTL Serial Cable back, out of the way, so that there's NO chance it'll touch anything it shouldn't!  That pin is live whenever the USB connector is plugged in, and it is most assuredly not a good thing should it touch anything in the Polisy!  So, get it out of the way.  I had a twist tie handy, but electrical tape is also perfectly useful for this purpose.  (You could cut it off, as well, but that seems excessive to me...)

 

 

 

(4) Move the Jumper

You'll note there's a jumper connecting two pins on the serial port -- that jumpers the RX (received data) line to the ground pin, and it's there because if the RX line is just left floating (connected to nothing) it picks up electrical noise, which can look like random keystrokes to the Polisy.  While mostly the random keystrokes won't do anything, they'll certainly suck CPU cycles as the Polisy tries to figure out what commands it's getting.  Moreover, since the port is operating at over 10,000 characters per second, the laws of statistics say that it won't be too terribly long before those random keystrokes actually end up being a valid sequence that'll instruct the Polisy to do something you won't like it to do!

We're going to need to remove that jumper (you did remember to power off the Polisy, right?  If not, do so now).  Murphy's Law states that since you need that jumper, it's almost certain that you'll lose it.  So, instead of putting it on your bench, or in your coffee cup, or goodness-knows-where, just shift it over a couple slots to that it's plugged into the single pin on the end of the connector (with half of it hanging over the edge).  Not only does this ensure we don't lose that jumper, it also makes sure we don't accidentally use that end-most pin -- it's live and connected to the Polisy internal power bus, and we DO NOT want to connect ANYTHING to that pin -- or the pin on the extreme other end of that connector (both of the end pins are power pins -- we're going to be using ONLY the middle three pins!)

 

 

(5)  Connect the Serial Ground

As with every electrical connection, one ALWAYS connects the ground first.  That's the black wire on your Adafruit USB to TTL Serial Cable -- connect it to the pin shown in the photo below.  Check carefully which pin is which -- in the photo below, the jumper (with the red arrow) is on the extreme right-most pin with half of it hanging over the edge, and the ground connector is on the adjacent pin (black arrow).  If you get it wrong, you'll either short one of the data lines to ground, or worse yet, you'll short the Polisy's 5-volt power-supply or it's 3.3-volt power-supply to ground.  Neither is good.

Double check after you've plugged it in.  Seriously.

 

 

(6) Connect the Transmit and Receive Data Wires

You've tied back the red wire on the Adafruit USB to TTL Serial Cable, and you've connected the black one.  That leaves only the RX and TX data lines to connect -- these connect as shown in the photo below, on the other two middle pins of the connector.

When you're done, double-check -- you should have the jumper on one of the end pins of the Polisy internal serial console port, and the pin at the other end of the connector should be empty!  (These are power pins from the Polisy - we have no need for those.  And whatever you do, do NOT connect the red wire from the cable to either of those end pins!).

 

 

 

(7) Using the Serial Console

Now what?  Well, you've done all the hard stuff - now all you have to do is start the terminal software (the last part of section (1) above, which you've already done, right?), and power up your Polisy.  The output from the Polisy's boot sequence will appear, and you'll end up with a prompt to login.  Login just as you would with an SSH connection.  The details of what to do, and how to use the serial console are NOT the subject of this thread -- this thread is about connecting the hardware, and nothing else!  So please, please, start another thread to discuss your issues, questions, concerns, or anything else about the terminal software and everything else associated with using the serial console!

 

(8) Preparing for the Future

Make life easier -- mark the connector with the wire colors so it's easier next time.  In the photo below, I had some green painter's tape that I marked up... in retrospect, blue tape would have been easier!  But if you look closely at the connector itself, beneath the black cable pins, you'll see the markings...

 

 

(9) Putting Everything Back

When you've done what you need to do, you can simply remove the cable -- but it's best to do this with the Polisy powered off, of course.

And don't forget to put that jumper back into the correct place -- it jumpers the RX line to the ground line -- refer to the photo above to make sure it goes back into the correct place.  (Note that if you get it across the wrong pins, you'll be very unhappy: shift it one place in one direction and you'll jumper the Polisy's transmit data line to it's receive data line... shift it one place in the other direction and you'll short out the Polisy's power supply to ground.   Use caution.  Double check.  Seriously.

 

Conclusion

When all else fails -- your network connections are dead, the reset button isn't fixing it, and not even UDI's excellent support has been able to recover it -- the serial console is that "last resort" that'll regain access to enable debugging and recovery.   Or, if you're a geek who lives on the edge, access to the serial console is a requirement for those experiments that go wrong ("Gee... I wonder what happens if I delete this file named kernel?").  Access to the serial console port is pretty easy, and by using a well-supported standard cable and by following this guide, the typical trial-and-error process to figure out which wires go where can be eliminated.

 

[Michel Kohanim]

@mwester,

THANK YOU THANK YOU THANK YOU!!!!

With kind regards,
Michel