Emoncms

Emoncms is an open source web application for processing, logging and visualising energy, temperature and other environmental data. It is part of the OpenEnergyMonitor project.

Emoncms 12 moves the interface to Bootstrap 5. See the release notes.

Documentation

• User guide: docs.openenergymonitor.org/emoncms
• Docs contents, user guide and developer docs: docs/README.md
• Development setup: docs/developer/development.md
• Glossary of terms such as input, node, feed and process: glossary

API

Every install includes its API reference:

• API Help on the Inputs page and Feed API Help on the Feeds page.
• /llms-full.txt or /api.md: the full reference as Markdown, for AI assistants and other tools. /llms.txt is a short index.

The emoncms.org reference: Input API, Feed API.

Install

Emoncms is tested on Raspberry Pi OS and Ubuntu. It should work on other Debian systems. Shared hosting and XAMPP are not supported, because Emoncms needs background services. A small Linux VPS works well.

• Install with EmonScripts
• Download the emonSD image for a Raspberry Pi
• Buy an SD card with emonSD installed

Docker

An all-in-one Docker container is available for amd64, arm64 and arm/v7. It is built from the Emoncms stable branch on Alpine Linux, and tagged with the Alpine and Emoncms versions. It includes MariaDB, Redis, Mosquitto, the graph, sync, backup, dashboard and app modules, and the emoncms_mqtt, service-runner and feedwriter services.

sudo docker pull alexjunk/emoncms

See emoncms-docker.github.io.

Requirements

• PHP 8.1 or later. CI tests PHP 8.1 to 8.4.
• PHP extensions: mysqli, redis, gettext, mbstring, curl, gd, xml.
• MySQL or MariaDB.
• Apache with mod_rewrite.
• Redis, recommended.
• Mosquitto, for MQTT input.

Redis reduces disk writes, which extends the life of SD cards. Emoncms runs without Redis where it is not available, but input processes marked as needing Redis do not work.

Modules

Install a module by cloning it into the Modules folder, or into /opt/emoncms/modules with a symlink for modules that have background scripts. Run Update Database on the Admin page after installing a module.

Modules installed on the emonSD image:

• Graph: feed viewer.
• Device: set up inputs and feeds from device templates.
• Dashboard: dashboard builder.
• App: ready-made dashboards such as My Electric Flow and My Heatpump.
• Config: emonHub configuration editor and log viewer.
• Network: WiFi and network settings.
• Backup: backup, restore and SD card import.
• Sync: upload or download feeds between servers.
• Post Process: process recorded feed data.
• Usefulscripts: maintenance scripts.

Other modules include Email reports and the DemandShaper. See the Emoncms repositories.

Branches

• master: latest development. Open pull requests against master.
• stable: release branch, used by emonPi and emonBase updates. See the releases.

Contributing

Please read the state of development and contributing page before starting significant work. Then discuss your idea with us in the issue list, by email ([email protected]), or on a call (email us to arrange one). We are happy to talk ideas through from the start. Trystan & Glyn, OpenEnergyMonitor.

Issues and pull requests made with the help of an AI agent are welcome. See AGENTS.md.

Report security problems privately. See SECURITY.md.

Tools

• PHPFina data file viewer: explore PHPFina feed data files without an Emoncms install. Useful for checking backups and archived data.
• Android app: Google Play, source, forum.

More information

• Emoncms.org, hosted Emoncms
• OpenEnergyMonitor forum
• OpenEnergyMonitor

Licence

Emoncms is released under the GNU Affero General Public License, version 3 or later. See LICENSE.txt and COPYRIGHT.txt.