Serial Docs & Documentation in General

General
1

I think the documentation generally needs to be reviewed. It often doesn’t do a good job of explaining how to use various classes and language features. To find out how things work one needs to use this forum, and that shouldn’t be.

Case in point, Serial. I spent a significant amount of time trying to work out the use of Serial.DataTerminalReady. I finally came to the forum and found out how it worked. That is: set Serial.DTR = True, set Serial.DataTerminalReady to True or False, then call Serial.Reset.

In the documentation, under Serial.Reset:

“Changes to the serial device are queued so that you can modify multiple properties of it without them all taking effect immediately. For instance, you can set the baud, parity and stop bits as one operation instead of three. The same thing applies to the line state properties. Once you’ve made all your changes, you need to call .Reset on the serial device to reset the device to the new settings.”

So the information was there. But “the line state properties”? That’s kind of vague. I only read the documentation if I don’t know about the thing already. Once you know, this statement makes sense, what if you don’t?

I am still left wondering which properties exactly are “queued”, given that I have been setting .Baud without calling .Reset, and now wondering how on Earth that ever worked, or if it did.

And Serial.DTR…

Documentation: “Enables DTR (Data Terminal Ready) flow control.”

Not knowing what that meant, it wasn’t immediately clear that this was not controlling the DTR line. Once you know what it means, then it makes sense. If you don’t?

And doesn’t one need to call Serial.Reset to have this take effect? It doesn’t say so. But you can work that out through trial-and-error, right?

You might add, say: “In order to use the DataTerminalReady property, the DTR property must be set to True. If DTR is set to False, then changing DataTerminalReady has no effect.”

And Serial.DataTerminalReady…

Documentation: “Sets the state of the data terminal line.”

That is clear. Except that the author has omitted something: in order to set the state of DTR with this property, you must first set Serial.DTR = True, and then after setting Serial.DataTerminalReady, you must then call Serial.Reset. Now if you didn’t know how to control DTR, and you looked at this documentation, you would not know that you must call Serial.Reset. So what do you do? You spend a significant amount of time f-ing around until you give up and come to this forum to find out how it works.

Now there is something else that was mystifying me, and it would take a scope to figure it out. That is, when you set DataTerminalReady to True, does the line go low or high? I believe it is low as this is the active state right? It doesn’t waste a lot of ink to mention this as well. If someone is using this property, this might be useful information.

WHY NOT JUST WRITE DOCUMENTATION THAT WORKS SO WE DON’T HAVE TO COME TO THE FORUM ALL THE TIME FOR ANSWERS? The documentation in general does not present data in a way appropriate for someone who doesn’t already know.

The company might start by sifting through this forum and finding out what questions are being asked, then go back to docs and see if the explanation can be improved.

2

You’re asking an awful lot from a Language Reference. An LR is the place to go when you know, to get the full picture, not the place to learn how to do. It assumes that you generally know how to use the class in question. And in the case of something like Serial, that you know a bit about serial I/O. Nothing in Xojo is going to teach you that. I think what you’re really looking for is a tutorial or an example project. The forum is GREAT for that.

3

I have used and still use other languages than Xojo, and frankly, never encountered that level of support. At least in recent years; should I mention paper books such as “Apple Pascal”, or when RealBasic is concerned, “RealBasic for Dummies”. That last one I keep next to my desk. Still available on Amazon for less than $5.00, it is great for beginners.

A bad workman always blames his tools. Computing has never been easy. It requires both an open mind and the will to learn. Plus patience and perseverance. The current LR is full of very good examples, and this forum has very little equivalents. Instead of blaming the documentation, would it not be more worthwhile to embrace what is available ?

BTW, I feel like Tim that the very subject of serial communication, besides touching a rather esoteric aspect of older computing, is in itself a whole field that usually requires engineering skills much beyond the purpose of a LR. But other other sources exist, like RS-232 - Wikipedia

Maybe you don’t know that precisely, Paul Lefebvre spends a great deal of time on the forum and routinely uses that to improve the LR. Of course, he is modest enough not to boast about it, so I feel necessary to salute his excellent work.

That said, anybody is welcome to suggest improvements by filing a feature request, or a bug report when something is inaccurate or incomplete. I did it myself several times, and it was usually implemented the very same day.

4

There is a section in the User Guide on serial communication, but it doesn’t sound like it goes into the detail you need: http://developer.xojo.com/userguide/serial-devices

In case it helps, Geoff did do a simple serial port tutorial that is on the web site:
https://www.xojo.com/resources/serialport.php

It doesn’t really seem like it would be practical for Xojo to document general-purpose serial communication protocols, but if you feel strongly about this, be sure to create a Feedback case so it can be considered.

5

Since I use the serial interface a lot, I took interest on reading Tom’s post. I don’t recall having to use Serial.reset much, but I do recall that it seemed to “fix” some unexplained issues. Now that I read Tom’s post, I can’t see why the following information would not belong right at the onset of the Serial class:

This has nothing to do with the overall protocol, or with how you use DTR, CTS, etc, etc. It is a direct result of Xojo’s implementation of the serial port class, and should definitely be on that very first page on the Serial class. No reason it cannot be repeated under the Serial.reset description page, but it should not just be buried in there.
If I can get the Feedback app to stop crashing on my PC, I will try to create a FR.

6

You typically set those before you open the port. Reset is not required in that situation. I use serial a lot and rarely require reset.

7

Having posted this, it occurred to me that a solution is to make the documentation into a wiki. Then the people who are here answering questions can make the amendments as needed. Its just entering the same data into a different form, so that the data is better organized.

I think it is fair to expect a software development system one buys to be documented. I think it is a great system. But the documentation fails too often. I think it is in the best interests of everyone concerned to have the docs clear. That would make it easier for people like Michel, Paul, Norman, Tim, and others who spend a lot of time answering questions here.

8

Paul, re serial protocols, that is outside of the scope of the docs.Also I don’t need an explanation of the basics of serial ports, or the terminology. I just want to know the exact behaviour of the class, that’s all.

The reason I am doing this is to talk to an Arduino. Right now I am writing a loader for the Arduino, to save my users from the need to download and install additional software for loading. In order to start the process, it needs to reset the Arduino by toggling the DTR line. Then within some short period of time (looks like around 300 milliseconds), it needs to transmit a couple of bytes at 115200 baud. Then the exchange begins. That is about as far I have reached at the moment.

A funny thing occurred as I played around with the DTR line. Having toggled it twice True-False-True-False (and verified this with a scope), then I sent out the byte (verified with the scope), and the Arduino sends back a couple of bytes (verified). But no DataAvailable event occurred. I’ve been using Serial for two years, and it has worked really well by-and-large. So this is weird.

So this is where i get into the fine points of class behaviour. Does changing the state of DataTerminalReady to False actually act as flow control, stopping the data from coming through on DataAvailable? Or is it only a control on the hardware line? Or is this problem of no DataAvailable event just a bug? Lord knows. I am left to reverse engineer it. I tried reopening the port…I think that might have helped. Just after I tried that, I had had enough of reverse engineering and decided to take a couple of days off. Today I spent the day writing and debugging low-level C code, for compositing layers of LED pixels. Easy stuff, relative to yesterday’s experience. Because I had tools that let me see inside. With Xojo, I cannot see inside. So without documentation that is clear and concise, one ends up having to reverse engineer.

9

BTW Paul I liked that tutorial though there is an error:

“This means that it is either sending data or receiving data at any one moment. It doesn’t send and receive at the same time.”

It is serial because bits are sent one at a time, as compared to parallel where multiple bits are sent at the same time. Data can flow in both directions at the same time, that is called full duplex. If only flowing in one direction at a time that is half duplex. I presume the Serial class is always full duplex.

One other point that has come up, is the Error event. Is there a way to find out what error occurred?

The documentation: “Occurs when there is an error with the Serial control. Available on Windows and Mac OS X.”

10

The old docs ARE a wiki. That never gained traction because documentation is a lot of work. What is totally suboptimal is to have 2 sets of docs.

When learning something documentation is never detailed enough. And therefore you have ample opportunity to ask intelligent or embarrassing questions. And to waste a lot of time for simple things.

11

"A wiki is a website that provides collaborative modification of its content and structure directly from the web browser. "

That is, crowdsourcing of data. The old docs used wiki software, but I do not see any way for a user to modify the data contained. So it isn’t really a wiki.

Given that the data was set up using wiki software, it should be trivial to throw that open to the users to edit.

12

We dont throw it open to just anyone
There are a handful of people that do have authoring access

I dont think the new doc site has that capability

13

opening it up under a controlled rollout to prevent bad edits/spam is difficult. Been There. Done That.

Xojo has certain “editors” that are allowed to update it. (not me and I dont want that privilege)

14

Does anyone know why DataAvailable does not fire? I am having the same problem. Is this an issue with arduino boards?

15

There was a bug under Windows.10 a few years ago, in Autumn 2015 I think, which had a feedback case -

The bug was in early Win.10 systems and was, I think, eventually resolved by a windows serial driver fix or update from Microsoft nearly a year later.

I had one application affected, and I found that DataAvailable would not fire until a few characters were in the buffer - not just one or two, but more like somewhere between 6 and 20 .

You could test this by having your arduino send, say, 20 bytes of data at the start to see if it kicks into life.

If you are on Win.10 and this looks like your issue, then a quick look at feedback should give you a more complete story.

16

Begin with using the right drivers FTDI VCP. Can be downloaded from the arduino site.

The setup the serial class the right way. You’d have to set almost all properties of the class manually.

Baud 9600 default, parity none, stop bit 1, 8 bits data.
8-N-1 is it called.

Then all the booleans, CTS, DTR etc…
Play alittle with them.

17

Thanks for the responses. I have sorted it out with setting DTR True in the connection button.
See this post
https://forum.xojo.com/46075-serial-communication-issue