abelgomez/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>’).

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 binded to a particular variable.

# <var.name>:COMMENT:
# <comment>
# ...
# <comment>
# <var.name>:EOC

(The trailing colon after :COMMENT 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 binded to a particular command.

# <command.name>:COMMENT:
# <comment>
# ...
# <comment>
# <command.name>: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:
# <comment>
# ...
# <comment>
# DEVICE:EOC

(The trailing colon after :COMMENT 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 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)