A user's guide (manual) is really needed; the wiki page isn't enough

[Luke]

Let me spill my heart out. The idea was that people will contribute to the wiki and it will be an organic process that will reuire structure but not guidence. To this end, I spent a long time putting together the Project section together: http://wiki.pine64.org/index.php/Project where I hoped people will upload their projects and tutorials.

I even started on this section http://wiki.pine64.org/index.php/Knowledge_Idea, which I hoped would include fixes, external resources, videos, etc., Suffice to say, this didn't exactly work out. Despite numerous requests to contribute, help with documentation, help with writing up, provide suggestions and feedback ... I literally maybe had one or two people do something for the wiki. Perhaps others contributed something to, and I may have overlooked it (in which case I apologize) but it couldn't have been anything major.

I admit that this is very disheartening (since it was kind-of my and TL's idea), but much more importantly is also clear its not going to work and its time to move onto a plan B. The question is what would that plan actually be? I am not going to spend hours every month on updating the wiki with new projects and tutorials. New and interesting stuff literally pops up everywhere (this is just an hr ago on Twitter https://twitter.com/bobboteck/status/103...8379266048); nor do I feel like taking on the burden of documenting every new board in the future. And before someone says "have PINE64 do it" - let me just cut it short by saying that the PINE64 guys are amazing at other things, but will not produce the sort of tutorials many of you want.  

And then there is the subject of preferences of individual devs. In example, ayufan prefers to have documentation for his images on github - which include basic stuff such as flashing instructions, but also really interesting and advanced tutorials on how to overclock, use FEL, etc,. Its his hard work that benefits us all and so he has the final say as to where he wants the documentation to be. But it also begs the question of whether we should link/ duplicate/ or selectively copy his documentation in the PINE64 wiki ... this is just one example (another obvious one being RK and their wiki) but I can think of plenty more.

As always, I am all ears if you have suggestions on how to proceed.

[dukla2000]

...
I admit that this is very disheartening (since it was kind-of my and TL's idea), but much more importantly is also clear its not going to work and its time to move onto a plan B.
...

I disagree. Not that it is disheartening, but that plan B is needed.

We (all) need a big sign on our forehead that this is a community project. Pine can do h/w, Ayufan (& others) can do software. We need documentation folk too. A wiki is the best place/way to get multiple folks involved AFAIK. (A bit like Churchill on democracy - it may not be perfect but it is the best system we know!) 

So with no further ado I am diving in. We need to get (RockPro64) wiki complete enough so it can be readily used to answer noob questions on IRC or forum.

[Luke]

...
I admit that this is very disheartening (since it was kind-of my and TL's idea), but much more importantly is also clear its not going to work and its time to move onto a plan B.
...

I disagree. Not that it is disheartening, but that plan B is needed.

We (all) need a big sign on our forehead that this is a community project. Pine can do h/w, Ayufan (& others) can do software. We need documentation folk too. A wiki is the best place/way to get multiple folks involved AFAIK. (A bit like Churchill on democracy - it may not be perfect but it is the best system we know!) 

So with no further ado I am diving in. We need to get (RockPro64) wiki complete enough so it can be readily used to answer noob questions on IRC or forum.

Just don't get burned out on it ; let me know where and how I can help you (and others ?) out.

[dukla2000]

OK, had a huge hack. Several place I know need more work - needed to do a save though.

We need to sort some photos of 2.1 versions. And also a labelled version (like on the Pine64 website), but pref of a v2.1. And ideally a second version to label the LEDs, switches, connectors & jumper!

Leaving this open for now: I have a hectic weekend starting today (Friday). Could do hi res board pics at some stage, am useless at labelling them though.

[lucho]

Well, if you take photos of both sides (if possible, with a relatively long-focus lens, as otherwise if will be a perspective, not axonometric projection), then I'll try to do the labelling.

Re: Perfection – Salvador Dali said: "Have no fear of perfection – you'll never reach it." Nobody and nothing is perfect. Re: Wikis – they're made specially for collaboration like this.

P.S. OK, do take these photos, but now I decided that the existing image is enough for annotation. So I did it and updated/expanded the Layout wiki section.

P.P.S. As I initially forgot the "recovery" button, I had to edit the picture to add it and uploaded the new version of the picture. Then the wiki still kept showing the old version instead. Tried this twice without success and finally gave up, uploading the new version under a new name. Several hours later, the thought that it probably was my browser's cache that hasn't been updated and that's why it didn't show the new version came to my mind. And it turned out really so. So I reverted back to the new version of the old file. Now please, someone with administrative rights, delete the now useless page with a duplicating picture and if you want, purge the excessive versions of the picture on the other page. In other words, please clean up the mess that I inadvertently created. Thanks and sorry for the trouble – it's been quite a while since I haven't dealt with wikis, so I had forgotten some things.

[Luke]

Amazing work you guys ! Just awesome
Added NetBSD for the RockPro64 to the wiki.

[2Play!]

OK, so the question is not whether this is needed but only who could write it. I couldn't write a whole manual, but could at least add some information to the wiki page. For example, one of the most important (albeit small as it may seem) omissions is the role of the SW4 jumper. Here's what I've written elsewhere in this forum (slightly edited):

The possible combinations are summarised below (1 = present, 0 = not present, S = boot from the microSD card, M = boot from the eMMC module, X = unsupported combination):

Code:

microSD eMMC SW4 boot
   0    0    0    X
   0    0    1    X
   0    1    0    M
   0    1    1    X
   1    0    0    S
   1    0    1    S
   1    1    0    X
   1    1    1    S

Is this table correct? (I must be 100% sure before I add it.) If so, where on the wiki page is best to add it? The "Storage" section? It could also be helpful to explain how to remove the jumper "on the fly" several seconds after turning the power on in order to boot from the microSD card but then obtain access to the eMMC card. (This trick has been discussed elsewhere on this forum.)

I think its close enough. In the noobs it states:
There is an unlabelled (on the PCB silk-screen) 2-pin jumper (15) between the eMMC socket (13) and the SPI chip (16). The default condition is OPEN (no jumper). It is useful for controlling the boot as follows:

Default boot device (with no SPI software) is eMMC, then SDcard. If both the eMMC and the SDcard contain bootable images then the eMMC can be disabled by installing the jumper. This completely removes the eMMC from the resulting OS. If you wish the eMMC to be visible in the booted OS the jumper should be removed 2 seconds after applying power (and before the white LED comes on).

[Luke]

Thanks for all the feedback and hard work! Just a suggestion: do we want to open a thread under general regarding the wiki, so we can: track what content people want to be see added; so people have a place to report mistakes/ dead links; what users would like to see changed; and ultimately what people wish to contribute?
Eventually, the same work that is being done on the RPro64 wiki site will have to be done for the other boards / devices too, so moving the discussion to the general section is probably more fitting for the undertaking. Let me know what you all think.

[lucho]

You're welcome!  Yes, I agree that a general thread devoted to the wiki in the "General" section of the forum is a good idea. But regarding the board-specific information for the RockPro64, I'd prefer that we continue the discussion here, at this thread.

Re: my SW4 table – I will then add it, if there are no objections, as the current information is not exhaustive (thorough). It doesn't, for example, answer the question what happens if both the microSD card and the eMMC module are installed, but the jumper is not. It just won't boot when power is applied. And by the way, I haven't yet explained to myself the "jumper removal after power on" trick. How exactly does it work? Because of what? Can someone explain it in details? (I mean the internal mechanism due to which it works, not its usage, which has already been discussed.)

[dukla2000]

You're welcome!

ditto

Yes, I agree that a general thread devoted to the wiki in the "General" section of the forum is a good idea. But regarding the board-specific information for the RockPro64, I'd prefer that we continue the discussion here, at this thread.

Agree, and agree.

I am struggling with the NOOB wiki page and feel it is the same problem: on the one hand having a single page that references all Pine products is "nice". On the other it needs to cater for too many exceptions - Allwinner, Pine64 installer, 2A/3A/5A power supplies etc. I read the NOOB page at least 3 times while my Rockpro64 was in the post and was unable to decipher my path - I have been using arm SBC as my only PC for over 2 years (RPi 3, VIM2) so figure I am not too dumb!

As the NOOB page didnt help me, and in line with lucho OP, I figure we do need a ROCKPro64 specific "get it going" section: I have scoured the NOOB page again but cannot see a way to make ROCKPro64-specific info easily available. Because there is a lot of info to try cover for NOOBs (have they got eMMC, WifI card, NVMe etc etc) think we need a NOOB page for each model rather than trying to update the single existing. Or adding more to the main ROCKPro64 page.

Other thoughts/ideas for this welcome though.

Re: my SW4 table – I will then add it, if there are no objections, as the current information is not exhaustive (thorough). It doesn't, for example, answer the question what happens if both the microSD card and the eMMC module are installed, but the jumper is not. It just won't boot when power is applied.

No - it will boot from the eMMC. (Double checked this morning on my system and amended the wiki!)

And by the way, I haven't yet explained to myself the "jumper removal after power on" trick. How exactly does it work? Because of what? Can someone explain it in details? (I mean the internal mechanism due to which it works, not its usage, which has already been discussed.)

My reading of the schematic indicates this removes or shorts the eMMC clock. So if you have a bootable SDcard in place (and leave the jumper on) 111 effectively becomes 100 (as per your table) as there is no effective eMMC present. So u-boot can only find a bootable image on the SDcard and proceeds with that for an initrd etc.

The limitation of this is you cannot work on the eMMC at all after boot - /dev/mmcblk1 has not been initialised in the kernel. There are in fact 2 ways to work around this:
1) Remove the jumper before the white LED comes on. The means that rootfs has not yet been mounted - when it does mount it can see and enumerate the eMMC. (But as u-boot identified the SDcard in the first place all boot/kernel stuff comes from the SDcard.)
2) After boot completes and you get a command prompt you can also remove the jumper, and then run /usr/local/sbin
/rockpro64_reset_emmc.sh which will trigger initialisation of /dev/mmcblk1. Havent tested this myself.
(I needed this get out when I corrupted the eMMC enough so it would not boot. But not enough so that it still said to u-boot it had an image!)