PJRC and Teensy(s) need a Wiki

defragster

Senior Member+
Paul makes awesome [declarative and helpful] one off posts like this that get lost in the forum - don't get back to the website and are not readily searchable on the forum - if it hits it may be within a 10-25 page thread:

https://forum.pjrc.com/threads/2871...ies-timer-issues?p=73823&viewfull=1#post73823


With an index linked list of Paul's "top 100" forum answers in WiKi style a question could be answered once - post the Wiki and drop a link on the forum for new expositions. In short order a better resource would exist.

Libraries could show Github link where current bugs could be checked, and items common to Arduino could link there. The wonders of the Teensy card could be explored and filled in once for easy reference.


Here is a summary of the need as I saw it well expressed by someone in response a first time poster:

many of the Teensy website pages are implicitly for Teensy 2

PJRC needs to take a break and correct the web site and clarify which web page discussions apply to T2 vs. T3. Or delete obsolete T2 pages.

Sorely missing is a simple way to find what T3/LC libraries exist and how to use them and where they are centrally distributed.

T3 can do pin change interrupts, rising edge, falling edge, either edge, and so on. On many different pins. I'm not well versed in the details on attachInterrupt() vs. pin numbers permitted.

I noted before I've seen WiKi's as a good way to make current and present Library and Device info here are a recent and prior example - a couple clicks and you can find things and at least the second I included because it offers good searching:

http://www.esp8266.com/wiki/doku.php

http://digistump.com/wiki/
 
Oh, yup, many copies on the website are old.

Removing all of them and replacing with links to github is on my TO-DO list....

Wiki style would allow easy updating compared to the website to keep the info current - like Github links as noted.

Hmmm... maybe the website needs some updates about how to get fast signals. The pages were written back in the AVR-only days, when you just couldn't make a pin toggle faster than 8 MHz.
 
Last edited:
This does seem like a very good solution.

Pages for libraries, various hardware aspects, tutorials, a singular place to find all those funny technical details (pin 33).
 
This has been suggested many times and always ended up just like Paul's top 100 posts - somewhere. Paul at least once said that he would like to have a wiki, but couldn't work on it before July 2014 (I think).
 
The earlier wiki discussions hang around a decision. Specifically a decision on which wiki engine to use, since having the content hosted off PJRC on a third party wiki site seems a bad idea, as did anything that sucked Paul and Robin's time to administer, more than de-spaming this forum already does. So the current hold point is somebody other than Paul sitting down with the current options for building a wiki, making each of them work and finding all the gotcha's he doesn't have to, and that hasn't happened yet.

And I'll freely admit that learning how to set up a dozen different wiki's from scratch doesn't exactly fill me with excitement either.
 
Maybe I could offer to host the wiki, at least to start one, if Paul is interested. I wouldn't mind letting him point 'wiki.pjrc.com' at an IP address I'd give him so that he/we could try out some wiki software; I could do it using a sub-domain name of my own if need be, I've had the daggiest (imoo) domain name on the entire internet (daggiest site at least) for quite some time now.

I think the ideal thing would be for the wiki integrate with the forum so that users of the forum with more than 'x' posts are allowed to edit the wiki - this should cut down on the needs to defend and repair the wiki that much - wikis that just let anybody sign up and edit need vigilent defenders.

I've seen one of those threads before, I've mentioned similar to at least some of the above in one or two of them too.
 
Unlike the Forum the authorship could be more regulated - start with only the folks who got BETA LC's (and those supporting Libraries). Tying it to the Forum would be as important.

If PJRC got the format started it could grow from there - as WiKi's should - the Forum is one of the best parts of Teensy - but is so Opaque and even "on topic" posts can have the right answer buried, or evovled.

I've been here just over 3 months and posted this in a 9 page thread - this I knew existed and came up on page #7 with a search for doxygen:
LOL, yup. I tend to take on overly ambitious projects... like currently rewriting the SD library, when I probably should be putting more work into documentation.

Again I have to agree with Paul here - if documentation (a WiKi?) got off the ground it could help more people be more productive faster for all involved than even a 110% solution on Debug. You only have to debug when execution doesn't match expectations. Sometimes the failure point is: end use(r), library bug, hardware anomaly - all of which tie to Documentation. And the debugger will need documentation too for use beyond some awesome core group.

There was a query for 'what next' and I posted this and should have made this BUG sooner:
https://forum.pjrc.com/threads/27873-Arduino-org?p=70580&viewfull=1#post70580

Also libraries commented for Doyxgen would be an awesome tool - but those web pages won't dump on a wiki? They'd need cross linked to a server like the FORUM and PJRC pages would.
http://www.airspayce.com/mikem/arduino/RadioHead/index.html
https://forum.pjrc.com/threads/2558...alog-pins-as-Digital-Inputs?highlight=doxygen
https://forum.pjrc.com/threads/25904-How-to-use-Serial-readBytesUntil?highlight=doxygen
https://forum.pjrc.com/threads/2439...Teensy-3-0-ADC-as-a-library?highlight=doxygen

I get ZERO forum hits on "ADC" and 34 for "ADC0" : first one of which is the 7 page evolution of:
ADC library update, now with support for Teensy 3.1 Started by Pedvide, 04-06-2014 09:18 AM
When I bing "PJRC ADC" I get this first and then the direct link to the above forum post :
Using Analog Inputs
Teensy 2.0 and Teensy++ 1.0 & 2.0 have a 10 bit analog to digital converter (ADC) which can be used to read analog voltages, such as signals from sensors. Teensy 1.0 does not have analog inputs.

There would have to be good layout to incorporate all the above and more - like links to PJRC and Shared OSHpark boards and hardware too that shows up on Tindie - not just for self promotion purposes - but Paul purposefully defers to others - those items are an important part of the Teensy system.
 
Last edited:
I'd be willing to help with the little I know.

I'd argue that there should be broad sections to cover topics like the ADC from a hardware and software perspective and how the Teensy/Arduino environment integrates all that. There should also be separate pages with examples and tips regarding issues like input impedance, ADC sampling speed, resolution tricks like decimation, and so on.

Sections should also include a corner for folk who want to roll their own Teensy, what works, what doesn't, suggested BOM components, and so on.

As I see it, we could start this series of pages on a web-site of choice, have a go at it and then see if Paul/Robin want to host it at PJRC or keep it separate. I'd be happy to contribute to paying for the site, etc.
 
Anyone with a ToDo list like Paul - or even a pillow - has better things to do than documentation. The general rule is 'get somebody else to do it' - in this case the WiKi format and Doxygen could help with that.
Paul probably could design the TOC and general article flow and migrate the PJRC web topics in days that I would assume a week+ for given his grasp/retention of the subject matter and his productivity level. The biggest ( and perhaps best part ) would be to add Doxygen for the best of the 80 libraries and the code in cores - but with pull requests from (co)authors and comment only changes they'd just need merged.

On someone else's thread:
https://forum.pjrc.com/threads/28598-Suggestion-how-to-make-teensy-much-simpler

Suggestion - how to make teensy much simpler
One thing that is still a bit undeveloped with the arduino is concurrency and non-blocking libraries - and it makes it harder for beginners to write code, especially complex code, because of timing issues.

I posted:
How much could be done through documentation and samples and a model showing how to program well and not use delay() and cooperatively do what you can while waiting for what you need? This could make it 'simpler' learn and to do the right thing. The Teensy system of LIBS and HDW is awesome - but takes a good sample, deep dive into lib sources, or too often a reply on the forum:: GO WIKI!

To this end there could be a WiKi section devoted to concepts, models, Idioms or Programming paradigms to solve common issues, Intermediate to Advanced versions of the EXAMPLES included with the TeensyDuino install that are more developed - like: Concurrency, not using Delay, Debugging schemes, Serial [any BUS or I/O], Interrupts, Inline ASM, digitalWriteFast, Compiler keywords like 'FASTRUN', BIT and REGISTER manipulation, links to 1000 or 4000 LED and other published projects, Servos, Audio, Buttons. These don't have a single right answer - but a WiKi list to text or clean sketches could all lead to less time debugging and recurring problems and question/answer sessions.
 
As a relative newbie, often struggling, a wiki of some sort might make some searches easier, and easier to find the "nuggets" often buried in the forum. I have also found that an external search engine, with "pjrc" added to the search terms, more often quickly finds the specific content I'm looking for on the forum.

One thing that I am often stalled by, is that I tend to prototype, a subset or concept for a project, on a vanilla Uno or similar, and then move to Teensy 3.1's when things are working, and all the pieces are pulled together. That means keeping lists and links for the various gotchas, like pull-ups for I2C, or pin restrictions, or library incompatibilities/differences. And if time has passed, occasionally things don't work, or libraries have been updated, etc. The half-life of Teensy knowledge can be very short if you take any time off or snooze between projects.

A wiki certainly seems like it could be a good way to collect the "nuggets" and potentially keep them updated in a central, easy to navigate place. But I'd hate to see Paul have to take any time away from the things that only he can do.
 
Finding this post 3/8/15 weeks after I showed up Maybe make up a 'Tutorial 0' page - "Welcome to your Teensy". prompted this:

Yes, the entire website is in need of a LOT of work. Realistically, that's a huge project which isn't going to happen quickly. Several small, incremental updates of course will.

After Teensy-LC is released, and after doing a few dozen little but really important things that have piled up over the last couple months, I'm probably going to turn my attention to debug. In deciding what to do, and what to not do (or delay for a long time), I believe getting real but low-cost debug on future Teensy is probably the best direction that can benefit the most people.

But in the very short term, some way to improve on-screen messages or other info people actually see (nobody really reads documentation) about the pushbutton needs to happen. I just don't know how to get that message across.

So this isn't news to Paul, I'm just pulling my prior thread notes together. This note brings my BUG full circle: "(nobody really reads documentation)"

The up to date doc [outside this AWESOME FORUM] is the 1300+ page AVR manual, and the other small one, and the source code which isn't 'generally' readable (at least not using the "one hour rule" when you don't have prior context or know the source tree).

Without current and accessible documentation the best debugger will often make clear that you don't understand what just happened - which is why there is a bug.

With good documentation - and understanding of the proper flow/concept - two printf's and re-reading your own source is all the debugging help generally needed. This is what often happens when the Forum Rule is followed, in posting code that shows the problem it is often apparent when you know what to look for.

In the event this "Better Docs sooner" BUG - seems like [rant] I'll add [/rant] and :). I'm wholly impressed by PJRC and the Teensy product and environment!
 
Shall we simply go ahead and create a site and host doxygen on it?

I've never implemented such thing. Some folk also suggest that Github can be made to host it. May be a good idea given the number of github repos with libraries on them.
 
Last edited:
Paul was asking for more time not more work - if he can sign off on the first pass as he should "own" it in the end [updates and server hosting so it stays alive] - I suppose there is trust for the Sr. FORUM collective to assure a good product. Any 'comment' source mods for doxygen are harmless and transferable once merged.

Getting doxygen started so Paul can see the ease and value and ideally integrate it into Building at TeensyDuino update time might be helpful. The little I played with it, it seemed each library would need its own DoxyConfig to be executed? Perhaps a simple script if it runs from CMD line.

Since it isn't a Wiki or combined with one, that is the other half that might affect the best way to do it to allow unbroken hyperlinking in the end. I'm not sure how transportable wiki DB's are - but the PJRC.com source is 493.7MB and posted for download [ 566 HTML and Text Files , 1599 Images (JPEG, GIF, PNG) ]. Pushing The Teensy part of that to a common format on the chosen wiki would be a chore and should be done right the first time. If it was blindly cut and pasted - it could then be extended/updated over time. Maybe just the Core AVR stuff goes first?
 
Agreed that Paul and Robin should own the product, control it. I don't quite see the reason that we cannot start to build the pieces.

That is, WE develop a site that allows chapters, etc. to be added later as needed and Paul/Robin edit and sign off on the stuff as time goes by. That way, Paul or Robin don't have to get involved unless they want to be.
 
Last edited:
Cool - as noted any public code mods are (only) done for good once merged to the source. I thought I saw signs of a doxygen [super]user here once - maybe they'll hit the thread soon. There might be a known best way to walk the tree and make the underlying config.
 
1) Maybe not obvious enough before: I would host 'tester websites' for PJRC free of charge and surrender all relevant databases and files to PJRC on request. I'd also just let the stay on my server, heaps of room - 2 domains websites and emails hosted on an ubuntu text only server system capable of 100s more sites (of the kinds already in place).

2) Doxygen puts onus on source code to include documentation to the best of my understanding of it, I don't think that is as desirable as a wiki style of documentation (of which the source page could be generated using doxygen anyway) where there is greater opportunity to authorise more editors with less effort on behalf of any repository owners (who would get a new pull request any time anybody wanted to update some documentation - that would be annoying, ratio of pull requests for documentation instead of code improvements 100:1 probably).
 
Maybe I could offer to host the wiki, at least to start one, if Paul is interested.

That #6 and #17 sounds like a great way to start robsoles - I was hoping to see Paul pop in to indicate his interest and direction. If he created the TOC and style and components that would be uniformity he could support.

I have not looked at any wiki cores other than as a general user. If there is one that has a history of being secure and supported and maintainable with good search with decent UI and edit facilities that would run on your server we should find it.

Doxygen is based on uniform source code commenting from what I've seen. Comment header blocks on functions get pulled up. It scans source files and exposes code and vars and defines in any case and that are indexed and cross referenced. It spits out HTML files (or other) that show up in a hyperlinked set of pages like shown here: RadioHead Packet Radio library for embedded microprocessors This requires comment insertion and ongoing maintenance in the code to the degree accurate detail is desired (including sketches there are 1973 files showing in the 80 library directories). Also the script and time to parse the source files to generate the web server output. I pointed it at my LIBRARIES directory on my old i5 laptop and it took a few minutes - but I didn't break the libraries out individually so it picked the first and then made everything else a subset resulting in 70 megabytes and 4000 files.

Doing WIKI and Doxygen means two repositories, where one takes source edits. But if a fashion for library edits is chosen that doesn't sit in the code then it is more likely to diverge over time, and not be as complete as Doxygen parses the code and associates it with indicated comments.
 
I've looked into it before and pointed out an open source wiki which integrates with vBulletin, but I see your point about doxygen - there is probably a version of (or plugin for) doxygen which spits out wiki formatted text instead of pure HTML and, for people who don't want to learn anything about HTML that could make adding errata or other extra info (tips, shorter examples etc) to the doxygen output more comfortable.

I am a smidgeon tempted to set up vBulletin 4.2.2 on my server and then try to add that 'compatible' wiki and check out doxygen some more - of course this would add to my already slightly overloaded days for a little while but it would give me/us an opportunity to make suggestions to Paul based on something that we can demonstrate working (to at least some extent).

I'd prefer it if Paul said something along the lines of 'yes, check that stuff out for us' (so to speak), but, if just two or more of you others who are obviously genuine contributors (list of people who received the beta LC is good starting point, agreed) press me to proceed into my temptation then I will - please be patient tho, I am pretty quick at plenty but stalled by plenty else (boss, staff, clients & machines at my work all want a piece of me regularly...) so I need forgiveness from time to time ;)
 
. . . I'd prefer it if Paul said something along the lines of 'yes, check that stuff out for us' . . .
Agreed.

In my doxygen scan it hyperlinks to the on disk sources (TeensyDuino libs dir) on my machine in place from the web page. This was awesome - search - click - follow reference - click - SOURCE file. Very handy - so for a doxygen build having the source on the 'build' machine for access completes the feature set - and the paths work out relative to the server. The same would need to be done and updated for any non-included libs and the path would have to resolve out to what's coded in the html.

Also the scan of the sources as they stand didn't result in an empty tree. Even one header on each main library file could provide links to other resources (wiki - github - pjrc.com) or a summary.

I'm don't see the dual DB being an issue - as long as they start and stay relative to each other they should happily so-exist with proper setup. That's why getting too far into this on a domain that PJRC doesn't own could result in broken links if taken on later. ( like: wiki.pjrc.com and pjrc.com/doxy [ like this works :: http://www.airspayce.com/mikem/arduino/RadioHead/classRH__RF22.html ] )
 
I think I want to see how torturous it might be to set doxygen (and relevant libraries/other-files) up on my server as a service over HTTP - if it isn't too arduous an ordeal maybe we can show Paul, or if he wants nothing to do with it but would point a sub-domain of pjrc.com (namely, doxy.pjrc.com) at a server that promised not to be malicious then that would be ok by me (prefer to keep PJRC in a position to take the files off my server and host them elsewhere with little/no notice to me tho).

PM for you later, defragster, pretty sure ;)
 
I use doxygen to make self-documenting code quick and easy. It has to be so or many won't do it!

And learning to use it - I just chose a few simple things to note for each function, make a simple main page, put @file in every file, and notate key globals and constants.
Doesn't take long at all - esp. isince I elected to NOT learn much about all the frills of doxygen. Just copy the bare minimum of techniques I see in others' code.

Some make PDF from doxygen html and distribute that.
 
I'm certainly fine if the more seasoned and experienced Teensy community, e.g., folks who got beta LC's and those supporting libraries, band together to contribute a wiki for sharing accumulated knowledge about Teensy 3.0/3.1. I'd be happy to share lessons I learn too, but perhaps in the short term I should do that through blog entries and code shared via my github account if we want to take a more moderated approach to centralizing Teensy 3 wiki content. I'll watch and see what happens.

I totally understand Paul's prioritizing development over documentation but would be saddened if we avoided a basic, structured way of sharing community knowledge because we felt the only choices were (1) comprehensive, chapter-oriented material from strongly authoritative sources or (2) no docs beyond the current web site mixture of lots of Teensy 2 material and only a little Teensy 3 material. My vote would be to create some mechanism for sharing because, as is clear through this forum, Teensy is such a great platform people using it are motivated to contribute.

Let me know what I can do to assist. In the end anything that allows people like me to google successfully for solutions using error message fragments or simple keywords would be of great value. That's certainly how I became familiar with Arduino, Raspberry Pi, ESP8266, etc.
 
I can write stuff about the ADC library, at least the software side, I'm not too good with the external hardware part of it (buffers, amplifiers, etc).
I think ideally everyone who wants to collaborate should have an account to write/edit stuff, but it shouldn't be 100% open for everybody (no anonymous accounts) to avoid spamers.
 
Back
Top