Emoncms is an open-source web application for processing, logging and visualising energy, temperature and other environmental data and is part of the OpenEnergyMonitor project.
- PHP (tested with 7.0.30)
- MySQL or MariaDB (tested with 15.1)
- Apache (tested with 2.4.25)
- Redis* (tested with 3.2.6)
*Redis is recommended because it reduces the number of disk writes and therefore prolongs disk life (noticeably on SD cards e.g. Raspberry Pi). Some input-processors also require Redis and fail silently if Redis is not installed. Some environments such as shared hosting or as far as we have tried Windows servers don't support Redis hence why Emoncms has a fall back mode that allows core operation without Redis.
There are differences between the standard version of Emoncms and the version of Emoncms running on emoncms.org. This repository contains the code for the standard version of Emoncms. This is the version installed on the OpenEnergyMonitor SD Card that comes with the emonPi and emonBase and is recommended for all self-install versions of Emoncms.
The emoncms.org version Github: emoncms/emoncmsorg is a fork that is specific for multi-server installations. While both versions share the same roots, the code for emoncms.org differs significantly from the standard version of Emoncms, the user experience is intended to be similar but there are currently a number of differences in the API and look of the inputs and feeds interfaces as well as a reduced feature set in general on emoncms.org in order to ensure stability. In general development on emoncms.org moves slower than the standard Emoncms for this reason.
1. From the Guide
- Guide: Core Concepts - Core Emoncms concepts including inputs, input processing and feeds.
- Guide: Creating daily kWh graphs - How to create daily kWh graphs from cumulative kWh electricity/heat energy feeds.
- Guide: Daily Averages - How to extract daily averages from temperature, humidity & power feeds.
- Guide: Exporting CSV - How to use the graph module and feeds interface to export CSV data for use in 3rd party programs such as OpenOffice Calc or Excel.
- Guide: Histograms - How to use the histogram tool in the graph module.
- Guide: Home Energy Monitor - Example of configuring the MyElectric dashboard.
- Guide: Solar PV Monitor - Example of configuring the MySolar dashboard.
2. Emoncms Terminology
- Input: An incoming datasource. Each input has an associated "node" identifier and a "key" sub-identifier. Inputs are entry points, only the last value and time of the input is recorded. To record historic data a feed needs to be created from an input.
- Input: Node: A grouping identifier for an input or feed.
- Input: Key: A sub-identifier for items within each Node.
- Input process list (or input processing): A list of processes* performed sequentially on each input value as it is received on that input.
- Process: A function that can be attached to the process list of an input to change the value or to save the value to a feed*.
- Feed: A place where data is recorded, a time-series of datapoints. The standard time-series databases used by Emoncms are PHPFina and PHPTimeSeries and were written as part of the Emoncms project.
- For a description of what each input process does in Emoncms, see the helper note within the Emoncms input processing configuration interface.
3. Emoncms.org API Reference
The following API references apply to emoncms.org. They differ slightly to the API available on emonPI/emonBase installs, the API refrence for which can be found from the inputs and feed pages when logged in locally.
Emoncms is designed and tested to run on either Ubuntu Linux (Local, Dedicated machine or VPS) or RaspberryPi OS. It should work on other Debian Linux systems though we dont test or provide documentation for installation on these.
We do not recommend and are unable to support installation on shared hosting or XAMPP servers, shared hosting in particular has no or limited capabilities for running some of the scripts used by emoncms. There is now a large choice of low cost miniature Linux VPS hosting solutions that provide a much better installation environment at similar cost.
Recommended:
Experimental (not currently up to date):
Modules can be installed by downloading or git cloning into the emoncms/Modules folder. Be sure to check for database updates in Administration menu after installing new modules:
-
Graph module - Advanced graphing module that integrates with the emoncms feed list, highly recommended; examples of use can be found in emoncms guide [1][2][3][4].
-
Device module - Automatically configure inputs and feeds using device templates.
-
Dashboards module - Required for creating, viewing and publishing dashboards.
-
App module - Application specific dashboards e.g. MyElectric, MySolar.
-
Config - In-browser emonhub.conf editor and emonhub.log log viewer. Use
git cloneto install. -
Wifi module - Wifi configuration interface designed for use on the emonPi
-
DemandShaper module - Schedule smartplugs, EmonEVSE smart EV chargers, heatpumps to run at best time in terms of: carbon, cost, grid strain. Based on day ahead forecasts.
-
RemoteAccess module - Emoncms Remote Access client (Beta)
There are many other available modules such as the event module and openbem (open source building energy modelling module): check out the Emoncms repo list.
3rd party modules
-
master - The latest and greatest developments. Potential bugs, use at your own risk! All pull-requests should be made to the master branch.
-
stable - emonPi/emonBase release branch, regularly merged from master. Slightly more tried and tested. See release change log.
-
ARCHIVE low-write (v8.5) - Old emonPi/emonBase Emoncms version (July 15 emonSD ready-to-go SD card image). Low-write mode is now available in v9.0. The low write version of Emoncms is designed for running on SD cards. This is a cut down version of Emoncms supporting only the phpfina and phptimeseries feed engines (no in built feed averaging or histograms) and a reduced input processor set. Archived branch
- Backup
- Raspberry Pi Backup / Restore module (emonPi / emonBase)
For developers: The following lists the locations of the files that define Emoncms's inbuilt documentation for the input and feed API's and input process descriptions:
- The input API helper page emoncms/Modules/input/Views/input_api.php
- The feed API helper page emoncms/Modules/feed/Views/feedapi_view.php
- Input process descriptions are defined in the process list definition object at the top of the process list definition file here: emoncms/Modules/process/process_processlist.php
- PHPFina data file viewer - Easily explore phpfina timeseries feed engine data files directly without a full Emoncms installation. Useful for checking backups and archived data.
Note: due to ongoing development some docs may now be outdated
- Emoncms architecture
- Input processing implementation
- Developing a new Module
- Global variables in Emoncms
Emoncms timeseries database design (feed storage)
- Emoncms time series database development history
- Variable interval time series
- Fixed interval time series
- Fixed interval with averaging time series
- Improving write performance with buffering
- Cloud hosted platform - https://emoncms.org
- OpenEnergyMonitor Forums
- OpenEnergyMonitor Homepage