How to write a hardware driver for OGEMA

Last modified by David Nestle on 2018/02/02 11:21

OGEMA Driver concepts

Hardware drivers typically require specific knowledge of the communication system and the available low-level libraries supporting these communications. OGEMA provides a specific driver interface, the so-called ChannelManager, which allows the separation of a driver into two components, one that takes care of the low-level communication, and another one that is responsible for the integration of data into the OGEMA database. Example drivers can be found in the public OGEMA github repository (, for instance for the Homematic, Zwave, ZigBee, or Modbus protocols, they can serve as references for driver development. Low level drivers can also interact with the OGEMA resource database via the generic ChannelMapper app if no high level driver is available, but this usually does not provide all resource structures required for app interaction.

For drivers that only require simple interaction mechanisms outside OGEMA (e.g. HTTP requests, file system operations) the separation into low level and high level driver is not really required. For this reason the example drivers provided here are "integrated" drivers that directly write information received from outside OGEMA into resources and directly send out information to external locations from resources. This is also the concept supported when a new driver is generated via the SDK. The configuration of such a driver shall be made via a custom resource type provided by the driver consisting of a resource type for the global top-level resource of the driver and a resource type for each connection, e.g.:

public interface DriverTopLevelConfiguration extends Configuration {

 ResourceList<DriverConnectionModel> connections();

// TODO: add global settings


 * Driver models should be provided in a separate app that only provides
 * additional data models such as the app generic-drivers/driver-models. In this way
 * external applications can configure driver connections without having to add a
 * dependency to the driver itself.

public interface DriverConnectionModel extends CommunicationInformation {

  * Resource to read/write (usually provided as a reference); change resource type to what the driver provides. If the driver is intended
  * to write into existing resources that are referenced, rename to "target"

 FloatResource value();

//TODO: add connection settings that are not part of the super-interface CommunicationInformation

Note that most of the example drivers below not not follow this structure yet, but it is highly recommended for new drivers. Also note that drivers generating values or entire sensor / actor devices via some king of Auto-Detect functionality like Homematic should create the respective value / device resources in their DriverConnectionModel (which may be a driver device model then), not just a reference. If the driver does not support Auto-Detect the resources of type DriverConnectionModel have to be generated by some configuration app outside the driver.

Examples for Low/High Level Drivers from the OGEMA Repository:

These examples can be found in the public OGEMA repository on Github:

  • Modbus: A generic Modbus low-level driver, supporting both Modbus RTU and TCP. The driver is based on the channel manager. For every specific Modbus device type that shall be connected a dedicated high-level driver is required. An example high-level driver is the drs485de-driver for a Modbus-based Smart Meter.
  • ZWave: a ZWave driver consisting of high- and low-level driver, based on the channel manager.
  • Homematic: a driver for the Homematic system (the driver is end of life, because the hardware dongle it is based on is no longer commercially available). Both low- and high-level drivers available. A new driver version working with the CCU2 central or Raspberry Pi Homematic board is available on Github in homematic-xmlrpc-hl (high level driver) and homematic-xmlrpc-ll (low level driver). A summery of the driver documentation and the options to extend this driver is provided as experimental tutorial. The official Documentation for the driver is provided here.

See also

Examples for Integrated Drivers

  • KNX driver: performs read and control operations via a KNX IP-bridge.
  • OpenWeatherMap connector: Reads weather forecast data via OpenWeatherMap API
  • modbus-tcp-resource: Variant of Modbus driver directly reading from / writing to resources
  • schedule-csv-driver: reads timeseries from csv files and stores them in a schedule, the OGEMA format for persistent timeseries
  • sample-androiddriver: illustrates the interaction between an Android app and the OGEMA gateway, via the OGEMA REST interface.
  • Remote REST connector: A driver to connect to another OGEMA gateway via its REST interface. Integrated driver, not using the channel manager. Available in the OGEMA Github repository.
  • Rexometer driver: Driver to connect metering and sensor devices via a Rexometer radio network.
Created by David Nestle on 2017/01/26 14:02