<?php

/**
 * This class can control and monitor the Ingrasys IpoMan 1200 through
 * SNMP from PHP.
 *
 * Features:
 * - Switch individual ports on and off
 * - Get the status of individual ports
 * - Get the power usage for individual ports
 * - Get some basic device info like version data
 * - Get environmental data from a connected EMD
 *
 * Notes:
 * - Use on your own risk. I just wanted to share what works fine for me,
 *   but I cannot predict what it will do to your devices.
 * - The object_id's were derived from the official MIB file downloadable
 *   from the ingrasys.com website, and are harcoded here. This class does
 *   not require the MIB file to work.
 * - Most SNMP functionality will not work on ancient firmware (I guess
 *   pre-2009 ones).
 * - Some SNMP functionality requires more recent firmware, like 1.06.
 *   If you notice some methods not working you can either not use them,
 *   or upgrade the firmware to a later version.
 * - You can extend this class yourself if you want more functionality
 *   that is covered in the MIB but not implemented here. You're welcome
 *   to submit your changes to me. If you do, please document properly.
 *
 * The latest version of this class (and a usage example) can be downloaded
 * from http://www.basemotive.nl/opensource/
 *
 * An old version that can switch ports through HTTP is also available (but
 * no longer maintained) at http://www.basemotive.nl/opensource/
 *
 * @version 2.0 (Nov 16, 2010)
 * @author Stefan Mensink <opensource@basemotive.nl>
 * @copyright Basemotive V.O.F.
 */
class IpoManSNMP {
	/**
	 * Create a new object to interface with an IpoMan device
	 *
	 * @param string $host The hostname or IP-adress of the IpoMan device
	 * @param string $rocommunity The read-only SNMP community name
	 * @param string $rwcommunity The read-write SNMP community name
	 */
	public function __construct($host, $rocommunity, $rwcommunity) {
		$this->host = $host;
		$this->rocommunity = $rocommunity;
		$this->rwcommunity = $rwcommunity;
	}

	/**
	 * Switches an outlet off and on.
	 *
	 * @param integer $outlet The outlet to switch, 0 is the first outlet, 11 is
	 *   the last
	 * @param integer $delay The delay between switching off and on in seconds,
	 *   default is 1 second
	 */
	public function resetOutlet($outlet, $delay=1) {
		$this->switchOff($outlet);
		sleep($delay);
		$this->switchOn($outlet);
	}

	/**
	 * Switches an outlet on.
	 *
	 * @param integer $outlet The outlet number to switch, 0 is the first
	 *   outlet, 11 is the last
	 */
	public function switchOn($outlet) {
		// From MIB: ipmDeviceOutletControlEntry -> outletControlControl
		$this->snmpSet('.1.3.6.1.4.1.2468.1.4.2.1.3.2.4.1.2.'.($outlet+1), 'i', 3);
	}

	/**
	 * Switches an outlet off.
	 *
	 * @param integer $outlet The outlet number to switch, 0 is the first
	 *   outlet, 11 is the last
	 */
	public function switchOff($outlet) {
		// From MIB: ipmDeviceOutletControlEntry -> outletControlControl
		$this->snmpSet('.1.3.6.1.4.1.2468.1.4.2.1.3.2.4.1.2.'.($outlet+1), 'i', 4);
	}

	/**
	 * Retrieves the outlet status.
	 *
	 * An outlet status is a string representation. The possible statuses are:
	 * 'unknown', 'off', 'on', 'switching_off_to_on', 'switching_on_to_off',
	 * and 'cycling'. Most times you'll encounter either 'off' or 'on'
	 *
	 * @param integer $outlet The outlet number to retrieve the status for; if
	 *   ommitted, all outlet statuses are returned
	 * @return array|int All outlet statuses in an array, or an integer if a
	 *   specific outlet was given
	 */
	public function getOutletStatus($outlet='') {
		static $statusmap = array(
			'1' => 'unknown',
			'2' => 'off',
			'3' => 'on',
			'4' => 'switching_off_to_on',
			'5' => 'switching_on_to_off',
			'6' => 'cycling'
		);

		if ($outlet==='') {
			// Build an array of all the outlet statuses
			$result = array();
			for ($i=0; $i<12; $i++)
				$result[$i] = $this->getOutletStatus($i);
			return $result;
		} else {
			// Get the status for a specific outlet
			// From MIB: ipmDeviceOutletStatusEntry -> outletStatusStatus
			$status = $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.3.2.3.1.2.'.($outlet+1));
			return $statusmap[$status];
		}
	}

	/**
	 * Retrieve the current outlet power in deciWatts
	 *
	 * @param integer $outlet The outlet number, 0 is the first outlet,
	 *   11 is the last
	 * @return int The outlet wattage in deciWatts (0.1 Watts per unit)
	 */
	function getOutletPower($outlet) {
		// From MIB: ipmDeviceOutletStatusEntry -> outletStatusWH
		return (int) $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.3.2.3.1.5.'.($outlet+1));
	}

	/**
	 * Retrieve the outlet current in milliAmperes.
	 *
	 * @param integer $outlet The outlet number, 0 is the first outlet,
	 *   11 is the last
	 * @return int The outlet current in milliAmperes (0.001 Amp per unit)
	 */
	function getOutletCurrent($outlet) {
		// From MIB: ipmDeviceOutletStatusEntry -> outletStatusCurrent
		return (int) $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.3.2.3.1.3.'.($outlet+1));
	}

	/**
	 * Retrieve the outputted energy for an outlet in Wh.
	 * This number increases constantly, and is probably the best value to
	 * use for accounting purposes.
	 *
	 * @param integer $outlet The outlet number, 0 is the first outlet,
	 *   11 is the last
	 * @return the output in Wh (or 0.001 kWh per unit)
	 */
	function getOutletEnergy($outlet) {
		// From MIB: ipmDeviceOutletStatusEntry -> outletStatusKwatt
		return (int) $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.3.2.3.1.4.'.($outlet+1));
	}

	/**
	 * Gets the inlet voltage
	 * @param integer $inlet The inlet number, 0 or 1
	 * @return the inlet voltage in deciVolt (0.1 Volt per unit)
	 */
	function getInletVoltage($inlet=0) {
		// From MIB: ipmDeviceInletStatusEntry -> inletStatusVoltage
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.3.1.3.1.2.'.($inlet+1));
	}

	/**
	 * Gets the inlet current
	 * @param integer $inlet The inlet number, 0 or 1
	 * @return the inlet current in milliAmperes
	 */
	function getInletCurrent($inlet=0) {
		// From MIB: ipmDeviceInletStatusEntry -> inletStatusCurrent
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.3.1.3.1.3.'.($inlet+1));
	}

	/**
	 * Gets the inlet AC frequency
	 * @param integer $inlet The inlet number, 0 or 1
	 * @return the inlet current in centiHerz
	 */
	function getInletFrequency($inlet=0) {
		// From MIB: ipmDeviceInletStatusEntry -> inletStatusFrequency
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.3.1.3.1.4.'.($inlet+1));
	}

	 /*
	 * Retrieve the inputted energy for an inlet in Wh.
	 * This number increases constantly, and is probably the best value to
	 * use for accounting purposes.
	 * @param integer $inlet The inlet number, 0 or 1
	 * @return the input in Wh (or 0.001 kWh per unit)
	 */
	function getInletEnergy($inlet=0) {
		// From MIB: ipmDeviceInletStatusEntry -> inletStatusKwatt
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.3.1.3.1.5.'.($inlet+1));
	}

	/**
	 * Retrieve the current inlet power in deciWatts
	 * @param integer $inlet The inlet number, 0 or 1
	 * @return int The inlet wattage in deciWatts (0.1 Watts per unit)
	 */
	function getInletPower($inlet=0) {
		// From MIB: ipmDeviceInletStatusEntry -> inletStatusWH
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.3.1.3.1.6.'.($inlet+1));
	}

	/**
	 * Reset the inputted energy for an inlet in Wh.
	 * This requires firmware 1.06.
	 * @param integer $inlet The inlet number, 0 or 1
	 */
	function resetInletEnergy($inlet=0) {
		// From MIB: ipmDeviceInletStatusEntry -> inletWattReset
		$this->snmpSet('.1.3.6.1.4.1.2468.1.4.2.1.3.1.4', 'i', $inlet+2);
	}

	/**
	 * Reset the outputted energy for an outlet in Wh.
	 * This requires firmware 1.06.
	 * @param integer $outlet The outlet number, 0 to 11
	 */
	function resetOutletEnergy($outlet) {
		// From MIB: ipmDeviceOutlet -> ipmDeviceOutletWattReset
		$this->snmpSet('.1.3.6.1.4.1.2468.1.4.2.1.3.2.6', 'i', $outlet+2);
	}

	/**
	 * Get the EMD type.
	 * @return integer 1=unknown, 2=disabled, 3=HT (humidity + temperature), 4=T (temperature)
	 */
	function getEmdType() {
		// From MIB: ipmEnvEmdStatus -> ipmEnvEmdStatusEmdType
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.5.1.1.1');
	}

	/**
	 * Get the EMD temperature.
	 * You need to have an EMD attached for this to work.
	 * @return integer The temperature in 0.1 degrees Celcius units
	 */
	function getEmdTemperature() {
		// From MIB: ipmEnvEmdStatus -> ipmEnvEmdStatusTemperature
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.5.1.1.2');
	}

	/**
	 * Get the EMD humidity.
	 * You need to have an EMD attached for this to work.
	 * @return integer The humidity in 0.1 percent
	 */
	function getEmdHumidity() {
		// From MIB: ipmEnvEmdStatus -> ipmEnvEmdStatusHumidity
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.5.1.1.3');
	}

	/**
	 * Get the manufacturer name for the device.
	 * @return string The manufacturer name, typically 'Ingrasys'
	 */
	function getManufacturer() {
		// From MIB: ipmIdent -> ipmIdentManufacturer
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.1.1');
	}

	/**
	 * Get the model name for the device.
	 * @return string The model name; returns NULL on MIB version 102.
	 */
	function getModel() {
		// From MIB: ipmIdent -> ipmIdentModel
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.1.2');
	}

	/**
	 * Get the software version for the device.
	 * @return string A full description of the device and software version.
	 */
	function getSoftwareVersion() {
		// From MIB: ipmIdent -> ipmIdentAgentSoftwareVersion
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.1.3');
	}

	/**
	 * Get the name of the device.
	 * @return string The device name, typically 'PDU'.
	 */
	function getName() {
		// From MIB: ipmIdent -> ipmIdentName
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.1.4');
	}

	/**
	 * Get the MIB version for the device.
	 * Known versions are 102 (firmware 1.05) and 103 (firmware 1.06)
	 */
	function getMibVersion() {
		// From MIB: ipmAgentConfig -> ipmAgentMibVersion
		return $this->snmpGet('.1.3.6.1.4.1.2468.1.4.2.1.2.1.1');
	}

	/**
	 * Set an SNMP object value on the IpoMan device
	 * @param string $object_id The object id to set
	 * @param string $type The SNMP type for the value (see the PHP documentation)
	 * @param mixed $value The value to set
	 * @access private
	 */
	private function snmpSet($object_id, $type, $value) {
		snmpset($this->host, $this->rwcommunity, $object_id, $type, $value);
	}

	/**
	 * Get an SNMP object value from the IpoMan device
	 * @param string $object_id The object id to fetch
	 * @param bool $strip_type If encapsulated types like 'INTEGER: ' should
	 *   be stripped from the result
	 * @return string the retrieved value
	 * @access private
	 */
	private function snmpGet($object_id, $strip_type=true) {
		$value = snmpget($this->host, $this->rocommunity, $object_id);
		if ($strip_type && strpos($value, ':')!==false)
			$value = substr($value, strpos($value, ':')+2);
		return $value;
	}

	/**
	 * The hostname or IP-adress of the IpoMan device
	 * @access private
	 */
	private $host;

	/**
	 * The read-only SNMP community name
	 * @access private
	 */
	private $rocommunity;

	/**
	 * The read-write SNMP community name
	 * @access private
	 */
	private $rwcommunity;
}

?>