Network UPS Tools Developer Guide

Russell Kroll, Arnaud Quette, Charles Lepple, Peter Selinger, Jim Klimov and NUT project community contributors


Table of Contents

1. Introduction
2. NUT design document
2.1. The layering
2.2. How information gets around
2.3. Instant commands
2.4. Setting variables
2.5. Example data path
2.6. History
3. Information for developers
3.1. General stuff — common subdirectory
3.2. Device drivers — main.c
3.3. Portability
3.4. Continuous Integration and Automated Builds
3.5. Integrated Development Environments (IDEs) and debugging NUT
3.6. Coding style
3.7. Miscellaneous coding style tools
3.8. Submitting patches
3.9. Patch cohesion
3.10. The finishing touches: manual pages and device entry in HCL
3.11. Source code management
3.12. Ignoring generated files
3.13. Commit message formatting
3.14. Commit sign-off
3.15. Repository etiquette and quality assurance
3.16. Building the Code
4. Creating a new driver to support another device
4.1. Smart vs. Contact-closure
4.2. Serial vs. USB vs. SNMP and more
4.3. Overall concept
4.4. Skeleton driver
4.5. Essential structure
4.6. Essential functions
4.7. Data types
4.8. Manipulating the data
4.9. UPS alarms
4.10. Staleness control
4.11. Serial port handling
4.12. USB port handling
4.13. Variable names
4.14. Message passing support
4.15. Enumerated types
4.16. Range values
4.17. Writable strings
4.18. Instant commands
4.19. Delays and ser_* functions
4.20. Canonical input mode processing
4.21. Adding the driver into the tree
4.22. Contact closure hardware information
4.23. How to make a new subdriver to support another USB/HID UPS
4.24. How to make a new subdriver to support another SNMP device
4.25. How to make a new subdriver to support another Q* UPS
5. Driver/server socket protocol
5.1. Formatting
5.2. Commands used by the drivers
5.3. Commands sent by the server
5.4. Design notes
6. NUT configuration management with Augeas
6.1. Introduction
6.2. Requirements
6.3. Create a test sandbox
6.4. Start testing and using
6.5. Complete configuration wizard example
7. NUT device discovery
7.1. Introduction
7.2. Python
7.3. Perl
7.4. Java
8. Creating new client
8.1. C / C++
8.2. Python
8.3. Perl
8.4. Java
9. Network protocol information
9.1. Old command removal notice
9.2. Command reference
9.3. Revision history
9.4. GET
9.5. LIST
9.6. SET
9.7. INSTCMD
9.8. LOGOUT
9.9. LOGIN
9.10. PRIMARY (since NUT 2.8.0) or MASTER (deprecated)
9.11. FSD
9.12. PASSWORD
9.13. USERNAME
9.14. STARTTLS
9.15. Other commands
9.16. Error responses
9.17. Future ideas
10. NUT developers tools
10.1. Device simulation
10.2. Simulated devices discovery
10.3. Device recording
11. NUT core development and maintenance
11.1. NUT-specific autoconf macros
11.2. NUT roadmap and ideas for future expansion
A. NUT command and variable naming scheme
A.1. Structured naming
A.2. Time and Date format
A.3. Variables
device: General unit information
ups: General unit information
input: Incoming line/power information
output: Outgoing power/inverter information
Three-phase additions
EXAMPLES
battery: Any battery details
ambient: Conditions from external probe equipment
outlet: Smart outlet management
driver: Internal driver information
server: Internal server information
A.4. Instant commands
B. NUT daisychain support notes
B.1. Introduction
B.2. Implementation notes
General specification
Information for developers
C. NUT libraries complementary information
C.1. Introduction
C.2. libupsclient-config
C.3. pkgconfig support
C.4. Example configure script
C.5. Future consideration
C.6. Libtool information