Community
OpenEnergyMonitor

OpenEnergyMonitor Community

New homepage and building blocks website

Tags: #<Tag:0x00007f1bdc76feb8> #<Tag:0x00007f1bdc76fdc8> #<Tag:0x00007f1bdc76fcd8> #<Tag:0x00007f1bdc76fbe8>

Hello all

@Gwil @glyn.hudson and I have been quietly working in the background for sometime on a website overhaul for OpenEnergyMonitor including a new landing front page and new site called https://learn.openenergymonitor.org.

The idea behind learn.openenergymonitor is to bring all of the work on Building Blocks, Understanding Energy and PV diversion more to the fore of the project and to make these resources easier to navigate.

The sites are designed from the ground up to work with a variety of screen sizes including mobile and tablets.

We are not far off being able to go live with this, there’s a little more work to do double checking links and completing the dropdown menu on the front page. We would be interested to hear what you think of it and whether you can spot anything that needs fixing/adjusting?

The new front page can be found here:
Front page concept

and the new learn.openenergymonitor site here:
https://learn.openenergymonitor.org/

I have attached a number of screenshots below of what it should look like in case there is any display issues that we have missed on different browsers, so if you dont think it looks quite right, please look at these first.

Old Dupal site

‘Learn’ and the new front page website would replace the current use of drupal. With only the old forums being kept as an archive. We would delete all the other content that has been moved over to learn in order to avoid confusion.

Once Building Blocks are removed the idea is to add a redirect of all attempts to open links pointing to https://openenergymonitor.org/emon/buildingblocks/… to learn.openenergymonitor.org.

Edit on Github

Learn is a repository on github and anyone can propose a change by clicking on the ‘Edit’ button on any page which directs to the learn github repository edit page:

Changes are publicly transparent (as pull requests) but have to be approved by a repository maintainers currently (@glyn.hudson and I). We can add the @moderators if they like also as repository maintainers so changes can be approved quickly. Please let us know if you would like to help out as a repository maintainer.

For example: ‘An Introduction to AC Power’: https://github.com/openenergymonitor/learn/blob/master/view/electricity-monitoring/ac-power-theory/introduction.md

We haven’t yet finished converting all the pages to markdown to make them readable on github but we will be doing this over time.

Screenshots:

Front page

Learn: Electricity Monitoring

Learn: Sustainable Energy

Learn: PV Diversion

Mobile device

When viewed on a mobile device the menu colapses and can be brought up by tapping the ‘burger menu’. All pages have been designed to work well on mobile devices and small screens

This is becoming really a nice layout, all nicely integrated. Also the colours are slowly converging.
Time to wave goodbye to Drupal that served well but is a bit outdated now.

No problem helping out in the backoffice though I’m not yet used to Github’s internals (never to late to learn) though I think we (moderators) need to know where not to go. My knowledge isn’t big enough to statue on electrical matters going further then the basics, but maybe we can invent some escalating system with several levels with other moderators.

Something like level 1 (me for ex) reading as first what comesin, if I can handle I do, if it is going above my knowledge, I escalate to level 2 where more skilled people can handle and then to level x where Glyn, Tristant and Gwil take care of what can’t be done by us. Not to many levels though but at least those with best knowledge (and most probably needing most time to check) can concentrate on changes that need in-depth control.

Just my 2 cents

And again, very nice work.

2 Likes

I’ve had a quick look at https://learn.openenergymonitor.org/ and two initial comments: (1) I like the look and (2) let’s do a thorough job and carefully review everything before it goes public. There are some holes and a lot of duplication in the old Building Blocks and, while I don’t think there are many instances where it is contradictory, a serious editing effort is called for. (e.g. there’s no mention of using "scales = " in emonHub for calibration, nor anything specifically about calibration and the emonPi.)

Is learn going to be THE place for all documentation? I sincerely hope so, and if it is, can there be some guidelines and framework established so that there’s a structure, and those who contribute will be able to write knowing how it will fit in with the overall scheme and objectives?

An important practical plea: I believe it’s vitally important that all the information is brought together into a cohesive whole. Based on what I read in the Forums, the present scatter-gun approach where information is in 3 or 4 places is a major stumbling block for newcomers - and some not so new too. I see it is the intention that, as soon as something appears in learn, it will be removed from BB, the Wiki, GitHub or wherever. Can we please make sure that is done not only for material that is copied, but also for material that is duplicated, and can we please, please clearly mark outdated and/or obsolete material as such so that people can’t mistake it for current practice?

No, please immediately replace moved or deleted content - wherever it was - by a page that explains that it’s moved and gives the new source and a link. I don’t think a link or a redirect alone is good enough, we need to show people that the old is swept away and it’s now all in one place.

I’m with @bidouilleur in his ignorance of GitHub - so far, I’ve found it impenetrable, probably because I’ve never had the time to read any documentation about it more than once. So its use is a serious retrograde step from my point of view.

It’s good that overall control of the layout and content will be kept within a very small circle of administrators and that all submissions and changes are reviewed by them for accuracy and applicability.

1 Like

Thanks a lot @bidouilleur and @Robert.Wall, I will reply properly tomorrow, thanks for the feedback, much appreciated!

Hi @Robert.Wall and @bidouilleur

Thanks for your feedback.

  • Learn will replace Building Blocks, learn will contain first principal general info e.g what is AC power?, how do CT’s work?

  • The user guide will contain user setup instructions

  • The Wiki and GitHub will contain technical user documentation.

Yup, totally agree. Building Blocks will be removed (with a URL re-direct to lean) once learn goes live.

Github is a powerful tool, I don’t pretend to understand or use all of its functions. However, at the simplest level using github will give us revision control for documentation, this is very useful. To be able to edit markdown on github no knowledge or command line is needed just click the pencil icon and edit away, just like on druapal editor. See edit on github guide. Using github has the advantage that anyone can ‘clone’ the ‘learn’ repository and work on the entire site offline.

That is distressing:

How will newcomers, who aren’t clear about the distinction between these various concepts, know where to look? Maybe more to the point, how will they know that there are 4 totally distinct places to look?

If you’re intent on keeping all 4 locations, methinks we need an overall contents/index to all four “volumes”.

So for a start, Calibration Theory can stay in learn, but the Calibration Procedure as part of the setup instructions needs to move into User Guide? These are the sort of inconsistencies that the Supervising Editor needs to be on the lookout for and to sort out. :wink:

2 Likes

@Robert.Wall yes your quite right that there are certain parts of Learn that blur the lines between the user guide and a more general learning resource, calibration being a good example especially in the way it is written. It is perhaps in this case the calibration procedure for any monitor built using the current emontx2/3, emonpi input circuitry and EmonLib. It could also be used by someone building their own breadboard energy monitor such as: How to build an Arduino energy monitor. The editing guidelines should reflect this and our efforts to edit and prepare learn before being published.

We see learn as being the space for a more general learning resource in the present 3 domains of Electricity Monitoring, Sustainable Energy and PV Diversion. These may not be specific to OpenEnergyMonitor products/hardware units. While the guide is very much: This is how to setup the emonpi, configure inputs in emoncms etc.

Github and Wiki documentation
We have been moving over to having a github repository for particular hardware units (and significant versions):

The idea moving forward is to include both the firmware and the hardware files for a particular piece of hardware in its own repository, rather than the original approach of having a github repository for all Hardware and a github repository for many revisions of the emonTx. We are also keen to try moving new technical documentation that would have otherwise been placed in the wiki to a particular hardware units github repository

Building Blocks Redirect?
I appreciate that a redirect without a notice as to why the redirect has taken place could be confusing. We could detect that the user has landed on Learn from a redirect and display a notice to say “You have been redirected from the old building blocks to learn.openenergymonitor - the new location for building blocks documentation”. We could also detect the redirected URL and map the redirect across to the specific page. @Robert.Wall do you think this would be sufficient?

Once example of a github repository completely replaced by learn is https://github.com/openenergymonitor/documentation. Which I will replace with a notice that all content has been moved to learn.

1 Like

I don’t know. All I am conscious of is the number of comments in the forum that say in one form or another: “Help, I’m totally confused. Tell me what I need.” and the number of times @pb66 (notably, there are others) has to repeat more or less the same advice over and over again because it’s too hard to find.

I’d be quite happy to write a generic calibration procedure for learn and a specific one for OEM products.

Add to that, the users that say “I’m new to Linux” or “I’m new to all of this,” etc.

1 Like

For redirects I’d say direct with no page for 2 reasons

  1. ranking can be completely lost (not that ranking is essential, but if a robot shows wrong links … detects it, they get deleted … we’d lose search results)
  2. people tend not to click 2 times for the same thing, it ain’t there, they go back and try another link from the search results …

Plus the fact you can ‘intercept’ it and show a little nice pop up like, “yep it all changed a bit, please bookmark the new page” … or something like that.

that’s regarding that part

Regarding the scattered info, got to say true but I guess this is often an intermediate period when things ‘grow’. Many things are added, things change and as you don’t always have a clear view from the beginning where it all goes … you try several things and end up a bit like it is now.

Not sure there is a ‘real and unique’ solution. Guess the several systems add their value and not one single covers all (remember I’m not the expert here :wink: )

So maybe let’s try to see this the traditional way. We want to sell (information) and our customer (the surfer) wants to find easily and quickly what he’s looking for (immediate satisfaction generation).

If we take this as a general lead, what solution would be best ? Can the different systems be interlinked, embedded in each other maybe so it looks like 1 solution to the surfer and only back office is divided in modules ?

Just a thought :pensive:. Think those who ‘master’ the tools best will be those who can give the best answers … and I don’t master the tools …

That is exactly why I suggested [quote=“Robert.Wall, post:6, topic:2746”]
we need an overall contents/index to all four “volumes”.
[/quote]
so that everybody needs only to search in one place.

Thankyou @Robert.Wall that would be much appreciated and a kind offer, Im happy to enter any changes in github if you would prefer to send a word document with edits.

Do you mean direct map to learn page replacement or to learn home with a notice?

https://openenergymonitor.org/emon/buildingblocks/ac-power-introduction -> https://learn.openenergymonitor.org/electricity-monitoring/ac-power-theory/introduction

I think so, at least to start with there will be a common top blue bar and navigation across home, learn, community, guide & blog.

I think there is value in having distinct sections. For example, it’s quite common when you buy a new product to have included in the box a ‘Quick Start User Guide’ and also a ‘Technical Manual’.

Since we don’t include any paper based quick-start guide in the box I see the User Guide site as being the equivalent: a non-technical (where possible) step-by-step guide to getting users up and running using the basic system in default configuration without overloading them with technical info.

Where appropriate the User Guide will link out to technical info in ‘learn’ and the wiki/Github. We will also be maintaining the Resources section containing a definitive list to all the resources for each hardware item.

I agree, all sites should look very similar and be a smooth transition, we (or rather @Gwil) have been working on a common top-bar scheme that will be rolled out to all the sites (including the forum and shop) when it’s finished:

Common top nav bar:

Learn

Forum Draft, not finished yet

New Home page


An example of a good common top bar nav over different sites is PlatfromIO:

Getting started: http://platformio.org/get-started/cli
Technical docs (using read the docs): http://docs.platformio.org/en/latest/
Forum (using discourse): https://community.platformio.org/

We have been using patformIO has an example when designing our common top bar.

Reading through the networking section im aware it needs updating.
At the moment we have the following pages:

  • Which radio module - useful guide written by @Robert.Wall on identifying different radio modules used with OpenEnergyMonitor kit over the years. Perhaps more user guide > Technical section, rather than learn?
  • Rfm12b wireless - Technical spec for RFM12b and notes on connecting to an arduino suitable for Learn type content.
  • Rfm12b2 - RFM12 & 69 firmware use/modification guide - useful for either understanding or modifying OEM kit or using to integrate the RFM radio’s in self-built kit.
  • Rfm69cw - Technical spec for RFM69cw module
  • Wifi - old guide on using the Edimax adapter, content is pre emoncms wifi module and integrated support in emonSD image.

I’ve removed the much older pages currently on building blocks including: XBEE, ASK RF link, Arduino Master/slave simple serial networking

I think this section needs a networking introduction page explaining the variety of networking options available RFM12/69, ESP8266 Wifi, RaspberryPI Ethernet/WIFI (external/USB) to name a few. Including a brief mention of the use of these technologies in OpenEnergyMonitor units.

Perhaps the rfm12b and rfm69cw technical info could be moved to this introduction with the parts on identifying the modules removes as this is duplication of the “Which radio module” page.

A brief overview of RaspberryPI Wifi options in the introduction could replace a dedicated wifi page. There are probably better places and online guides available rather than having our own page here.

If we moved “Which radio module” to Guide > Technical and replaced the other pages with a networking introduction/overview that would however only leave one leave two pages in the networking section: Introduction and RFM12/69 Firmware Guide

1 Like

As part of the bigger change outlined above, I’ve been working on making this forum’s look and feel match that of the new theme. If anybody has any suggestions or notices an error, sluggishness or bugs (particularly on various devices, screen sizes, browsers, etc.) please let us know. Things are likely to change over time as the rest of the project develops.

Agreed.

I think these are candidates for comprehensive revision.

Quite a few users want to use serial to connect into the Hub. Not strictly networking, but it must not be forgotten - it’s ‘network’ if not ‘Internet/Intranet’

Thanks @Robert.Wall I haven’t unfortunately been able to progress this this week, but yes agreed and good point about a need for a guide for direct serial connectivity.

I have now merged the page for RFM12 and RFM69 to create a page that is intended to be a brief introduction to the module, technical spec and then how to connect directly to an Arduino - as a self build design reference:
https://learn.openenergymonitor.org/electricity-monitoring/networking/rfm12_69

this then leads nicely to the next page which is on how to send data between nodes with the RFM12/69:
https://learn.openenergymonitor.org/electricity-monitoring/networking/sending-data-between-nodes-rfm

Which module is still the first page in this section:
https://learn.openenergymonitor.org/electricity-monitoring/networking/which-radio-module

and I have removed the WIFI page for reasons given above, there are better resources/guides elsewhere for RaspberryPi + WIFI connectivity and the software configuration for this has been included as standard in the emonSD raspberrypi image for some time.

Trystan,

I was trying to find the old guides on PV diversion and expected them to be linked through the Solar PV section of the new format - sadly they aren’t. Can you include these?

Also on that main page, you have to click on ‘learn more’ below the headlines for the contents of each section and you can’t click on the image/graphics above. Can you make those images into clickable areas so that it’s easy to get to the info that way.

Also, the ‘learn mores’ are slightly confusing to the eye as they almost appear to be under the next column, so maybe this needs a bit more formatting to make them obviously part of the headline list above them - if you see what I mean

Simon

PS Great work so far - it’s a PITA doing this but it really makes things a lot easier for both new and old folks. Thanks.

Thanks @Bramco, the PV Diversion guides are available here: https://learn.openenergymonitor.org/pv-diversion/introduction/choosing-an-energy-diverter.md and are one of the three main Learn sections. Perhaps there needs to be a link through from the SolarPV guide too?

We will have a look at the learn links on the main page to see if we can improve, thanks.