SNMP stands for simple network mangement protocool. It is used to interface to different networking devices. In this case we are using it to communicate with a Wiener crate. There is a very useful set of tools that are free, simple to use and allow interfacing with any device that uses SNMP. This tool set is called net-snmp. In many networking devices, different attributes or functions are given an OIP, which is just an object identifier tag. This is organized into a tree and so you can either go through and get all the information that is available or read from only one branch. To make the information meaningful OIP numeric data can be translated into words by attaching an MIB file. An MIB is a mangement information base file. It is just a plain text file that maps the incomprehensible OIP numbers used by SNMP tools into readable information. Two things must be installed for the Wiener crate script to function; the net-snmp tools and the MIB file for the particular device. I have included a tutorial on installing both. You will also find instructions on how to use the python script and how to modify it to suit different requirements. I have documented each function and created extensible dictionary objects so new functions can be added as needed.

-Kareem

Written by Kareem Amin Nov 16th, 2006 kareem.amin@mail.mcgill.ca

Full Documentation:

Summary

Python script to acess data from Wiener crate using snmp protcool. Requires net-snmp and the MIB file associated with the Wiener crate to be installed. Extracts data from the net-snmp query and writes it into a text file in a KST readable format.

Where to get NET-SNMP and the MIB File

Net-SNMP

The net-snmp tool-kit is available at:

http://net-snmp.sourceforge.net/download.html

Detailed instructions for installing it are avaialble at:

http://net-snmp.sourceforge.net/docs/INSTALL.html

For most linux systems the following will work:

0) Download net-snmp and extract to current working directory

1) Run ./configure (type "./configure --help" for a quick usage summary.) (--prefix=PATH will change the default /usr/local installation path.) (see "Compilers and Options" on changing the complier to use)

2) Optionally edit include/net-snmp/net-snmp-config.h (due to prompting done by the configure script, this is very rarely necessary.)

3) make

4) Run the next command as root: 5) make install

6) configure the agent (either using 'snmpconf' or by crafting an snmpd.conf file manually. The file 'EXAMPLE.conf' may be a suitable starting point)

Note: By default, everything will be installed in /usr/local. (see below for more instructions)

MIB file

The MIB-file for the Wiener crate can be found at:

http://kingspeak.physics.mcgill.ca/twiki/pub/Internal/HardwareHowto/2006-Wiener9UVME_Crate/WIENER-CRATE-MIB.txt

The following are instructions on how to install the MIB file:

Firstly,

cp MY-MIB.txt /usr/local/share/snmp/mibs

or

mkdir $HOME/.snmp mkdir $HOME/.snmp/mibs cp MY-MIB.txt $HOME/.snmp/mibs

And then,

export MIBS=+MY-MIB

or alternatively:

echo "mibs +MY-MIB" >> $HOME/.snmp/snmp.conf

Note that you need both steps. The first command copies the file defining the new MIB to a expected location for MIB files. This defaults to /usr/local/share/snmp/mibs (or PREFIX/share/snmp/mibs if the the suite was installed into a different base location). Some ready-packaged distributions (such as Linux RPM packages) may look for MIB files in a different location, such as /etc/snmp/mibs - put the new file in this directory instead. This makes it available for everyone on the system. The tools will also look for mibs in your personal $HOME/.snmp/mibs directory, but this will only work for you.

The second command tells the tools to load in this new MIB file as well as the default set. Note that the tools do not load every MIB found in the directory - this is to avoid slowing them down excessively when there is a large collection of MIB files. If you do want the tools to load all the MIB files, set the environmental variable MIBS to the special value "ALL".

Note that the value for this variable is the name of the MIB module, not the name of the MIB file. These are typically the same (apart from the .txt suffix), but if in doubt, check the contents of the file. The value to use is the token immediately before the word DEFINITIONS at the start of the file. Of course, if you load 'ALL' mibs, then this distinction is irrelevant.

Most of the tools (apart from 'snmptable') will work quite happily without any MIB files at all, as long as you are prepared to work with numeric OIDs throughout. The MIB files are only used for translating between numeric and textual forms for queries and responses. The same holds true for the agent - see the AGENT section for details.

Taken from the net-snmp FAQ. It can be found at

http://net-snmp.sourceforge.net/docs/FAQ.html

Formatting and syntax

All variables are descriptive of their function and long variable names are seperated with underscores. Each function is described briefly in its first line. All arguments to functions are passed through the objects variables. The objects complete attributes are detailed later in the file.

Script data path and functions

The script is an object with nine functions. Four are run only at initalization and four are run every time the script is called. The ninth function simply decides whether the script is to run for a finite number of times or goes into an infinite loop.

The script object is read_wiener_crate.

The following are the nine functions:

These four are run only at once when the object is created:

  • sort_commands(self)
  • error_check(self)
  • find_variable_names(self)
  • construct_command(self)

These are run every x number of seconds that the user specifes at the command line. The default value is 1 second:

  • run_command(self)
  • extract_data(self)
  • compute_power(self)
  • write_data(self)
  • run_crate(self)

All the objects methods take the self object as an argument.

Data flow

The following is a brief exposition of the scripts data flow.

Initalization:

1. The script sorts the commands that are inputted at the command line into a specific format that is used throughout the script. The current format as of the writing of this documentation is [ip_address,get/set,variables_to_probe,scope,time_between_queries,end_time,output_file,debug_flag].

2. The error_check function is then called and preforms a variety of different checks. It informs the user if any problems are found.

3.Find_variable_names is run next and exectues an snmp walk command over the variable names to find out the relation between the data names such as v8p, ivcc and their MIB equivalents, U0, U1, etc.

4.The script then looks to see if -s find has been required. If a find is required the script outputs the data names and quits. If not it creates an empty power_output_list that will be usefully later on the size of which depends on the number of data_variables there are.

5.The construct command is run next and creates a list of a string of commands that are to be run. It uses the format required by the net-snmp tools to create this string. The format is as follows [snmpcommand] -v '+ self.version + ' -m ' + self.mib_file +' -c ' + self.community_name + ' ' + str(self.commands[ip_address][number_of_ips]) + [variable_to_probe]

Run-Time:

6. run_command simply runs the string of commands passed by the construct_command module and catches their output into a cache. It puts end delimeters after every query to a particular variable in order to identify them later on. e.g. if you are probing voltage and current the following would be the sample cache:

WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U0 = Opaque: Float: 6.620000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U1 = Opaque: Float: 11.200000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U3 = Opaque: Float: 3.690000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U4 = Opaque: Float: 6.590000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U5 = Opaque: Float: 11.160000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U7 = Opaque: Float: 3.710000 V /endvoltage

WIENER-CRATE-MIB::outputMeasurementCurrent.U0 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U1 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U3 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U4 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U5 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U7 = Opaque: Float: 0.000000 A /endcurrent

7. The extract data method slices between sets of data and then extracts the data line by line. For example it would slice the cache to the /end voltage then iterate through that data to extract the U0 voltage, the U1 voltage etc. It returns a list of all the data.

8. The compute_power method multiplies the voltage by the current to compute the data and then sums them up to obtain the total power.

9. The write_data method calculates the current UNIX time appends it to the beginning of the string then creates a string out of the list of data that is passed to it. It then appends a human readable time at the end of the string. It opens the output file appends the information, then closes it. This is where the formatting for the output is done.

10. The run_crate method decides whether to loop a finite number of times or an infinite number. It also checks the file size after every iteration and creates a new file once the max_file size is reached with the same name and a number appended to the end of the file_name. For more information consult the modifications section of the documentation.

Description of functions

Please see the script for this. They are commented to explain any ambigiuous steps and variable names are long and descriptive. The header of each function has a short description of it and it is commented liberally throughout. See the data-path for general information on how the script works.

Output

The output is formatted into the following scheme. The Unix time in seconds leads every block of data. Each block is terminated by a carriage return. Data from the crate follows the Unix time with tabs to mark the end of each data. The default format if all variables are requested (i.e. -v all at the command prompt) is voltage, current, temperature, then fan data. That is followed by the power which is computed by the script and the total power. The human readable time is appeneded to the end of the set of data. Its default format is year, month, day, hour, minutes, seconds in local time. If you would like to modify this scheme read the section entitled modifiying the script.

Sample net-snmp query

WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U0 = Opaque: Float: 6.620000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U1 = Opaque: Float: 8.780000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U3 = Opaque: Float: 3.690000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U4 = Opaque: Float: 6.590000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U5 = Opaque: Float: 8.800000 V WIENER-CRATE-MIB::outputMeasurementSenseVoltage.U7 = Opaque: Float: 3.710000 V

WIENER-CRATE-MIB::outputMeasurementCurrent.U0 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U1 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U3 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U4 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U5 = Opaque: Float: 0.000000 A WIENER-CRATE-MIB::outputMeasurementCurrent.U7 = Opaque: Float: 0.000000 A

WIENER-CRATE-MIB::sensorTemperature.TEMP1 = INTEGER: 19 ?C WIENER-CRATE-MIB::sensorTemperature.TEMP2 = INTEGER: 19 ?C WIENER-CRATE-MIB::sensorTemperature.TEMP3 = INTEGER: -128 ?C WIENER-CRATE-MIB::sensorTemperature.TEMP4 = INTEGER: -128 ?C WIENER-CRATE-MIB::sensorTemperature.TEMP5 = INTEGER: -128 ?C WIENER-CRATE-MIB::sensorTemperature.TEMP6 = INTEGER: -128 ?C WIENER-CRATE-MIB::sensorTemperature.TEMP7 = INTEGER: -128 ?C WIENER-CRATE-MIB::sensorTemperature.TEMP8 = INTEGER: -128 ?C

WIENER-CRATE-MIB::fanSpeed.1 = INTEGER: 1342 RPM WIENER-CRATE-MIB::fanSpeed.2 = INTEGER: 1091 RPM WIENER-CRATE-MIB::fanSpeed.3 = INTEGER: 1245 RPM WIENER-CRATE-MIB::fanSpeed.4 = INTEGER: 1185 RPM WIENER-CRATE-MIB::fanSpeed.5 = INTEGER: 1207 RPM WIENER-CRATE-MIB::fanSpeed.6 = INTEGER: 948 RPM

Sample output

1164064488.13 6.620000 11.200000 3.690000 6.590000 11.160000 3.710000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 19 19 -128 -128 -128 -128 -128 -128 1316 1128 1237 1173 1181 993 0.0 0.0 0.0 0.0 0.0 0.0 0.0 20061120181448

1164064488.86 6.620000 11.200000 3.690000 6.590000 11.160000 3.710000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 19 19 -128 -128 -128 -128 -128 -128 1323 1121 1237 1173 1177 1001 0.0 0.0 0.0 0.0 0.0 0.0 0.0 20061120181448

Usage and examples

Usage

To call the script use:

python [script_name] [options]

You can see the list of options available by running the script with the -h option.

Essential commands

-i ip address [ip address] Multiple ips allowed but not recommended read future developments for more information, use multiple threads to run on different ips.

-c command possible options [get,getall,set] Multiple commands allowed but not recommended.

-s scope possible options [all,find,variable_names] where variable_names varies from crate to crate. You can use the find option to find out the variable names on your particular crate. Multiple scopes will be supported in the future. For now you can either get one scope or everything but you cannot get a combination of for example v8p and ivcc. Not essential if you use the getall command.

-v variables to get/set [voltage,current,temp,fan] Multiple variables allowed.

Optional commands

-t time between iterations [time in seconds] the default value is 1 second. Please see above if you want to change this value. This option accepts float values however I have not found the sleep function which I use to implement waiting between iterations to be very accurate at times less than a second. If you require constant updates you can just comment out the sleep function and it will iterate at maximum speed.

-f time in seconds that you want the crate to run for [time in seconds]

-o output file, default value = snmpoutput.txt You must include an extension for the file or else the script will raise an error

-h produces a help file

-d gives debugging information (verbose mode)

The get calls the snmpget command and the getall calls the snmpwalk command. I would recommend using the get command at all times and specify the scope to all. It is possible to get the same functionality by using the getall command and ommitting the scope.

Examples

The order of the commands is not important. The following will run for 5 seconds, repeat every second, get all the data from all the variables. Thus it will provide information about current, temp, voltage, fan.

python wienercrate.py -i 132.206.126.243 -c get -s all -v all -f 5 -t 1

The following command is equivalent

python wienercrate.py -i 132.206.126.243 -c getall -v all -f 5 -t 1

The following gets only information about the voltage

python wienercrate.py -i 132.206.126.243 -c getall -v voltage -f 5 -t 1

This gets voltage and fan

python wienercrate.py -i 132.206.126.243 -c getall -v voltage fan -f 5 -t 1

This loops forever

python wienercrate.py -i 132.206.126.243 -c get -s all -v all

This provides debugging information

python wienercrate.py -i 132.206.126.243 -c get -s all -v all -f 5 -t 1 -d

This loops forever with a 3 second delay between each call

python wienercrate.py -i 132.206.126.243 -c get -s all -v all -t 3

This shows you the variable names

python wienercrate.py -i 132.206.126.243 -s find

This gets the information about one variable only v8p

python wienercrate.py -i 132.206.126.243 -c get -v all -s v8p

This sends the output to a file called samplefile.txt

python wienercrate.py -i 132.206.126.243 -c get -s all -v all -f 5 -t 1 -o samplefile.txt

This displays the help file

python wienercrate.py -i 132.206.126.243 -h

List of object attributes and methods

['commands', 'community_name', 'compute_power', 'construct_command', 'data_names', 'debug', 'error_check', 'execute_read', 'extract_data', 'find_variable_names', 'get_set', 'list_of_commands', 'loop', 'mib_file', 'names_of_variables', 'output_file', 'power_output_list', 'repeat', 'run_command', 'run_crate', 'sleep_time', 'sort_commands', 'variable', 'version', 'write_data']

Attributes

1.commands is a list with all the sorted arguments.

2.community_name is set at the beginning to 'public' for the reading. In the future for setting it will be set to 'guru'. These are requirements of the net-snmp toolset to access the wiener crate.

3.data_names is returned by find_variable_names as a dictionary of the list of data variables accessable and their corresponding values in MIB format. They can be queried by using the -s find option. e.g. {'v8p' : U0} where U0 is the reference name and v8p is the shortcut to that. The MIB file assigns the name v8p to U0. The names are assignable however that will have to wait for the setting version of the wiener_crate script.

4.debug is a flag to either turn on or off debugging mode

5.get_set is a list of hard-coded commands that correspond to net-snmp commands.

6.list_of_commands is a list of strings that are to be run after the construct_command

7.loop is a flag that defines whether it is a finite or infinite loop

8.mib_file is defined in the initalization as the name of the MIB file

9.names_of_variables are the lower case value of the variable names of the crate. e.g. ivcc, v8p

10.output_file is a string with the name of the output file

11.power_output_list = power calculation list

12.repeat is integer number of repeats

13.sleep_time is an integer with the number of seconds to sleep

14.variable is a dictionary of variables to MIB equivalents

15.version is s tring with the version of net-snmp to use

Methods

These have been discussed above. See the section on description of functions.

sort_commands(self)

error_check(self)

find_variable_names(self)

construct_command(self)

run_command(self)

extract_data(self)

compute_power(self)

write_data(self)

run_crate(self)

Modifications

1. The default output file is specified in the init constructor to be 'snmpoutput.txt' and can be changed to a more suitable name. It may also be changed during run time by using the -o [filenamehere] for that specific call. Note that the file MUST contain an extension. If not an error will notify you that you must include it.

2. In the run_command function the file size is compared to 10MB (written in bytes), if it is larger a new file with the following naming convention will be used oldfilename[number].oldextension. The number will start from 1 and increase depending on whether this is the first 10MB file or the second or the third etc. The value can be changed to whatever is more convenient.

3.The default time between iterations of reading the crate is set to 1 second in the error_check module the variable is sleep_time. The sleep_time variable is in seconds.

4. If you would like to add new commands to be used from the command line you can modify the delimeters list in the sort_commands function. The order in which they are specified is important. Just append your command to the end of the list and reference it through out as self.commands[number_in_the_list]. Do not change the order or the script will no longer function. If you do add a new option please append the help file with information about it. This will hopefully be changed in the future so that it is somewhat automated, using an external library that constructs command line options. The construct_command function has two dictionaries self.get_set and self.variables. These can be modified to add new variables that can be retrieved. Currently the list of variables that can be retrieved by the script are voltage, current, temp, fan. The list of commands you have are get, getall, set. To add new commands just append a new dictionary value with the command as it is written in the command line in lower case and the MIB equivalent that the snmp tools must retrieve. For example (voltage : "OutputMeasurementSenseVoltage"). You must also add a new if statement block to the extract_data function to extract that new set of data. See point five on how to do that. Here is an example of the dictionary used:

self.variable = {'voltage':'outputMeasurementSenseVoltage' + self.data_names[number_of_ips][scope], 'current':'outputMeasurementCurrent' + self.data_names[number_of_ips][scope], 'temp':'sensorTemperature' + self.data_names[number_of_ips][scope], 'fan':'fanSpeed' + self.data_names[number_of_ips][scope]}

5. In the extract_data function you can modify the extracation procedure. The output is split according to a specified string to extract the data. If the wiener crate that you are using formats the data differently, simply change the two strings around which the script has to extract the numeric value. You can see the formatting of the output of the crate by running the crate with the -d option. For example to get the voltage, the script currently splits around 'INTEGER: ' and ' V' to get the voltage. If you have added a new option to be extracted you could copy and paste the previous block and simply change the splitting strings.

6. You might find it useful to display the the file size in megabytes it currently is displayed in kilobytes. For that you can go to the write_date function at divide self.file_size by 1024*1024 instead of just 1024.

7. Finally you may choose to modify the way the time is written in the following way. The strftime() function formats the time and is called in the write_data function. The following is information from the python documentation on how to modify it to format different times. It currently formats the time returned by the localtime() function. This can be substituted with the gmtime function if GMT time is required.

Taken from the python documentation:

strftime( format[, t]) Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a string as specified by the format argument. If t is not provided, the current time as returned by localtime() is used. format must be a string. Value error is raised if any field in t is outside of the allowed range. Changed in version 2.1: Allowed t to be omitted. Changed in version 2.4: value error raised if a field in t is out of range. Changed in version 2.5: 0 is now a legal argument for any position in the time tuple; if it is normally illegal the value is forced to a correct one..

The following directives can be embedded in the format string. They are shown without the optional field width and precision specification, and are replaced by the indicated characters in the strftime() result:

Directive Meaning
%a Locale's abbreviated weekday name.
%A Locale's full weekday name.
%b Locale's abbreviated month name.
%B Locale's full month name.
%c Locale's appropriate date and time representation.
%d Day of the month as a decimal number [01,31].
%H Hour (24-hour clock) as a decimal number [00,23].
%I Hour (12-hour clock) as a decimal number [01,12].
%j Day of the year as a decimal number [001,366].
%m Month as a decimal number [01,12].
%M Minute as a decimal number [00,59].
%p Locale's equivalent of either AM or PM.
%S Second as a decimal number [00,61].
%U Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
%w Weekday as a decimal number [0(Sunday),6].
%W Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.
%x Locale's appropriate date representation.
%X Locale's appropriate time representation.
%y Year without century as a decimal number [00,99].
%Y Year with century as a decimal number.
%Z Time zone name (no characters if no time zone exists).

Future Development

In the future this will be part of a wienercrate object that reads and set for now it only reads information but it can be easily modified to set. Also it has the capability of reading multiple IP's at once but this feature has not be tested and is currently limited in the future it will be fully supported. Options that could be usefully in the future might be a read only option where the scrip gives back the information without writing it, multiple output files for different ips, reading multiple defined variables at one time such as v8p and IVCC, and an option to decide the maximum file size without it being hard coded. They are all quite easy to implement. Also a key to terminate the inifinite loop without using the ctrl-z option in the terminal. Perhaps an improvment would be to use the snmpbulkget request which I did not know of when I started writing the script. It uses a more efficient method to communicate and get bulk requests. However since the script currently runs about 4-5 times per second it does not seem like speed would be an issue for the current purposes. Lastly, the dictionary created by the find_variables command assigns the data names such as v8p, ivcc, etc to their MIB equivalents U0, U1, etc.. For now it assigns them to hard coded MIB equivalents, in the crate I am using they are U0,U1,U3 etc. In the future the script can be modified to find these automatically in case some other crates have a U2 which this crate does not.

Files

I have included below two files. Make sure to change the wienercrate.py.txt file to wienercrate.py before running. The wienercrate python file has a documentation in its header that should be enough for most purposes. It provides usage examples and notes on how to change a number of default behaviours that maybe useful. It also has a lot of comments in case something needs to be changed or fixed.

The second file is a sample output created by the python script.

-- WinterlandUser - 07 Nov 2006

* wienercrate.py.txt: This is the python script make sure to remove the .txt before running

* samplesnmpoutput.txt: This is a sample output file

Topic attachments
I Attachment Action Size Date Who Comment
Texttxt samplesnmpoutput.txt manage 21.5 K 2006-11-20 - 23:23 WinterlandUser This is a sample output file
Texttxt snmpoutput.txt manage 0.5 K 2006-11-20 - 23:22 WinterlandUser Sample output file from the python script
Texttxt wienercrate.py.txt manage 32.4 K 2006-11-22 - 22:06 WinterlandUser This is the python script make sure to remove the .txt before running

This topic: AnalogFMux > Internal/HardwareHowto > 2006-Wiener9UVME_Crate > 2006-SNMP_Notes Topic revision: r5 - 2007-03-01 - MattDobbs
© 2020 Winterland Cosmology Lab, McGill University, Montréal, Québec, Canada