Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/networkupstools/nut-ddl

Network UPS Tools Devices Dumps Library
https://github.com/networkupstools/nut-ddl

Last synced: about 2 months ago
JSON representation

Network UPS Tools Devices Dumps Library

Host: GitHub
URL: https://github.com/networkupstools/nut-ddl
Owner: networkupstools
Created: 2014-02-18T20:36:25.000Z (almost 11 years ago)
Default Branch: master
Last Pushed: 2024-04-02T02:11:14.000Z (9 months ago)
Last Synced: 2024-05-01T11:41:30.270Z (8 months ago)
Language: Makefile
Homepage: http://networkupstools.org/ddl/index.html#_supported_devices
Size: 831 KB
Stars: 4
Watchers: 6
Forks: 16
Open Issues: 5
Metadata Files:
- Readme: README.adoc

Awesome Lists containing this project

README

////
NOTE:
- 'env-github' attribute is set on GitHub
- 'preamble-only' attribute is set in DDL generation to include only the
preamble and unset to exclude it
- 'nut-website-root' attribute point to the root of the website, either
as a relative path (for DDL generation) or as the URL of the website
(for GitHub)
////

ifdef::env-github[]
NUT Devices Dumps Library
=========================
:nut-website-root: https://www.networkupstools.org/
:toc:
:toclevels: 4
:toc-placement: preamble
endif::env-github[]

ifndef::nut-website-root[]
:nut-website-root:
endif::nut-website-root[]

ifdef::env-github,preamble-only[]
This library provides link:{nut-website-root}docs/man/upsc.html['upsc'] styled
data dumps for
ifndef::env-github[<<_supported_devices,various hardware supported by NUT>>,]
ifdef::env-github[various hardware supported by NUT,]
with two principal aims:

DDL for users::
NUT DDL complements NUT
link:{nut-website-root}stable-hcl.html[hardware compatibility list]
and provides more detailed information to users on how
ifndef::env-github[<<_supported_devices,devices are supported>>.]
ifdef::env-github[devices are supported.]

DDL for developers::
NUT DDL provides base simulation data to the
link:{nut-website-root}docs/man/dummy-ups.html[dummy-ups] driver.
endif::env-github,preamble-only[]

ifndef::preamble-only[]
File naming convention
----------------------

The files provided here respect the following format:

________.

For example:

Dell__UPS_Tower_1920W_HV__snmp-ups__2.6.0__01.dev
Dell__UPS_Tower_1920W_HV__snmp-ups__2.6.0__01.seq
Eaton__9395_550KVA__bcmxcp__2.4.3__01.nds
Eaton__ePDU_Managed_Aphel__snmp-ups__2.6.1__01.dev
HP__RT3000_1fe5__usbhid-ups__2.6.3__01.dev

A message to you, Rudy
~~~~~~~~~~~~~~~~~~~~~~

Maintainers of this library should keep in mind that:

* Devices are grouped by manufacturer, i.e.:
** +/+..++
** +/+..++

* Spaces in file names and directories must be replaced by a single
underscore (+_+)

* At sign (+@+), dollar sign (+$+), double quotes (+"+), colons (+:+)
and parentheses are not allowed in the names of files and directories

* Fields in file names are separated by two underscores (+__+)

* ++ is the progressive number of reports available for a
device limited to a version of NUT (also if the driver, ++,
is different from one report to another), i.e. for each device:

** every report being the first one for a particular version of NUT must
have a report number equal to +01+.

** every report still in the same version number must increase the report
number also if the driver is not the same as the other ones

* +.seq+ files generated from a specific +.dev+ file must have the same
name of the +.dev+ file, e.g.:
+
Dell__UPS_Tower_1920W_HV__snmp-ups__2.6.0__01.dev
Dell__UPS_Tower_1920W_HV__snmp-ups__2.6.0__01.seq

* Words in the filename and manufacturer directory should be plain ASCII
(vendors usually have transliteration to English per branding or human
language rules); other strings had been seen as problematic (especially
with builds on older platforms without good locale support).

[[devseq-files]]
DEV/SEQ files
-------------

The +.dev+ files provide a <> to record a snapshot
of your device state and simulate it through the
link:{nut-website-root}docs/man/dummy-ups.html[dummy-ups] NUT driver, while
the +.seq+ files give you the possibility to
<> power events and the like.

In addition to that, users are invited to use them to report their
experience with NUT, as detailed below, to help improve support for
their devices and help other users: to do so, you may want to add some
<>, as well as a list of
<>
to complete your report and to <>.

[[basic-syntax]]
Basic syntax
~~~~~~~~~~~~

The +.dev+ files contain a list of all valid data and associated values of
a specific device, and have the same format as an
link:{nut-website-root}docs/man/upsc.html['upsc'] dump (+: +).
For local experiments, you can easily create definition files on your NUT
system from an existing UPS or another power device, using "+upsc > file.dev+".

To report new data for the Devices Dumps Library (DDL) mentioned above, such
"data dump" reports can be best prepared by the
link:https://raw.githubusercontent.com/networkupstools/nut/master/tools/nut-ddl-dump.sh[`tools/nut-ddl-dump.sh`]
script from the main NUT codebase, and reported on the NUT mailing list or
via link:https://github.com/networkupstools/nut/issues[NUT issues on GitHub]
or as a pull request against the
link:https://github.com/networkupstools/nut-ddl[NUT Devices Dumps Library]
following the naming and other rules described in this document.

<> are supported too.
Empty lines are ignored.

[[dynamic-simulation]]
Dynamic simulation
~~~~~~~~~~~~~~~~~~

To change a +.dev+ (static) to a +.seq+ (dynamic simulation), you have to
change the suffix of the file, and to append the following kind of sequence,
at the end of a file:

----
TIMER 300
ups.status: OB DISCHRG
TIMER 300
ups.status: OB LB DISCHRG
TIMER 60
----

Here, we:

* wait 5 minutes with the initial content, then
* generate a power failure (switch On Battery)
* We wait 5 more minutes before reaching the battery low level.
* We wait again 1 minute, and then
* loop at the beginning of the file, resetting the power status to Online.

For more information, refer to NUT
link:{nut-website-root}docs/developer-guide.chunked/index.html[Developer Guide].
There is a whole chapter dedicated to data capture and simulation.

[[comments]]
Comments
~~~~~~~~

Comments are allowed as lines preceeded by a hash (++#++), and as lines with
spaces followed by a hash (`++$$ # $$++').

Formally, everything that is not an `upsc` key-value output, should be some
form of a comment (or a blank line). Some comments may contain special markup
as detailed below, allowing for further somewhat structured information to be
passed in the DDL files. They are parsed for web-site representation by
link:https://github.com/networkupstools/nut-website/blob/master/tools/nut-ddl.py.in[nut-ddl.py]
and certain types of comments might be parsed by other tools as well.

[[rw-variablesinstant-commands]]
RW variables/instant commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Though not used by device simulation tools, you can add to your file some
commented lines to declare
link:{nut-website-root}docs/man/upscmd.html[instant commands] and
link:{nut-website-root}docs/man/upsrw.html[RW variables]: these lines will
be useful when generating the online DDL.

The link:{nut-website-root}docs/man/upsrw.html[RW variables] are declared as:

----
#RW:::
----

Where:

[horizontal]
++::
Name of the RW variable.

++::
Type of the RW variable ++, one of *STRING*, *RANGE*, *ENUM*.

++::
Options of ++ for ++, i.e.:
+
* if ++ is *STRING*, maximum length of the settable string
+
--
----
#RW::STRING:
----

Note that, since the length of RW *STRING* variables wasn't published by
link:{nut-website-root}docs/man/upsrw.html['upsrw'] before 2.7.1, you can
omit it and the preceeding colon, i.e:

----
#RW::STRING
----
--
* if ++ is *RANGE*, minimum and maximum settable value for the range,
each one enclosed in quotes and separated by a space (+"" ""+):
+
----
#RW::RANGE:"" ""
----
* if ++ is *ENUM*, settable enumerated value, enclosed in quotes
(+""+):
+
----
#RW::ENUM:""
----

link:{nut-website-root}docs/man/upscmd.html[Commands] are declared as:

----
#CMD:
----

[[special-comments]]
Special comments
^^^^^^^^^^^^^^^^

+.dev+/+.seq+ files support some special comments to express your
comments/opinions/suggestions about each var/command or for the whole
device:

End Of Line comments::
With the special End Of Line comment `#COMMENT: `, you can add a
short sentence (supporting http://asciidoc.org/[AsciiDoc] inline markup)
after the declaration of variables, RW types/values and commands, i.e.:
+
--
----
: #COMMENT:
#RW::STRING: #COMMENT:
#RW::RANGE:"" "" #COMMENT
#RW::ENUM:""#COMMENT:
#CMD: #COMMENT:
----

(don't forget the leading hash in `RW` and `CMD` lines)

Note that the colon after `#COMMENT` is not mandatory.
--

Vars comments::
Comments that are bound to a particular variable.
+
--
----
# :COMMENT:
#
# ...
#
# :EOC
----

(The trailing colon after `:COMMENT` or `:EOC` is not mandatory.)

e.g.:

----
# battery.charge:COMMENT:
# The values reported by NUT are all bogus, I keep getting something like this:
#
# ----
# battery.charge: -1
# battery.charge: -10
# ----
#
# and so on..
#
# Should I start finding rainbows or a whole universe where unicorns rule the world to get it working?
# battery.charge:EOC
----
--

Commands comments::
Comments bound to a particular command.
+
--
----
# :COMMENT:
#
# ...
#
# :EOC
----

(The trailing colon after `:COMMENT` or `:EOC` is not mandatory.)

e.g.:

----
# shutdown.return:COMMENT
# Why doesn't this command work?
#
# For my continued misery of course!
# shutdown.return:EOC
----
--

Device comment::
A special comment to express general thoughts about the whole device and
to describe the way NUT supports it. At most one is allowed per file.
+
Keep in mind that each comment line is stripped of two leftmost characters
(assuming the hash and space characters), and the rest is treated as usual
asciidoc markup, e.g. keep blank lines to separate multiple paragraphs.
+
See also `DEVICE:COMMENT-BLOCK: ` which supports multiple pre-formatted
block comments specifically for data dumps and tool output "screenshots" (with
titles for particular subjects).
+
--
----
# DEVICE:COMMENT:
#
# ...
#
# DEVICE:EOC
----

(The trailing colon after `:COMMENT` or `:EOC` is not mandatory.)

e.g.:

----
# DEVICE:COMMENT
# Bwah..
# This device is supported so badly by NUT that I had to burn my office down to the ground..
# _At least_ *now* I don't have to stand the taste of that coffee anymore..
# DEVICE:EOC
----
--

Device comment block::
A way to pass otherwise "un-classified" blocks of information which benefits
from pre-formatting, such as `ups.conf` device configuration section examples,
or "console screenshots". It may include a title (recommended for readability).
+
NOTE: For certain frequently seen content types there are special tags to take
care of default title and possible other mark-up in the rendered documents.
So it is not necessarily fully unstructured information after all.
+
--
----
# DEVICE:COMMENT-BLOCK:
#
# ...
#
# DEVICE:EOC
----

e.g.:

----
### For driver config snippets, especially if with useful overrides etc.:

# DEVICE:COMMENT-BLOCK:UPSCONF: # see comment below about optional title
# > A single-token title is UPS name if no section in conf section,
# > otherwise non-trivial title is pasted as a starting comment
# [ups]
# driver = blazer_ser
# port = /dev/ttyUSB0
# # Certain overrides were needed:
# ...
# DEVICE:EOC

### or:

# DEVICE:COMMENT-BLOCK: Driver configuration
# :; cat /etc/nut/ups.conf
#
# [ups]
# driver = blazer_ser
# port = /dev/ttyUSB0
# DEVICE:EOC

### For `lsusb` dumps:

# DEVICE:COMMENT-BLOCK:LSUSB: `lsusb -vvv` # see comment below about optional title
# > Accepts optional title with exact command,
# > possibly not even `lsusb` per se on some OSes
# ...
# DEVICE:EOC

### or:

# DEVICE:COMMENT-BLOCK: `lsusb` listing
# :; lsusb -vvv
# ...
# DEVICE:EOC

### For service startup/shutdown log messages:

# DEVICE:COMMENT-BLOCK:LOGS: Console messages of NUT driver startup
# > Accepts optional title with description of the log - used "as is"
# ...
# DEVICE:EOC

### or:

# DEVICE:COMMENT-BLOCK: Syslog of NUT startup
# ...
# DEVICE:EOC

### For unstructured `upsrw` dumps:

# DEVICE:COMMENT-BLOCK:FIXME:UPSRW: # see comment below about optional title
# > A single-token title is UPS name for example command,
# > multi-token is pasted as a starting comment
# [battery.charge.low]
# Remaining battery level when UPS switches to LB (percent)
# ...
# DEVICE:EOC

### or:

# DEVICE:COMMENT-BLOCK: Variables per `upsrw ups@localhost` listing
# TODO: Convert to RW:... and RO:... markup
# :; upsrw ups
# [battery.charge.low]
# Remaining battery level when UPS switches to LB (percent)
# Type: STRING
# Maximum length: 10
# Value: 10
# ...
# DEVICE:EOC

### For unstructured `upscmd` dumps:

# DEVICE:COMMENT-BLOCK:FIXME:UPSCMD: # see comment below about optional title
# > A single-token title is UPS name for example command,
# > multi-token is pasted as a starting comment
# beeper.disable - Disable the UPS beeper
# ...
# DEVICE:EOC

### or:

# DEVICE:COMMENT-BLOCK: Commands per `upscmd -l ups@localhost` listing
# TODO: Convert to CMD:... markup
# :; upscmd -l ups
# Instant commands supported on UPS [ups]:
#
# beeper.disable - Disable the UPS beeper
# beeper.enable - Enable the UPS beeper
#...
# DEVICE:EOC
----
--

Device information URL(s)::
Further information about this device or report can be found at specified URL,
e.g. vendor product page, NUT issue tracker or mailing list archive page where
the report originated, etc. Many URLs may be listed, but only one per tag.
+
Use of specific `DEVICE:URL:VENDOR:` (product/vendor/manufacturer pages) and
`DEVICE:URL:REPORT:` (GitHub issue or pull request, mailing list archive, blog
etc. where the reported information originated and more clues may appear later)
is encouraged over the less specific `DEVICE:URL:` used for additional info.
+
--
----
# DEVICE:URL:VENDOR:
# DEVICE:URL:REPORT:
# DEVICE:URL:
----

e.g.:

----
# DEVICE:URL:REPORT: https://github.com/networkupstools/nut/issues/867
# DEVICE:URL:VENDOR: https://www.njoy.ro/UPS/keen-600
----
--

Device support level::
Express on a scale of 1 to 10 how much you think the device is well supported
by NUT.
+
--
----
# DEVICE:SUPPORT-LEVEL:
----

e.g.:

----
# DEVICE:SUPPORT-LEVEL:7
----
--

Note that the leading space is mandatory: each line must begin with a hash
followed by a single space (`++$$# $$++'), all comments not following this
syntax will either produce an error or be ignored.

Multi-line comments (vars, commands, device) support
http://asciidoc.org/[AsciiDoc] markup (inline, paragraphs, blocks, lists,
tables, ...).

Note that the following AsciiDoc markup elements are *not* allowed:

- sections
- labeled lists using two semi-colons (`;;`) as delimiter (labeled lists
delimited by two-four colons are allowed)
- open blocks directly at level 0 of the comment (you can use them as
nested elements in other kinds of block)

Also, keep in mind that the leading space will always be removed and
therefore you shouldn't consider it in your AsciiDoc markup, e.g.,
if you want to add a listing block, the comment should look like this:

----
# ----
# The verbatim text start after the space
# If a tab is needed, preceed it with a space:
# <- a tab; remember to preceed it with a space otherwise it won't behave as expected
# \-/<- I don't know why, but I needed a space here at the beginning of the line, so i doubled it
# ----
----

As an exception it's allowed to use empty commented lines (`++$$#$$++'),
such as in:

----
# ====
# The previous line it's not empty (it starts an example block), so it needs a space.
# Here's text and therefore a space preceed it..
#
#
# ..while the two previous lines are empty, therefore a space is not needed after the hash
# ====
----

They will be retained and can be used to add vertical space or to separate
blocks when needed; note that using a hash followed by a single space
(`++$$# $$++') will produce the same effect.

Also note that empty lines, comments without the required leading space
after the hash and lines with spaces preceeding a hash will 'break'
multi-line comments.

[[report-a-bad-value]]
Report a bad value
^^^^^^^^^^^^^^^^^^

If certain values are not correctly reported, you can flag them with the
special End Of Line comment `#BAD`, you can even add a short sentence
(still supporting http://asciidoc.org/[AsciiDoc] inline markup) after it,
explaining the reason (e.g. `#BAD: unbelievably high value`, note that
the colons are not mandatory).

This kind of flags/comments is allowed (i.e. you can append it at the
end of the line) in the declaration of variables, RW types/values and
commands, i.e.:

----
: #BAD
#RW::STRING: #BAD:
#RW::RANGE:"" "" #BAD:
#RW::ENUM:""#BAD:
#CMD: #BAD
----

(don't forget the leading hash in `RW` and `CMD` lines)

////
NDS files
---------

**N**UT **D**evice **S**imulation files (+.nds+) are meant to be the next
version of <>.

These files add support for instant commands, personalized RW variables
and a way to express your comments/opinions/suggestions about each
var/command or for the whole device.

[[basic-syntax]]
Basic syntax
~~~~~~~~~~~~

Just like in <>, NUT variables are
declared as:

----
:
----

RW variables are declared as:

----
RW:::
----

Where:

[horizontal]
++::
Name of the RW variable.

++::
Type of the RW variable ++, one of *STRING*, *RANGE*, *ENUM*.

++::
Options of ++ for ++, i.e.:
+
* if ++ is *STRING*, maximum length of the settable string
+
----
RW::STRING:
----
* if ++ is *RANGE*, minimum and maximum settable value for the range,
each one enclosed in quotes and separated by a space (+"" ""+):
+
----
RW::RANGE:"" ""
----
* if ++ is *ENUM*, settable enumerated value, enclosed in quotes
(+""+):
+
----
RW::ENUM:""
----

Commands are declared as:

----
CMD:
----

Dynamic simulation
~~~~~~~~~~~~~~~~~~

As in <>, +.nds+ files can simulate/record power
events and the like through the `++TIMER ++' instruction, e.g.:

----
TIMER 300
ups.status: OB DISCHRG
TIMER 300
ups.status: OB LB DISCHRG
TIMER 60
----

For more information, refer to NUT
link:{nut-website-root}docs/developer-guide.chunked/index.html[Developer Guide].
There is a whole chapter dedicated to data capture and simulation.

[[comments]]
Comments
~~~~~~~~

Like in <>, comments are allowed as lines
preceeded by a hash (++#++), and as lines with spaces followed by a hash
(`++$$ # $$++').
Empty lines are ignored.

In addition, +.nds+ files support some special comments:

End Of Line comments::
With the special End Of Line comment `#COMMENT: `, you can add a
short sentence (supporting http://asciidoc.org/[AsciiDoc] inline markup)
after the declaration of variables, RW types/values and commands, i.e.:
+
--
----
: #COMMENT:
RW::STRING: #COMMENT:
RW::RANGE:"" "" #COMMENT
RW::ENUM:""#COMMENT:
CMD: #COMMENT:
----

Note that the colon after `#COMMENT` is not mandatory.
--

Vars comments::
Comments that are bound to a particular variable.
+
--
----
# :COMMENT:
#
# ...
#
# :EOC
----

(The trailing colon after `:COMMENT` is not mandatory.)

e.g.:

Commands comments::
Comments bound to a particular command.
+
--
----
# :COMMENT:
#
# ...
#
# :EOC
----

(The trailing colon after `:COMMENT` is not mandatory.)

e.g.:

----
# shutdown.return:COMMENT
# Why doesn't this command work?
#
# For my continued misery of course!
# shutdown.return:EOC
----
--

Device comment::
A special comment to express general thoughts about the whole device and
to describe the way NUT supports it.
+
--
----
# DEVICE:COMMENT:
#
# ...
#
# DEVICE:EOC
----

(The trailing colon after `:COMMENT` is not mandatory.)

e.g.:

Device support level::
Express on a scale of 1 to 10 how much you think the device is well supported
by NUT.
+
--
----
# DEVICE:SUPPORT-LEVEL:
----

e.g.:

----
# DEVICE:SUPPORT-LEVEL:7
----
--

NDS version::
This is reserved to store the version of NDS this particular file belongs to.
+
--
----
# NDS:VERSION:
----

e.g.:

----
# NDS:VERSION:2
----
--

Multi-line comments (vars, commands, device) support
http://asciidoc.org/[AsciiDoc] markup (inline, paragraphs, blocks, lists,
tables, ...).

Note that the following AsciiDoc markup elements are *not* allowed:

As an exception it's allowed to use empty commented lines (`++$$#$$++'),
such as in:

They will be retained and can be used to add vertical space or to separate
blocks when needed; note that using a hash followed by a single space
(`++$$# $$++') will produce the same effect.

Also note that empty lines, comments without the required leading space
after the hash and lines with spaces preceeding a hash will 'break'
multi-line comments.

[[report-a-bad-value]]
Report a bad value
^^^^^^^^^^^^^^^^^^

This kind of flags/comments is allowed (i.e. you can append it at the
end of the line) in the declaration of variables, RW types/values and
commands, i.e.:

----
: #BAD
RW::STRING: #BAD:
RW::RANGE:"" "" #BAD:
RW::ENUM:""#BAD:
CMD: #BAD
----
////
endif::preamble-only[]