Creating an ARDI Event Driver

This tutorial will re-create the ARDI LogFile Event driver as an example of how to create your own ARDI driver in Python.

Many of the steps are very similar to those from our Creating an ARDI Live Driver tutorial - however the functions that we create are a little different.

To begin, we will sketch out the basic structure of our Python script.

First, create a new folder in /opt/ardi/drivers/event with the name of your driver (ie. /opt/ardi/drivers/event/logfile2.

Now create a matching python source file - a plain text file - in that folder, named <foldername>.py - ie /opt/ardi/drivers/event/logfile2/logfile2.py.

Paste in the following content…

basehistdriver.py

from ardi.driver import eventdriverbase
 
class MyDriver:
 
   def __init__(self):
      self.connected = False
 
   def SetAddress(self,addr):
      pass
 
   def Connect(self):
      return True
 
   def Disconnect(self):
      pass
 
  def RunQuery(self, query):
      return query.Finish()
 
class driverfactory:
    def createinstance(self):
        return MyDriver()
 
if __name__ == "__main__":
    sdf = driverfactory()
    base = eventdriverbase.eventdriver()
    base.start(sdf)
 

This is the basic layout of every ARDI Python historical driver.

It's almost identical to that of the live driver, however in this case we don't have the Optimise or Poll functions, replacing them instead with Query.

Your class has access to some important functions and variables.

This function is responsible for outputting an event that is then sent to ARDI.

Data from the dictionary is used to create an Event. Each event needs - as an absolute minimum - a start element (containing the UTC date/time of the event) and a name element (used to identify the event).

They may also include end or duration properties. End is the UTC date/time when the event is complete, and Duration is the number of seconds the event lasts for. Note that if both end and duration are given, the 'end' time is given priority.

Any other properties you include are displayed as metadata for the event. For example, you could include status information, averages or totals for key events. These other elements are not translated (ie. any dates/times given in these properties will not be translated into UTC).

This member is a Python logging object that can be used to record any information of note, through calls like self.core.logger.info and self.core.logger.debug.

There are four key functions required in your driver class.

This function is called after your driver is first created. It includes an encoded address for your data source from ARDI.

You'll need to split it into its component parts and store them for when its time to connect.

The connect function is called whenever your driver is to connect to a data source.

It returns True if connection was successful and False if connection fails.

This does the opposite of connect - it closes the connection to your data source and does any cleanup required.

The Query function is used to actually perform a query on the event source.

It includes a single python object that contains all of the information you need to run your query.

The address for our text file driver will include the following options…

The address lists these options, separated by a colon (:) character. IE. /tmp/data.txt:,:1:2:%Y-%m-%d %H:%M:%S.

It's up to this function to…

• Split the address string into its component parts
• Record this information for use in the connect and query functions

        bits = addr.split(':')
        self.filename = bits[0]
        self.delimiter = bits[1]
        if self.delimiter == "\\t":
            self.delimiter = "\t"
        self.namecol = bits[2]
        self.startcol = bits[3]
        self.dateformat = bits[4]

It's up to our connect function to…

• Check that the file exists

Because we want to allow applications to change the file between polling it, we won't actually open the file at this point - we will open the file each time we poll it.

   if os.path.isfile(self.file):
      return True
 
   self.core.logger.warn("File not found - Data source could not be opened")
   return False

This is where the magic happens. This function is responsible for reading the data source and returning time-stamped values for the points that have been requested.

         #Begin the Query
 
	self.core.logger.info("Query Started: Between " + query.start + " and " + query.end)									
 
	#Open and process the file...
	with open(self.filename,'r') as f:
		for line in f:
			#Split each line by the delimiter...
			bits = line.split(self.delimiter)
 
			#Is this date in the range?
			startdate = bits[self.startcol]                        
			TT = datetime.datetime.strptime( startdate, self.dateformat )
			if TT < query.start:
				lastvalue[bits[self.namecol]] = str(bits[self.valuecol]).strip()
				continue
 
			if TT > query.end:
				#This is AFTER the date range - break out of the loop.
				break
 
			#Add this value to the data to be transmitted.
                        data = {}
 
                        #Name and Start are required...
                        data['name'] = bits[self.namecol]
                        data['start'] = bits[self.startcol]
 
                        #We can throw in some additional stuff here, if we want
                        data['origin'] = bits[0]
 
                        #Write this out
                        query.AddLineFromDictionary(data)
 
	#That's it - lets output our results.
	return query.Finish()

The last step is to create a web interface for our driver, so that we can set the drivers various options (file name, delimiter, column numbers etc.) in a friendly manner.

This will require some basic HTML & PHP.

Firstly, copy one of the existing drivers user interfaces by copying /opt/ardi/web/data/event/logfile to /opt/ardi/web/data/event/logfile2 (the folder name must match the name of the driver folder & file).

There are several PHP files in this folder. Click on them for examples and documentation on what they do.