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]