Thread Rating:
  • 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
documentation improvements badly needed !
16-12-2011, 03:57 PM,
#11
RE: documentation improvements badly needed !
(16-12-2011, 03:38 PM)pingotg Wrote: Maybe there's a place to put draft documents? So that they can be reviewed and commented on / corrected.

John

Great idea John!
Reply
16-12-2011, 05:03 PM,
#12
RE: documentation improvements badly needed !
Hi,
Why don't you use the wiki ? If you make some mistake someone will correct it. AFAIK, you can also put draft documents on it.
Wiki's are made for that kind of job, aren't they ?
Régis

(16-12-2011, 03:38 PM)pingotg Wrote: Maybe there's a place to put draft documents? So that they can be reviewed and commented on / corrected.

John

It is easier to complain than it is to do, but it is better to do than it is to complain.
Reply
24-12-2011, 08:21 AM,
#13
RE: documentation improvements badly needed !
I totall agree with the lack of documentation on Pinguino language. I am a new to Pinguino and frustrated by the lack of a reference language document. How can you program anything if you don't know how to use the language and syntax etc? I do technical writing and write product manuals but I need the information and understanding before I can write any useful docs so I can't help out for the moment.

I am trying to lean C as I usually program in assembler so everything is very new to me.

Reply
24-12-2011, 12:03 PM, (This post was last modified: 24-12-2011, 12:08 PM by pingotg.)
#14
RE: documentation improvements badly needed !
I think the idea was that it was the same as Arduino language (except it's not, yet). It seems in practice that if you regard it as C but:
main has already been written and it calls
setup then calls
loop

and all is good. Read the PIC32 doc from microchip for how the actual chip works and all is fine.

Use the IDE if you like or figure out what it does and use makefiles

For C, use any good C book/tutorial. There are good ones online if you look.

Much easier than asm but still not so easy as it could (should) be. That said, understanding the chip is the biggest task. You might like to get the book by Lucio di Jasio "Programming 32-bit Microcontrollers in C - Exploring the PIC32"

John
Reply
05-01-2012, 10:45 AM,
#15
RE: documentation improvements badly needed !
(24-12-2011, 08:21 AM)magicman Wrote: I totall agree with the lack of documentation on Pinguino language. I am a new to Pinguino and frustrated by the lack of a reference language document. How can you program anything if you don't know how to use the language and syntax etc? I do technical writing and write product manuals but I need the information and understanding before I can write any useful docs so I can't help out for the moment.

I am trying to lean C as I usually program in assembler so everything is very new to me.


Just by curiosity, you are "new to Pinguino" moving from Arduino or for some other reason ?

I personally wanted to switch from Arduino to Pinguino so that I had more power (32bit) and more AD inputs (16) on a small system (micro), but I decided to stay with Arduino (the 0022 IDE !) because it is (unfortunately?) the _only_ environment that has enough stability and documentation.
Reply
05-01-2012, 08:52 PM, (This post was last modified: 05-01-2012, 08:59 PM by N3XT.)
#16
RE: documentation improvements badly needed !
For example, is there any link Pinguino32X r240 setup.exe in pinguino.cc ? You have to combine all site like jpmandon blog, pinguino blog, google code, pinguino.cc, hackinglab.org, cytron blog ...
(21-11-2011, 10:30 PM)Firatdede Wrote: Also It may be good to seperate programs. Some programs don't work at Pic32 Pingunios. It's difficult and confusing to understand and comprehend for beginners like me..:/

You are right. The pinguino32 project must be seperated libraries. It is confusing for all users ...

To Fıratdede :
Ayrıca türkçe destek istersen yardımcı olmaya calısırım hem pinguino için hemde pinguino32 için.
Reply
25-03-2012, 01:17 PM,
#17
RE: documentation improvements badly needed !
Just by curiosity, you are "new to Pinguino" moving from Arduino or for some other reason ?

I personally wanted to switch from Arduino to Pinguino so that I had more power (32bit) and more AD inputs (16) on a small system (micro), but I decided to stay with Arduino (the 0022 IDE !) because it is (unfortunately?) the _only_ environment that has enough stability and documentation.

[/quote]

I am new to Pinguino and not familiar with Arduino either. Lack of documentation has killed my initial enthusiasm. Unless thios is resolved I fear others will move away from pinguino. Maybe Rasberry Pi is something to try.
Reply
26-03-2012, 08:20 PM,
#18
RE: documentation improvements badly needed !
@magicman Wouldn't compare pinguino32 and raspberry-pi. All too different. What you need depends on your application and little else.

---

For the docs, there are two problems I see. One is, that it seems to me like the docs on libraries want to hide their origins in Arduino libraries that they are ported from. That looks awkward and does not make sense to me. These docs could simply link and refer to the original documentation on arduino.cc and mention the differences in setup and usage.
It just does not make any sense to try to duplicate documentation that is already there.

Also a language reference is not needed at all, since this is plain C/C++. A list of bookmarks refering to useful references/tutorial on these - especially suited for beginners - would be useful there.

Another more general problem is the undefined relation between the p8 and p32 ports that run in pinguino. They are based on different toolchains, one supports C++ the other doesn't, so it's not difficult to foresee, that they may further drift apart. However, the differences - will this run on p8 and/or on p32 and what may be the differences - are not clearly stated in the docs (as per library).

At the moment the best overview on ported and yet to be ported libraries is given in http://wiki.pinguino.cc/index.php/Compatibility as a FAQ... but that IMO should be put more central, on http://wiki.pinguino.cc/index.php/Libraries for example.

I fancy that something like a simple table at the core of the library docs would be handy, with the
- library name + internal link,
- name of the original library it is ported from (may be an Arduino lib or other predecessor) + link to their site+docs,
- supported on p8 (checkmark),
- supported on p32 (checkmark),
- remarks on usage differences (between base-lib/ported and p8/p32 version).

In the average case of a ported library, an entry in that table would be sufficient for documentation. That means, the actual documentation should be offloaded to the original library's docs. Duplicating efforts and space just does not make sense, especially where ressources are limited.
If libraries have their own pages in the wiki, the basic info from that entry could be repeated there too (like in a one-liner on top). Examples are always good, but without complete breadboard-wiring (fritzing) they are of little use to the beginner.

Then... the real problem for the documentation is simply, that pinguino (or this site especially) has very few active users at the moment.
Also, many don't realize, that in such an open and voluntary-work project it is up to the users to write docs themselves. This goes against a habit, where we like and expect to see something similar to the huge code+appnote libraries that the big chip-manufacturers offer on their sites.
Reply
08-01-2013, 03:42 PM, (This post was last modified: 08-01-2013, 04:18 PM by wimp#1.)
#19
RE: documentation improvements badly needed !
I strongly dislike the idea that a user has to reverse engineer a library in order to write the manual the original author didn't bother to make.
A practical example: there seem to be several flavours of serial port libraries for the pinguino, and misspelled examples, and at least one seems to be interrupt driven. there is a "OnSerialRX" event that looks interesting, but its wiki page is empty.
How do I invoke this? I am a noob at interrupts and C.
I have tried all serial comm varieties and I end up the same way: lost characters at end of line, next line may contain last chr of previous line before the \r. Or I may experience serial port lockdown due to overrun error.
Use the new Serial Interrupt Library you may say. But how??
An example would be fine. Especially for us that are past the "light a LED and type Hello World\r\n" stage.
There are several Arduino "sketches" in the X3 examples directory but I presume that Pinguino doesn't use the "sketch" concept, there is always 30% Pinguino C code at the top and 70% /* commented (Arduino?) statements */ at the bottom at each demo file.
Since the Arduino and Pinguino only are superficially similar there are so many traps to fall into. The Arduino has for example a reserved function name for serial comm. Just create a function with that name outside the loop() - it will be executed each time a complete serial text line (text+\r) is received. Interrupts will be between each statement in the loop(). I want that too!
Edit: interrupts will be between each loop lap. Worse but still good!

(I just read a similar rant about the Arduino hereSmile
http://bleaklow.com/2012/02/29/why_im_di...tform.html
Windows, Icons, Mice and Pointers
Reply
08-01-2013, 08:02 PM, (This post was last modified: 08-01-2013, 08:19 PM by pingotg.)
#20
RE: documentation improvements badly needed !
I suppose the alternative is to wait until the doc is written. This project needs volunteers, including for writing the doc.

Not to say it's ideal or to justify the situation but the RPi also lacks lots of doc. Some it is clear will probably never be released for the RPi.

I think Arduino is some years old? And funded by Atmel rather than only volunteers?

edit: I just read that blog. The same can apply here, too, but similarly you can just use the bare chip and then refer to Mucrochip doc - which is generally good. The tools you got with the Pinguino project download let you compile and load the result ("hex") onto the target PIC. You don't have to use the PDE file syntax etc. Also, you could use MPLAB if you prefer.

John
Reply


Forum Jump:


Users browsing this thread: 2 Guest(s)