Guide and Technical Wiki

Continuing the discussion from New Blog!:

This all looks really great. One question, how will the Guide and the older Wiki fit together? I noted you had included a ‘technical’ section in the Guide and just wondered if you were intending to migrate all the documentation to this? Your initial thoughts on the Guide were that it was for a ‘new user’. As someone who has struggled to find the right bit of information in the past, I’m keen others have an easier time :smiley:

Yes, we will be moving over some technical info. However we won’t be just copy and pasting from the wiki. It will more likely be a refined summary of the important snippets, possible with links to the wiki for more in depth info.

It’s always a challenge working out how and where to present documentation and to what level. I would be interested to hear if you have any thoughts on specific items of documentation you think would be useful to be on the new guide site.

Keeping in mind the idea of the guide site is:

“Just the information a user should need to setup and configure the OpenEnergyMonitor system”

We don’t want to overload the user with too much technical info, however I think a technical section of the guide is important to give a technical overview of the system and link to the relevant sections to get more in-depth info.

But this statement needs a bit more definition as to what basic knowledge is assumed? Someone familiar with the Pi has a significant head start, but if you want to help a very basic user the guide needs to be refined (IMHO).

I think I found a dead link

gives a nice 404 right now :innocent:

Rather than assuming what knowledge and/or skill sets a user might have, why not come straight out and tell prospective users what knowledge and skills will make dealing with an OEM system easier?

Not that they require those skills, but the fact that if they have at least some working knowledege in the applicable areas, things wil be easier, maybe much easier, for them.

OEM isn’t exacly an entry level project, and it’s not rocket science. But I can see how it might be percieved that way by somone just starting out.

Yes that is what I mean. By assuming, I mean the point at which you start the level of instruction (and say what the reader needs to know).

And what if they don’t know? We need to be careful that we don’t frighten off those who lack the “assumed” level of skill but are ready to and want to learn.

Unless of course that’s what we want to do.

I know (I really do know) how hard it can be to steer someone through the very basics, but when they turn round and say “I learned a lot…” it makes it kind-of rewarding.

Thanks, been fixed.

I totally agree. It;s very rewarding. lacked of perceived knowledge is no barrier to entry. IMHO everyone should be able to setup and use an OEM system. If they run into issues the problems are most probably with us and our systems or lack of documentation. We would really like the Guide site to allow even non technical users to setup the system. Although I agree, a bit of tech knowledge (e.g. SSH connection etc.) would go a long way.

I’d hoped that was my point. If the aim is to be able for someone with no knowledge use it, then I’d suggest we need more info (it is easy to forget that you now somethings implicitly). Equally, if it starts from too low a point, there is a risk of making it too big a job.

I’d be inclined to find suitable information out there for the basics and point folk to those resources and say that they need to be comfotable doing xyz to easily get started.

I can already be a good example :slight_smile:
This weekend I intend to update my emonpi … I couldn’t find a simple topic on how to upgrade … found the guide for install, but do you have to go over a complete install to update?
I saw on emoncm admin an update button, but it doesn’t react (logs are not showing anything moved since initial install done by OEM etc…)

It is possible that me, as newbie, didn’t dig enough yet but still … sometimes a simple topic with 'how to upgrade xxxx ’ with a few lines to explain if possible or not and if possible, how, in some step by step guide .

First time you try something is always with a feeling “hope I’m not going to break it” . Next upgrades are mostly easy as we have ‘already done it’.

1 Like

Eric - this is what I’ve created for my own use using a Mac and is not ready for prime time. I can certainly comment this better for others.

Upgrade emonPi - Create new SD Card

All commands done via the Mac Terminal app.

Format new SD Card on Mac OS X
(from Raspberry Pi Documentation - Getting Started)
Run to determine current disks (w/o SD Card)
diskutil list

Insert SD Card
diskutil list
Document the diskN for the SD Card

Partition and format as FAT32
(Link2sd partitioning sd card from mac - LG Optimus V | Android Forums)
diskutil partitionDisk /dev/diskN MBR FAT32 ‘UNTITLED’ 100%
(be careful of quotes around disk NAME - sometimes they change!)

diskutil unmountdisk /dev/rdiskN

Write Image to SD Card on Mac OS X
(from Raspberry Pi Documentation - Getting Started)
sudo dd bs=1m of=/dev/rdiskN if=emonSD-22Dec2015.img
sudo dd bs=1m of=/dev/rdiskN if=

Eject SD Card on Mac OS X
sudo diskutil eject /dev/rdisk1

And this is the emonPi side of things

Upgrade emonPi - TImezone, Data, etc…pdf (203.8 KB)

1 Like

That would indeed be a testament to some mighty good documentation. The one thing that seems to be the wrench in the gears is Linux itself. Given Linux is considered by many to be part of a “computer nerd’s” environment, just getting folks to where they’re not afraid of it might not be easy. Even after 25+ years, Linux still isn’t mainstream like a certain product from Redmond, Washington (that lots of us love to hate). Don’t get me wrong. I’d like to see OEM be every bit as good (or better!) as the commercially available product TED.

Linux knowledge should not be necessary to setup for basic system. No where in the emonpi setup guide is Linux trickery or command line required.

As last this is what we’re aiming for!

Mmmm. One of the problems with Discourse is how it quotes, quotes of quotes. In this insatnce it was @glyn.hudson who said “IMHO everyone should be able to setup and use an OEM system” an not me :frowning: I quoted him, but as the quote was picked out of my reply, it was attributed to me.

Looking at your post you quoted me correctly and it was obvious that it was me that said that. It looks like @Bill.Thomson made a mistake when quoting you and accidently quoted me instead!

Yes that is what happened but if you try you cannot quote a quote of a quote.

Apologies if I caused any confusion.
Here’s the type of thing I was speaking of regarding Linux:

and while understanding the commands might not be necessary, it can be a big help.

Based on your explanation with some fiddling (correct path etc as none of us ever use terminal from the same spot …) I was able to upgrade my emonpi
Had to add the expansion part as I used another 8Gb SD-card

For those neeeding it, after you have ugraded with the prepared image (it is configured for 4 Gb SD cards) you can expand it so it uses the full 8 Gb capacity
Log on the pi (remember PW changed to emonpi2016)

Expand SD Card

Caution: don’t try and run the ‘Expand file-system option’ in raspi-config. This won’t work because of the extra third partition

If you have flashed the image to an SD card greater than 4GB you can run to expand the ~/data partition

$ sudo emonSDexpand

It detected my node , just redid the config part so it sends to my online emoncms, corrected the voltage via a rough hack … all is smooth for now

Thanks Jon

Hi there, I’d like to ask/add something to this thread, but first:
Great work, I like the new forum a lot!

Here my question regarding the structure of information about OEM:
In the old site, you would find

  • the most important information on the core sites (very structured)

  • all the small and big problems being discussed in the old forum (unstructured)

  • some bits of information in the old Wiki (more or less structured, condensed)

On the new site, we have

  • the new core site guide (structured, condensed)

  • the new forum (unstructured, uncondensed)

Finally my question: Will there be a wiki?

I see two reasons, why this could be interesting:

  1. “All” the information in the old forum could be brought into a more condensed and organised form
  2. The sub-projects, tinker solutions could have their own, less official site.

To give an example: I more more or less started to play with the dashboards, and I had to insert and try every widget, inserting it and play around with the options to see what it can do. Now, to spare other people what I have gone though, I would like to create an overview with screenshots of the widgets and a short explanation. A wiki would be the place for that, I guess…

Good overview. Very observant :slight_smile: .

We actually have a wiki which is used for technical hardware docs: :slight_smile:

Sounds good, I think the best thing to do would be to post to the new forum (which is very searchable). The issue with having a fully open-wiki is that since emoncms and other areas of the project are constantly evolving any docs would go out of data very quickly. We are focused our efforts on keeping the core user guide updated which does include Emoncms dashboard documentation:

The user guide site is fully open-source no github. Feel free to add some info and propose a change: