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 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: Archive: 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: ':'. 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."; } } 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, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6021, DOI 10.17487/RFC6021, October 2010, . [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, . [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, . [RFC7577] Quittek, J., Winter, R., and T. Dietz, "Definition of Managed Objects for Battery Monitoring", RFC 7577, DOI 10.17487/RFC7577, July 2015, . 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]