SISheogorath/nut-ddl

Network UPS Tools Devices Dumps Library

NUT Devices Dumps Library

This library provides upsc styled data dumps for various hardware supported by NUT, with two principal aims:

DDL for users

NUT DDL complements NUT hardware compatibility list and provides more detailed information to users on how devices are supported.

DDL for developers

NUT DDL provides base simulation data to the dummy-ups driver.

Table of Contents

• File naming convention
  • A message to you, Rudy
• DEV/SEQ files
  • Basic syntax
  • Dynamic simulation
  • Comments
    • RW variables/instant commands
    • Special comments
    • Report a bad value

File naming convention

The files provided here respect the following format:

<manufacturer>__<model>__<driver-name>__<nut-version>__<report-number>.<extension>

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.:

  • <manufacturer-1>/<dump-1>..<dump-n>

  • <manufacturer-n>/<dump-1>..<dump-n>

• 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 (__)

• <report-number> is the progressive number of reports available for a device limited to a version of NUT (also if the driver, <driver-name>, 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).

DEV/SEQ files

The .dev files provide a simple mean to record a snapshot of your device state and simulate it through the dummy-ups NUT driver, while the .seq files give you the possibility to dynamically simulate 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 ‘special’ comments, as well as a list of available instant commands/RW variables to complete your report and to flag bad values.

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 upsc dump (<var.name>: <value>). 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 tools/nut-ddl-dump.sh script from the main NUT codebase, and reported on the NUT mailing list or via NUT issues on GitHub or as a pull request against the NUT Devices Dumps Library following the naming and other rules described in this document.

Comments are supported too. Empty lines are ignored.

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 Developer Guide. There is a whole chapter dedicated to data capture and simulation.

Comments

Comments are allowed as lines preceeded by a hash (#), and as lines with spaces followed by a hash (‘ # <comment>’).

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 nut-ddl.py and certain types of comments might be parsed by other tools as well.

RW variables/instant commands

Though not used by device simulation tools, you can add to your file some commented lines to declare instant commands and RW variables: these lines will be useful when generating the online DDL.

The RW variables are declared as:

#RW:<var.name>:<type>:<options>

Where:

<var.name>	Name of the RW variable.
<type>	Type of the RW variable <var.name>, one of STRING, RANGE, ENUM.
<options>	Options of <type> for <var.name>, i.e.: if <type> is STRING, maximum length of the settable string #RW:<var.name>:STRING:<length> Note that, since the length of RW STRING variables wasn’t published by upsrw before 2.7.1, you can omit it and the preceeding colon, i.e: #RW:<var.name>:STRING if <type> is RANGE, minimum and maximum settable value for the range, each one enclosed in quotes and separated by a space ("<min>" "<max>"): #RW:<var.name>:RANGE:"<min>" "<max>" if <type> is ENUM, settable enumerated value, enclosed in quotes ("<enumerated value>"): #RW:<var.name>:ENUM:"<enumerated value>"

Commands are declared as:

#CMD:<command.name>

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: <comment>, you can add a short sentence (supporting AsciiDoc inline markup) after the declaration of variables, RW types/values and commands, i.e.:

<var.name>: <value>	#COMMENT: <comment>
#RW:<var.name>:STRING:<length>	#COMMENT: <comment>
#RW:<var.name>:RANGE:"<min>" "<max>" #COMMENT <comment>
#RW:<var.name>:ENUM:"<enumerated value>"#COMMENT: <comment>
#CMD:<command.name> #COMMENT: <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.

# <var.name>:COMMENT:
# <comment>
# ...
# <comment>
# <var.name>: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.

# <command.name>:COMMENT:
# <comment>
# ...
# <comment>
# <command.name>: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: <title> which supports multiple pre-formatted block comments specifically for data dumps and tool output "screenshots" (with titles for particular subjects).

# DEVICE:COMMENT:
# <comment>
# ...
# <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: <title>
# <pre-formatted text>
# ...
# <pre-formatted text>
# 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:<link>
# DEVICE:URL:REPORT:<link>
# DEVICE:URL:<link>

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:<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 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

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 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.:

<var.name>: <value>	#BAD
#RW:<var.name>:STRING:<length>	#BAD: <reason>
#RW:<var.name>:RANGE:"<min>" "<max>" #BAD: <reason>
#RW:<var.name>:ENUM:"<enumerated value>"#BAD: <reason>
#CMD:<command.name> #BAD

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