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
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.
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
More information
Licence
Emoncms is released under the GNU Affero General Public License, version 3 or later. See LICENSE.txt and COPYRIGHT.txt.
