ismb / jemma

Java-based Energy Monitoring and Management Application

JEMMA - Java Energy ManageMent Application framework

JEMMA is a open-source (LGPL) framework which implements the Energy@home specifications for energy monitoring and management application. JEMMA currently supports the ZigBee Home Automation 1.2 and the ZigBee Gateway Device standards resulting from of a collaboration between the Energy@home Association and the ZigBee Alliance.

More information are available on the JEMMA Website and the JEMMA GitHub page.

Full component list

JEMMA is a modular framework. To better handle development of each module, bundle developments are spread in a number of separate GitHub projects. The following table summarizes the current official JEMMA bundles.

Project	Description	Version
ismb/jemma	The core set of JEMMA components	1.0.0-rc1
ismb/jemma.osgi.dal.adapter	JEMMA Dal Adapter	1.1.2
ismb/jemma.drafts.org.osgi.osgi.service.dal	Dal Base Classes (draft)	1.0.2
ismb/jemma.drafts.org.osgi.osgi.service.dal.functions	Dal Base Functions (draft)	1.0.2
ismb/jemma.osgi.dal.functions.eh	DAL Classes Functions for Energy@home devicess	1.0.2
ismb/jemma.osgi.dal.web-apis	JEMMA REST and WebSocket API to access Devices, Functions and Events available in OSGi Device Abstraction Layer	2.0.2
ismb/jemma.osgi.ah.adapter.http	JEMMA HTTP AH Adapter	2.0.5
ismb/jemma.osgi.ah.app	This bundle is just a placeholder for the whole framework version	3.3.2
ismb/jemma.osgi.ah.configurator	jemma.osgi.ah.configurator	1.0.9
ismb/jemma.osgi.ah.demo.fakevalues	Fake devices for JEMMA testing/tutorials	0.1.3
ismb/jemma.osgi.ah.energyathome	Energy@Home Home Automation bundle	2.2.32
ismb/jemma.osgi.ah.felix.console.web	Apache web console plugin for Jemma	1.0.11
ismb/jemma.osgi.ah.greenathome	Greenathome Appliance	2.1.22
ismb/jemma.osgi.ah.hac	JEMMA Home Automation Core services	3.1.5
ismb/jemma.osgi.ah.hac.lib	JEMMA Home Automation Core libraries	3.1.6
ismb/jemma.osgi.ah.hap.client	A service adding a reliable layer to transfer data from the platform to the provisioning server	1.2.17
ismb/jemma.osgi.ah.io	This bundles implements a state machine to properly handle FlexGateway's leds	1.0.18
ismb/jemma.osgi.ah.m2m.device	Exposes stateless XML Rest API to send data and to perform queries.	1.2.17
ismb/jemma.osgi.ah.upnp.energyathome	This bundle allows UPnP discovery.	1.0.3
ismb/jemma.osgi.ah.webui.base	This bundles base common utilities to the web interfaces.	2.0.14
ismb/jemma.osgi.ah.webui.energyathome	This bundle provides a web interface to configure appliances and the entire system.	1.0.62
ismb/jemma.osgi.ah.webui.energyathome.demo	This bundle provides a web interface to configure appliances and the entire system.	1.0.47
ismb/jemma.osgi.ah.zigbee	ZigBee Network Manager	2.1.28
ismb/jemma.osgi.ah.zigbee.appliances	This bundle is a generic driver for ZigBee Home Automation devices used by the driver locator when a device is discovered to support all its clusters.	1.0.4
ismb/jemma.osgi.ah.zigbee.appliances.generic	This bundle is a generic driver for ZigBee Home Automation devices used by the driver locator when a device is discovered to support all its clusters.	1.0.4
ismb/jemma.osgi.javagal	Java-based ZigBee Gateway Abstraction Layer Implementation	2.0.10
ismb/jemma.osgi.javagal.gui	JavaGAL Web GUI	1.0.7
ismb/jemma.osgi.javagal.json	JavaGAL JSON interfaces	1.0.3
ismb/jemma.osgi.javagal.rest	JavaGAL REST interfaces	1.0.2
ismb/jemma.osgi.utils	JEMMA utils for OSGi environemnt	1.0.8
ismb/jemma-maven-repository	Support project used to store binary dependencies for JEMMA.	1.0.0-rc1

Get Started

Tutorials, how-tos and other resources are available on the project wiki-based documentation.

JEMMA can also be controlled through REST/WebSocket APIs relying on OSGi Device Abstraction Layer. To start interacting with it you need also these bundles:

• OSGi Device Abstraction Layer
• OSGi Device Abstraction Layer functions
• Energy@Home specific OSGi Device Abstraction Layer functions
• The DAL adapter for JEMMA: it registers DAL services for JEMMA devices
• The DAL web APIs

Take a look at this wiki page to discover functionalities that can be exposed by JEMMA devices

License

The JEMMA code-base has been developed since 2010 by Telecom Italia which holds the Copyright on the original code base.

The full JEMMA source code, unless specified otherwise in specific files, have been released under the GNU Lesser General Public License (LGPL) version 3. LGPL conditions can be found on the GNU website.

Contribute

Willing to contribute ? Check our project tracker. Information on how to contribute can be found here

Linked projects

• ZCL cluster generator - A code generator which creates jemma zcl proxy classes from xml descriptions.
• Simple command provider - A simple OSGi CommandProvider demonstrating JEMMA device APIs usage

jemma's Issues

Evaluate if possible to shorten directories in the root of the project without messing up maven/eclipse etc.

Rationale: so the project names show nicely in the github home page.
(also to be checked : is this a good practice for OSGi and Maven ? )

Clean-up the current code base from obscure maven dependencies

The next code-base should only have dependencies towards bundles/poms which are available on mainstream repositories (e.g. mavencentral)

First tutorial to compile and launch version 0.0.1

Initial overall description and bundle list on the wiki should be on the wiki

Package naming conventions

Verify JavaGAL and other bundles are using an appropriate package naming convention

Plan some approach for Unit/Integration/System testing

Support for OSGi standard RFC-196 - Device Abstraction Layer

Integrate and release the JAVA GAL as a JEMMA component

Complete purchase of the official domain and sub-domain for this project

Complete purchase of the official domain and sub-domain for this project

We should describe the proposed JEMMA SW management processes to the community

maybe 1 simple wiki page can be enough e.g. how we manage branches, how we track issues, etc.

Flow to be discussed:

• gitflow
• feature branch
• forking
• ... or some combination of them

Overall refactoring to simplify architecture

Describe well how to add new devices, how to add new radio differents from ZigBee, how to modify or deliver a new GUI

Descrivere bene come si può estendere per aggiungere nuovi device, per aggiungere nuove radio diverse da ZigBee, per modificare la GUI, …

Create section on the website for "compliant/tested hardware"

see here

First release of the full repository

First release of the full repository

Review of documentation of all bundles and key APIs

in order to evolve the platform further, we might need a clean-up and refactoring of all bundles. A first step for this would be to better document available bundles (high-level documentation on the wiki) + good javadocs for the main classes/interfaces/services/components

Process the latest version of the e@h specification and classify each feature (implemented, in-progress, not yet available)

Hack-a-day style tutorials (e.g. some catchy application running @ home)

Consider a stand-alone "cloud-less" distribution of JEMMA, for people not willing to use the cloud

Write tutorial for Flexkey/gateway/plugs

This is related to #22

Analysis of application performances (PROFILING)

To perform ana analysis of top resource-consuming tasks in JEMMA, and optimize most relevant code parts

Support for OSGi standard RFC-192 - ZigBee Device Services

Integrate with a Rule Engine

Integrate JEMMA with a rule engine such as IFTTT or FreeDomotic

Integrate at least on IP-based device to the demonstrator

e.g. WiFi washing machine, etc.

Define a good strategy to handle dependencies towards legacy code (GAL/JGAL) and external project e.g. zigbee4osgi

Define a good strategy to handle dependencies towards legacy code (GAL/JGAL) and external project e.g. zigbee4osgi

Deploy binaries to Maven Central

According to this guide we could use Sonatype OSS Repository. But maybe we can consider also some alternatives.

Import bugfixes/improvements already available in the T.I. repository

(Note: to be split into several tickets)

Simple use case implementation as a tutorial for developers

The tutorial should show how a sw developer can interact with smart appliances from inside Jemma or also from external clients.

Verification with compliance on Raspberry PI devices (incl. writing a tutorial)

Review the current ProfileID control

The current version of JEMMA does some internal check when an incoming message is received: it is not clear yet, but somewhere there is a check to verify that the ProfileId match the declared one by the node itself (or the supported one from the GAL).
However this check should be avoided, giving the responsability to the application to receive and handle this message (at the moment the message could be dropped and the application is not even aware that a message has arrived).

Clean-up and re-organize logging system (e.g. log4j, apache logging, ops4j.pax.logging, etc.)

Beyond selecting an appropriate logging framework, we should also perform a full round of review of all bundles and harmonize all levels and conventions. High-level information to ensure we don't derive is kept here

JEMMA-Core as a separate distribution

The core of Jemma is composed of a very limited set of bundles (5-6 in total) which provide the only functionality of discovery and communication with Energy@home devices including parsing/unparsing ZigBee clusters. All the other bundles deal with the application layers and the communication with the server.
I propose that developers shall have a simple way to download and use the JEMMA-core where the application bundles shall be considered an optional add-on

Other standards potentially to be considered for integration

This issue tracks standards which could be considered for integration in JEMMA at various levels, but which have not been discussed yet with developers.

• http://en.wikipedia.org/wiki/TR-069
• ISO/IEC/IEEE P21451-1-4 XMPP for the Smart Grid - http://www.ktc.se/wp-content/uploads/2013/05/AEC2013-NYC-NY-Rev.-12-R3.pdf

(Comment below if you have other standards to propose)

Deploy Jenkins for continuous integration + Sonar server

(to be evaluated)

Define a workflow for integrating non ZigBee HA-compliant devices

try to define a set of APIs and provide an implementation to ease the integration of non ZigBee HA compliant devices (e.g. Plugwise)

Integration of At least one storage device demonstrated

e.g. UPS, battery, etc.

First blog post with the release announcement

First blog post with the release announcement

Fix Eclipse warnings

JEMMA release 0.0.1 has more than 2049 Warnings. We should solve them in order to have a more "manageable" set of checks.

short high-level documentation for all bundles i.e. a Readme.md for each bundle

short high-level documentation for all bundles - just 1 paragraph outlining the main features of each bundle.

Implement more generic provisioning framework to enable upload to alternate cloud services

E.g. to deploy a local server, or to use a cloud provider, etc.

Simplify/streamline installation and commissioning process

First blog post with the release announcement

Incl. consistent style

Collect interesting frameworks/technologies to consider for integration

• https://github.com/openhab/openhab (list more here)
• openadr http://openadr.org/
• https://www.alljoyn.org/
• https://www.homegear.eu/index.php/Main_Page#Download_Homegear

Initial overall description and bundle list on the wiki

Initial overall description of the framework (what it is used for, what does it include, bundle list, etc.)

Maven-based toolchain shall be working for compile and run

Maven-based toolchain shall be working for compile and run, using a private maven repository for those dependencies we cannot easily pull from public repositories.

brochure/poster in PDF available on the JEMMA website

Some marketing material is needed there,

Create mailing list systems

Create mailing list systems (google groups) - including links to subscribe and some tuturial to post

Main public pages shall be created on github pages

they should include:

• high-level "marketing-style" description of the project
• links to subscribe/access mailing lists #1
• links to the wiki #2 #3
• links to code repositories and distribution channels

Provide some high-level description of the JEMMA Architecture on the Wiki

Process the latest version of the e@h use cases and classify each case (implemented, in-progress, not yet available)

related to #38

Support for etsi M2M-compliant APIs from the gateway up

Unnecessary compression of json messages

At the moment, the library used to manage json RPCs between the osgi application and the web ui, Jabsorb, tries to compress every json response that needs to be sent to the web ui.

Jabsorb has a GZip threshold that represents the minimum number of bytes gained from compression that makes acceptable to send a compressed json to the client. When the result of the compression falls below that threshold, the compressed message is discarded by the library and the original uncompressed message is sent instead.
Jemma's compressed json messages are usually so small that the compressed message is actually bigger than the original one or that the compression gain is often smaller than the threshold, so ATM compressing them seems useless.

What i've described above can be noticed looking at Jemma logs:

WARN org.jabsorb.JSONRPCServlet - gzipping resulted in a larger output size! aborting (sending non-gzipped response)... 
you may want to increase the gzip threshold if this happens a lot! original size = 1598 gzipped size = 1621

Is this issue actually relevant? It depends on where the Jemma is deployed.
While i don't have actual numbers, i suspect that when deployed on gateways with a slow CPU, the cpu time lost trying endlessly to compress json messages is not negligible (and could be used to perform other tasks).

I'm going to send in open a pull request for this (since i've already made this modification and tested it), that completely disables gzip compression. Feel free to keep it on hold until actual stats on performance will be measured.