docs/developer-guide/eman-developer-guide.rst

   1 .. _eman-dev-guide:
   2
   3 eman Developer Guide
   4 ====================
   5
   6 Overview
   7 --------
   8
   9 The OpenDaylight Energy Management (eman) plugin implements an abstract
  10 Information Model that describes energy measurement and control features
  11 that may be supported by a variety of device types. The eman plugin may
  12 support a number of southbound interfaces to accommodate a set of
  13 protocols, including but not limited to SNMP, NETCONF, IPDR. The plugin
  14 presents a northbound REST API. This framework enables any number of
  15 applications to interoperate with any number of devices in order to
  16 measure and optimize energy usage. The Information Model will be
  17 inherited from the `SCTE 216 standard – Adaptive Power Systems Interface
  18 Specification (APSIS)
  19 <http://www.scte.org/SCTEDocs/Standards/ANSI_SCTE%20216%202015.pdf>`_,
  20 which in turn inherits definitions within the `IETF eman document set
  21 <https://datatracker.ietf.org/wg/eman/documents/>`_.
  22
  23 This documentation is directed to developers who may use the eman features
  24 to build other OpenDaylight features or applications.
  25
  26 eman is composed of 3 Karaf features:
  27     * ``eman`` incudes the YANG model and its implementation
  28     * ``eman-api`` adds support for REST
  29     * ``eman-ui`` adds support for DLUX.
  30
  31 Developers will typically interface with ``eman-api``.
  32
  33
  34 eman Architecture
  35 -----------------
  36
  37 ``eman`` defines a YANG model that represents the IETF energy management
  38 Information Model, and includes RPCs. The implementation of the model
  39 currently supports an SNMP 'binding' via interfacing with the
  40 OpenDaylight SNMP module. In the future, other Southbound protocols may
  41 be supported.
  42
  43 Developers my use the ``eman-api`` feature to read and write energy
  44 related data and commands to devices that support the IETF eman MIBS.
  45
  46 Key APIs and Interfaces
  47 -----------------------
  48
  49 The eman API currently supports a subset of the IETF eman Information Model,
  50 including the EnergyObjectPowerMeasurement table. Users of the API may
  51 get individual attributes or the entire table. When querying the table, the
  52 results are written into the MD-SAL, for subsequent access. For example,
  53 a developer may periodically poll a device for its powerMeasurements,
  54 and fetch a collection of measurements to discover a history of measurements.
  55
  56
  57 Operational API
  58 ---------------
  59
  60 Via MD-SAL, the following endpoint provides access to previously
  61 captured power measurements.
  62
  63 .. note::
  64   "eo" indicates "energy object" as per the IETF Information Model
  65
  66 operational::
  67
  68   eman:eoDevices/eoDevice{id}/eoPowerMeasurement{id}
  69
  70     id indicates an index into a collection
  71
  72 EoDevices may contain a collection of individual eoDevice objects, which
  73 in turn may contain a collection of eoPowerMeasurement objects
  74
  75 Operations API
  76 --------------
  77
  78 A set of RPCs enable interactions with devices.
  79
  80 get-eoAttribute enables query on an individual attribute of a energy object::
  81
  82   get-eoAttribute
  83
  84     deviceIP indicates IP address of target device
  85     attribute indicates name of requested attribute
  86
  87 .. note:: Future releases will provide a enumeration of allowed names.
  88
  89 The supported name are:
  90
  91 * eoPower
  92 * eoPowerNameplate
  93 * eoPowerUnitMultiplier
  94 * eoPowerAccuracy
  95 * eoPowerMeasurementCaliber
  96 * eoPowerCurrentType
  97 * eoPowerMeasurementLocal
  98 * eoPowerAdminState
  99 * eoPowerOperState
 100 * eoPowerStateEnterReason
 101
 102 set-eoAttribute enables sending a command to an energy object::
 103
 104   set-eoAttribute
 105
 106     deviceIP. IP address of target device
 107     attribute. string indicating name of attribute. Currently, no attributes
 108
 109 get-eoDevicePowerMeasures reads an eoPowerMEasurements table from a device
 110 and stores the result in MD-SAL, making it available vie the operational API::
 111
 112   get-eoDevicePowerMeasures
 113
 114     deviceIP. IP address of target device
 115
 116 API Reference Documentation
 117 ---------------------------
 118
 119 See eman project page for additional information:
 120 https://wiki.opendaylight.org/view/eman:Main