Pre-Requirements
Raritan's JSON-RPC Perl bindings require the following perl packages:
- LWP::Protocol::https
- LWP::UserAgent
- HTTP::Request::Common
- JSON
- JSON::RPC::Common::Marshal::HTTP
- Error
- Data::Dumper
- parent
Linux
In yum-based Linux distributions the following command will install the required packages:
yum install "perl(LWP::Protocol::https)" "perl(LWP::UserAgent)" \
"perl(HTTP::Request::Common)" "perl(JSON)" \
"perl(JSON::RPC::Common::Marshal::HTTP)" "perl(Error)" \
"perl(Data::Dumper)" "perl(parent)"
Windows
There are various Perl distributions available for Windows (see http://perl.org/get.html). The bindings were tested with ActiveState Perl (http://www.activestate.com/activeperl/downloads). After installing ActiveState Perl, the required modules can be installed with the following command:
ppm install LWP::Protocol::https LWP::UserAgent HTTP::Request::Common \
JSON JSON::RPC::Common::Marshal::HTTP Error Data::Dumper parent
Examples
Getting device information:
Code:
use Raritan::RPC;
use Data::Dumper;
my $agent = new Raritan::RPC::Agent('https://my-px.example.com', 'admin', 'raritan');
my $pdu = $agent->createProxy('/model/pdu/0');
my $metadata = $pdu->getMetaData();
print Dumper($metadata);
Result:
$VAR1 = {
'hwRevision' => '0x64',
'hasSwitchableOutlets' => 1,
'hasLatchingOutletRelays' => 0,
'isInlineMeter' => 0,
'ctrlBoardSerial' => 'PKI9050003',
'hasMeteredOutlets' => 0,
'fwRevision' => '3.0.2.5-41550',
'nameplate' => {
'model' => 'PX2-2630U-A1',
'imageFileURL' => '',
'manufacturer' => 'Raritan',
'rating' => {
'voltage' => '360-415V',
'current' => '24A',
'power' => '15.0-17.3kVA',
'frequency' => '50/60Hz'
},
'partNumber' => '',
'serialNumber' => 'PKE0954001'
},
'macAddress' => '00:0d:5d:07:87:5c'
};
Power-cycling an outlet:
use Raritan::RPC;
my $agent = new Raritan::RPC::Agent('https://my-px.example.com', 'admin', 'raritan');
my $pdu = $agent->createProxy('/model/pdu/0');
my $outlets = $pdu->getOutlets();
$outlets->[0]->cyclePowerState();
Configuring the SNMP agent:
use Raritan::RPC;
my $agent = new Raritan::RPC::Agent('https://my-device.example.com', 'admin', 'raritan');
my $snmp_proxy = $agent->createProxy('/snmp');
my $config = $snmp_proxy->getConfiguration();
$config->{v2enable} = 0;
$config->{readComm} = 'public';
$config->{writeComm} = 'private';
$snmp_proxy->setConfiguration($config);
IDL-to-Perl Mapping
IDL Modules and Perl Package Names
All classes dealing with Raritan JSON-RPC communication are located in Perl packages starting with Raritan::RPC
. All named sections in IDL files (module
, interface
and enumeration
) provide a scope for their included identifiers and are added as further components to the Perl package name.
Interfaces and Methods
IDL interfaces are mapped to Perl proxy classes which provide all methods defined by the IDL interface and its bases. Perl methods require the same number of scalar arguments as defined in the IDL signature. Simple types like integers, strings or enumerations are passed by scalar value; structures, vectors and maps are passed by reference. Output parameters are passed as references to a scalar variable which will be modified to point to the returned value. If the method is declared to have a non-void return type the Perl method will return a single scalar value.
Examples:
# no parameters, no return value
$firmware->reboot();
# two input parameters, integer return value
$ret = $user_manager->createAccount('newuser', 'newpassword');
# one output parameter, integer return value
my $results;
$ret = $diagnostics->listTcpConnections(\$results);
Structures
IDL structures are mapped as scalar references to Perl hashes. Each element of the structure results in a hash entry whose key is the element identifier and whose value is a Perl scalar. When passing a structure to a method call addtional hash entries are ignored.
Example:
$ssh_settings = {
'allowPasswordAuth' => 1,
'allowPublicKeyAuth' => 0
};
$security->setSSHSettings($ssh_settings);
Enumerations
Enumerated values are referenced by their fully-qualified name:
$ret = $outlet->setPowerState(Raritan::RPC::pdumodel::Outlet::PowerState::PS_ON);
Vectors
Vectors are mapped as scalar references to Perl lists. Each list entry must be a scalar.
$recipients = [ 'somebody@invalid.com', 'somebody.else@invalid.com' ];
$smtp->testConfiguration($cfg, $recipients);
Maps
Maps are mapped as scalar references to Perl hashes:
$priorities = {
'important_client' => Raritan::RPC::webcam::Priority::VERY_HIGH,
'other_client' => Raritan::RPC::webcam::Priority::LOW
};
$ret = $webcam->setClientTypePriorities($priorities);
Exceptions
In case of error conditions during a proxy method call or the createProxy
funtion exceptions will be thrown. They can be caught using the try
statement from the Perl::Error
module.
The following exceptions are defined:
Raritan::RPC::HttpException
An error occured during HTTP communication, e.g. in case the connection was refused or the authentication failed. Please check the agent URL, the resource ID and your authentication credentials.
Raritan::RPC::JsonRpcSyntaxException
The response from the server was not a valid JSON object. Please check the agent URL and the resource ID.
Raritan::RPC::JsonRpcErrorException
The method call failed. This should not happen under normal circumstances and indicates a problem on the device.
Example for catching an exception:
use Raritan::RPC;
use Error qw(:try);
try {
print "Querying firmware version ... ";
my $agent = new Raritan::RPC::Agent('https://my-device.example.com', 'admin', 'raritan');
my $firmware_proxy = $agent->createProxy('/firmware');
my $version = $firmware_proxy->getVersion();
print "Success\n";
print "Firmware version: $version\n";
} catch Raritan::RPC::HttpException with {
my $e = shift;
print "ERROR: ", $e;
};
Raritan::RPC::Agent Method Reference
Constructor: new Raritan::RPC::Agent($url, $user, $password)
Creates a new agent.
Parameters:
- $url Base URL of the device (e.g. "https://my-device.example.com")
- $user User Name (optional)
- $password Password (optional)
set_auth_basic($user, $password)
This method enables HTTP basic authentication using username and password.
Parameters:
- $user User Name (optional)
- $password Password (optional)
set_auth_token($token)
This method enables HTTP authentication using a session token. A session token can be obtained by calling the newSession method of the session.SessionManager interface.
Parameters:
timeout($seconds)
Returns and optionally sets the request timeout.
Parameters:
- $seconds New timeout in seconds (optional)
Returns:
- Previous timeout in seconds
createProxy($rid, $basetype)
Creates a new proxy object for the given resource id.
This method will query the type information for the specified resource ID and create a proxy object which provides all methods defined in the IDL definition.
When connecting to very old firmware versions (PX2 2.2 and earlier, EMX 2.0 and earlier) the type information of a resource ID cannot be queried. In this case the $basetype argument is required.
Parameters:
- $rid The resource ID, e.g. "/auth/user/admin"
- $basetype The base type, e.g. "usermgmt.User" (optional)
Returns:
- A new proxy object for the specified resource ID
set_verbose($verbose)
Enables request tracing. When verbose mode is enabled all JSON-RPC requests and responses will be echoed to the console.
Parameters:
- $verbose
true
to enable verbose mode