{"id":20663616,"url":"https://github.com/networkupstools/nut-ddl","last_synced_at":"2026-03-07T21:30:47.982Z","repository":{"id":14255310,"uuid":"16962852","full_name":"networkupstools/nut-ddl","owner":"networkupstools","description":"Network UPS Tools Devices Dumps Library","archived":false,"fork":false,"pushed_at":"2025-11-24T16:24:39.000Z","size":903,"stargazers_count":7,"open_issues_count":11,"forks_count":20,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-11-28T04:51:38.195Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://networkupstools.org/ddl/index.html#_supported_devices","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/networkupstools.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-02-18T20:36:25.000Z","updated_at":"2025-11-24T16:24:44.000Z","dependencies_parsed_at":"2024-02-02T09:04:32.732Z","dependency_job_id":"e2cc24ea-a874-4cb8-96d4-333bf34f1e95","html_url":"https://github.com/networkupstools/nut-ddl","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/networkupstools/nut-ddl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-ddl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-ddl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-ddl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-ddl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/networkupstools","download_url":"https://codeload.github.com/networkupstools/nut-ddl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-ddl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30231592,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T19:01:10.287Z","status":"ssl_error","status_checked_at":"2026-03-07T18:59:58.103Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T19:18:53.844Z","updated_at":"2026-03-07T21:30:47.953Z","avatar_url":"https://github.com/networkupstools.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"////\nNOTE:\n- 'env-github' attribute is set on GitHub\n- 'preamble-only' attribute is set in DDL generation to include only the\n  preamble and unset to exclude it\n- 'nut-website-root' attribute point to the root of the website, either\n  as a relative path (for DDL generation) or as the URL of the website\n  (for GitHub)\n////\n\nifdef::env-github[]\nNUT Devices Dumps Library\n=========================\n:nut-website-root: https://www.networkupstools.org/\n:toc:\n:toclevels: 4\n:toc-placement: preamble\nendif::env-github[]\n\nifndef::nut-website-root[]\n:nut-website-root:\nendif::nut-website-root[]\n\nifdef::env-github,preamble-only[]\nThis library provides link:{nut-website-root}docs/man/upsc.html['upsc'] styled\ndata dumps for\nifndef::env-github[\u003c\u003c_supported_devices,various hardware supported by NUT\u003e\u003e,]\nifdef::env-github[various hardware supported by NUT,]\nwith two principal aims:\n\nDDL for users::\nNUT DDL complements NUT\nlink:{nut-website-root}stable-hcl.html[hardware compatibility list]\nand provides more detailed information to users on how\nifndef::env-github[\u003c\u003c_supported_devices,devices are supported\u003e\u003e.]\nifdef::env-github[devices are supported.]\n\nDDL for developers::\nNUT DDL provides base simulation data to the\nlink:{nut-website-root}docs/man/dummy-ups.html[dummy-ups] driver.\nendif::env-github,preamble-only[]\n\n\nifndef::preamble-only[]\nFile naming convention\n----------------------\n\nThe files provided here respect the following format:\n\n\t\u003cmanufacturer\u003e__\u003cmodel\u003e__\u003cdriver-name\u003e__\u003cnut-version\u003e__\u003creport-number\u003e.\u003cextension\u003e\n\nFor example:\n\n\tDell__UPS_Tower_1920W_HV__snmp-ups__2.6.0__01.dev\n\tDell__UPS_Tower_1920W_HV__snmp-ups__2.6.0__01.seq\n\tEaton__9395_550KVA__bcmxcp__2.4.3__01.nds\n\tEaton__ePDU_Managed_Aphel__snmp-ups__2.6.1__01.dev\n\tHP__RT3000_1fe5__usbhid-ups__2.6.3__01.dev\n\n\nA message to you, Rudy\n~~~~~~~~~~~~~~~~~~~~~~\n\nMaintainers of this library should keep in mind that:\n\n* Devices are grouped by manufacturer, i.e.:\n** +\u003cmanufacturer-1\u003e/\u003cdump-1\u003e+..+\u003cdump-n\u003e+\n** +\u003cmanufacturer-n\u003e/\u003cdump-1\u003e+..+\u003cdump-n\u003e+\n\n* Spaces in file names and directories must be replaced by a single\n  underscore (+_+)\n\n* At sign (+@+), dollar sign (+$+), double quotes (+\"+), colons (+:+)\n  and parentheses are not allowed in the names of files and directories\n\n* Fields in file names are separated by two underscores (+__+)\n\n* +\u003creport-number\u003e+ is the progressive number of reports available for a\n  device limited to a version of NUT (also if the driver, +\u003cdriver-name\u003e+,\n  is different from one report to another), i.e. for each device:\n\n** every report being the first one for a particular version of NUT must\n   have a report number equal to +01+.\n\n** every report still in the same version number must increase the report\n   number also if the driver is not the same as the other ones\n\n* +.seq+ files generated from a specific +.dev+ file must have the same\n  name of the +.dev+ file, e.g.:\n+\n\tDell__UPS_Tower_1920W_HV__snmp-ups__2.6.0__01.dev\n\tDell__UPS_Tower_1920W_HV__snmp-ups__2.6.0__01.seq\n\n* Words in the filename and manufacturer directory should be plain ASCII\n  (vendors usually have transliteration to English per branding or human\n  language rules); other strings had been seen as problematic (especially\n  with builds on older platforms without good locale support).\n\n\n[[devseq-files]]\nDEV/SEQ files\n-------------\n\nThe +.dev+ files provide a \u003c\u003cbasic-syntax,simple mean\u003e\u003e to record a snapshot\nof your device state and simulate it through the\nlink:{nut-website-root}docs/man/dummy-ups.html[dummy-ups] NUT driver, while\nthe +.seq+ files give you the possibility to\n\u003c\u003cdynamic-simulation,dynamically simulate\u003e\u003e power events and the like.\n\nIn addition to that, users are invited to use them to report their\nexperience with NUT, as detailed below, to help improve support for\ntheir devices and help other users: to do so, you may want to add some\n\u003c\u003cspecial-comments,`special' comments\u003e\u003e, as well as a list of\n\u003c\u003crw-variablesinstant-commands,available instant commands/RW variables\u003e\u003e\nto complete your report and to \u003c\u003creport-a-bad-value,flag bad values\u003e\u003e.\n\n\n[[basic-syntax]]\nBasic syntax\n~~~~~~~~~~~~\n\nThe +.dev+ files contain a list of all valid data and associated values of\na specific device, and have the same format as an\nlink:{nut-website-root}docs/man/upsc.html['upsc'] dump (+\u003cvar.name\u003e: \u003cvalue\u003e+).\nFor local experiments, you can easily create definition files on your NUT\nsystem from an existing UPS or another power device, using \"+upsc \u003e file.dev+\".\n\nTo report new data for the Devices Dumps Library (DDL) mentioned above, such\n\"data dump\" reports can be best prepared by the\nlink:https://raw.githubusercontent.com/networkupstools/nut/master/tools/nut-ddl-dump.sh[`tools/nut-ddl-dump.sh`]\nscript from the main NUT codebase, and reported on the NUT mailing list or\nvia link:https://github.com/networkupstools/nut/issues[NUT issues on GitHub]\nor as a pull request against the\nlink:https://github.com/networkupstools/nut-ddl[NUT Devices Dumps Library]\nfollowing the naming and other rules described in this document.\n\n\u003c\u003ccomments,Comments\u003e\u003e are supported too.\nEmpty lines are ignored.\n\n\n[[dynamic-simulation]]\nDynamic simulation\n~~~~~~~~~~~~~~~~~~\n\nTo change a +.dev+ (static) to a +.seq+ (dynamic simulation), you have to\nchange the suffix of the file, and to append the following kind of sequence,\nat the end of a file:\n\n----\nTIMER 300\nups.status: OB DISCHRG\nTIMER 300\nups.status: OB LB DISCHRG\nTIMER 60\n----\n\nHere, we:\n\n* wait 5 minutes with the initial content, then\n* generate a power failure (switch On Battery)\n* We wait 5 more minutes before reaching the battery low level.\n* We wait again 1 minute, and then\n* loop at the beginning of the file, resetting the power status to Online.\n\nFor more information, refer to NUT\nlink:{nut-website-root}docs/developer-guide.chunked/index.html[Developer Guide].\nThere is a whole chapter dedicated to data capture and simulation.\n\n\n[[comments]]\nComments\n~~~~~~~~\n\nComments are allowed as lines preceeded by a hash (++#++), and as lines with\nspaces followed by a hash (`++$$   # \u003ccomment\u003e$$++').\n\nFormally, everything that is not an `upsc` key-value output, should be some\nform of a comment (or a blank line). Some comments may contain special markup\nas detailed below, allowing for further somewhat structured information to be\npassed in the DDL files. They are parsed for web-site representation by\nlink:https://github.com/networkupstools/nut-website/blob/master/tools/nut-ddl.py.in[nut-ddl.py]\nand certain types of comments might be parsed by other tools as well.\n\n[[rw-variablesinstant-commands]]\nRW variables/instant commands\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThough not used by device simulation tools, you can add to your file some\ncommented lines to declare\nlink:{nut-website-root}docs/man/upscmd.html[instant commands] and\nlink:{nut-website-root}docs/man/upsrw.html[RW variables]: these lines will\nbe useful when generating the online DDL.\n\nThe link:{nut-website-root}docs/man/upsrw.html[RW variables] are declared as:\n\n----\n#RW:\u003cvar.name\u003e:\u003ctype\u003e:\u003coptions\u003e\n----\n\nWhere:\n\n[horizontal]\n+\u003cvar.name\u003e+::\nName of the RW variable.\n\n+\u003ctype\u003e+::\nType of the RW variable +\u003cvar.name\u003e+, one of *STRING*, *RANGE*, *ENUM*.\n\n+\u003coptions\u003e+::\nOptions of +\u003ctype\u003e+ for +\u003cvar.name\u003e+, i.e.:\n+\n* if +\u003ctype\u003e+ is *STRING*, maximum length of the settable string\n+\n--\n----\n#RW:\u003cvar.name\u003e:STRING:\u003clength\u003e\n----\n\nNote that, since the length of RW *STRING* variables wasn't published by\nlink:{nut-website-root}docs/man/upsrw.html['upsrw'] before 2.7.1, you can\nomit it and the preceeding colon, i.e:\n\n----\n#RW:\u003cvar.name\u003e:STRING\n----\n--\n* if +\u003ctype\u003e+ is *RANGE*, minimum and maximum settable value for the range,\n  each one enclosed in quotes and separated by a space (+\"\u003cmin\u003e\" \"\u003cmax\u003e\"+):\n+\n----\n#RW:\u003cvar.name\u003e:RANGE:\"\u003cmin\u003e\" \"\u003cmax\u003e\"\n----\n* if +\u003ctype\u003e+ is *ENUM*, settable enumerated value, enclosed in quotes\n  (+\"\u003cenumerated value\u003e\"+):\n+\n----\n#RW:\u003cvar.name\u003e:ENUM:\"\u003cenumerated value\u003e\"\n----\n\nlink:{nut-website-root}docs/man/upscmd.html[Commands] are declared as:\n\n----\n#CMD:\u003ccommand.name\u003e\n----\n\n\n[[special-comments]]\nSpecial comments\n^^^^^^^^^^^^^^^^\n\n+.dev+/+.seq+ files support some special comments to express your\ncomments/opinions/suggestions about each var/command or for the whole\ndevice:\n\nEnd Of Line comments::\nWith the special End Of Line comment `#COMMENT: \u003ccomment\u003e`, you can add a\nshort sentence (supporting http://asciidoc.org/[AsciiDoc] inline markup)\nafter the declaration of variables, RW types/values and commands, i.e.:\n+\n--\n----\n\u003cvar.name\u003e: \u003cvalue\u003e\t#COMMENT: \u003ccomment\u003e\n#RW:\u003cvar.name\u003e:STRING:\u003clength\u003e\t#COMMENT: \u003ccomment\u003e\n#RW:\u003cvar.name\u003e:RANGE:\"\u003cmin\u003e\" \"\u003cmax\u003e\" #COMMENT \u003ccomment\u003e\n#RW:\u003cvar.name\u003e:ENUM:\"\u003cenumerated value\u003e\"#COMMENT: \u003ccomment\u003e\n#CMD:\u003ccommand.name\u003e #COMMENT: \u003ccomment\u003e\n----\n\n(don't forget the leading hash in `RW` and `CMD` lines)\n\nNote that the colon after `#COMMENT` is not mandatory.\n--\n\nVars comments::\nComments that are bound to a particular variable.\n+\n--\n----\n# \u003cvar.name\u003e:COMMENT:\n# \u003ccomment\u003e\n# ...\n# \u003ccomment\u003e\n# \u003cvar.name\u003e:EOC\n----\n\n(The trailing colon after `:COMMENT` or `:EOC` is not mandatory.)\n\ne.g.:\n\n----\n# battery.charge:COMMENT:\n# The values reported by NUT are all bogus, I keep getting something like this:\n# \n# ----\n# battery.charge: -1\n# battery.charge: -10\n# ----\n#\n# and so on..\n# \n# Should I start finding rainbows or a whole universe where unicorns rule the world to get it working?\n# battery.charge:EOC\n----\n--\n\nCommands comments::\nComments bound to a particular command.\n+\n--\n----\n# \u003ccommand.name\u003e:COMMENT:\n# \u003ccomment\u003e\n# ...\n# \u003ccomment\u003e\n# \u003ccommand.name\u003e:EOC\n----\n\n(The trailing colon after `:COMMENT` or `:EOC` is not mandatory.)\n\ne.g.:\n\n----\n# shutdown.return:COMMENT\n# Why doesn't this command work?\n# \n# For my continued misery of course!\n# shutdown.return:EOC\n----\n--\n\nDevice comment::\nA special comment to express general thoughts about the whole device and\nto describe the way NUT supports it. At most one is allowed per file.\n+\nKeep in mind that each comment line is stripped of two leftmost characters\n(assuming the hash and space characters), and the rest is treated as usual\nasciidoc markup, e.g. keep blank lines to separate multiple paragraphs.\n+\nSee also `DEVICE:COMMENT-BLOCK: \u003ctitle\u003e` which supports multiple pre-formatted\nblock comments specifically for data dumps and tool output \"screenshots\" (with\ntitles for particular subjects).\n+\n--\n----\n# DEVICE:COMMENT:\n# \u003ccomment\u003e\n# ...\n# \u003ccomment\u003e\n# DEVICE:EOC\n----\n\n(The trailing colon after `:COMMENT` or `:EOC` is not mandatory.)\n\ne.g.:\n\n----\n# DEVICE:COMMENT\n# Bwah..\n# This device is supported so badly by NUT that I had to burn my office down to the ground..\n# _At least_ *now* I don't have to stand the taste of that coffee anymore..\n# DEVICE:EOC\n----\n--\n\nDevice comment block::\nA way to pass otherwise \"un-classified\" blocks of information which benefits\nfrom pre-formatting, such as `ups.conf` device configuration section examples,\nor \"console screenshots\". It may include a title (recommended for readability).\n+\nNOTE: For certain frequently seen content types there are special tags to take\ncare of default title and possible other mark-up in the rendered documents.\nSo it is not necessarily fully unstructured information after all.\n+\n--\n----\n# DEVICE:COMMENT-BLOCK: \u003ctitle\u003e\n# \u003cpre-formatted text\u003e\n# ...\n# \u003cpre-formatted text\u003e\n# DEVICE:EOC\n----\n\ne.g.:\n\n----\n### For driver config snippets, especially if with useful overrides etc.:\n\n# DEVICE:COMMENT-BLOCK:UPSCONF: # see comment below about optional title\n# \u003e A single-token title is UPS name if no section in conf section,\n# \u003e otherwise non-trivial title is pasted as a starting comment\n# [ups]\n#   driver = blazer_ser\n#   port = /dev/ttyUSB0\n#   # Certain overrides were needed:\n# ...\n# DEVICE:EOC\n\n### or:\n\n# DEVICE:COMMENT-BLOCK: Driver configuration\n# :; cat /etc/nut/ups.conf\n#\n# [ups]\n#   driver = blazer_ser\n#   port = /dev/ttyUSB0\n# DEVICE:EOC\n\n\n### For `lsusb` dumps:\n\n# DEVICE:COMMENT-BLOCK:LSUSB: `lsusb -vvv` # see comment below about optional title\n# \u003e Accepts optional title with exact command,\n# \u003e possibly not even `lsusb` per se on some OSes\n# ...\n# DEVICE:EOC\n\n### or:\n\n# DEVICE:COMMENT-BLOCK: `lsusb` listing\n# :; lsusb -vvv\n# ...\n# DEVICE:EOC\n\n\n### For service startup/shutdown log messages:\n\n# DEVICE:COMMENT-BLOCK:LOGS: Console messages of NUT driver startup\n# \u003e Accepts optional title with description of the log - used \"as is\"\n# ...\n# DEVICE:EOC\n\n### or:\n\n# DEVICE:COMMENT-BLOCK: Syslog of NUT startup\n# ...\n# DEVICE:EOC\n\n\n### For unstructured `upsrw` dumps:\n\n# DEVICE:COMMENT-BLOCK:FIXME:UPSRW: # see comment below about optional title\n# \u003e A single-token title is UPS name for example command,\n# \u003e multi-token is pasted as a starting comment\n# [battery.charge.low]\n# Remaining battery level when UPS switches to LB (percent)\n# ...\n# DEVICE:EOC\n\n### or:\n\n# DEVICE:COMMENT-BLOCK: Variables per `upsrw ups@localhost` listing\n# TODO: Convert to RW:... and RO:... markup\n# :; upsrw ups\n# [battery.charge.low]\n# Remaining battery level when UPS switches to LB (percent)\n# Type: STRING\n# Maximum length: 10\n# Value: 10\n# ...\n# DEVICE:EOC\n\n\n### For unstructured `upscmd` dumps:\n\n# DEVICE:COMMENT-BLOCK:FIXME:UPSCMD: # see comment below about optional title\n# \u003e A single-token title is UPS name for example command,\n# \u003e multi-token is pasted as a starting comment\n# beeper.disable - Disable the UPS beeper\n# ...\n# DEVICE:EOC\n\n### or:\n\n# DEVICE:COMMENT-BLOCK: Commands per `upscmd -l ups@localhost` listing\n# TODO: Convert to CMD:... markup\n# :; upscmd -l ups\n# Instant commands supported on UPS [ups]:\n#\n# beeper.disable - Disable the UPS beeper\n# beeper.enable - Enable the UPS beeper\n#...\n# DEVICE:EOC\n----\n--\n\nDevice information URL(s)::\nFurther information about this device or report can be found at specified URL,\ne.g. vendor product page, NUT issue tracker or mailing list archive page where\nthe report originated, etc. Many URLs may be listed, but only one per tag.\n+\nUse of specific `DEVICE:URL:VENDOR:` (product/vendor/manufacturer pages) and\n`DEVICE:URL:REPORT:` (GitHub issue or pull request, mailing list archive, blog\netc. where the reported information originated and more clues may appear later)\nis encouraged over the less specific `DEVICE:URL:` used for additional info.\n+\n--\n----\n# DEVICE:URL:VENDOR:\u003clink\u003e\n# DEVICE:URL:REPORT:\u003clink\u003e\n# DEVICE:URL:\u003clink\u003e\n----\n\ne.g.:\n\n----\n# DEVICE:URL:REPORT: https://github.com/networkupstools/nut/issues/867\n# DEVICE:URL:VENDOR: https://www.njoy.ro/UPS/keen-600\n----\n--\n\nDevice support level::\nExpress on a scale of 1 to 10 how much you think the device is well supported\nby NUT.\n+\n--\n----\n# DEVICE:SUPPORT-LEVEL:\u003csupport-level\u003e\n----\n\ne.g.:\n\n----\n# DEVICE:SUPPORT-LEVEL:7\n----\n--\n\nNote that the leading space is mandatory: each line must begin with a hash\nfollowed by a single space (`++$$# $$++'), all comments not following this\nsyntax will either produce an error or be ignored.\n\nMulti-line comments (vars, commands, device) support\nhttp://asciidoc.org/[AsciiDoc] markup (inline, paragraphs, blocks, lists,\ntables, ...).\n\nNote that the following AsciiDoc markup elements are *not* allowed:\n\n- sections\n- labeled lists using two semi-colons (`;;`) as delimiter (labeled lists\n  delimited by two-four colons are allowed)\n- open blocks directly at level 0 of the comment (you can use them as\n  nested elements in other kinds of block)\n\nAlso, keep in mind that the leading space will always be removed and\ntherefore you shouldn't consider it in your AsciiDoc markup, e.g.,\nif you want to add a listing block, the comment should look like this:\n\n----\n# ----\n# The verbatim text start after the space\n# If a tab is needed, preceed it with a space:\n# \t\u003c- a tab; remember to preceed it with a space otherwise it won't behave as expected\n#  \\-/\u003c- I don't know why, but I needed a space here at the beginning of the line, so i doubled it\n# ----\n----\n\nAs an exception it's allowed to use empty commented lines (`++$$#$$++'),\nsuch as in:\n\n----\n# ====\n# The previous line it's not empty (it starts an example block), so it needs a space.\n# Here's text and therefore a space preceed it..\n#\n#\n# ..while the two previous lines are empty, therefore a space is not needed after the hash\n# ====\n----\n\nThey will be retained and can be used to add vertical space or to separate\nblocks when needed; note that using a hash followed by a single space\n(`++$$# $$++') will produce the same effect.\n\nAlso note that empty lines, comments without the required leading space\nafter the hash and lines with spaces preceeding a hash will 'break'\nmulti-line comments.\n\n\n[[report-a-bad-value]]\nReport a bad value\n^^^^^^^^^^^^^^^^^^\n\nIf certain values are not correctly reported, you can flag them with the\nspecial End Of Line comment `#BAD`, you can even add a short sentence\n(still supporting http://asciidoc.org/[AsciiDoc] inline markup) after it,\nexplaining the reason (e.g. `#BAD: unbelievably high value`, note that\nthe colons are not mandatory).\n\nThis kind of flags/comments is allowed (i.e. you can append it at the\nend of the line) in the declaration of variables, RW types/values and\ncommands, i.e.:\n\n----\n\u003cvar.name\u003e: \u003cvalue\u003e\t#BAD\n#RW:\u003cvar.name\u003e:STRING:\u003clength\u003e\t#BAD: \u003creason\u003e\n#RW:\u003cvar.name\u003e:RANGE:\"\u003cmin\u003e\" \"\u003cmax\u003e\" #BAD: \u003creason\u003e\n#RW:\u003cvar.name\u003e:ENUM:\"\u003cenumerated value\u003e\"#BAD: \u003creason\u003e\n#CMD:\u003ccommand.name\u003e #BAD\n----\n\n(don't forget the leading hash in `RW` and `CMD` lines)\n\n\n////\nNDS files\n---------\n\n**N**UT **D**evice **S**imulation files (+.nds+) are meant to be the next\nversion of \u003c\u003cdevseq-files,+.dev+/+.seq+ files\u003e\u003e.\n\nThese files add support for instant commands, personalized RW variables\nand a way to express your comments/opinions/suggestions about each\nvar/command or for the whole device.\n\n\n[[basic-syntax]]\nBasic syntax\n~~~~~~~~~~~~\n\nJust like in \u003c\u003cdevseq-files,+.dev+/+.seq+ files\u003e\u003e, NUT variables are\ndeclared as:\n\n----\n\u003cvar.name\u003e: \u003cvalue\u003e\n----\n\nRW variables are declared as:\n\n----\nRW:\u003cvar.name\u003e:\u003ctype\u003e:\u003coptions\u003e\n----\n\nWhere:\n\n[horizontal]\n+\u003cvar.name\u003e+::\nName of the RW variable.\n\n+\u003ctype\u003e+::\nType of the RW variable +\u003cvar.name\u003e+, one of *STRING*, *RANGE*, *ENUM*.\n\n+\u003coptions\u003e+::\nOptions of +\u003ctype\u003e+ for +\u003cvar.name\u003e+, i.e.:\n+\n* if +\u003ctype\u003e+ is *STRING*, maximum length of the settable string\n+\n----\nRW:\u003cvar.name\u003e:STRING:\u003clength\u003e\n----\n* if +\u003ctype\u003e+ is *RANGE*, minimum and maximum settable value for the range,\n  each one enclosed in quotes and separated by a space (+\"\u003cmin\u003e\" \"\u003cmax\u003e\"+):\n+\n----\nRW:\u003cvar.name\u003e:RANGE:\"\u003cmin\u003e\" \"\u003cmax\u003e\"\n----\n* if +\u003ctype\u003e+ is *ENUM*, settable enumerated value, enclosed in quotes\n  (+\"\u003cenumerated value\u003e\"+):\n+\n----\nRW:\u003cvar.name\u003e:ENUM:\"\u003cenumerated value\u003e\"\n----\n\nCommands are declared as:\n\n----\nCMD:\u003ccommand.name\u003e\n----\n\n\nDynamic simulation\n~~~~~~~~~~~~~~~~~~\n\nAs in \u003c\u003cdevseq-files,+.seq+ files\u003e\u003e, +.nds+ files can simulate/record power\nevents and the like through the `++TIMER \u003cseconds\u003e++' instruction, e.g.:\n\n----\nTIMER 300\nups.status: OB DISCHRG\nTIMER 300\nups.status: OB LB DISCHRG\nTIMER 60\n----\n\nFor more information, refer to NUT\nlink:{nut-website-root}docs/developer-guide.chunked/index.html[Developer Guide].\nThere is a whole chapter dedicated to data capture and simulation.\n\n\n[[comments]]\nComments\n~~~~~~~~\n\nLike in \u003c\u003cdevseq-files,+.dev+/+.seq+ files\u003e\u003e, comments are allowed as lines\npreceeded by a hash (++#++), and as lines with spaces followed by a hash\n(`++$$   # \u003ccomment\u003e$$++').\nEmpty lines are ignored.\n\nIn addition, +.nds+ files support some special comments:\n\nEnd Of Line comments::\nWith the special End Of Line comment `#COMMENT: \u003ccomment\u003e`, you can add a\nshort sentence (supporting http://asciidoc.org/[AsciiDoc] inline markup)\nafter the declaration of variables, RW types/values and commands, i.e.:\n+\n--\n----\n\u003cvar.name\u003e: \u003cvalue\u003e\t#COMMENT: \u003ccomment\u003e\nRW:\u003cvar.name\u003e:STRING:\u003clength\u003e\t#COMMENT: \u003ccomment\u003e\nRW:\u003cvar.name\u003e:RANGE:\"\u003cmin\u003e\" \"\u003cmax\u003e\" #COMMENT \u003ccomment\u003e\nRW:\u003cvar.name\u003e:ENUM:\"\u003cenumerated value\u003e\"#COMMENT: \u003ccomment\u003e\nCMD:\u003ccommand.name\u003e #COMMENT: \u003ccomment\u003e\n----\n\nNote that the colon after `#COMMENT` is not mandatory.\n--\n\nVars comments::\nComments that are bound to a particular variable.\n+\n--\n----\n# \u003cvar.name\u003e:COMMENT:\n# \u003ccomment\u003e\n# ...\n# \u003ccomment\u003e\n# \u003cvar.name\u003e:EOC\n----\n\n(The trailing colon after `:COMMENT` is not mandatory.)\n\ne.g.:\n\n----\n# battery.charge:COMMENT:\n# The values reported by NUT are all bogus, I keep getting something like this:\n# \n# ----\n# battery.charge: -1\n# battery.charge: -10\n# ----\n#\n# and so on..\n# \n# Should I start finding rainbows or a whole universe where unicorns rule the world to get it working?\n# battery.charge:EOC\n----\n--\n\nCommands comments::\nComments bound to a particular command.\n+\n--\n----\n# \u003ccommand.name\u003e:COMMENT:\n# \u003ccomment\u003e\n# ...\n# \u003ccomment\u003e\n# \u003ccommand.name\u003e:EOC\n----\n\n(The trailing colon after `:COMMENT` is not mandatory.)\n\ne.g.:\n\n----\n# shutdown.return:COMMENT\n# Why doesn't this command work?\n# \n# For my continued misery of course!\n# shutdown.return:EOC\n----\n--\n\nDevice comment::\nA special comment to express general thoughts about the whole device and\nto describe the way NUT supports it.\n+\n--\n----\n# DEVICE:COMMENT:\n# \u003ccomment\u003e\n# ...\n# \u003ccomment\u003e\n# DEVICE:EOC\n----\n\n(The trailing colon after `:COMMENT` is not mandatory.)\n\ne.g.:\n\n----\n# DEVICE:COMMENT\n# Bwah..\n# This device is supported so badly by NUT that I had to burn my office down to the ground..\n# _At least_ *now* I don't have to stand the taste of that coffee anymore..\n# DEVICE:EOC\n----\n--\n\nDevice support level::\nExpress on a scale of 1 to 10 how much you think the device is well supported\nby NUT.\n+\n--\n----\n# DEVICE:SUPPORT-LEVEL:\u003csupport-level\u003e\n----\n\ne.g.:\n\n----\n# DEVICE:SUPPORT-LEVEL:7\n----\n--\n\nNDS version::\nThis is reserved to store the version of NDS this particular file belongs to.\n+\n--\n----\n# NDS:VERSION:\u003cversion\u003e\n----\n\ne.g.:\n\n----\n# NDS:VERSION:2\n----\n--\n\nNote that the leading space is mandatory: each line must begin with a hash\nfollowed by a single space (`++$$# $$++'), all comments not following this\nsyntax will either produce an error or be ignored.\n\nMulti-line comments (vars, commands, device) support\nhttp://asciidoc.org/[AsciiDoc] markup (inline, paragraphs, blocks, lists,\ntables, ...).\n\nNote that the following AsciiDoc markup elements are *not* allowed:\n\n- sections\n- labeled lists using two semi-colons (`;;`) as delimiter (labeled lists\n  delimited by two-four colons are allowed)\n- open blocks directly at level 0 of the comment (you can use them as\n  nested elements in other kinds of block)\n\nAlso, keep in mind that the leading space will always be removed and\ntherefore you shouldn't consider it in your AsciiDoc markup, e.g.,\nif you want to add a listing block, the comment should look like this:\n\n----\n# ----\n# The verbatim text start after the space\n# If a tab is needed, preceed it with a space:\n# \t\u003c- a tab; remember to preceed it with a space otherwise it won't behave as expected\n#  \\-/\u003c- I don't know why, but I needed a space here at the beginning of the line, so i doubled it\n# ----\n----\n\nAs an exception it's allowed to use empty commented lines (`++$$#$$++'),\nsuch as in:\n\n----\n# ====\n# The previous line it's not empty (it starts an example block), so it needs a space.\n# Here's text and therefore a space preceed it..\n#\n#\n# ..while the two previous lines are empty, therefore a space is not needed after the hash\n# ====\n----\n\nThey will be retained and can be used to add vertical space or to separate\nblocks when needed; note that using a hash followed by a single space\n(`++$$# $$++') will produce the same effect.\n\nAlso note that empty lines, comments without the required leading space\nafter the hash and lines with spaces preceeding a hash will 'break'\nmulti-line comments.\n\n\n[[report-a-bad-value]]\nReport a bad value\n^^^^^^^^^^^^^^^^^^\n\nIf certain values are not correctly reported, you can flag them with the\nspecial End Of Line comment `#BAD`, you can even add a short sentence\n(still supporting http://asciidoc.org/[AsciiDoc] inline markup) after it,\nexplaining the reason (e.g. `#BAD: unbelievably high value`, note that\nthe colons are not mandatory).\n\nThis kind of flags/comments is allowed (i.e. you can append it at the\nend of the line) in the declaration of variables, RW types/values and\ncommands, i.e.:\n\n----\n\u003cvar.name\u003e: \u003cvalue\u003e\t#BAD\nRW:\u003cvar.name\u003e:STRING:\u003clength\u003e\t#BAD: \u003creason\u003e\nRW:\u003cvar.name\u003e:RANGE:\"\u003cmin\u003e\" \"\u003cmax\u003e\" #BAD: \u003creason\u003e\nRW:\u003cvar.name\u003e:ENUM:\"\u003cenumerated value\u003e\"#BAD: \u003creason\u003e\nCMD:\u003ccommand.name\u003e #BAD\n----\n////\nendif::preamble-only[]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkupstools%2Fnut-ddl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetworkupstools%2Fnut-ddl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkupstools%2Fnut-ddl/lists"}