[Search] [txt|xml|pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00                                                            
Energy Management Working Group                              A. Petrescu
Internet-Draft                                          S. Ben Hadj Said
Intended status: Informational                                 CEA, LIST
Expires: January 9, 2017                                      E. Harjula
                                                      University of Oulu
                                                      A. Plymoth Nilsson
                                                                  Telhoc
                                                            B. Landfeldt
                                                         Lund University
                                                            July 8, 2016


                       YANG Model of Battery MIB
                 draft-petrescu-battery-mib-yang-00.txt

Abstract

   This document describes a YANG data model for battery monitoring.
   The model is based on the Battery-MIB module definition that was
   elaborated in [RFC7577].

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on January 9, 2017.

Copyright Notice

   Copyright (c) 2016 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect



Petrescu, et al.         Expires January 9, 2017                [Page 1]


Internet-Draft              battery-mib-yang                   July 2016


   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Battery-MIB: Overview . . . . . . . . . . . . . . . . . . . .   3
   5.  Yang module definition  . . . . . . . . . . . . . . . . . . .   5
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  27
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  27
   8.  Contributors  . . . . . . . . . . . . . . . . . . . . . . . .  27
   9.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  28
   10. Normative References  . . . . . . . . . . . . . . . . . . . .  28
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  29

1.  Introduction

   This document describes the YANG data model [RFC6020] [RFC6021] of
   the Battery-MIB module [RFC7577].  The main task of the Battery-MIB
   module is to provide information about the battery in use and raise
   notifications about its status.

   Translating the Battery-MIB module into a standardized language such
   as YANG is crucial as it promotes interoperability between networking
   devices, SDN controllers and applications from different
   manufacturers, different revisions and different function sets.  This
   in turn enables management and control systems to be built and
   implemented in systems where battery operated devices perform tasks.
   Example application areas are ad-hoc networks, routing decisions and
   protocols, sensor based systems where actions to extend sensor life
   times are necessary, and mode.  The YANG extension to the Battery-MIB
   module enables interoperability between all components of these
   systems, allowing newer and older devices to co-exist and easy
   integration with evolving network management tools and services.
   Even though the extension adds additional overheads in terms of data
   size and memory requirement, the penalty is quite limited so that the
   advantages of a unified description method outweighs the cost
   involced.

   Using a YANG model, the Battery MIB can be exposed by a networking
   device via different protocols such as NETCONF [RFC6241], RESTCONF
   [I-D.draft-ietf-netconf-restconf], CoMI
   [I-D.draft-vanderstock-core-comi].  Furthermore, it can be encoded
   either in XML or JSON [I-D.draft-ietf-netmod-yang-json].  This YANG



Petrescu, et al.         Expires January 9, 2017                [Page 2]


Internet-Draft              battery-mib-yang                   July 2016


   module fits perfectly for use with the CoMI protocol in the context
   of communications between constrained devices where the knowledge
   about devices batteries status is of paramount importance.

   The YANG module of Battery-MIB respects the translation rules defined
   in [RFC6643].  The model has been validated with the on-line tool
   yangdump-pro at http://www.netconfcentral.org/run_yangdump (address
   accessed in July 2016).

2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].

   MIB: Management Information Base

   YANG: Yet Another Next Generation

3.  Tree Diagrams

   A simplified graphical representation of the data model is used in
   the YANG modules specified in this document.  The meaning of the
   symbols in these diagrams is as follows:

   o  Brackets "[" and "]" enclose list keys.

   o  Abbreviations before data node names: "rw" means
      configuration(read-write) and "ro" state data (read-only).

   o  Symbols after data node names: "?" means an optional node, "!"
      means a presence container, and "*" denotes a list and leaf-list.

   o  Parentheses enclose choice and case nodes, and case nodes are also
      marked with a colon (":").

   o  Ellipsis ("...") stands for contents of subtrees that are not
      shown.

4.  Battery-MIB: Overview

   The Battery-MIB module defines a set of objects for reporting
   information about batteries and seven notifications mechanisms
   [RFC7577].  The batteryTable and batteryEntry in Battery-MIB module
   are represented by a container and list nodes, respectively, in YANG
   language.  Then, the managed objects inside the batteryEntry are
   represented by leaf nodes.  The tree diagrams of the Battery-MIB data




Petrescu, et al.         Expires January 9, 2017                [Page 3]


Internet-Draft              battery-mib-yang                   July 2016


   model and notifications are depicted in Figure 1 and Figure 2,
   respectively.

+--rw batteryTable
  +--rw batteryEntry* [entPhysicalIndex]
    +--rw entPhysicalIndex                 -> /ent-mib:entityPhysical/entPhysicalEntry/entPhysicalIndex
    +--ro batteryIdentifier?               snmp:SnmpAdminString
    +--ro batteryFirmwareVersion?          snmp:SnmpAdminString
    +--ro batteryType?                     enumeration
    +--ro batteryTechnology?               uint32
    +--ro batteryDesignVoltage?            uint32
    +--ro batteryNumberOfCells?            uint32
    +--ro batteryDesignCapacity?           uint32
    +--ro batteryChargingCurrent?          uint32
    +--ro batteryTrickleChargingCurrent?   uint32
    +--ro batteryActualCapacity?           uint32
    +--ro batteryChargingCycleCount?       uint32
    +--ro batteryLastChargingCycleTime?    y-type:date-and-time
    +--ro batteryChargingOperState?        enumeration
    +--rw batteryChargingAdminState?       enumeration
    +--ro batteryActualCharge?             uint32
    +--rw batteryActualVoltage?            uint32
    +--ro batteryActualCurrent?            int32
    +--ro batteryTemperature?              int32
    +--rw batteryAlarmLowCharge?           uint32
    +--rw batteryAlarmLowVoltage?          uint32
    +--rw batteryAlarmLowCapacity?         uint32
    +--rw batteryAlarmHighCycleCount?      uint32
    +--rw batteryAlarmHighTemperature?     int32
    +--rw batteryAlarmLowTemperature?      int32
    +--ro batteryCellIdentifier?           snmp:SnmpAdminString

                  Figure 1: Battery Data Model Structure

notifications:
   +---n batteryChargingStateNotification
   |  +--ro batteryChargingStateNotification-batteryChargingOperState
   |     +--ro entPhysicalIndex?           -> /batteryTable/batteryEntry/entPhysicalIndex
   |     +--ro batteryChargingOperState?   -> /batteryTable/batteryEntry/batteryChargingOperState
   +---n batteryLowNotification
   |  +--ro batteryLowNotification-batteryCellIdentifier
   |  |  +--ro entPhysicalIndex?        -> /batteryTable/batteryEntry/entPhysicalIndex
   |  |  +--ro batteryCellIdentifier?   -> /batteryTable/batteryEntry/batteryCellIdentifier
   |  +--ro batteryLowNotification-batteryActualCharge
   |  |  +--ro entPhysicalIndex?      -> /batteryTable/batteryEntry/entPhysicalIndex
   |  |  +--ro batteryActualCharge?   -> /batteryTable/batteryEntry/batteryActualCharge
   |  +--ro batteryLowNotification-batteryActualVoltage
   |     +--ro entPhysicalIndex?       -> /batteryTable/batteryEntry/entPhysicalIndex



Petrescu, et al.         Expires January 9, 2017                [Page 4]


Internet-Draft              battery-mib-yang                   July 2016


   |     +--ro batteryActualVoltage?   -> /batteryTable/batteryEntry/batteryActualVoltage
   +---n batteryCriticalNotification
   |  +--ro batteryCriticalNotification-batteryCellIdentifier
   |  |  +--ro entPhysicalIndex?        -> /batteryTable/batteryEntry/entPhysicalIndex
   |  |  +--ro batteryCellIdentifier?   -> /batteryTable/batteryEntry/batteryCellIdentifier
   |  +--ro batteryCriticalNotification-batteryActualCharge
   |  |  +--ro entPhysicalIndex?      -> /batteryTable/batteryEntry/entPhysicalIndex
   |  |  +--ro batteryActualCharge?   -> /batteryTable/batteryEntry/batteryActualCharge
   |  +--ro batteryCriticalNotification-batteryActualVoltage
   |     +--ro entPhysicalIndex?       -> /batteryTable/batteryEntry/entPhysicalIndex
   |     +--ro batteryActualVoltage?   -> /batteryTable/batteryEntry/batteryActualVoltage
   +---n batteryTemperatureNotification
   |  +--ro batteryTemperatureNotification-batteryCellIdentifier
   |  |  +--ro entPhysicalIndex?        -> /batteryTable/batteryEntry/entPhysicalIndex
   |  |  +--ro batteryCellIdentifier?   -> /batteryTable/batteryEntry/batteryCellIdentifier
   |  +--ro batteryTemperatureNotification-batteryTemperature
   |     +--ro entPhysicalIndex?     -> /batteryTable/batteryEntry/entPhysicalIndex
   |     +--ro batteryTemperature?   -> /batteryTable/batteryEntry/batteryTemperature
   +---n batteryAgingNotification
   |  +--ro batteryAgingNotification-batteryCellIdentifier
   |  |  +--ro entPhysicalIndex?        -> /batteryTable/batteryEntry/entPhysicalIndex
   |  |  +--ro batteryCellIdentifier?   -> /batteryTable/batteryEntry/batteryCellIdentifier
   |  +--ro batteryAgingNotification-batteryActualCapacity
   |  |  +--ro entPhysicalIndex?        -> /batteryTable/batteryEntry/entPhysicalIndex
   |  |  +--ro batteryActualCapacity?   -> /batteryTable/batteryEntry/batteryActualCapacity
   |  +--ro batteryAgingNotification-batteryChargingCycleCount
   |     +--ro entPhysicalIndex?            -> /batteryTable/batteryEntry/entPhysicalIndex
   |     +--ro batteryChargingCycleCount?   -> /batteryTable/batteryEntry/batteryChargingCycleCount
   +---n batteryConnectedNotification
   |  +--ro batteryConnectedNotification-batteryIdentifier
   |     +--ro entPhysicalIndex?    -> /batteryTable/batteryEntry/entPhysicalIndex
   |     +--ro batteryIdentifier?   -> /batteryTable/batteryEntry/batteryIdentifier
   +---n batteryDisconnectedNotification

                 Figure 2: Battery notifications Structure

5.  Yang module definition

<CODE BEGINS>
module BATTERY-MIB {
yang-version 1;
namespace
  "urn:ietf:params:xml:ns:yang:smiv2:BATTERY-MIB";
prefix "battery";

import ietf-yang-types      { prefix "y-type"; }
import SNMP-FRAMEWORK-MIB   { prefix "snmp"; }
import ENTITY-MIB           { prefix "ent-mib"; }



Petrescu, et al.         Expires January 9, 2017                [Page 5]


Internet-Draft              battery-mib-yang                   July 2016


organization
    "IETF EMAN (Energy Management) Working Group";

contact
    "General Discussion: eman@ietf.organization
    To subscribe: <http://www.ietf.org/mailman/listinfo/eman>
    Archive: <http://www.ietf.org/mail-archive/web/eman>
    Editor:
        Juergen Quittek
        NEC Europe, Ltd.
        NEC Laboratories EuropeKurfuersten-Anlage 36
        69115 Heidelberg
        Germany
        Tel: +49 6221 4342-115
        Email: quittek@neclab.eu

    Translated to YANG model:
        Siwar Ben Hadj Said
        CEA, LIST
        France
        Email: siwar.benhadjsaid@cea.fr";

description
    "This MIB module defines a set of objects for monitoring
    batteries of networked devices and their components.

    Copyright (c) 2015 IETF Trust and the persons identified as
    authors of the code.  All rights reserved.

    Redistribution and use in source and binary forms, with or
    without modification, is permitted pursuant to, and subject
    to the license terms contained in, the Simplified BSD License
    set forth in Section 4.c of the IETF Trust's Legal Provisions
    Relating to IETF Documents
      (http://trustee.ietf.org/license-info).

    This version of this MIB module is part of RFC 7577; see
    the RFC itself for full legal notices.";

    revision "2015-06-15"{
      description
        "Initial version published as RFC 7577.";
    }

/***  DATA Model   ***/

container batteryTable {
  description



Petrescu, et al.         Expires January 9, 2017                [Page 6]


Internet-Draft              battery-mib-yang                   July 2016


   "This table provides information on batteries. It contains
    one conceptual row per battery in a managed entity.

    Batteries are indexed by the entPhysicalIndex of the
    entPhysicalTable defined in the ENTITY-MIB (RFC 6933).

    For implementations of the BATTERY-MIB, an implementation of
    the ENTITY-MIB complying with the entity4RCCompliance
    MODULE-COMPLIANCE statement of the the ENTITY-MIB is required.

    If batteries are replaced, and the replacing battery uses
    the same physical connector as the replaced battery, then
    the replacing battery SHOULD be indexed with the same value
    of object entPhysicalIndex as the replaced battery.";

  list batteryEntry {
    key "entPhysicalIndex";
    description
     "An entry providing information on a battery.";

    leaf entPhysicalIndex {
      type leafref {
        path "/ent-mib:entityPhysical/ent-mib:entPhysicalEntry/ent-mib:entPhysicalIndex";
      }
      description
       "This object allows to identify the slot of the device
       in which the battery is currently contained. It is defined
       in the Entity-MIB module.";
    }

    leaf batteryIdentifier{
      type  snmp:SnmpAdminString;
      config false;
      description
       "This object contains an identifier for the battery.

       Many manufactures deliver not only simple batteries
       but battery packages including additional hardware
       and firmware.

       Typically, these modules include an identifier that
       can be retrieved by a device in which a battery
       has been installed. The identifier is useful in the
       same or other devices. Then, the device or the
       network management system can trace batteries and
       achieve continuity of battery monitoring.

       If the battery is identified by more than one value,



Petrescu, et al.         Expires January 9, 2017                [Page 7]


Internet-Draft              battery-mib-yang                   July 2016


       for example, by a model number and a serial number,
       then the value of this object is a concatenation of
       these values, separated by the colon symbol ':'. The
       values should be ordered so that a more significant
       value comes before a less significant one. In the
       example above, the (more significant) model number
       would be first, and the serial number would follow:
       '<model number>:<serial number>'.

       If the battery identifier cannot be represented using
       the ISO/IEC IS 10646-1 character set, then a
       hexadecimal encoding of a binary representation of
       the entire battery identifier must be used.

       The value of this object must be an empty string if
       there is no battery identifier or if the battery
       identifier is unknown.";
    }

    leaf batteryFirmwareVersion{
      type snmp:SnmpAdminString;
      config false;
      description
       "This object indicates the version number of the
        firmware that is included in a battery module.

        Many manufacturers deliver not pure batteries but
        battery packages including additional hardware
        and firmware.

        Since the behavior of the battery may change with
        the firmaware, it may be useful to retrieve the
        firmware version number.

        The value of this object must be an empty string
        if there is no firmware or if the version number
        of the firmware is unknown.";
    }

    leaf batteryType{
      type enumeration{
            enum "unknown"      { value 1; }
            enum "other"        { value 2; }
            enum "primary"      { value 3; }
            enum "rechargeable" { value 4; }
            enum "capacitor"    { value 5; }
      }
      config false;



Petrescu, et al.         Expires January 9, 2017                [Page 8]


Internet-Draft              battery-mib-yang                   July 2016


      description
        "This object indicates the type of battery.
        It distinguishes between primary (not
        rechargeable) batteries, rechargeable (secondary)
        batteries, and capacitors. Capacitors are not
        really batteries but are often used in the same
        way as a battery.

        The value other (2) can be used if the battery
        type is known but is none of the ones above.
        Value unknoown (1) is to be used if the type
        battery cannot be determined.";
    }

    leaf batteryTechnology {
      type uint32;
      config false;
      description
        "This object indicates the technology used by the
        battery. Numbers identifying battery technologies
        are registered at IANA. A current list of
        assignements can be found at
        (http://www.iana.org/assignements/battery-technologies).

        Value unknown(1) MUST be used if the technology
        of the battery cannot be determined.

        Value other(2) can be used if the battery
        technology is known but is not one of the types
        already registered at IANA.";
    }

    leaf batteryDesignVoltage {
      type  uint32;
      units "millivolt";
      config false;
      description
        "This object provides the design (or nomial) voltage
        of the battery in units of millivolt (mV).

        Note that the design voltage is a constant value and
        typically different from the actual voltage of the
        battery.

        A value of 0 indicates that the design voltage is
        unknown.";
    }




Petrescu, et al.         Expires January 9, 2017                [Page 9]


Internet-Draft              battery-mib-yang                   July 2016


    leaf batteryNumberOfCells {
      type uint32;
      config false;
      description
        "This object indicates the number of cells
        contained in the battery. A value of 0 indicates
        that the number of cells is unknown.";
    }

    leaf batteryDesignCapacity {
      type uint32;
      units "milliampere hours";
      config false;
      description
        "This object provides the design (or nominal)
        capacity of the battery in units of milliampere
        hours (mAh).

        Note that the design capacity is a constant value
        and typically different from the actual capacity
        of the battery. usually, this is a value provided
        by the manufacturer of the battery.

        A value of 0 indicates that the design capacity is
        unknown.";
    }

    leaf batteryChargingCurrent {
      type uint32;
      units "milliampere";
      config false;
      description
        "This object provides the maximum current to be used
        for charging the battery in units of milliampere (mA).

        Note that the maximum charging charging current may
        not lead to optimal charge of the battery and that
        some batteries can only be charged with the maximum
        current for limited amount of time.

        A value of 0 indicates that the maximum charging
        current is unknown.";
    }

    leaf batteryTrickleChargingCurrent {
      type uint32;
      units "milliampere";
      config false;



Petrescu, et al.         Expires January 9, 2017               [Page 10]


Internet-Draft              battery-mib-yang                   July 2016


      description
        "This obkject provides the recommended average
        current to be used for trickle charging the battery
        in units of mA.

        Typically, this is a value recommanded by the
        manufacturer of the battery or by the manufacturer
        of the charging circuit.

        A value of 0 indicates that the recommanded trickle
        charging current is unknown.";
    }

    leaf batteryActualCapacity {
      type uint32;
      units "milliampere hours";
      config false;
      description
        "This object provides the actual capacity of the
        battery in units of mAh.

        Typically, the actual capacity of battery decreases
        with time and with usage of the battery. It is
        usually lower that the design capacity.

        Note that the actual capacity needs to be measured
        and is typically an estimate based on observed
        discharging and charging cycles of the battery.

        A value of 'ffffffff'H indicates that the actual
        capacity cannot be determined.";
    }

    leaf batteryChargingCycleCount {
      type uint32;
      config false;
      description
        "This object indicates the number of completed
        charging cycles that the battery underwent.
        In line with the Smart Battery Data Specification
        Revision 1.1, a charging cycle is defined as the
        process of discharging the battery by a total
        amount equal to the battery design capacity as
        given by object batteryDesignCapacity. A charging
        cycle may include several steps of charging and
        discharging the battery until the discharging
        amount given by batteryDesignCapacity has been
        reached.  As soon as a charging cycle has been



Petrescu, et al.         Expires January 9, 2017               [Page 11]


Internet-Draft              battery-mib-yang                   July 2016


        completed, the next one starts immediately,
        independent of the battery's current charge at
        the end of the cycle.

        For batteries of type primary(3), the value of this
        object is always 0. A value of 'ffffffff'H
        indicates that the number of charging cycles cannot
        be determined.";
    }

    leaf batteryLastChargingCycleTime {
      type y-type:date-and-time;
      config false;
      description
        "The date and time of the last charging cycle. The
        value '0000000000000000'H is returned if the
        battery has not been charged yet or if the last
        charging time cannot be determined.

        For batteries of type primary(1), the value of this
        object is always '0000000000000000'H.";
    }

    leaf batteryChargingOperState {
      type enumeration{
            enum "unknown"           { value 1; }
            enum "charging"          { value 2; }
            enum "maintainingCharge" { value 3; }
            enum "noCharging"        { value 4; }
            enum "discharging"       { value 5; }
        }
      config false;
      description
        "This object indicates the current charging state
        of the battery. Value unknown(1) indicates that
        the charging state of the battery cannot be determined.

        Value charging(2) indicates that the battery is
        being charged in a way such that the charge of
        the battery increases.

        Value maintainingCharge(3) indicates that the
        battery is being charged with a low-average current
        that compensates self-discharging. This includes
        trickle charging, float charging, and other methods
        for maintaining the current charge of a battery. In
        typical implementations of charging controllers,
        state maintainingCharge(3) is only applied if the



Petrescu, et al.         Expires January 9, 2017               [Page 12]


Internet-Draft              battery-mib-yang                   July 2016


        battery is fully charged or almost fully charged.

        Value noCharging(4) indicates that the battery is
        not being charged or discharged by electric current
        between the battery and electric circuits external
        to the battery. Note that the battery may still
        be subject to self-discharging.

        Value discharging(5) indicates that the battery is
        either used as the power source for electric
        circuits external to the battery or discharged
        intentionally by the charging controller, e.g.,
        for the purpose of battery maintenance. In any
        case, the charge of the battery decreases.";
    }

    leaf batteryChargingAdminState {
      type enumeration{
            enum notSet         { value 1; }
            enum charge         { value 2; }
            enum doNotCharge    { value 3; }
            enum discharge      { value 4; }
        }
      config true;
      description
        "The value of this object indicates the desired
        charging state of the battery. The real state
        is indicated by object batteryChargingOperState.
        See the definition of object
        batteryChargingOperState for a description of the
        values.

        When this object is initialized by an
        implementation of the BATTERY-MIB module, its value
        is set to notSet(1). In this case, the charging
        controller is free to choose which operational
        state is suitable.

        When the batteryChargingAdminState object is set,
        then the BATTERY-MIB implementation must try to
        set the battery to the indicated state. The result
        will be indicated by object batteryChargingOperState.

        Setting object batteryChargingAdminState to value
        notSet(1) is a request to the charging controller
        to operate autonomously and choose the operational
        state that is suitable.




Petrescu, et al.         Expires January 9, 2017               [Page 13]


Internet-Draft              battery-mib-yang                   July 2016


        Setting object batteryChargingAdminState to value
        charge(2) is a request to enter the operational
        state charging(2) until the battery is fully
        charged.  When the battery is fully charged,
        or if the battery was already fully charged or
        almost fully charged at the time of the request,
        the operational state will change to
        maintainingCharge(3) if the charging controller
        and the battery support the functionality of
        maintaining the charge,or it will change to
        noCharging(4) otherwise.

        Setting object batteryChargingAdminState to value
        doNotCharge(3) is a request for entering operational
        state noCharging(4).

        Setting object batteryChargingAdminState to value
        discharge(4) is a request for entering operational
        state discharging(5). Discharging can be
        accomplished by ordinary use, applying a dedicated
        load, or any other means.  An example for applying
        this state is battery maintenance.  If the battery
        is empty or almost empty, the operational state
        will change to noCharging(4).

        The charging controller will decide which charge
        condition will be considered empty dependent on the
        battery technology used.  This is done to avoid
        damage on the battery due to deep discharge.

        Due to operational conditions and limitations of
        the implementation of the BATTERY-MIB module,
        changing the battery status according to a set
        value of object batteryChargingAdminState may
        not be possible. Setting the value of object
        batteryChargingAdminState may result in not
        changing the state of the battery to this value or
        even in setting the charging state to another value
        than the requested one. For example, the charging
        controller might at any time decide to enter state
        discharging(5), if there is an operational need to
        use the battery for supplying power.";
    }

    leaf batteryActualCharge {
      type uint32;
      units "milliampere hours";
      config false;



Petrescu, et al.         Expires January 9, 2017               [Page 14]


Internet-Draft              battery-mib-yang                   July 2016


      description
        "This object provides the actual charge of the
        battery in units of mAh.

        Note that the actual charge needs to be measured
        and is typically an estimate based on observed
        discharging and charging cycles of the battery.

        A value of 'ffffffff'H indicates that the actual
        charge cannot be determined.";
    }

    leaf batteryActualVoltage {
      type uint32;
      units "millivolt";
      description
        "This object provides the actual voltage of the
        battery in units of mV.
        A value of 'ffffffff'H indicates that the actual
        voltage cannot be determined.";
    }

    leaf batteryActualCurrent {
      type int32;
      units "milliampere";
      config false;
      description
        "This object provides the actual charging or
        discharging current of the battery in units of mA.

        The charging current is represented by positive
        values, and the discharging current is represented
        by negative values.

        A value of '7fffffff'H indicates that the actual
        current cannot be determined.";
    }

    leaf batteryTemperature {
      type int32;
      units "deci-degrees Celsius";
      config false;
      description
        "The ambient temperature at or within close
        proximity of the battery.
        A value of '7fffffff'H indicates that the
        temperature cannot be determined.";
    }



Petrescu, et al.         Expires January 9, 2017               [Page 15]


Internet-Draft              battery-mib-yang                   July 2016


    leaf batteryAlarmLowCharge {
      type uint32;
      units "milliampere hours";
      config true;
      description
        "This object provides the lower-threshold value for
        object batteryActualCharge.  If the value of object
        batteryActualCharge falls below this threshold, a
        low-battery alarm will be raised.  The alarm
        procedure may include generating a
        batteryLowNotification.

        This object should be set to a value such that when
        the batteryLowNotification is generated, the battery
        is still sufficiently charged to keep the device(s)
        that it powers operational for a time long enough to
        take actions before the powered device(s) enters a
        'sleep' or 'off' state.

        A value of 0 indicates that no alarm will be raised
        for any value of object batteryActualVoltage.";
    }

    leaf batteryAlarmLowVoltage {
      type uint32;
      units "millivolt";
      config true;
      description
        "This object provides the lower-threshold value for
        object batteryActualVoltage.  If the value of object
        batteryActualVoltage falls below this threshold, a
        low-battery alarm will be raised.  The alarm
        procedure may include generating a
        batteryLowNotification.

        This object should be set to a value such that when
        the batteryLowNotification is generated, the battery
        is still sufficiently charged to keep the device(s)
        that it powers operational for a time long enough to
        take actions before the powered device(s) enters a
        'sleep' or 'off' state.

        A value of 0 indicates that no alarm will be raised
        for any value of object batteryActualVoltage.";
    }

    leaf batteryAlarmLowCapacity {
      type uint32;



Petrescu, et al.         Expires January 9, 2017               [Page 16]


Internet-Draft              battery-mib-yang                   July 2016


      units "milliampere hours";
      config true;
      description
        "This object provides the lower-threshold value for
        object batteryActualCapacity.  If the value of
        object batteryActualCapacity falls below this
        threshold, a battery aging alarm will be raised.
        The alarm procedure may include generating a
        batteryAgingNotification.

        A value of 0 indicates that no alarm will be raised
        for any value of object batteryActualCapacity.";
    }

    leaf batteryAlarmHighCycleCount {
      type uint32;
      config true;
      description
        "This object provides the upper-threshold value for
        object batteryChargingCycleCount.  If the value of
        object batteryChargingCycleCount rises above this
        threshold, a battery aging alarm will be raised.
        The alarm procedure may include generating a
        batteryAgingNotification.

        A value of 0 indicates that no alarm will be raised
        for any value of object batteryChargingCycleCount.";
    }

    leaf batteryAlarmHighTemperature {
      type int32;
      units "deci-degrees Celsius";
      config true;
      description
        "This object provides the upper-threshold value for
        object batteryTemperature.  If the value of object
        batteryTemperature rises above this threshold, a
        battery high temperature alarm will be raised. The
        alarm procedure may include generating a
        batteryTemperatureNotification.

        A value of '7fffffff'H indicates that no alarm
        will be raised for any value of object
        batteryTemperature.";
    }

    leaf batteryAlarmLowTemperature {
      type int32;



Petrescu, et al.         Expires January 9, 2017               [Page 17]


Internet-Draft              battery-mib-yang                   July 2016


      units "deci-degrees Celsius";
      config true;
      description
        "This object provides the lower-threshold value for
        object batteryTemperature.  If the value of object
        batteryTemperature falls below this threshold, a
        battery low temperature alarm will be raised. The
        alarm procedure may include generating a
        batteryTemperatureNotification.

        A value of '7fffffff'H indicates that no alarm will
        be raised for any value of object batteryTemperature.";
    }

    leaf batteryCellIdentifier {
      type snmp:SnmpAdminString;
      config false;
      description
        "The value of this object identifies one or more
        cells of a battery. The format of the cell
        identifier may vary between different implementations.
        It should uniquely identify one or more cells of
        the indexed battery.

        This object can be used for batteries, such as lithium
        polymer batteries for which battery controllers monitor
        cells individually.

        This object is used by notifications of types
        batteryLowNotification, batteryTemperatureNotification,
        batteryCriticalNotification, and batteryAgingNotification.
        These notifications can use the value of this object
        to indicate the event that triggered the generation of
        the notification in more detail by specifying a single
        cell or a set of cells within the battery that is specifically
        addressed by the notification.

        An example use case for this object is a single
        cell in a battery that exceeds the temperature
        indicated by object batteryAlarmHighTemperature.
        In such a case,a batteryTemperatureNotification
        can be generated that not only indicates the
        battery for which the temperature limit has been
        exceeded but also the particular cell. The initial
        value of this object is the empty string.
        The value of this object is set each time a
        batteryLowNotification, batteryTemperatureNotification,
        batteryCriticalNotification, or



Petrescu, et al.         Expires January 9, 2017               [Page 18]


Internet-Draft              battery-mib-yang                   July 2016


        batteryAgingNotification is generated.

        When a notification is generated that does not
        indicate a specific cell or set of cells, the
        value of this object is set to the empty string.";
    }
  }
}

/***  Battery Notifications  ***/

notification batteryChargingStateNotification {
  description
    "This notification can be generated when a charging state
    of the battery (indicated by the value of object
    batteryChargingOperState) is triggered by an event other
    than a write action to object batteryChargingAdminState.
    Such an event may, for example, be triggered by a local
    battery controller.";

  container batteryChargingStateNotification-batteryChargingOperState {
    description
      "It indicates the charging state of the battery";

    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
         in which the battery is currently contained.";
    }

    leaf batteryChargingOperState {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryChargingOperState";
      }
      description
        "It indicates the current charging state of the battery.";
    }
  }
}

notification batteryLowNotification {
  description
    "This notification can be generated when the current
    charge (batteryActualCharge) or the current voltage
    (batteryActualVoltage) of the battery falls below a



Petrescu, et al.         Expires January 9, 2017               [Page 19]


Internet-Draft              battery-mib-yang                   July 2016


    threshold defined by object batteryAlarmLowCharge or
    object batteryAlarmLowVoltage, respectively.

    Note that, typically, this notification is generated in
    a state where the battery is still sufficiently charged
    to keep the device(s) that it powers operational for
    some time.
    If the charging state of the battery has become critical,
    i.e., the device(s) powered by the battery must go to a
    'sleep' or 'off' state, then the batteryCriticalNotification
    should be used instead.

    If the low charge or voltage has been detected for a
    single cell or a set of cells of the battery and not
    for the entire battery, then object
    batteryCellIdentifier should be set to a value that
    identifies the cell or set of cells. Otherwise, the value
    of object batteryCellIdentifier should be set to the empty
    string when this notification is generated.

    The notification should not be sent again for the same
    battery or cell before either (a) the current voltage or
    the current charge, respectively, has become higher than
    the corresponding threshold through charging or (b) an
    indication of a maintenance action has been detected,
    such as a battery disconnection event or a reinitialization
    of the battery monitoring system.

    This notification should not be sent when the battery
    is in a charging mode, i.e., the value of object
    batteryChargingOperState is charging(2).";

  container batteryLowNotification-batteryCellIdentifier{
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }

    leaf batteryCellIdentifier {
      type leafref {
         path "/battery:batteryTable/battery:batteryEntry/battery:batteryCellIdentifier";
      }
      description
        "It identifies one or more cells of a battery.";



Petrescu, et al.         Expires January 9, 2017               [Page 20]


Internet-Draft              battery-mib-yang                   July 2016


    }
  }

  container batteryLowNotification-batteryActualCharge {
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }

    leaf batteryActualCharge {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryActualCharge";
      }
      description
        "It provides the actual charge of the battery in
        units of mAh.";
    }
  }

  container batteryLowNotification-batteryActualVoltage {
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }

    leaf batteryActualVoltage {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryActualVoltage";
      }
      description
        "It provides the actual voltage of the battery
        in units of mV.";
    }
  }
}

notification batteryCriticalNotification {
  description
    "This notification can be generated when the current
    charge of the battery falls so low that it cannot



Petrescu, et al.         Expires January 9, 2017               [Page 21]


Internet-Draft              battery-mib-yang                   July 2016


    provide a sufficient power supply function for
    regular operation of the powered device(s).
    The battery needs to be charged before it can be
    used for regular power supply again.  The battery
    may still provide sufficient power for a 'sleep' mode
    of a powered device(s) or for a transition into an
    'off' mode.

    If the critical state is caused by a single cell or
    a set of cells of the battery, then object
    batteryCellIdentifier should be set to a value that
    identifies the cell or set of cells.  Otherwise, the
    value of object batteryCellIdentifier should be set
    to the empty string when this notification is generated.

    The notification should not be sent again for the
    same battery before either the battery charge has
    increased through charging to a non-critical value
    or an indication of a maintenance action has been
    detected, such as a battery disconnection event
    or a reinitialization of the battery monitoring system.

    This notification should not be sent when the
    battery is in a charging mode, i.e., the value of
    object batteryChargingOperState is charging(2)";

  container batteryCriticalNotification-batteryCellIdentifier{
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }

    leaf batteryCellIdentifier {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryCellIdentifier";
      }
      description
        "It identifies one or more cells of a battery.";
    }
  }

  container batteryCriticalNotification-batteryActualCharge {
    leaf entPhysicalIndex {
      type leafref {



Petrescu, et al.         Expires January 9, 2017               [Page 22]


Internet-Draft              battery-mib-yang                   July 2016


        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }
    leaf batteryActualCharge {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryActualCharge";
      }
      description
        "It provides the actual charge of the battery in
        units of mAh.";
    }
  }

  container batteryCriticalNotification-batteryActualVoltage {
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }
    leaf batteryActualVoltage {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryActualVoltage";
      }
      description
        "It provides the actual voltage of the battery
        in units of mV.";
    }
  }
}

notification batteryTemperatureNotification {
  description
    "This notification can be generated when the measured
    temperature (batteryTemperature) rises above the threshold
    defined by object batteryAlarmHighTemperature or
    falls below the threshold defined by object
    batteryAlarmLowTemperature.

    If the low or high temperature has been detected for
    a single cell or a set of cells of the battery and
    not for the entire battery, then object
    batteryCellIdentifier should be set to a value that



Petrescu, et al.         Expires January 9, 2017               [Page 23]


Internet-Draft              battery-mib-yang                   July 2016


    identifies the cell or set of cells. Otherwise, the
    value of object batteryCellIdentifier should be set
    to the empty string when this notification is generated.

    It may occur that the temperature alternates between
    values slightly below and slightly above a threshold.
    For limiting the notification rate in such a case,
    this notification should not be sent again for the
    same battery or cell, respectively, within a time
    interval of 10 minutes.

    An exception to the rate limitations occurs immediately
    after the reinitialization of the battery monitoring
    system. At this point in time, if the battery temperature
    is above the threshold defined by object
    batteryAlarmHighTemperature or below the threshold defined
    by object batteryAlarmLowTemperature, respectively, then
    this notification should be sent, independent of the time
    at which previous notifications for the same battery or
    cell, respectively, had been sent.";

  container batteryTemperatureNotification-batteryCellIdentifier {
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }
    leaf batteryCellIdentifier {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryCellIdentifier";
      }
      description
        "It identifies one or more cells of a battery.";
    }
  }

  container batteryTemperatureNotification-batteryTemperature {
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }



Petrescu, et al.         Expires January 9, 2017               [Page 24]


Internet-Draft              battery-mib-yang                   July 2016


    leaf batteryTemperature {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryTemperature";
      }
      description
        "The ambient temperature at or within close
        proximity of the battery.";
    }
  }
}

notification batteryAgingNotification {
  description
    "This notification can be generated when the actual
    capacity (batteryActualCapacity) falls below a
    threshold defined by object batteryAlarmLowCapacity
    or when the charging cycle count of the battery
    (batteryChargingCycleCount) exceeds the threshold
    defined by object batteryAlarmHighCycleCount.

    If the aging has been detected for a single cell or
    a set of cells of the battery and not for the entire
    battery, then object batteryCellIdentifier should be
    set to a value that identifies the cell or set of cells.
    Otherwise, the value of object batteryCellIdentifier
    should be set to the empty string when this notification
    is generated.

    This notification should not be sent again for the same
    battery or cell, respectively, before an indication of
    a maintenance action has been detected, such as a battery
    disconnection event or a reinitialization of the battery
    monitoring system.";

  container batteryAgingNotification-batteryCellIdentifier {
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }

    leaf batteryCellIdentifier {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryCellIdentifier";
      }



Petrescu, et al.         Expires January 9, 2017               [Page 25]


Internet-Draft              battery-mib-yang                   July 2016


      description
        "It identifies one or more cells of a battery.";
    }
  }

  container batteryAgingNotification-batteryActualCapacity {
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }

    leaf batteryActualCapacity {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryActualCapacity";
      }
      description
        "It provides the actual capacity of the battery
        in units of mAh";
    }
  }

  container batteryAgingNotification-batteryChargingCycleCount {
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }

    leaf batteryChargingCycleCount {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryChargingCycleCount";
      }
      description
        "It indicates the number of completed charging
        cycles that the battery underwent.";
    }
  }
}

notification batteryConnectedNotification {
  description



Petrescu, et al.         Expires January 9, 2017               [Page 26]


Internet-Draft              battery-mib-yang                   July 2016


    "This notification can be generated when it has been
    detected that a battery has been connected.  The battery
    can be identified by the value of object batteryIdentifier
    as well as by the value of index entPhysicalIndex that is
    contained in the OID of object batteryIdentifier.";

  container batteryConnectedNotification-batteryIdentifier {
    leaf entPhysicalIndex {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:entPhysicalIndex";
      }
      description
        "It allows to identify the slot of the device
        in which the battery is currently contained.";
    }

    leaf batteryIdentifier {
      type leafref {
        path "/battery:batteryTable/battery:batteryEntry/battery:batteryIdentifier";
      }
      description
        "It identifies one or more cells of a battery.";
    }
  }
}

notification batteryDisconnectedNotification {
  description
    "This notification can be generated when it has been
    detected that one or more batteries have been disconnected.";
}
}
<CODE ENDS>

6.  Security Considerations

   TBD.

7.  IANA Considerations

   IANA?

8.  Contributors

   if needed.






Petrescu, et al.         Expires January 9, 2017               [Page 27]


Internet-Draft              battery-mib-yang                   July 2016


9.  Acknowledgements

   This work is supported by the European Celtic-Plus project CONVINcE
   and was partially funded by Finland, France, Sweden and Turkey.

10.  Normative References

   [I-D.draft-ietf-netconf-restconf]
              Bierman, L., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", I-D draft-ietf-netconf-restconf-13, April 2016.

   [I-D.draft-ietf-netmod-yang-json]
              Lhotka, L., "JSON Encoding of Data Modeled with YANG",
              I-D draft-ietf-netmod-yang-json-10, March 2016.

   [I-D.draft-vanderstock-core-comi]
              van der Stok, P. and A. Bierman, "RESTCONF Protocol", I-D
              draft-vanderstock-core-comi-09, March 2016.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <http://www.rfc-editor.org/info/rfc6020>.

   [RFC6021]  Schoenwaelder, J., Ed., "Common YANG Data Types",
              RFC 6021, DOI 10.17487/RFC6021, October 2010,
              <http://www.rfc-editor.org/info/rfc6021>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <http://www.rfc-editor.org/info/rfc6241>.

   [RFC6643]  Schoenwaelder, J., "Translation of Structure of Management
              Information Version 2 (SMIv2) MIB Modules to YANG
              Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012,
              <http://www.rfc-editor.org/info/rfc6643>.

   [RFC7577]  Quittek, J., Winter, R., and T. Dietz, "Definition of
              Managed Objects for Battery Monitoring", RFC 7577,
              DOI 10.17487/RFC7577, July 2015,
              <http://www.rfc-editor.org/info/rfc7577>.




Petrescu, et al.         Expires January 9, 2017               [Page 28]


Internet-Draft              battery-mib-yang                   July 2016


Authors' Addresses

   Alexandre Petrescu
   CEA, LIST
   CEA Saclay
   Gif-sur-Yvette , Ile-de-France   91190
   France

   Phone: +33169089223
   Email: Alexandre.Petrescu@cea.fr


   Siwar Ben Hadj Said
   CEA, LIST
   CEA Saclay
   Gif-sur-Yvette , Ile-de-France   91190
   France

   Phone: +33169082939
   Email: Siwar.BenHadjSaid@cea.fr


   Erkki Harjula
   University of Oulu
   Centre for Wireless Communications (CWC), P.O. Box 4500
   FI-90014
   Finland

   Phone: +358 50 3030478
   Email: Erkki.Harjula@ee.oulu.fi


   Anders Plymoth Nilsson
   Telhoc
   Sweden

   Email: anders@telhoc.se


   Bjoern Landfeldt
   Lund University
   P.O. Box 118
   Lund   221 00
   Sweden

   Phone: +46 46 2224407
   Email: bjorn.landfeldt@eit.lth.se




Petrescu, et al.         Expires January 9, 2017               [Page 29]