user guide moved from guide

docs/user_guide/apps.md

@@ -0,0 +1,45 @@
+# Application dashboards
+
+The Emoncms app's module contains pre-built application specific dashboards. These are built from the ground up for ease of setup, responsive design and to often include calculations that are harder to perform in the custom dashboard builder.
+
+**Available Apps**
+
+- My Electric
+- My Energy
+- My Solar
+- My Solar Divert
+- Cost Comparison
+- My Electric 2
+- My Heatpump
+- Octopus Agile
+- Time of use
+- Time of use - flexible
+- Time of use - flexible + CL
+
+## My Electric
+
+My Electric is a dashboard designed for the simple [home energy monitor application](/applications/home-energy). It includes realtime power and kWh used today as well as a moving power graph and daily kWh bar chart.
+
+![My Electric](img/myelectric_webapp.png)
+
+## My Electric 2
+
+My Electric 2 is a slightly more interactive version of the 'My Electric' dashboard. Clicking on a particular day on the bar graph zooms in to see the power graph for that day, providing an easier way to explore historic consumption data.
+
+![My Electric 2](img/myelectric2.png)
+
+## My Solar PV
+
+The My Solar app can be used to explore onsite solar generation, self consumption, export and building consumption both in realtime with a moving power graph view and historically with a daily and monthly bargraph. See [Solar PV application guide](/applications/solar-pv).
+
+![My solar PV](img/my-solarpv1.png)
+
+## My Heatpump
+
+The My Heatpump app can be used to explore the performance of a heatpump including, electricity consumption, heat output, COP and system temperatures. 
+
+![My Heatpump](img/myheatpump.png)
+
+Clicking on a particular day brings up the detailed electric, heat, flow and return temperature graph for that day:
+
+![My Heatpump 2](img/myheatpump2.jpeg)

docs/user_guide/coreconcepts.md

@@ -0,0 +1,64 @@
+# Emoncms Core Concepts
+
+Emoncms is an open-source web application developed as part of this project, for processing, logging and visualising energy, temperature and other environmental data. 
+
+Emoncms receives data from OpenEnergyMonitor monitoring hardware and is installed locally on the emonPi/emonBase. A similar (but not identical) version is also publicly available on emoncms.org. Either one may be used, or both may be used in parallel.
+
+The following guide introduces the core concepts behind emoncms and provides links to guides to learn more.
+
+## Inputs, Devices, Input processing and Feeds
+
+**Inputs:** Data arriving in emoncms is registered first as inputs (This is automatic). Inputs hold only the most recent value and time associated with incoming data. Each input has an associated "node" identifier and a "key" sub-identifier. To record historic data a feed needs to be created from an input.
+
+**Feed:** A place where data is recorded, a time-series of datapoints. The standard time-series databases used by emoncms are [PHPFina](https://learn.openenergymonitor.org/electricity-monitoring/timeseries/Fixed-interval) and [PHPTimeSeries](https://learn.openenergymonitor.org/electricity-monitoring/timeseries/Variable-interval) and were created as part of the emoncms project.
+
+**Input processing:** It is often useful to be able to perform mathematical operations on inputs before recording the result to a feed. We can use input processing to calibrate inputs, add, subtract, multiply and divide inputs by each other, and process inputs in one format to another such as the conversion of input power values to a cumulative kWh feed.
+
+**Devices:** If the emoncms device module is installed (included by default on emonPi/emonBase) the input "node" indentifier links these inputs to a device. The device module provides device templates for automatic feed creation and application of input processing.
+
+The following guides provide an overview of how to use these features:
+
+- [Log Locally](/setup/local/): An example of configuring emonPi inputs, adding input processing and logging data to feeds
+- [Calculating Daily kWh](/emoncms/daily-kwh/): Covers input processes: power_to_kwh, log_to_feed (join) & kWh Accumulator
+- Application guides: [Home Energy](/applications/home-energy/) and [Solar PV](/applications/solar-pv/) cover input processing and feed creation for these applications.
+
+## Graphs, Visualisations, Apps & Dashboards
+
+Data recorded in feeds can be visualised with a number of different tools to suit a wide range of applications.
+
+**Emoncms Graph module:** The emoncms graph module is the standard feed data viewer accessible directly from the emoncms feeds page by selecting or clicking on feeds. This interface provides options to compare multiple feeds on a single graph, calculate averages, daily, monthly and annual values and export data as CSV. Graphs created using this interface can be saved and included on Emoncms dashboards. 
+
+Guides: [View Graphs](/emoncms/graphs/), [Calculating Daily kWh](/emoncms/daily-kwh/), [Calculating Averages](/emoncms/daily-averages/), [Exporting CSV](/emoncms/export-csv/), [Histograms](/emoncms/histograms/)
+
+**Visualisations:** Emoncms visualisations pre-dated the graph module and include a wider range of different visualisations - some of which are reproducable using the graph module such as 'rawdata', 'bargraph' and many aspects of 'multigraph'. Visualisations can also be included in dashboards.
+
+**Dashboards:** The Emoncms dashboard module provides a way to build custom dashboards using a drag-and-drop interface using a variety of widgets and graphs. Dashboards can be made public.
+
+**Apps:** The Emoncms apps module provides pre-built application specific dashboards e.g MyElectric for home energy consumption, MySolar for home solar self consumption visualisation and MyHeatpump for heatpump performance analysis.
+
+## Emoncms Modules
+
+Emoncms is designed as a modular extendable application. [Emoncms core](https://github.com/emoncms/emoncms) includes the core: user, inputs, input processing, feeds & visualisations functionality.
+
+The following modules are all optional, but are installed as default on our emonSD software stack included on the emonPi/emonBase SD card.
+
+| Module | Github |
+| ----------- | ----------- |
+| Graph       | [https://github.com/emoncms/graph](https://github.com/emoncms/graph) |
+| App       | [https://github.com/emoncms/app](https://github.com/emoncms/app) |
+| Dashboard       | [https://github.com/emoncms/dashboard](https://github.com/emoncms/dashboard) |
+| Backup       | [https://github.com/emoncms/backup](https://github.com/emoncms/backup) |
+| Post Process       | [https://github.com/emoncms/postprocess](https://github.com/emoncms/postprocess) |
+| Sync       | [https://github.com/emoncms/sync](https://github.com/emoncms/sync) |
+| DemandShaper       | [https://github.com/emoncms/demandshaper](https://github.com/emoncms/demandshaper) |
+| WiFi       | [https://github.com/emoncms/wifi](https://github.com/emoncms/wifi) |
+| Config       | [https://github.com/emoncms/config](https://github.com/emoncms/config) |
+| Usefulscripts       | [https://github.com/emoncms/usefulscripts](https://github.com/emoncms/usefulscripts) |
+
+## emonSD and EmonScripts
+
+The emonSD software stack, designed to run on a emonPi/emonBase (or any RaspberryPi), is available as a pre-built image for download here: [https://github.com/openenergymonitor/emonpi/wiki/emonSD-pre-built-SD-card-Download-&-Change-Log](https://github.com/openenergymonitor/emonpi/wiki/emonSD-pre-built-SD-card-Download-&-Change-Log)
+
+This image is built using a collection of automated build scripts called EmonScripts, available here: [https://github.com/openenergymonitor/EmonScripts](https://github.com/openenergymonitor/EmonScripts). These scripts also handle the emoncms system updater available from the Emoncms Admin page. 
+
+The EmonScripts installer can also be used to install on any Debian system. Follow the instructions here for [custom raspberrypi, ubuntu and digital ocean droplet installation](https://github.com/openenergymonitor/EmonScripts/blob/master/install/readme.md).

docs/user_guide/daily-averages.md

@@ -0,0 +1,34 @@
+# Calculating Averages
+
+This guide details how to generate interval based averages i.e hourly, or timezone correct: daily, weekly and monthly averages from emoncms feeds. Designed for determining power, temperature and humidity averages.
+
+Averages are returned for the time period given by the returned timestamp up to the next timestamp. The timestamp is for the start of the average period.
+
+## Hourly averages
+
+1. Open the feed for which you wish to generate averages for in the default data viewer called graph.
+2. Click on the Average tickbox for the feed, below the graph.
+3. Select 'fixed interval' for type and then enter 3600 in the box next to it (i.e: 3600 seconds in an hour)
+4. To complete hit **Reload**.
+
+**Note:** If its your first time you may need to click on **Reload a second time** as the averages are computed in the background when the request is first made.
+
+The result should look like this:
+
+![hourlyaverage.png](img/graph_averages_hourly.png)
+
+**CSV Export:** The returned averages can be exported as CSV for use in external programs by clicking on the 'Show CSV Output' button available at the bottom of the graph viewer page. See Exporting CSV for more on this.
+
+## Daily averages
+
+To calculate timezone correct daily averages:
+
+1. Open the feed in the default data viewer (graph) as above.
+2. Click on the Average tickbox for the feed, below the graph.
+3. select **daily** for type from the dropdown menu.
+4. To view the output as a bar graph select 'Bars' from the dropdown graph type selector next to the feed
+5. To complete hit **Reload**.
+
+![dailyaverage.png](img/graph_averages_daily.png)
+
+**CSV Export:** The returned averages can be exported as CSV for use in external programs by clicking on the 'Show CSV Output' button available at the bottom of the graph viewer page. See Exporting CSV for more on this.

docs/user_guide/daily-kwh.md

@@ -0,0 +1,75 @@
+# Calculating Daily kWh
+
+Emoncms supports the creation of daily, weekly & monthly kWh data and graph's from several different emoncms input types.
+
+- Power in Watts (i.e emontx, emonpi CT channels)
+- Wh/kWh readings that do not reset on power cycle e.g energy meters
+- Wh/kWh readings that reset on power cycle e.g emontx/emonpi pulse count
+
+## Creating daily kWh data from power inputs
+
+The standard emonTx and emonPi firmware transmit real power values for each CT channel. Accumulating kWh data can be calculated from this power data using the emoncms "Power to kWh" input processor.
+
+1. In the inputs interface select the power input for which you wish to generate kWh data. Click on the spanner icon to bring up the input processing configuration interface.
+
+2. Select the `power to kWh` input processor and create a feed, select a feed interval that either matches your post rate i.e 10s on the emontx and emonpi or for reduced disk use; intervals of up to 3600s can be used. Add `_kwh` to the feed name in order to help distinguish it from the power feed.
+
+![inputproc_powertokwh.png](img/inputproc_powertokwh.png)
+
+## Creating daily kWh data from cumulative Wh or kWh inputs
+
+**Option 1: Wh/kWh readings that do not reset on power cycle e.g energy meters**<br>
+If meter data is irregular, missing data will be recorded as null values with the standard 'log to feed' input process. If a null value happens to coincide with midnight, the bar graph produced will show spikes or gaps. To avoid this issue use the `Log to feed (Join)` input process - which joins across missing values with a straight line.
+
+1. In the inputs interface select the input for which you wish to record kWh data. Click on the spanner icon to bring up the input processing configuration interface.
+
+2. If the input value is in Watt hours (Wh) apply a scale of 0.001 to convert to a kWh reading.
+
+3. Select the `Log to feed (Join)` input processor and create a new feed, select a feed interval that either matches your post rate i.e 10s on the emontx and emonpi or for reduced disk use; intervals of up to 3600s can be used.
+
+![inputproc_logfeedjoin.png](img/inputproc_logfeedjoin.png)
+
+**Option 2: Wh/kWh readings that reset on power cycle e.g emontx/emonpi pulse count**<br>
+The emontx and emonpi pulse count and continuous monitoring cumulative energy inputs reset if the unit is power cycled. If these inputs are recorded with the standard 'log to feed' process the resulting feed includes all resets as well as null values if there is any missing data. The bar graph produced will show spikes or gaps. To avoid this issue use the `Wh Accumulator` or `kWh Accumulator` input process - which both joins across missing values with a straight line and removes the reset - continuing from the value prior to the reset.
+
+1. In the inputs interface select the input for which you wish to record kWh data. Click on the spanner icon to bring up the input processing configuration interface.
+
+2. If the input value is in Watt hours (Wh) apply a scale of 0.001 to convert to a kWh reading.
+
+3. Select the `kWh Accumulator` input processor and create a new feed, select a feed interval that either matches your post rate i.e 10s on the emontx and emonpi or for reduced disk use; intervals of up to 3600s can be used.
+
+![inputproc_logfeedjoin.png](img/inputproc_kwhacc.png)
+
+---
+
+## Viewing a kWh per day bar graph
+
+**Note:** At least 2 days of data is required to generate a daily kWh graph from accumulating kWh data. At the moment, the bar graphs built using the vis module don't show the current day's kWh consumption. The MyElectric app in the apps module, which also uses the cumulative kWh feed type, does show the current day.
+
+Click on `Setup > Visualisation`, and select the `BarGraph`.
+
+Select the cumulative kWh feed created above.
+
+**Delta:** The important property here is 'delta'. With delta set to 1, the bar graph will draw the total kWh for each day calculated from the kWh value at the end of the day, minus the kWh value at the start of the day.
+
+**Scale & Units:** If the feed is in watt hours, the scale can be used to convert it to kWh by multiplying by 0.001. Units can be set in the units field.
+
+**Interval:** The interval property can be set if you wish to have kwh at a set interval such as kwh per hour, for daily, weekly, monthly data use the **mode** property.
+
+**Mode:** Use this property to obtain timezone correct kwh data. Set to either daily, weekly or monthly.
+
+![vis_bargraph_daily.png](img/vis_bargraph_daily.png)
+
+The same options can be used in dashboards for the same output.
+
+All of the visualisations in emoncms that make use of daily data also support this approach including: SimpleZoom, Stacked, StackedSolar, Zoom and OrderBars.
+
+The **Graph module** (set as default data viewer on the emonPi/emonBase and Emoncms.org) can also be used to create kWh per day bar graph from cumultive Wh / kWh data:
+
+Raw feed cumulative kWh view:
+
+![graph_cumulative.png](img/graph_cumulative.png)
+
+To convert the cumulative kWh feed to daily kWh bargraph using the graph tool select Window `type-daily` feed `type=Bars` and `delta = 1` then click `reload`
+
+![graph_kwhday.png](img/graph_kwhday.png)

docs/user_guide/dashboards.md

@@ -0,0 +1,17 @@
+# Dashboard Builder
+
+The Emoncms dashboard module can be used to build custom dashboards using a drag-and-drop approach to assembling different widgets, graphs, containers and text.
+
+Dashboard Editor Video Guide:
+
+<div class='videoWrapper'>
+<iframe width="560" height="315" src="https://www.youtube.com/embed/eqN9rc9VnqI" frameborder="0" allowfullscreen></iframe>
+</div>
+
+Community created video tutorial for creating a Emoncms dashboard with a custom background:
+
+<div class='videoWrapper'>
+<iframe width="560" height="315" src="https://www.youtube.com/embed/N4xHyiE6mc0" frameborder="0" allowfullscreen></iframe>
+</div>
+
+See [Emoncms Showcase forum](https://community.openenergymonitor.org/c/emoncms/showcase) for further examples of what is possible.

docs/user_guide/export-csv.md

@@ -0,0 +1,39 @@
+# Exporting CSV
+
+Its possible to easily export data selected using the emoncms data viewer by clicking on the **Show CSV Output** button at the bottom of the page. Multiple feeds can be selected with datapoints aligned to the same timestamps.
+
+The data viewer CSV export tool is limited to 8928 datapoints. For larger exports the export tool that is part of the feed interface can be used, see below.
+
+## Data viewer CSV export tool
+
+There are 3 timestamp formats available:
+
+1. Unix timestamp
+2. Seconds since the start of the export
+3. Date time string "2016-04-06 00:00:00"
+
+**Unix timestamp**
+
+![csv_export_1.png](img/csvexport_timestamp.png)
+
+**Date time string (i.e: 2019-11-01 00:00:00)**
+
+![csv_export_2.png](img/csvexport_datetime.png)
+
+**Seconds since the start of the export**
+
+![csv_export_3.png](img/csvexport_secondsstart.png)
+
+**Example of exporting multiple feeds**
+
+Multiple feeds can be exported for the same timestamps by selecting multiple feeds from the left hand feed selection menu.
+
+Make sure that null values are shown to ensure that datapoints line up correctly.
+
+![csv_export_4.png](img/csvexport_multiple.png)
+
+## Full Export via Feed interface
+
+Full feed exports can be obtained via the export tool that can be accessed from the feed list interface. The start time, end time interval and timezone offset can be selected and am estimate is given of the download size. Select a feed using the tick box selector and then click on the down-arrow icon in the feed list toolbar to open the feed export tool.
+
+![csvexportfromfeeds.png](img/csvexport_feedlist.png)