GPIO module documentation

It is my feeling that the GPIO module StrongHelp manual should be included with the distributed documentation in the HardDisk4 archive.
Given that RISC OS Open promotes itself as being useful for hobbyists, one of the most important pieces of documentation for hobbyists is hidden away in the source tree. Unless someone knows exactly where to look already, they will never find it.

Probably a good idea to distribute it, but the HardDisc archive is in use on platforms that don’t have the GPIO pins – RPC and RPCEmu are the obvious ones.

My favourite subject…lack of or poor/incorrect documentation!

Is the documentation in question on the wiki? That should really be the central point for it all, not obscure source code or StrongHelp manuals.

I may well be wrong, but I recall the GPIO documentation mentioning that the current GPIO module is platform agnostic. I think it_s to do with SWIs and maybe star commands. So I guess on platforms without GPIO it’s useless. However for platforms with GPIO, and the GPIO module implemented it’s extremely useful.

If it’s in the Wiki I haven’t seen it.

There’s this page on the Wiki, but AFAIK it no longer applies. I just tried installing GPIO and GPIOConfig and got GPIO SWI out of range.

https://www.riscosopen.org/wiki/documentation/show/Beginners%20FAQ:Programming

Really I’d love to see a Wiki page on how to utilise the hardware such as GPIO, IIC and SPI, even if it had a platform specific preamble. It’d make a lot of functionality more accessible to the largest potential demographic. Ie Pi users.

Is the documentation in question on the wiki? That should really be the central point for it all, not obscure source code or StrongHelp manuals.

StrongHelp manual in a docs directory (BCM2835Dev\bsd\RiscOS\Sources\ThirdParty\TankStage\HWSupport\GPIO\Docs\GPIO,3d6) of the source download for BCM2835, similar in OMAP3 (haven’t looked in the other new board archives).
So, that ticks two annoy boxes at once for you. As a result of being hidden away it appears to be somewhat out of date and doesn’t list various current boards.

I wonder how easy a StrongHelp <—> wiki format converter would be? (Knowing my luck there’s probably a StrongHelp <—> HTML converter already if we go looking).

StrongHelp is, after all is said and done, just a set of markup files stashed inside the StrongHelp file.

The GPIO StrongHelp manual is distributed as part of the RC16 image, but annoyingly the only way to get hold of that is to burn a 2GB SD card and then copy the data off it! It has been suggested before that the Pi disc image should be available to downlaod as a zipfile, but for some reason this hasn’t been taken up.

I wonder if todays change in CVS “Auto generate packages of some disc components” is aiming to be a complete disc image eventually?

Looks to me like the foundations of a package manager update setup for the disc based components, in which case people only download the specific items they need.
Reduces bandwidth requirements at both ends as well as allowing client end controls on what is updated/overwritten.

This is excellent news. Glad to see a start has been made on packaging the contents of Diversions, Utilities and Apps.

The GPIO StrongHelp manual is distributed as part of the RC16 image, but annoyingly the only way to get hold of that is to burn a 2GB SD card and then copy the data off it!

Or go to my web site, look up where the GPIO module resides and load it from there

Or go to my web site, look up where the GPIO module resides and load it from there

Which would be a prime example of exactly what Tristan was talking about with this comment:

Given that RISC OS Open promotes itself as being useful for hobbyists, one of the most important pieces of documentation for hobbyists is hidden away in the source tree. Unless someone knows exactly where to look already, they will never find it.

Unless of course you can give me a good reason why a NOOB would even think to look on a web site they have never heard of before to find the info on how to dig in to the CVS and pull out a set of information in a format that requires a special (platform dependent) reader.¹
Tristan was saying it should be accessible and Jon pointed out that the wiki was the logical place to ensure it is accessible to all with ease.

Compounding the problem is that a quick check through the StrongHelp manual shows it to be out of date, probably as a result of being well hidden and thus not getting a review/rework anymore than some of the old Acorn wishlist notes etc that are also buried in the CVS content.

¹ I’m sure Arthur Dent would recognise the document storage technique.

go to my web site

???

Looks to me like the foundations of a package manager update setup for the disc based components

This is excellent news. Glad to see a start has been made on packaging the contents of Diversions, Utilities and Apps.

More specifically, it’s a continuation of discussions ROOL have been having with Alan Buckley since 2016, but they didn’t get very far because of the intrusive and widespread nature of the changes required to make the packages, and behind-the-scenes technicalities.

Subsequently in August 2018 some server upgrades meant that the nightly builder now resides on the same farm as the packages so it should be somewhat easier to join the dots.

More time passed and the change from Castle to Apache licence work required dotting license terms around with each component.

Then, somehow, the task ended up on my todo list (a place where many things wait to be done for varying amounts of time). That finally piqued my interest yesterday afternoon to produce PkgHardDisc4 which brings all the bits together.

Don’t hold your breath though, it’s back over to ROOL to do some server side magic to copy the results over; outside my skill set.

Unless of course you can give me a good reason why a NOOB would even think to look on a web site they have never heard of before to find the info on how to dig in to the CVS and pull out a set of information in a format that requires a special (platform dependent) reader.

There are clues – the ‘,3d6’ suffix to indicate that it is a StrongHelp file. Anyway I produced a list of ROM modules with a link for each to where the source was located for my own purposes. There is, of course, full information on display in the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying ‘Beware of the Leopard’.

There are clues – the ‘,3d6’ suffix to indicate that it is a StrongHelp file.

Fail.
I got a BBC B when they first came out and I wouldn’t know that was a StrongHelp fie without looking up the filetype info on the wiki.
I’m a career geek so the ,3d6 as a file type (instead of something like .doc or .txt is something I know.

But a NOOB?

BTW. You contributed to the obscurity with (as John pointed out) “…go to my web site…” which wasn’t a link.

Fail.

What I see here is people who have specific system related knowledge not realising that people who do not have such knowledge would be lost.

Filetypes are pretty much unique to RISC OS these days, and “3d6” is gibberish if you don’t already know of StrongHelp and it’s filetypes and why it looks like that in CVS.

I’m with Steve here – try again…

I’m with Steve here – try again…

There is also the trivial typo on the GPIO_Info page which needs “higest” replacing with “highest” in two instances – something which might have been corrected earlier if the document had been more accessible.

BTW. You contributed to the obscurity with (as John pointed out) “…go to my web site…” which wasn’t a link.

Indeed. You will also find that only clues are given in the StrongHelp file to such things as tracking events (as far as I recall).

If a piece of software is provided as an application, there is a standard way to obtain help (the ‘Help’ menu entry, the !Help file inside it and by using the !Help application with the mouse over the icon bar icon, a menu item or the window’s work area). When something is provided as a ROM module (or as a Module inside HardDisc4) then all you have is ‘*Help GPIO’ (the module name). It would be really helpful if the various *ROMModules, *HELP Modules, *Modules or *Help <Modulename> could offer similar functionality as the !Help for an application. Not sure how I would do this but I can make the suggestion as this is the ‘Wish List’.

For the Pi there is indeed a StrongHelp file for the GPIO module in Utilities.!Manuals.Root.GPIO but this isn’t an obvious place to look. So it is in the standard (extended) HardDisc4 provided with the Pi SD card image (but nowhere else).

The Pi SD card image for RISC OS 5.26 is also hidden and can only be obtained indirectly via NOOBS. So the NOOB has one advantage over the rest!

All of which ignores the fact that the StrongHelp file is wrong in places (try the primer) and inadequate in others – try to find out from it what Mode and Group are for. Features seems to return a bitmask of 0 on all the pi’s I’ve tried it on. What is returned in features, and how should it be decoded? If indeed it does ever return anything.

My rather understated “As a result of being hidden away it appears to be somewhat out of date and doesn’t list various current boards.” obviously didn’t go far enough.

BTW. I tried skimming through the primer and despite not personally knowing a great deal about the setup I could spot that it was wrong due to antiquity.

Needs some TLC.