DIY SNMP Device for PDU SNMP module

Overview

Colocation manager is shipped with PDU SNMP module allowing to control and read states of PDU/similar devices using SNMP protocol. Number of devices/manufacturers are supported by default. In order to allow adding custom devices that are not on supported devices list, we've come up with DIY Device Driver, allowing for PDU module to read from any SNMP-enabled device.

Configuration

PDU_SNMP module is shipped with Colocation Manager, other than that no additional download is required.
PHP on HostBill server needs to have SNMP extension enabled
Once PDU_SNMP module is activated in Settings → Modules, proceed to Settings → Apps connections and create new connection for PDU_SNMP module.
Following configuration options are available:
- IP Address - IP or hostname of your SNMP device
- Read community - SNMP read community
- Write community - SNMP Write community - used only for setting port state (ON/OFF for outlets)
- PDU Driver - select your device driver, if not on list, select Diydevice
  When changing device driver brief overview of its capabilities will be shown. DIY Device options are described in separate section below
- AC Voltage - if your device does not support kWh readouts and you plan to bill for power you can calculate it based on its Currency readouts, AC Voltage and parameters below:
- Power factor - enter power factor for kWh calculations
- Phases - enter number of device phases for kWh calculations

DIY Device driver offers following configuration options:

SNMP Port - defaults to 161
SNMP Protocol - select SNMP protocol supported by your device:
- v1
- v2c
- v3 - this protocol will require you to provide some additional configuration:
  - Security level - required, one of: noAuthNoPriv, authNoPriv, authPriv
  - Authentication protocol - MD5 or SHA
  - Authentication pass phrase
  - Privacy protocol - DES or AES
  - Privacy pass phrase
  - Context name
  - Context EngineID
Feature configurations - tick checkbox next to feature to enable it for your device. Consult your device documentation / MIBs. Notes:
- OID can be numeric (like 3.1.3.6.1231.2.1.4.5.11.1211.1) or in text form (like: SNMPv2-SMI::enterprises.14748.1.31.1). On port-related OIDs you can use {$port} variable which will be substituted with actual port number on get/set calls
- use Test button to test entered OID against your device. When feature is port-related you can enter port number (in a form returned by List Ports) to perform test on
- select Unit that your device returns data over SNMP - consult MIB/documentation of your device for details

Feature name	Description	OID	Values	Unit	Test
List Ports	This is default feature that all devices should support. It's used to test connection as well as listing ports in Colocation manager when defining connections in device.	see notes above the table	-	-	Test will perform snmpwalk and show you returned data in debug window.
Get Port state	Informs whether Port (outlet) is on or off.	Use {$port} in OID in place where port number should be placed. You can use moveioid modifier (see section below the table)	Enter what values your device reports for ON and OFF state (ie 1 and 0)	-	Test will perform snmpget on OID, parsed with port value you enter next to test button
Set Port State	Allows to enable/disable outlet on your device. Used in client portal widget to manage PDU, as well as in Colocation manager/admin area	Use {$port} in OID in place where port number should be placed. You can use moveioid modifier (see section below the table)	Enter what values your device requires for ON and OFF state (ie 1 and 0)	-	Test will send ON value using snmpset on OID, parsed with port value you enter next to test button.
Get Port Current	Get Current (amperage) of given port. Select what unit your device returns values in	Use {$port} in OID in place where port number should be placed. You can use moveioid modifier (see section below the table)	-	uA,mA,cA,A,kA	Test will perform snmpget on OID, parsed with port value you enter next to test button
Get port Voltage	Get Voltage of given port. Select what unit your device returns values in	Use {$port} in OID in place where port number should be placed. You can use moveioid modifier (see section below the table)	-	uV,mV,cV,V,kV,MV	Test will perform snmpget on OID, parsed with port value you enter next to test button
Get port Acumulated kWh	If your device supports kWh consumption metering, and expose this information over snmp it can be used for power billing.	Use {$port} in OID in place where port number should be placed. You can use moveioid modifier (see section below the table)	-	-	Test will perform snmpget on OID, parsed with port value you enter next to test button
Get port Active Power (W)	Get port's Active power (W). Select what unit your device returns values in	Use {$port} in OID in place where port number should be placed. You can use moveioid modifier (see section below the table)	-	mW,cW,W,kW	Test will perform snmpget on OID, parsed with port value you enter next to test button
Get Port Apparent Power (VA)	Get port's Apparent power (VA). Select what unit your device returns values in	Use {$port} in OID in place where port number should be placed. You can use moveioid modifier (see section below the table)	-	mVA,cVA,VA,kVA	Test will perform snmpget on OID, parsed with port value you enter next to test button

Modifying port number in OID using moveoid

On some devices readouts related to certain port number are placed fixed amount of numbers "away" from port number. DIY Device lets you define OID in dynamic fashion, using {$port} variable.

Sample 1:

Our device returns sample list of Outlets as a result of snmpwalk on OID: SNMPv2-SMI::enterprises.14748.1.31.1

We got this list by entering above OID in List Ports feature and clicking on "Test" next to it

7.0 => Outlet 1
12.0 => Outlet 2
17.0 => Outlet 3
22.0 => Outlet 4
27.0 => Outlet 5
32.0 => Outlet 6
37.0 => Outlet 7
42.0 => Outlet 8
47.0 => Outlet 9
52.0 => Outlet 10

From MIB documentation we've established, that 1 number away from port number is its current amperage.
So for port SNMPv2-SMI::enterprises.14748.1.31.1.7.0 amperage is on SNMPv2-SMI::enterprises.14748.1.31.1.8.0

To have it working with DIY Device, in OID for Get port current we'll enter:

SNMPv2-SMI::enterprises.14748.1.31.1.{$port|moveoid:0:1}

Which "means": take {$port} value, move oid on bit "0" by "1"

Sample 2:

List ports test returned Outlet 1 id as: 10.11.232.0.1
Full OID for Outlet 1 is XXXXXXXXXXX.10.11.232.0.1
Full OID for Voltage for Outlet 1 is : XXXXXXXXXXX.10.11.232.1.1
- So, we need to add "1" on 3rd number in OID
We need to enter following OID in "Get port voltage" feature:

XXXXXXXXXXX.{$port|moveoid:3:1}