Radiation Monitor Python Script Documentation

From New IAC Wiki
Revision as of 07:46, 14 September 2010 by Buckminst (talk | contribs) (Protected "Radiation Monitor Python Script Documentation" ([edit=comp] (indefinite) [move=comp] (indefinite) [read=comp] (indefinite)))
Jump to navigation Jump to search

Configuration And Use

Configuration File

Example Configuration File

#local:134.50.87.179:55554
listen:255.255.255.255:55555
sendto:127.0.0.1:54321
#sendto:134.50.87.179:54321
#verbose
#debug
noforward
#nodaemon
#truncate

Configuration Directives

local

listen

sendto

verbose

debug

noforward

nodaemon

truncate

API

DBus Quick Reference

Service Bus: SessionBus()

Service Name: iac.nagios.radmonitors

Service Path: /IAC/Nagios/RadMonitors

Exposed Methods

get_active_channels()
get_active_monitors()
get_active_monitor_count()
get_radiation_levels()
add_send_client(string)
reload_configuration()

DBus Interaction

Before you can interact with the Radiation Monitor's DBus service, you will need to load some prerequisite Python libraries:

import dbus

This is the minimum to connect to DBus. If you wish to do more than connect as a client, you will need to load the following libraries:

import dbus.service, gobject
from dbus import glib

It is also recommend that you initialize threading now if you are planning on performing threaded tasks:

gobject.threads_init()
glib.init_threads()

Connecting to the Radiation Monitor DBus service

To interact with the Radiation Monitor DBus service in Python, you will first need to connect to the DBus Session bus:

dbus_bus = dbus.SessionBus()

Once you have successfully connected to the session bus, you will then want to get the DBus service object for the Radiation Monitor. This is done via the get_object bus method:

dbus_object = dbus_bus.get_object(service_name, service_path)

For our Radiation Monitor interface, the proper invocation is as follows:

dbus_object = dbus_bus.get_object("iac.nagios.radmonitors", "/IAC/Nagios/RadMonitors")

After this is done, you may choose to call the Radiation Monitor's DBus methods either through the service object itself, or you may create references to specific methods for use:

dbus_method_ref = dbus_object.get_dbus_method(method, service_name)

Example:

>>> remote_method = remote_object.get_dbus_method('get_active_monitor_count', 'iac.nagios.radmonitors')
>>> remote_method()
dbus.Int32(7)

Introspection Schema

The Radiation Monitor DBus service returns the following schema upon being called with its inherited Introspect() method:

<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node name="/IAC/Nagios/RadMonitors">
  <interface name="iac.nagios.radmonitors">
    <method name="reload_configuration">
    </method>
    <method name="get_active_monitors">
    </method>
    <method name="get_active_monitor_count">
    </method>
    <method name="add_send_client">
      <arg direction="in"  type="v" name="new_client" />
    </method>
    <method name="get_radiation_levels">
    </method>
    <method name="get_active_channels">
    </method>
  </interface>
  <interface name="org.freedesktop.DBus.Introspectable">
    <method name="Introspect">
      <arg direction="out" type="s" />
    </method>
  </interface>
</node>

Methods

get_active_channels

This exposed DBus method will return a dbus.Array value representing the active channels the script sees. It is invoked in the following manner:

dbus_object.get_active_channels()

Example output:

>>> remote_object.get_active_channels()
dbus.Array([dbus.Int32(1), dbus.Int32(2), dbus.Int32(3), dbus.Int32(4), dbus.Int32(5), dbus.Int32(6), dbus.Int32(7)], signature=dbus.Signature('i'))

get_active_monitors

This exposed DBus method will return a dbus.Array value representing the IP address of all radiation monitors the script sees. It is invoked in the following manner:

dbus_object.get_active_monitors()

Example output:

>>> remote_object.get_active_monitors()
dbus.Array([dbus.String(u'192.168.40.155'), dbus.String(u'192.168.40.154'), dbus.String(u'192.168.40.121'), dbus.String(u'192.168.40.172'),
dbus.String(u'192.168.40.137'), dbus.String(u'192.168.40.159'), dbus.String(u'192.168.40.120')], signature=dbus.Signature('s'))

get_active_monitor_count

This exposed DBus method will return a dbus.Int32 value representing the total number of active monitors the script sees. It is invoked in the following manner:

dbus_object.get_active_monitor_count()

Example output:

>>> remote_object.get_active_monitor_count()
dbus.Int32(7)

get_radiation_levels

This exposed DBus method will return a dbus.Array value representing the current radiation level of all monitors the script sees. It is invoked in the following manner:

dbus_object.get_radiation_levels()

Example output:

>>> remote_object.get_radiation_levels()
dbus.Array([dbus.String(u'0.0'), dbus.String(u'0.0'), dbus.String(u'0.0'), dbus.String(u'0.0'), dbus.String(u'0.1'), dbus.String(u'0.1'),
dbus.String(u'0.1')], signature=dbus.Signature('s'))

add_send_client

This exposed DBus method will add a new send target client to a running instance of the script, allowing for on-the-fly addition of targets without restarting. It is invoked in the following manner:

dbus_object.add_send_client(string)

Where string is a string containing the IP address and destination port number of the send target, formatted as "ip:port". The function returns a dbus.Boolean value; True if the add is successful, False if not.

Note: This only adds the new send client to the in-memory send list. If you wish to retain this send client for future use, you will need to edit the configuration file and add the appropriate sendto directive for that client.

Example output:

>>> remote_object.add_send_client("134.50.87.179:55555")
dbus.Boolean(True)

reload_configuration

This exposed DBus method will cause a running instance of the script to reload its configuration file, as if having been sent signal SIGHUP. It is invoked in the following manner:

dbus_object.reload_configuration()

Then function always returns dbus.Boolean True at this time.

Example output:

>>> remote_object.reload_configuration()
dbus.Boolean(True)