Bug 85355 - [patch] Error in the pin numbers of the described connector in the Handbook (serial).
Summary: [patch] Error in the pin numbers of the described connector in the Handbook (...
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: Gary W. Swearingen
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2005-08-27 18:10 UTC by Julien Gabel
Modified: 2005-09-30 19:06 UTC (History)
0 users

See Also:


Attachments
chapter.sgml.diff (1.15 KB, patch)
2005-08-27 18:10 UTC, Julien Gabel
no flags Details | Diff
chapter.sgml.diff (1.46 KB, patch)
2005-08-30 10:48 UTC, Julien Gabel
no flags Details | Diff
chapter.sgml.wbook.diff (1.63 KB, patch)
2005-08-30 10:48 UTC, Julien Gabel
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Julien Gabel 2005-08-27 18:10:23 UTC
It seems there is a little mistake in the proposed pin numbers for null-modem DB-25
connector shown in the example.

Fix: Here is a patch:
How-To-Repeat: Compare different source of information about this topic, as in the proposed Hardware Book at:
 http://www.hardwarebook.net/cable/serial/nullmodem25to25.html
Comment 1 Gary W. Swearingen 2005-08-27 21:40:19 UTC
Julien Gabel <jpeg@thilelli.net> writes:

> +	  <para>If you like making your own cables, you can construct a
> +	    null-modem cable for use with terminals.  This table shows the RS-232C

"for asyncronous communications with terminals".  (I'm not sure what
"terminals" include, but synchronous comm needs more wires.)

(I'd also kill "If you like making your own cables, ".)

> +	    signal names and the pin numbers on a DB-25 connector.  More information
> +	    and collection of cable descriptions may be found in the <ulink
> +	    url="http://www.hardwarebook.net/cable/index.html">Hardware Book</ulink>.</para>

I'd add: The standard also calls for a straight-through pin 1 to pin 1
"protective ground" line, but it is often omitted.  Some terminals can
get by using only pins 2, 3, and 7, while others, especially printers,
require other configurations than the example here.  Synchronous
communications, for example, requires more lines to be used.

> +		  <entry>8</entry>
> +		  <entry>DCD</entry>

That design (after the fix) seems to be the most popular, but a book
"RS-232 Made Easy" uses several pages developing and justifying a
generic null-modem design like that, except he has 4 & 5 going to 8
and vice versa.  I probably used in at least one of my cables.  Oh,
well; that's life with RS-232.
Comment 2 Gary W. Swearingen 2005-08-27 21:45:40 UTC
Julien Gabel <jpeg@thilelli.net> writes:

> +	    and collection of cable descriptions may be found in the <ulink

"and a collection"; maybe "may be found in" -> "is in"
Comment 3 Yar Tikhiy 2005-08-29 09:30:36 UTC
On Sat, Aug 27, 2005 at 08:40:20PM +0000, Gary W. Swearingen wrote:
>  Julien Gabel <jpeg@thilelli.net> writes:
>  
>  > +	  <para>If you like making your own cables, you can construct a
>  > +	    null-modem cable for use with terminals.  This table shows the RS-232C
>  
>  "for asyncronous communications with terminals".  (I'm not sure what
>  "terminals" include, but synchronous comm needs more wires.)

It might be reasonable to tell that in general, a null-modem cable
is for connecting a DTE directly to another DTE.  AFAIK, null-modem
cables can be constructed for synchronous comms, too.  Then, the
topic can be narrowed down to async comms.

>  > +	    signal names and the pin numbers on a DB-25 connector.  More information
>  > +	    and collection of cable descriptions may be found in the <ulink
>  > +	    url="http://www.hardwarebook.net/cable/index.html">Hardware Book</ulink>.</para>

To me, www.hardwarebook.net doen't seem the definite resource.
IMHO, if the topic is rather wide, the reader should better be
hinted to do a (re)search on the Net instead of pointed to a single
resource, which is likely to become incomplete, outdated, or down.

>  I'd add: The standard also calls for a straight-through pin 1 to pin 1
>  "protective ground" line, but it is often omitted.  Some terminals can
>  get by using only pins 2, 3, and 7, while others, especially printers,
>  require other configurations than the example here.  Synchronous
>  communications, for example, requires more lines to be used.

Perhaps, we can spend a paragraph on giving the reader some insight
into null-modem design principles, eh?  In particular, the 3-wire
cable, for which we happen to have some entries in /etc/gettytab,
will provide data lines, but won't support flow control (RTS, CTS)
or modem control (DTR, DSR, DCD).  So the reader could understand
*why* he may or may not need the simpler or the more complex cable
design.  I myself once spent some time making a 8-wire null-modem
cable only to find out that my terminak didn't support flow control
in the first place :-)

Apropos, has there ever been a DTE printer?  I think that printers
or sync comms shouldn't belong there if it were told above that we
would deal with async DTE-DTE comms only in this section.

>  > +		  <entry>8</entry>
>  > +		  <entry>DCD</entry>
>  
>  That design (after the fix) seems to be the most popular, but a book
>  "RS-232 Made Easy" uses several pages developing and justifying a
>  generic null-modem design like that, except he has 4 & 5 going to 8
>  and vice versa.  I probably used in at least one of my cables.  Oh,
>  well; that's life with RS-232.

We may show two or three different designs in the handbook if we
can tell the reader about their merits.  The problem with the design
currently in the handbook is that it is erroneous *and* bogus.  I'd
suggest adding another row to the table so that it becomes evident
that DTR on this side is connected to DSR+DCD on the other side
while DTR on the other side is connected to DSR+DCD on this side.
An RS-232 null-modem cable should be symmetric, to my mind.

-- 
Yar
Comment 4 Gary W. Swearingen 2005-08-29 15:52:16 UTC
Yar Tikhiy <yar@comp.chem.msu.su> writes:

> It might be reasonable to tell that in general, a null-modem cable
> is for connecting a DTE directly to another DTE.  AFAIK, null-modem
> cables can be constructed for synchronous comms, too.  Then, the
> topic can be narrowed down to async comms.

I doubt if Julien wants to do more rewrites on the section.  But I
can't resist replying anyway; maybe Yar wants to rewrite it later.

It probably should have some of the cable stuff from the "Serial
Ports" section which says that a null-modem is AKA DTE-to-DTE cable
and what DTE is, eg, a computer.  And terminals traditionally have
included teletypes and printers. (Once there were no CRTs or LCDs.)

> To me, www.hardwarebook.net doen't seem the definite resource.
> IMHO, if the topic is rather wide, the reader should better be
> hinted to do a (re)search on the Net instead of pointed to a single
> resource, which is likely to become incomplete, outdated, or down.

I was thinking the same things.

> Apropos, has there ever been a DTE printer?  I think that printers
> or sync comms shouldn't belong there if it were told above that we
> would deal with async DTE-DTE comms only in this section.

Serial printers were once common (I have one) and I think few, if any,
were configured as DCE (eg, modems); the bulk were DTEs. But sync
comms don't need to be mentioned; I don't know if FreeBSD can even
handle it.  I just wanted some note about the large number of
null-modem designs for different purposes, for folks raised on USB.

> We may show two or three different designs in the handbook if we
> can tell the reader about their merits.  The problem with the design
> currently in the handbook is that it is erroneous *and* bogus.  I'd
> suggest adding another row to the table so that it becomes evident
> that DTR on this side is connected to DSR+DCD on the other side
> while DTR on the other side is connected to DSR+DCD on this side.

The Note below the pin-out is supposed to make it evident, and with
the Note the design is symmetric.

> An RS-232 null-modem cable should be symmetric, to my mind.

A "typical async null-modem cable", yes.  But few of the many RS-232
null-modem cable designs shown in the book are symmetric, owing to the
variety of designs of much DTE. (Less true today than yesteryear.)
Comment 5 Yar Tikhiy 2005-08-29 17:24:04 UTC
On Mon, Aug 29, 2005 at 07:52:16AM -0700, Gary W. Swearingen wrote:
> Yar Tikhiy <yar@comp.chem.msu.su> writes:
> 
> > It might be reasonable to tell that in general, a null-modem cable
> > is for connecting a DTE directly to another DTE.  AFAIK, null-modem
> > cables can be constructed for synchronous comms, too.  Then, the
> > topic can be narrowed down to async comms.
> 
> I doubt if Julien wants to do more rewrites on the section.  But I
> can't resist replying anyway; maybe Yar wants to rewrite it later.

I'd like to when time permits.  I use FreeBSD and null-modem cables
often :-) It's good that our discussion of this topic will stay in
the PR audit trail so that I can consult with it.  Thank you for
your suggestions!

> It probably should have some of the cable stuff from the "Serial
> Ports" section which says that a null-modem is AKA DTE-to-DTE cable
> and what DTE is, eg, a computer.  And terminals traditionally have
> included teletypes and printers. (Once there were no CRTs or LCDs.)

And I'd rather add a better definition for DTE and DCE, which are
mistaken every there and then.

-- 
Yar
Comment 6 Julien Gabel 2005-08-30 10:48:35 UTC
>> It might be reasonable to tell that in general, a null-modem cable
>> is for connecting a DTE directly to another DTE.  AFAIK, null-modem
>> cables can be constructed for synchronous comms, too.  Then, the
>> topic can be narrowed down to async comms.

> I doubt if Julien wants to do more rewrites on the section.  But I
> can't resist replying anyway; maybe Yar wants to rewrite it later.

In fact i don't really want to do a rewrite of this particular section,
especially since i don't have a _good_ knowledge on this topic.  The
purpose of the initial PR was to correct what seems to be an error in
the proposed table (and eventually a pointer to more information), based
on a very recent experience to get a trace after a panic via a serial
console... and so a null-modem cable.

> It probably should have some of the cable stuff from the "Serial
> Ports" section which says that a null-modem is AKA DTE-to-DTE cable
> and what DTE is, eg, a computer.  And terminals traditionally have
> included teletypes and printers. (Once there were no CRTs or LCDs.)

>> To me, www.hardwarebook.net doen't seem the definite resource.
>> IMHO, if the topic is rather wide, the reader should better be
>> hinted to do a (re)search on the Net instead of pointed to a single
>> resource, which is likely to become incomplete, outdated, or down.

> I was thinking the same things.

Ok.  Is it worth to mention a specialized book ("RS-232 Made Easy",
for example) or not?

>> We may show two or three different designs in the handbook if we
>> can tell the reader about their merits.  The problem with the design
>> currently in the handbook is that it is erroneous *and* bogus.  I'd
>> suggest adding another row to the table so that it becomes evident
>> that DTR on this side is connected to DSR+DCD on the other side
>> while DTR on the other side is connected to DSR+DCD on this side.

> The Note below the pin-out is supposed to make it evident, and with
> the Note the design is symmetric.

I tend to think the note is ok here, too.


Please find a new patch attached which resumes the recent comments
about the different null-modem designs, mainly based on the first
reply from Gary.  I think it was the most concise and do not require
a large rewriting or reorganization of the serial chapter (which can
always be made later).

Note: there are two versions of the patch.  One with a reference to
the "RS-232 Made Easy" reference book, one without it.

--
-jpeg.
Comment 7 Gary W. Swearingen 2005-08-30 16:01:44 UTC
"Julien Gabel" <jpeg@thilelli.net> writes:

> Ok.  Is it worth to mention a specialized book ("RS-232 Made Easy",
> for example) or not?

I first wrote "not".  Too few people could find the old book in time
for their need.  But it does have the important benefit of giving
readers some reason to select the alternate design and thus justify
the added paragraph's existance and discourage it's removal.  See
below.

> Note: there are two versions of the patch.  One with a reference to
> the "RS-232 Made Easy" reference book, one without it.

The first two paragraphs look OK to me, as-is.  But what you copied
into the last para from my informal comments could be improved.  For
example, I was wrong to have "generic null-modem"; there is no such
thing.  I'll also comment on the first two paras, for kicks.

+	  <para>If you prefer making your own cables (for quality purpose for
+	    example), you can construct a null-modem cable for use with terminals.

I would omit the (...); else, use "(for quality purposes, for example)"
or "(e.g., for quality purposes)").  On second though, I would change
it to simply "You can [...] with many serial devices".

+	    DB-25 connector.  A warning though: the standard also calls for a

I would omit "A warning though:" or at least "though".

+	    straight-through pin 1 to pin 1 <quote>protective ground</quote>

IIRC, that should be "<emphasis>", or something like that, so it
could, for example, be rendered into italics.


For the record: If this gets overhauled later, it should get a 9-pin
version, which is more common these days (and which doesn't even have
a protective ground pin).  Also: The design(s) _could_ be presented
once in terms of signal names (eg, SG), and then the association of
signals with pins given for 25-pin and 9-pin connectors.


+	  <para>If the proposed design seems to be the most popular, others tend
+	  to prefer a generic null-modem design like that, except it has pins 4
+	  and 5 going to pin 8 and vice versa.</para>

   <para>The proposed design seems to be the most popular. In one
   variation (explained in the book <emphasis>RS-232 Made
   Easy</emphasis>) the note doesn't apply and at each end pins 4 and
   5 connect only to each other and to pin 8 at the other end.</para>

The few who want to look for the book can start with a WWW search.

Maybe someone can double-check my "replacement explanation".
The book's diagram is something like this:

  1 -- 1  (No need to mention further, IMO)
  7 -- 7
  2 -- 3
  3 -- 2
  4+5 -- 8
  8 -- 4+5
  6 -- 20
 20 -- 6
Comment 8 Yar Tikhiy 2005-08-31 11:03:11 UTC
On Tue, Aug 30, 2005 at 11:48:35AM +0200, Julien Gabel wrote:
> 
> >> We may show two or three different designs in the handbook if we
> >> can tell the reader about their merits.  The problem with the design
> >> currently in the handbook is that it is erroneous *and* bogus.  I'd
> >> suggest adding another row to the table so that it becomes evident
> >> that DTR on this side is connected to DSR+DCD on the other side
> >> while DTR on the other side is connected to DSR+DCD on this side.
> 
> > The Note below the pin-out is supposed to make it evident, and with
> > the Note the design is symmetric.
> 
> I tend to think the note is ok here, too.

I'd really like to see the design scheme all-sufficient without the
note.  The note may clarify the scheme and help the reader to
comprehend it, but the note should by no means be crucial to follow
the scheme.  It is the matter of adding a mere row to the table:

	...
	DTR 20 connects to  6 DSR
	DTR 20 connects to  8 DCD
	DSR  6 connects to 20 DTR
	DCD  8 connects to 20 DTR

The reader is free either to install an internal strap between pins
6 and 8 in each connector or to use two pairs of wires to connect
pins 6 and 8 on each side to the single pin 20 on the other side.

-- 
Yar
Comment 9 Gary W. Swearingen freebsd_committer 2005-09-03 16:04:51 UTC
State Changed
From-To: open->analyzed

Problem has been discussed; nearly decided on fix. 


Comment 10 Gary W. Swearingen freebsd_committer 2005-09-03 16:04:51 UTC
Responsible Changed
From-To: freebsd-doc->garys

I'll work with contributor and mentor on this.
Comment 11 Julien Gabel 2005-09-03 22:11:41 UTC
>> Ok.  Is it worth to mention a specialized book ("RS-232 Made Easy",
>> for example) or not?

> I first wrote "not".  Too few people could find the old book in time
> for their need.  But it does have the important benefit of giving
> readers some reason to select the alternate design and thus justify
> the added paragraph's existance and discourage it's removal.  See
> below.

Seems fine to me.

>> Note: there are two versions of the patch.  One with a reference to
>> the "RS-232 Made Easy" reference book, one without it.

> The first two paragraphs look OK to me, as-is.  But what you copied
> into the last para from my informal comments could be improved.  For
> example, I was wrong to have "generic null-modem"; there is no such
> thing.  I'll also comment on the first two paras, for kicks.
>
> + <para>If you prefer making your own cables (for quality purpose for
> + example), you can construct a null-modem cable for use with terminals.
>
> I would omit the (...); else, use "(for quality purposes, for example)"
> or "(e.g., for quality purposes)").  On second though, I would change
> it to simply "You can [...] with many serial devices".

Ok, i will modify this part according to your proposal.

> + DB-25 connector.  A warning though: the standard also calls for a
>
> I would omit "A warning though:" or at least "though".

Same thing here.

> + straight-through pin 1 to pin 1 <quote>protective ground</quote>
>
> IIRC, that should be "<emphasis>", or something like that, so it
> could, for example, be rendered into italics.

Don't know what is the best here.  If you think it is better to put
"<emphasis>" instead of "<quote>", i have nothing against that (and
will change it in the next patch).

> For the record: If this gets overhauled later, it should get a 9-pin
> version, which is more common these days (and which doesn't even have
> a protective ground pin).  Also: The design(s) _could_ be presented
> once in terms of signal names (eg, SG), and then the association of
> signals with pins given for 25-pin and 9-pin connectors.

Without overhaul all this section, i will try to include something
about that since i agree that nowadays the DB-9 connectors are more
common, as with modern PCs (i currently use my notebook as "terminal"
for connecting to servers this way).

> + <para>If the proposed design seems to be the most popular, others tend
> +   to prefer a generic null-modem design like that, except it has pins 4
> +   and 5 going to pin 8 and vice versa.</para>
>
>    <para>The proposed design seems to be the most popular. In one
>    variation (explained in the book <emphasis>RS-232 Made
>    Easy</emphasis>) the note doesn't apply and at each end pins 4 and
>    5 connect only to each other and to pin 8 at the other end.</para>
>
> The few who want to look for the book can start with a WWW search.

I will keep the ISBN number, in order to help further search on WWW.

> Maybe someone can double-check my "replacement explanation".
> The book's diagram is something like this:
>
>   1 -- 1  (No need to mention further, IMO)
>   7 -- 7
>   2 -- 3
>   3 -- 2
>   4+5 -- 8
>   8 -- 4+5
>   6 -- 20
>  20 -- 6

I will work with you directly to provide a new patch (one is pending
behind the door), including Yar's proposition.

-- 
-jpeg.
Comment 12 Julien Gabel 2005-09-03 22:11:55 UTC
>>>> We may show two or three different designs in the handbook if we
>>>> can tell the reader about their merits.  The problem with the design
>>>> currently in the handbook is that it is erroneous *and* bogus.  I'd
>>>> suggest adding another row to the table so that it becomes evident
>>>> that DTR on this side is connected to DSR+DCD on the other side
>>>> while DTR on the other side is connected to DSR+DCD on this side.

>>> The Note below the pin-out is supposed to make it evident, and with
>>> the Note the design is symmetric.

>> I tend to think the note is ok here, too.

> I'd really like to see the design scheme all-sufficient without the
> note.  The note may clarify the scheme and help the reader to
> comprehend it, but the note should by no means be crucial to follow
> the scheme.  It is the matter of adding a mere row to the table:
>
> 	...
> 	DTR 20 connects to  6 DSR
> 	DTR 20 connects to  8 DCD
> 	DSR  6 connects to 20 DTR
> 	DCD  8 connects to 20 DTR
>
> The reader is free either to install an internal strap between pins
> 6 and 8 in each connector or to use two pairs of wires to connect
> pins 6 and 8 on each side to the single pin 20 on the other side.

I will propose a new patch with some modifications, incuding yours,
in next hours to the responsible committer (Gary W. Swearingen).

-- 
-jpeg.
Comment 13 Gary W. Swearingen freebsd_committer 2005-09-30 19:05:19 UTC
State Changed
From-To: analyzed->closed

Committed change after working with submitter on it.