Documentation and Application Notes

ALIBE · 2006-04-04 14:35

Ok, this is going to be a rough one for me. But, to make sense I'll have to give some bg.

I was trying out Acroname's Brainstem 1.0. At first glance, it seemed very very attractive to me - especially the fact that it is x-plat and one could use C, C++, C#, ASM, TEA. So I went ahead and bought their product w/ a bunch of sensors and what not.

During the course of learning, development cycle, I faced a HUGE HUGE problem getting relevant information. That is both documentation and application notes, examples, the usual drill. That proved to be a problem - I'd spend hrs and hrs on weekends digging up code in their forums (yes, it is ALL in their forums and site - PAIN), examples and how-tos - just to getting started.· Don't get me wrong, I'm avid researcher and digger-upper, but I would also expect to be able to get started and going ASAP. Once you get started, I would expect to learn more by digging into forums, googles. additional resources.

So, what are you saying dude?
I know Parallax has always been very good abt documentation, examples, how-tos, app notes, etc and providing one-stop-get-started-guide. I would like to stress that the documentation I got for Basic Stamp was the best that could have happened to me when I was getting into uCs. I want Parallax to carry on that same model and extending it further.

document the propeller spin objects extensively in the guide with ready-to-run simple examples
simple to read and follow introductory begginer's content.
provide extensive application notes that can be easily assembled and tried out
do not ask begginers to go to the forum to get started. Forums are an excellent resource for someone who has already gotten their feet wet. And, should only be considered as an additional resource. Forums are NOT cannot replace good documentation
Provide an online circuit cellar for propeller that people can submit to and discuss. I have bought so many Basic Stamp 3P cookbooks and half of the circuits are buggy. An online cellar will help rectify that problem due to the discussion element in it.

There might be many more that people here and at PArallax (are already tihnking of) can think of.

But, these above bulleted factors are the #1 issues I had w/ Brainstem folks and forced me to put the uC on eBay. I will probably never go back there due to the utter lack of organized information. More information that is disorganized is not as useful as little information that is well organized.

IMHO

Paul Baker · 2006-04-04 14:55

Eventually most of your goals will likely be met, but dont expect it to be so right out of the gate. It takes quite a bit of time developing extensive documentation and examples. The nice thing about Parallax is that they arent like many companies who make a big push in the beggining then sortof give up at a certain point. They continually work on refining documents and providing more examples. You may have noticed that there are several people both inside and outside of Parallax that are working on examples. Since the initial unveiling at the seminar; several debug tools have been developed, an ADC class has been made, an object to interface to an RTC has been made, a class of PBASIC commands have been made, and the list continues to grow everyday. Parallax has created an object submission database where anyone can contribute objects they have created. And if you look at Beau's Bode plot object you'll see that Parallax made it so you can embed schematics right into the documentation portions of the code.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
6+6=10 (Long live the duodecimal system)

ALIBE · 2006-04-04 15:20

Being Parallax's customer and hobbyist for more than 7 yrs now, I do realize and understand that they are probably the best there is when it comes to making the material available. And, that they continuously strive to making things better and refine and improve upon. No doubt there.

My point was to stress that there are many companies out there (including the one I quote earlier) that are following some subtle yet "bad model" of reaching out to the consumer. In my mind, the best reachout gesture, is to get the customer quickly up-and-running and keeping him/her motivated. That comes with getting the right material at the right time. The term "right material" is kinda covered in the bullet notes earlier. The "right time" is when I get the product - I have all I need to get rolling. Many times, people fall off the motivation tree just because of the "time slice" they are asked to spend looking up basic information.

I agree, there will never be a "final" ver of the document - it will always be "living". But, the ver 1.0 is what is important to me - as I would expect the material to help me get started.

There's always ver 2
[noparse]:)[/noparse]
·

Jon Williams · 2006-04-04 15:22

If you look at our history you'll see that we've always released products with essential information, and then -- as Paul points out -- we've stuck with it and developed a library of information for that product (especially our micros). The same will happen with the Propeller. You can wait a year or so for lots of "organized" Propeller application notes to be developed, but you'll be missing out on a lot of fun.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Jon Williams
Applications Engineer, Parallax

ALIBE · 2006-04-04 15:30

agreed.

to start off, it might be useful to see a few quick-start basic app notes.

Jon Williams · 2006-04-04 15:56

What would you like to see in an application note? Can you point to an existing note (for any product) that you consider a good model? I'm not saying we'll deliver what you want, but we're always interested in the feedback to make our own documentation better.

BTW, you can find two of my articles here: http://www.parallax.com/propeller/downloads.asp

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Jon Williams
Applications Engineer, Parallax

Paul Baker · 2006-04-04 16:19

ALIBE, if you have much experience in programming you'll find Spin to be remarkably easy to pick up. Even with a smattering of documentation availible at the time, I picked it up rather easily. It also greatly helps that the propeller is a generic hardware architecture, and the majority of special features provided are in software; because those software objects are open source (all propeller objects are), so with a little bit of determination you can delve into the objects to figure out how things are done. I have even made minor modification to one of the objects provided to give extra functionality for a project.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
6+6=10 (Long live the duodecimal system)

ALIBE · 2006-04-07 17:51

thanks Paul. I guess I must get coding before the ship leaves [noparse]:)[/noparse]

Jon,
to your question on what I'd like to see in app notes. Having examples of generic and reusable examples would be a great value-add. For example:

1. Checking battery power and showing its state in the form of LEDs
2. Hooking up GPS and steering LEDs to show compass poles or driving servos
3. Showing how propeller can exchange data w/ the hooked up PC or PocketPC (sort of master/slave mode)
4. Showing how to integrate propeller w/ Video out to TV or PC Monitor.
4.1 If it can show how to overlay text or gx that would be great
5. Showing how 2 propellers can talk to each other using IR or RF (including BT)
6. Showing how to control electric, stepper motors
6.1 if the example can talk to a specific motor - potentially hobby truck motor such as Traxxas motor or something similar
7. showing interfacing w/ I2C devices such as Devantec SRF08 Range Finder, (or something I2C)

these come to mind. I'm sure people can think of many more. As a reader and consumer of these walkthrus, I would expect the examples to be self contained and if one wants to, should be able to apply that to his/her bigger projects.

IMHO

thoughts?

Jon Williams · 2006-04-07 18:07

Sorry, I didn't state my question very well -- I'm not asking (yet) for specific applications, I'm asking about the format that you would find most useful to you. Is there another vendor that provides good app notes that we could use as a model?

All of the ideas you express above are within the realm of the Propeller, some are even in process. For my part, I'm going through all of my BASIC Stamp programs and starting to port them to the Propeller, updating the programs to take full advantage of the Propeller's capabilities. What that means, though, is I occasionally have to stop a project to work on support objects. I'm finally happy with my asynchronous timer, now I'm working on an RTC -- there's no sense in connecting a DS1302 similar device when I can launch an RTC into a cog.

Just a reminder... all those great BASIC Stamp app notes we have weren't available when the products launched, they took a bit of time to develop.· That will hold true with the Propeller as well.· We once talked about holding product deliver until we had a bunch of app notes done, but thought it would be better to put it into the hands of our customers ASAP as you will think of things and have ideas that we might not.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Jon Williams
Applications Engineer, Parallax

Kaos Kidd · 2006-04-07 18:17

...The customers will add to the App Notes as well, driving what a particular project might be, and what it encompases...
As Parallax devlops notes, so will the customers. Sharing here as well as with the developers. The general information pool is greatly expanded by letting both the private (customers) and puiblic (parallax) developers work at the same time. It's along the lines of a double blind programming test. Jon would could it differently then Beau, as I would differently from both of them. The combined information between thoes coding is what makes app notes great. Simply because they have already seed different ways of doing the samy thing. Some times better, some times not, it all depends on the issues at hand.

Parallax's app notes are a vary high quality white paper. If I had any suggestions, it would be a "for more information check out...." at the end of each app note. This would give the inquisitive reader someplace to start in continuing from where the app note left off at.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Just tossing my two bits worth into the bit bucket

KK
·

ALIBE · 2006-04-07 18:53

Jon,
thanks. I get your ?n now. So, here's my response.

I always thought Parallax's format is the best I could find. So, you BS-II app notes format would work perfect. I would only add more meat to the description - that is assume the reader is blank (like me[noparse]:)[/noparse]. Parts listing would be perfect. And, as Kaos was saying earlier, a "See Also" section would be great. And, including a link to the source code download or pointer to it on a CD would be great.

A long time ago, I used to program in Borland Turbo C and Turbo Pascal (3.0 and 4.0) and later ver. But, their documentation is probably the BEST one could find then. Suppose you are referecing a method ::biosdisk(). They would have detailed description, and a free standing example that can be reused anywhere you felt like. I was a huge fan of their prod and documentation. I later on built a many AntiVirus programs for DOS using biosdisk(). This was back in the 80's.

I think Parallax' documentation for BS-II is absolutely right on the nail. I would only consider the above suggestions
IMHO

ALIBE · 2006-04-07 18:55

Jon, I think you point on ver 1 w/ limited app notes is valid. I want to get the devboard first and may be get an updated manual.

Jon Williams · 2006-04-07 20:37

What I mean is that it's just a matter of time; the notes will come, and those that find their way to the Propeller a couple years from now will be bless with the work the rest of us (you too!) between now and then.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Jon Williams
Applications Engineer, Parallax

Maurie · 2006-04-07 23:13

Hi Jon,

I've been developing projects using BS2's, BS2e's and BS2SX's for some years now and recently a project using an MSP430F1232 from Texas Instruments. In all of these projects I was able to access the detailed schematic for each I/O pin, which showed the options available on it, direction and control of signals, and internal pull-up or pull-down resistors. For the Stamps it was necessary to go to the relevant Microchip or Ubicom datasheet, and TI has an extensive set of datasheets for the MSP430's.

Do you intend to produce something similar for the Propeller? Perhaps in the Manual coming out in June?

I have noticed some to-and-fro discussion on pull-up resistors needed for SDA, SCL and RES pins on the "Home Brew" thread here http://forums.parallax.com/forums/default.aspx?f=25&m=118363

I think a good diagram of the pin schematics would avoid confusion, and in the case of the Propeller, unlike previous Stamps, Parallax is the only place we can get it.

Thanks

Maurie

cgracey · 2006-04-08 00:29

It's very simple: just an input buffer with an enableable output buffer. No more no less.

Maurie said...
Hi Jon,

I've been developing projects using BS2's, BS2e's and BS2SX's for some years now and recently a project using an MSP430F1232 from Texas Instruments. In all of these projects I was able to access the detailed schematic for each I/O pin, which showed the options available on it, direction and control of signals, and internal pull-up or pull-down resistors. For the Stamps it was necessary to go to the relevant Microchip or Ubicom datasheet, and TI has an extensive set of datasheets for the MSP430's.

Do you intend to produce something similar for the Propeller? Perhaps in the Manual coming out in June?

I have noticed some to-and-fro discussion on pull-up resistors needed for SDA, SCL and RES pins on the "Home Brew" thread here http://forums.parallax.com/forums/default.aspx?f=25&m=118363

I think a good diagram of the pin schematics would avoid confusion, and in the case of the Propeller, unlike previous Stamps, Parallax is the only place we can get it.

Thanks

Maurie

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

Chip Gracey
Parallax, Inc.

Bruce Bates · 2006-04-08 04:55

Chip -

Does this imply that the Propeller exhibits the same idiosyncracies (described below) as found in MicroChip PIC processors, and possibly others as well. If so, any comments about them would be appreciated. My guess is that if it does, it may only appear in assembler, and not in SPIN.

1. The READ-MODIFY-WRITE situation where the pin state on a given port may change unexpectedly if the direction is change.

2. The WRITE followed by READ timing issue, where an intervening NOP may be required to ensure the WRITE is complete before the READ takes place. As I understand it, this is due to the difference between when "ready" is defined for the pin port I/O INPUT buffer vs. OUTPUT buffer.

Regards,

Bruce Bates

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

Documentation and Application Notes

Comments