The Network Monitoring Software, or the NMS in short, depends on its capability to acquire the data from the monitored devices. When we collect the data in our NMS software we can analyze it and process the result in the desired way. It’s same with the Mikrotik Dude.
We already saw how to make one test routine in this post. In that case I used processing part named the Probe. Such probe has whole logic and data exchange inside its definition.
In many other situations we need to collect the data from different devices. The collection process is the same. However, processing the data can be different. That means that we need to have some mechanism that will allow us to collect the data and to process it later in an appropriate way for the different device types.
As you recall, I showed you in previous post a trick to display a toner name and its level under the printer’s label. I inserted something I named the function inside the line of the text.
What is a function?
A function is the acquisition part of the Mikrotik Dude. The function is intended to perform one single task and to collect data. However, we do not know just on return value if everything is correct or not.
That means that we will execute the function to perform some operation. In most cases that will be the data collection over the SNMP protocol. After execution, our function will return a value. Depending on the type of the data that we collected, that can be a number, text or even array of the values.
Building complex functions
The Mikrotik Dude has large amount of the predefined functions, like the logical functions and & or. We also have function for the string manipulation, the SNMP OID processing, formatting the output result in bitrate or byte rate, etc.
Let us assume that we want to read and return some data from some device (like a printer). That device is inside our network and it has a network card. Furthermore, manufacturer built the SNMP support service and we can check the status of that device from our Dude server.
First step is to find information about the SNMP OID structure for that device. That can be found on the Internet or in the materials supplied by manufacturer. Inside all the information that we can obtain from the device, we need to distinguish the information we really need; the toner level.
Second step is to create new function that will collect the data for us. Moreover, we will inside our new function use other function named oid. That function will accept OID number that we want to read and return its value to us. Then we will assign that value (some text or number) with our new function.
From now onward, we will use our new function to perform the data processing. The oid function will be reused in other functions to acquire other values.
Writing our own functions
We will now demonstrate how to write your own functions. In our example, we will see how to write a couple of mutually connected functions that will collect all the data we need. We will write four functions per toner:
- To return the toner name
- To return the toner current level
- To return the toner maximum level
- To calculate the percent of toner that remains in cassette
Sound horrible? Don’t be afraid. Even if this sounds very complicated, it’s not. We need to perform some search and to do our homework before we can write the code.
This example will work on most of the printers. However, some manufacturers are not implementing the OIDs that I will use here. In that case you either can’t check toner level in this way or you need to know manufacturer’s OIDs.
Collecting the toner information
The first function will collect the toner name. I found this very useful, as I can display it either on network map or in the probe. Moreover, when the toner level drops under 10 percent, an alarm will raise and we can see the model name of the toner. Now the helpdesk crew can easily identify proper toner for an alarmed printer.
Most of the printers will use the OID numbers starting with 22.214.171.124.2.1.43 sequence. After that number there will be other number IDs organized in the tree-like structure. We’re now concentrating on the toner information and we will need the following OIDs:
- Toner #1 name – 126.96.36.199.188.8.131.52.184.108.40.206.1
- Toner #1 current level – 220.127.116.11.18.104.22.168.22.214.171.124.1
- Toner #1 maximum level – 126.96.36.199.188.8.131.52.184.108.40.206.1
Then we will write the functions that will collect the information about the toner levels. We can use those functions to later build the function for the toner percentage.
We will go with the details for the first function, the other two are similar and we will just display finished function.
Our function building primer
When we’re in the Dude, we should go to the menu on the left side. There we can find an option named Functions.
We can right-click on it and open it in a separate window. This is a very useful feature and I often use it to open the windows with the probes and the functions. In my case this looks like this:
There are a lot of function and we can’t see them all. As you can see from this screenshot, I have my convention about the names.
All functions are named with the small letter f in the beginning. Then I use a 3 letter abbreviation related to the device or the service. In our case this is related to the printer device and therefore it will be prn.
Then I indicate the “command” that will be executed with this function. As we need to collect data, then we need to execute kind of the get command.
After that I write a short description. I don’t want to use long names for functions and at the same time I want to avoid cryptic names that I can’t recognize at a later date. Or even worse, that no one else on the Earth can understand. The description like Toner1Name is short enough yet informational at the same time.
We can always add longer description in the appropriate field. There we can add text like “This function will read and return the name of the toner #1 inside the printer”. We can also see that text in the column named Description. As you can see from my screenshot, the description can be written in any language supported by OS. I wrote mine mostly in Serbian.
I want to make a remark here. The printer can have 1 or 4 toners, depending on whether it is monochrome (black) or color printer. Most laser printers are monochrome/black printers. However, we can use the color laser or ink-jet printer as well. Then we have 4 toners and therefore we need 4 sets of these functions.
We will now click on the button with the red + on it. This is Add new function option. A new dialog will appear on the screen.
Now we should complete the appropriate fields. We will start with the function name. In our case that will be fPrnGetToner1Name.
I added a description. It’s in Serbian and this means “Read the name of the first toner”. In this context read means find and return the value of the toner name.
We will add the body of the function. The body holds the processing part and this is the heart of our function.
In this example it is very simple. We will call the predefined function oid and pass appropriate OID number as the parameter. We will build the other two functions in the same way.
Here is the function for the current toner level:
And for the maximum toner level:
If you look carefully, you will see that I didn’t use numbers in last two examples. This is because some OID parts have also the human readable names. In this case, the whole part 220.127.116.11.2.1 can be replaced with iso.org.dod.internet.mgmt.mib-2. You can use both ways inside the functions.
And now we have the final function that will return the percentage of the remaining toner. Here is example:
This one function is very old and it’s written first. Later I decided to add other parts as new functions. And here is how this function is related to the other functions.
If we analyze the body of the function, we can see that we have this:
First of all, we used a new function named string_substring. This is also a predefined function. This function is intended to be used to extract a substring from the string.
Further we can see that we can use mathematical operations inside our functions. This means that we can use all four basic operations with numbers. There is no need for cast conversion. The Dude will automatically convert a number value to the string and vice versa.
As I already explained, I wrote this function first then I made the others. Now this function will look like this:
As I mentioned in my previous post, we need to call other functions and to pass parameters to them. When we do not need or cannot use any parameter, we will use just parenthesis after the name. Bear this in mind.
OK, what did we do here? We made a division of the two integer numbers. Then we converted this to a string and extracted the first four digits. That will be 0.xx in most cases. When the toner is full that will be 1.00. As last step, we will change this number and multiply with 100.
For example, our toner has 31 percent of the remaining toner. When we perform the division, the result will be 0.31. Then we will multiply it by 100 and got 31 as result.
So far I found that only Canon doesn’t utilize this method. As you can see from the screenshot we can use this with HP, Canon, Lexmark. I also found that this works with Samsung printers.
In case we have the color printer there are four toners and therefore four sets of these probes. There is also a difference in the position of the colors. In color printer the black toner is 4th.
Where to go further?
This was simple a primer for the Mikrotik Dude functions. In same way you can read any other SNMP value and expand possibilities.
When we’re talking about printers, we can even read the printer status, paper level in cassette and so on. With other devices we can read their operational parameters, like the disk size, name and remaining space. Or we can read the temperature from the internal sensor and raise alarm when it’s over some level.
You can read OID tree for every device with the SNMP Walk tool from the Dude. There is also a standalone suite of SNMP tools that can read all those values for you.
This is a powerful mechanism and we will use it often in further projects. Try to build your own functions and explore those that you already have. You will discover a whole new world.