----------------------- Calc-Electric Interfacing (Jan 2010) ----------------------- --------------------------------------------------------- ----- Introduction ----- --------------------------------------------------------- Calc-Electric has two types of interface files which are designed to allow you to interface Calc-Electric with any other application which can read text files. If you wish to enable either or both of these interface files you need to check the boxes in the Advanced Settings form within Calc-Electric (only in the licensed version) In brief the interface files are: i) the live interface file - this is a small file which is written every minute and simply contains the instantaneous values you would see on the Data Logging Form in the Calc-Electric program screen. The idea of this file, is that you can have a page on the web which shows live instantaneous readings from Calc-Electric. ii) the data history file - this file contains all logged data since you started Calc-Electric (or deleted a previous version of this file You can view a web page showing Calc-Electric readings from a test home using these interface files at http://www.21c-living.com/livecalcelectric/livedisplay.asp --------------------------------------------------------- ----- Detailed descriptions of the interface files ------ --------------------------------------------------------- i) The live data file The live data file is written to the directory that Calc-Electric applicaton and all of its configuration files are installed to. Usually this will be c:\Program Files\Calc_Electric\ Each minute the program first creates a control file in this directory called LIVEDATA.CTL If it creates this successfully it then writes the livedata file, called LIVEDATA.DTA Only when this has been done successfully is the LIVEDATA.CTL file removed. The purpose of this procedure is that any system that you write to use the livedata file, should look for the LIVEDATA.CTL file first. If your application sees it it should pause. Only when it notices that the LIVEDATA.CTL file has gone, should you access the the LIVEDATA.DTA file. By this method any application you write can avoid clashing with the Calc-Electric program over the LIVEDATA.DTA file. As long as the control file is absent your application may read, copy or even delete the livedata file. This file will be recreated or over written by calc-electric every minute. Content of the Livedata file The livedata file is a text file consisting of 2 lines. The first line is a list of field names, the second line single line of data separated into fields. The fields are separated by a delimiter, usually a comma and the line of data is usually terminated by a carriage return/linefeed combination. (if you wish Calc-Electric to use a different delimter and/or line terminator you can define these by carefully editing the ADVANCEDSETTINGS.CFG file which is in the same directory). A fragment of the advanced settings file is shown below: [Advanced Settings] [Output File] END_OF_LINE_CHARACTERS=13,10 FIELD_DELIMITER=44 A sample live data file is shown below: DateTime,Year,Month,Day,Hour,Min,Sec,TotalEnergy,TotalCost,LoggingSeconds,LoggingTotalPulse,Power5minAvg,Cost5minAvg,Power1hrAvg,Cost1hrAvg,InstantPower,InstantCost,REVSperEnergyUnit,CostPerEnergyUnit,TarrifNumber,LightLevel 06/01/2010 19:29:45,2010,1,6,19,29,45,3.91,45.8643,15600,1173,1.48,17.3604,1.2167,14.2715,2.1696,25.4493,300,11.73,1,3501 The fields are self explanatory, except perhasp for the final field (light level). Contains the instatneous light level detected when the file was written. It's not much use in this case, its potentional use will be explained in the description of the other interface file. For an example of a vbscript application which uses this livedata file to update a web page with the live readings, please have a look at the file called ce_liveupload_sample.vbs which you can find on this site. ii) the data history file This file is designed to allow you to extract the full history of calc-electric as it accumulates. It has the same format as the export file which you can generate from within calc-electric. This file is a difference file. All the readings that are logged to calc -electric are written to this file. Your application will from time to time access this file to get this data. Usually you should write your application to delete this file after extracting the data. Calc-Electric will then create a new one with the data that has accumulated since the deletion, this is which this file is referred to as a difference file. The recommended procedrure for an external application to use this file is described below. A) your application should check to see that Calc-Electric is not writing to this file. This is indicated by the presence of a control file called livedata.ctl b) if there is no livedata.ctl file present then you can access the data file (livedata.dta). The best way of doing this is for your application to quickly rename the livedata.dta file to something else. In the sample vbscript application (ce_liveupload_sample.vbs) we rename the file to newlivedata.dta Once your application has done this, Calc-electric has no knowledge of the renamed file and you can access it as you wish. Calc-electric will create a new livedata.dta file the next time it logs data and this file will contain the data logged since your application renamed the file. Please refer to our sample application, cd_import_sample.vbs to see this in action (this application access the livedata.dta file an adds the data to an access database which other applications can access). The format of the livedata.dta file is the same as the export file format (described in the help file) except it doesn't have the user comment field. You will notice there is a field called LightLevel at the end of the line. You won't usually need this field. It is included there so that if Calc-Electric went out of tune and, for example, started recording each disk revolution as several events, you could use the raw light level readings to try to make sense of the logged data. This won't be easy, but if you've got a large amount of data gathered over a long period of time, you may wish to try to salvage it.