docs/user-guide/eman-user-guide.rst

   1 .. _eman-user-guide:
   2
   3 eman User 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 those operating the features such as
  24 network administrator, cloud administrator, network engineer, or system
  25 administrators.
  26
  27 eman is composed of 3 Karaf features:
  28     * ``eman`` incudes the YANG model and its implementation
  29     * ``eman-api`` adds support for REST
  30     * ``eman-ui`` adds support for DLUX.
  31
  32 Developers will typically interface with ``eman-api``.
  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 Besides a set of common controller features eman depends upon the
  47 OpenDaylight SNMP features to be installed.
  48
  49 Configuring eman
  50 ----------------
  51
  52 eman relies upon the presence of SNMP agents.
  53
  54 The following describes a way to install and configure an SNMP simulator
  55 on localhost.
  56
  57 on macOS, open terminal
  58
  59 1. Install snmpsim.::
  60
  61     $ sudo easy_install -n snmpsim
  62
  63 2. configure filesystem::
  64
  65     mkdir ~/.snmpsim, then mkdir ~/.snmpsim/data/
  66
  67 3. Install moak data. This file is used by pysnmp to provide mock data
  68    for an APSIS agent::
  69
  70     copy eman/sample_code/data/energy-object.snmprec to ~/.snmpsim/data/.
  71
  72 4. launch snmp simulator::
  73
  74     $ sudo snmpsimd.py --agent-udpv4-endpoint=127.0.0.1:161
  75         —process-group=<your group> —process-user=<your user>
  76
  77 5. VerifyOpen another terminal window and execute::
  78
  79     $ snmpget -v2c -c energy-object localhost:161 1.3.6.1.2.1.229.0.1.0.
  80
  81    The result should be ‘1’, as defined in your snmprec file
  82
  83 .. note::
  84      group and user are settings within our local OS.
  85      For Mac users, look at settings/users and groups.
  86      If port 161 is not available, use another unprivileged port such as 1161.
  87
  88 .. note::
  89      snmpget queries snmpsimd to return a value for the OID 1.3.6.1.2.1.229.0.1.0.
  90      According to the energy-object.snmprec file, the value for that OID is ‘1’.
  91      Try other OIDs, or edit the snmprec file to see your results
  92
  93 Future release may include more flexible and robust means to simulate
  94 a network of energy aware SNMP agents.
  95
  96 Typically, a process may periodically poll a device to acquire power
  97 measurements and repose them into MD-SAL. Subsequently, process may read a
  98 history of power measurements from MD-SAL via the eman operational API.