Skip to content

jemma refactoring goals

Jump to bottom
Riccardo edited this page Jun 1, 2017 · 4 revisions

Jemma-2.x Refactoring Plan

Introduction

JEMMA and many of its components has been developed over the last years in different projects. Although its functionality and stability are good, with the current design is rather difficult to maintain, so we would like to propose a plan to refactor parts of the code, if this is accepted by people actively using the project.

In order to clearly mark the change, we'd like to propose to develop a refactored version, working under a different major version name i.e. JEMMA 2.x.

Notes below are meant to explain what we would like to solve, why and how.

Goals of the Refactoring activity

  • Better follow New OSGi Specifications: when JEMMA was initially developed, many relevant specifications were not standard. In order to foster re-use, it makes a lot of sense to refactor the project so to follow indications of relevant OSGI standard such as e.g.
  • Better Compliance with old, well-known OSGi Specifications: a number of classes currently have problems e.g. with respect to configuration, which lead to run-time problems when configurations are altered.
  • Better compliance with correct design patterns: Also: bundle and service dependencies should be reviewed, since some users have experienced problems on bottom layers when upper layer bundles (e.g. green-at-home) are not available in the configurations.
  • Testability: with the current structure is rather difficult to automatically test stability and correct behaviour of devices. Some changes in the design could be studied to allow for automatic testing. - ideal situation: we (= us, as developers) would like to be able to detect when this happens, replicate reported problems and understand what is the problem, so to implement fix, if needed.
  • General code quality, unit testing and logging: most of the code is generally to be reviewed to ease code maintainance
    • some key components are currently badly structured (JavaGAL above all), thus they become difficult to debug.
  • Updated dependencies: JEMMA depends on some outdated components e.g. to register servlets. Some work could be done to upgrade dependencies so that we can depend on more maintained packages.
  • Compatibility with OpenHAB 2.x: at the moment, JEMMA cannot be easily used as a binding easily, as there is some dependencies clash (unless some hacks are in place, or JEMMA is executed in an external OSGi environment). This is a bad limitation in many projects
  • documentation and classes/functions/attributes naming needs to be greatly improved - ZigBee standard is rather complex, but many classes in JEMMA are just there to reflect or implement some procedures of the ZigBee standard. At least, we should have, were possible, some notes in the SW documentation explaining which part of the standard we are implementing.
  • Modularity: some users are reported to use only some of the JEMMA sub-components. It would be good to have the code structured in a way that developers are free to use JEMMA:
    • only as a DAL-compliant ZigBee driver
    • only as a plain-old Java application ( we may not be able to help on this if we want to stay fully OSGi-based - but maybe some wrapper points could be defined to ease this)
    • using it as a DOG bundle or as a VIRTUS module
    • using it as a OpenHAB binding
    • use it as a full-fledged gateway including JEMMA application bundles
  • relation with up-stream projects
    • we have been recently testing with tlaukkan/zigbee4java project, which has some common ancestor with JEMMA, and results are rather good,although it's currently limited to Texas Instruments dongles
    • tlaukkan/zigbee4java is more generic since it works on plain (non-OSGi) Java
    • We may consider transitioning our Freescale-related code (i.e. tu support KW2x dongles) to the same format and the refactor our code to wrap tlaukkan/zigbee4java as upstream project
    • Advantage: tlaukkan/zigbee4java users will gain a new dongle support, we may have a broader community (Java Community > OSGi community) testing and debugging the existing KW2x support. In the process we gain support for the TI dongle.
  • Improving structure of the SW project
    • ideal situation: a smaller number of git repositories (i.e. maybe even just one for the core ZigBee OSGi driver), a MINIMAL set of bundles which can be incorporated to properly handle interaction with Energy@home devices.

Reference Architecture

The following pictures (made with Visual Paradigm) outlines the new proposed high-level design of the JEMMA Gateway.

JEMMA-2.x-overall.svg

The zigbee-osgi-driver is an OSGi bundle which handles all the ZigBee-dependant features. It can be accessed by other OSGi components by means of the Device Abstract Layer (DAL) specifications.

Modules accessing the DAL include e.g. :

  • jemma-dal-webapi: the component which exposes DAL API remotely (i.e. via REST or WebSocket)
  • JEMMA-local-binding: the component which makes JEMMA services available within OpenHAB 2.x
  • Any of the Energy@home services
  • Any other OSGi bundle acting as a standard client for DAL specification (e.g. local applications)

Third-party applications will use JEMMA DAL API locally (if they are hosted as local OSGi bundles) OR via the REST/WebSocket API provided by jemma-dal-webapi, as in the case of the JEMMA GUIs.

zigbee-osgi-driver details

The following picture provides a internal details of zigbee-osgi-driver. The internal architecture has been re-design to simplify upstream dependency from the tlaukkan/zigbee4java project.

JEMMA-2.x-zigbee-osgi-driver.svg

zigbee-osgi-driver-implementation (likely this will be a Java package) includes most of the implementation exposing the DAL API. It will have visibility on all required classes and interfaces imported from the tlaukkan/zigbee4java project, including zigbee-dongle-kw2x.

The main goal of zigbee-osgi-driver-implementation is to provide compliance with ZigBeeDevice Service Specification, meaning that it implements the ZigBee protocols and handles the interaction with bundles that use the ZigBee devices. It must discover ZigBee devices on the ZigBee network and map each discovered device into an OSGi registered ZigBeeNode services. It must also export, on the ZigBee Network ZigBeeEndpoint services.

zigbee-dongle-kw2x is a new implementation compliant with the zigbee4java patterns, which provides zigbee4java-dongle-api. This component imports zigbee-common-api provided by zigbee-common component. This component will be contributed to the zigbee4java project (or a dedicated fork, if this is not of interest for the zigbee4java community).

zigbee-common: is the package defining all ZigBee dongle and network interface, which are the two main interfaces for extending supported dongle devices. Also in zigbee4java v3 version, it unifies ZCL and ZDO which could be used by dongle implementation. This component exports zigbee4java-common-api, and will thus be imported in zigbee-osgi-driver.

Since zigbee-osgi-driver overall need to be compliant with OSGi-based services including Serial Device Service and USB Information Device Service, a dedicated internal component (i.e. the zigbee-serial-osgi class) will act as wrapper providing serial port communication for different dongles. This will play the same role played by zigbee-serial-android for Android implementations, but for OSGi.

Clone this wiki locally