166 lines
3.8 KiB
Text
166 lines
3.8 KiB
Text
:titles.underlines: "__","==","--","~~","^^"
|
|
|
|
Network UPS Tools Developer Guide
|
|
_________________________________
|
|
:Author: Russell_Kroll,_Arnaud_Quette,_Charles_Lepple_and_Peter_Selinger
|
|
:Author Initials: RK, AQ, CL & PS
|
|
|
|
Introduction
|
|
============
|
|
|
|
NUT is both a powerful toolkit and framework that provides support for Power
|
|
Devices, such as Uninterruptible Power Supplies, Power Distribution Units
|
|
and Solar Controllers.
|
|
|
|
This document intend to describe how NUT is designed, and the way to
|
|
develop new device drivers and client applications.
|
|
|
|
|
|
[[design]]
|
|
|
|
include::design.txt[]
|
|
|
|
|
|
[[developers]]
|
|
|
|
include::developers.txt[]
|
|
|
|
|
|
[[new-drivers]]
|
|
|
|
include::new-drivers.txt[]
|
|
|
|
|
|
[[sock-protocol]]
|
|
|
|
include::sock-protocol.txt[]
|
|
|
|
|
|
[[augeas]]
|
|
|
|
include::../scripts/augeas/README[]
|
|
|
|
|
|
[[devscan]]
|
|
|
|
include::../tools/nut-scanner/README[]
|
|
|
|
|
|
[[new-clients]]
|
|
|
|
include::new-clients.txt[]
|
|
|
|
|
|
[[net-protocol]]
|
|
|
|
include::net-protocol.txt[]
|
|
|
|
|
|
[[dev-tools]]
|
|
|
|
NUT developers tools
|
|
====================
|
|
|
|
NUT provides several tools for clients and core developers, and QA people.
|
|
|
|
[[dev-simu]]
|
|
|
|
Device simulation
|
|
-----------------
|
|
|
|
The dummy-ups driver propose a simulation mode, also known as 'Dummy Mode'.
|
|
This mode allows to simulate any kind of devices, even non existing ones.
|
|
|
|
Using this method, you can either replay a real life sequence,
|
|
<<dev-recording,recorded from an actual device>>, or directly interact
|
|
through upsrw or by editing the device file, to modify the variables values.
|
|
|
|
Here is an example to setup a device simulation:
|
|
|
|
- install NUT as usual, if not already done
|
|
- get a simulation file (.dev) or sequence (.seq), or generate one using the
|
|
<<dev-recording,device recorder>>. Sample files are provided in the 'data'
|
|
directory of the NUT source. You can also download these from the development
|
|
repository, such as the
|
|
link:http://anonscm.debian.org/viewvc/nut/trunk/data/evolution500.seq?revision=2778&view=co[evolution500.seq].
|
|
- copy the simulation file to your sysconfig directory, like /etc/nut or
|
|
/etc/ups
|
|
- configure NUT for simulation (linkman:ups.conf[5]):
|
|
+
|
|
[dummy]
|
|
driver = dummy-ups
|
|
port = evolution500.dev
|
|
desc = "dummy-ups in dummy mode"
|
|
+
|
|
- now start NUT, at least dummy-ups and upsd:
|
|
+
|
|
$ upsdrvctl start dummy
|
|
$ upsd
|
|
+
|
|
- and check the data:
|
|
+
|
|
$ upsc dummy
|
|
...
|
|
+
|
|
- you can also use upsrw to modify the data:
|
|
+
|
|
$ upsrw -s ups.status="OB LB" -u user -p password dummy
|
|
+
|
|
- or directly edit /etc/nut/evolution500.seq. In this case, modification will
|
|
only apply according to the TIMER events and the current position in the
|
|
sequence.
|
|
|
|
For more information, refer to linkman:dummy-ups[8] manual page.
|
|
|
|
|
|
[[dev-recording]]
|
|
|
|
Device recording
|
|
----------------
|
|
|
|
To complete dummy-ups, NUT provides a device recorder script called
|
|
'device-recorder.sh' and located in the 'tools/' directory of the
|
|
NUT source tree.
|
|
|
|
This script uses 'upsc' to record device information, and stores
|
|
these in a differential fashion every 5 seconds (by default).
|
|
|
|
Its usage is the following:
|
|
|
|
Usage: dummy-recorder.sh <device-name> [output-file] [interval]
|
|
|
|
For example, to record information from the device 'myups' every 10 seconds:
|
|
|
|
tools/device-recorder.sh myups@localhost myups.seq 10
|
|
|
|
During the recording, you will want to generate power events, such as power
|
|
failure and restoration. These will be tracked in the simulation files, and be
|
|
eventually be replayed by the <<dev-simu,dummy-ups>> driver.
|
|
|
|
|
|
NUT core development and maintenance
|
|
====================================
|
|
|
|
This section is intended to people who want to develop new core features,
|
|
or to do some maintenance.
|
|
|
|
|
|
include::macros.txt[]
|
|
|
|
|
|
[[roadmap]]
|
|
|
|
include::../TODO[]
|
|
|
|
|
|
[[nut-names]]
|
|
Appendix A: NUT command and variable naming scheme
|
|
==================================================
|
|
|
|
include::nut-names.txt[]
|
|
|
|
[[lib-info]]
|
|
Appendix B: NUT libraries complementary information
|
|
===================================================
|
|
|
|
include::../lib/README[]
|