RFC: Add support for daisy-chained devices

[aquette]

It's not unusual to see some daisy-chained PDUs, connected together in master-slave mode, to only consume 1 IP address for their communication interface (generally, network card exposing SNMP data) and expose only 1 point of communication to manage several devices.

This breaks the historical consideration of NUT that 1 driver provides data for 1 device.
However, there is a need and a smart approach can be considered to fulfill it while not breaking the standard scope (sort of compatibility).

Functional proposal

Specification

The daisychain support will use the device collection to extend the historical NUT scope (1 driver - 1 device) and provide data from the additional devices.
A new variable will be introduce to express the number of devices exposed: device.count:

• default to 1
• if higher than 1, enable daisychain support and access devices data through device.X.{...}

To ensure backward compatibility in NUT, the data of the various devices will be exposed the following way:

• A special case is "device.0", for the master device of the daisychain.
  It is equivalent to "device" and root collections, and is omitted from the device subcollection
  since all the numerous data are already exposed. As an example, to access
  device.0.outlet.1.id, you use the normal "outlet.1.id".
• For the 1rst daisy chained device (slave) and subsequent ones, you then use device.1.outlet.1.id, device.2.outlet.1.id, ...

That way, client application that are unaware of the daisychain support, will only see the first device, and not nothing at all.

Moreover, this solution is generic, and not specific to the PDU use case currently considered. It thus support both the current NUT scope, along with potential evolutions, and technology change (hybrid chain with UPS and PDU for example).

Example

device.count: 3
device.mfr: EATON
device.model: EPDU MI 38U-A IN: L6-30P 24A 1P OUT: 36XC13:6XC19
device.1.mfr: EATON
device.1.model: EPDU MI 38U-A IN: L6-30P 24A 1P OUT: 36XC13:6XC19
device.2.mfr: EATON
device.2.model: EPDU MI 38U-A IN: L6-30P 24A 1P OUT: 36XC13:6XC19
...
input.voltage: 237.75
device.1.input.voltage: 237.75
device.2.input.voltage: 237.75
...
outlet.1.status: on
device.1.outlet.1.status: on
device.2.outlet.1.status: off
...

Implementation

A branch is available to support the development of this new feature:
https://github.com/networkupstools/nut/tree/daisychain

Documentation

docs/nut-names.txt will be completed and details will be referring to docs/daisychain.txt

Driver

The first, and maybe the only one, implementation will happen in snmp-ups.

[aquette]

@clepple , @zykh , @balooloo , @jimklimov : calling for review and comment

[zykh]

@aquette: I was about to open a similar issue, as I need something like that (among other things) in order to support Voltronic Power's P30 (solar things) and P33 (big, big UPSes) devices in nutdrv_qx.

I started working on these two protocols a couple of years ago and kept them updated as new versions of their softwares were released, but I could not test them with real hardware, so I had to wait for some user to do it.
Now, P33 is still in that state, but, for P30, a couple of months ago a user mailed the list (http://thread.gmane.org/gmane.comp.monitoring.nut.user/9573) and it turned out he has one of such devices, so I was planning to rebase my work on master and get it tested.

There are some differences between the way I implemented it in the subdriver for P30 devices and your idea, though, so maybe we can coordinate our efforts.

Here are my constraints and what I did.

P30 devices can report data either about the connected device (which is, in this case, mapped in the subdriver using the usual NUT vars, where available) or about an array of linked-together devices (either working in parallel mode or as phase 1, 2 or 3 of a 3-phase system) and, in this case:

• they only report the maximum number of linked-together devices (not the number of actually attached ones),
• you then have to query (let's say with a '' command) the connected device (i.e. the one you are talking with) for all the possibly supported devices (e.g. if maximum number is 5, then queries are: '1', '2', '3', '4', '5'): only if a device is really available, the query succeeds (e.g. maximum number 5, but only 3 devices are linked-together, then 2 out of the 5 queries will fail),
• the array is randomly filled, so you can't expect the lower indices to be used before the higher ones,
• plus, the actually connected device reports its data as any one of the s and it has to be identified in the array comparing serial numbers (each '' command reports the serial number and the connected device also reports its own serial number when queried with a different command).

So, at the moment, in my implementation:

• there's a 'device.count.maximum' var that maps the maximum number of linked-together devices,
• every supported is mapped to a 'device..' tree of data (e.g. '1' -> 'device.1.'),
• if a device is available (i.e. the '' query succeeds), a var 'device..availability' (tentative name) is filled with 'available', otherwise it reads 'not available',
• there is a 'device.id' variable filled with the that represents the actually connected device in the array of linked-together devices (e.g. the connected device reports its data when queried with '3' -> its data is stored in 'device.3.' tree -> 'device.id' = 3): so data about the connected device (apart from ratings, default values, alarm and status, which is mirrored to ups.status) is not mapped to usual NUT vars but only to a 'device..' tree, where is stored in 'device.id'.

This is the simplest way I've found to support these devices, given their peculiarities and actual nutdrv_qx's own contraints -- probably if I'd had more time I could've changed nutdrv_qx main driver to do it in another way.

Apart from that, there are a couple of other issues with 'device.n' items:

• statuses/alarms: at the moment I do all the needed things in the subdriver, but, given that we plan to offer a broader support for this kind of vars, we may want to do it à la ups.{status,alarm},
• cmdvartab / server/desc: we really need to improve the way we match items, otherwise we better be prepared for a plethora of "Unavailable".

[aquette]

Hi @zykh , thx for your feedback. I'll need to think a bit more about that...
Do you have a devdump for such config btw?

[jimklimov]

@aquette 👍 Proposal looks reasonable to me.

[aquette]

Hi @zykh and all,
I've started to push the documentation, and implementation for snmp-ups, on the mentioned daisychain branch.

Part of the remainders, there is ups.status (not applicable to PDU) and ups.alarm.
For ups.alarm, I see 2 options:

1. everything in ups.alarm, with "device.x: " appended before the alarm message.

• pros: single and standard place to monitor alarms
• cons: can get flooded and truncate alarms (loss of data)

2. per device alarms in device.x.ups.alarm

• pros: per device visibility, can limit the publication truncation
• cons: daisychain slaves alarms may not be seen by NUT client that are not daisychain-aware

I'm more in favor of option 1. Any comment.

Last question @zykh : are you typing P30 as "scd" or "ups"?
Last (side) comment: I'll be also pushing soon for the RFC to transition to "device.alarm" by NUT 3.0

[zykh]

For ups.alarm, I see 2 options:

1. everything in ups.alarm, with "device.x: " appended before the alarm message.

• pros: single and standard place to monitor alarms
• cons: can get flooded and truncate alarms (loss of data)

2. per device alarms in device.x.ups.alarm

• pros: per device visibility, can limit the publication truncation
• cons: daisychain slaves alarms may not be seen by NUT client that are not daisychain-aware

I'm more in favor of option 1. Any comment.

I'm more for 2 (post 'ups.alarm'->'device.alarm' rename: 'device.x.alarm'): if we say that any var not beginning with 'device.x' belongs to the 'master' device, then 'ups.alarm' = 'device.0.ups.alarm', so, in order to be consistent with other vars, 'ups.alarm' should only contain data about that single device.

Maybe we could change the daisychain concept to something like the way we manage outlets:

A special case is "outlet.0" which is equivalent to "outlet", and represent the whole set of outlets of the device.

So, instead of saying that 'device.0' = 'master', we could say that 'device.0' (and all the vars not beginning with 'device.x') represents the whole set of attached devices.
We would then get something like this:

• 'var' = 'device.0.var' = 'device.1.var' + 'device.2.var' + ... + 'device.N.var' (not a literal sum)

I see that useful not only to get a single point of access to alarms (and status), but also for other vars, for example we may want to publish the load % of all the daisychained devices (let's suppose that they power the same load), and for instant commands, for example we may want to reboot all the devices at the same time, and RW vars that, when changed, may need to be consistent between the attached devices.

If 'device.count' == 1, then nothing would change from our actual implementation:

• 'device.alarm' = 'device.0.alarm' = 'device.1.alarm',
• 'ups.load' = 'device.0.ups.load' = 'device.1.ups.load'
• ...

obviously 'device.x' items need not to be published in this case.

Last question @zykh : are you typing P30 as "scd" or "ups"?

I set 'device.type' to 'scd', but P30 devices can supply a load, so I still use 'ups.status' for UPS-related things.

I'll try to get some time during this weekend to rebase on master and publish here the output of upsc.

Last (side) comment: I'll be also pushing soon for the RFC to transition to "device.alarm" by NUT 3.0

I, too, am for 'device.alarm'.
But, maybe, we may want to retain also other alarms (like 'ups.alarm', but possibly others: we could simply say that 'alarm' is a valid SPEC for some DOMAINs): 'device.[x.]alarm' would then be the 'sum' of all of them.

[aquette]

hi @zykh

your comment on "device.0" being the sum of the daisychain Vs my current proposal (device.0 == daisychain master) fully makes sense, for the reasons you stated.

I need to discuss this internally and then revise my proposal and implementation

[aquette]

So I revised the implementation, and pushed the code to the branch.
Attached is a dump of daisychain (1+7) PDU in hybrid mode (1ph and 3ph) (.dev renamed to .txt to please github upload).
For now, support is limited to data + alarms. Settings and commands are the next step.

daisy-1plus7-hybrid.txt