In this page are presented some useful example about how manage histories with axon functions

Summary

There are different ways to handle histories in FIN:

• His Computed: used to indicate that histories are generate with function;

• His Imported: used to indicate that histories have been imported, usually from a csv file;

• His Collected: used to indicate that histories are collect from curVal;

• His Synchronized: used to populate histories from the device that the point originated from. (Example TODO)

There are three differents hisMode:

• “sampled” (default)

• “cov”

• “consumption“

Examples/Exercises

In the examples below, there are some examples about how configure and use the different history types.

It’s suggested to follow each chapter with the suggested order, since some concepts/results are reused from previous chapters.

His Computed: Generate Fake histories

Create the function you want to use to create your fake histories: Computed Histories
Examples (you can upload them using folio update of trio files):

Open

• Create 4 points:

  • {navName:"Computed Power", kind=="Number", /* hisMode:“sampled” not required since it's the default */, ... }

  • {navName:"Computed Occupancy", kind=="Bool", hisMode:"cov", ... }

  • {navName:"Computed Setpoint", kind=="Number", hisMode:"cov", ... }

  • {navName:"Computed Energy", kind=="Number", hisMode:"consumption", hisTotalized, ... }
    
    

“unit” tag is not required since the history is created by hisFunc. Anyway, it should be better to add the proper one to the points.

 

Open

 

 

• For each point enabled history and set to hisType:"computed" Point Property Sheet | HistoryPreview and

  • hisFunc:"powerHisFunc"

  • hisFunc:"occupancyHisFunc"

  • hisFunc:"setpointHisFunc"

  • hisFunc:"energyHisFunc"

Open

 

• Test the results using in Folio

  • read(navName=="Computed Power").hisRead(today())

  • read(navName=="Computed Occupancy").hisRead(lastWeek())

  • read(navName=="Computed Setpoint").hisRead(pastMonth())

  • read(navName=="Computed Energy").hisRead(thisYear(), {-limit})
    
    

If a point has the hisFunc tag (i.e. it is a computed point) the function itself is completely responsible for generating the desired history output. The his read is essentially delegated to the his func.

It means that reading the histories of the Energy Point returns like the “row” his data, so an increasing value and not a “~collected” one.

Open

Example of His configuration on a point

 

His Imported: Write\Read his to\from csv file

It could be useful to write and read points to/from a csv file. Here an example of how to do it. This requires to already have configured points as indicated in Generate Fake histories chapter.

• Write: You can use one of these functions (in Folio) to write your CSV file in the folder ..\{{FIN_FolderName}}\var\proj\{{projName}}\io\{{fileName.csv}}

  • read(navName=="Computed Power").hisRead(thisYear(), {-limit}).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).ioWriteCsv(`io/hisPower.csv`)

  • read(navName=="Computed Occupancy").hisRead(thisYear(), {-limit}).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).ioWriteCsv(`io/hisOccupancy.csv`)

  • read(navName=="Computed Setpoint").hisRead(thisYear(), {-limit}).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).ioWriteCsv(`io/hisSetpoint.csv`)

  • read(navName=="Computed Energy").hisRead(thisYear(), {-limit}).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).ioWriteCsv(`io/hisEnergy.csv`)
    
    

• Create 4 new points

  • {navName:"From Csv Power", unit:"kW", kind=="Number", /* hisMode:“sampled” not required since it's the default */, ... }

  • {navName:"From Csv Occupancy", kind=="Bool", hisMode:"cov", ... }

  • {navName:"From Csv Setpoint", unit:"°C", kind=="Number", hisMode:"cov", ... }

  • {navName:"From Csv Energy", unit:"kWh", kind=="Number", hisMode:"consumption", hisTotalized, ... }

Open

 

 

• For each point enable the history as

• Import the following function that will be used to read csv

  name:writeHisFromCsv func doc: Read the csv file containg histories. The csv must contains 2 columns: "ts": with data stored with format "YYYY-MM-DDThh:mm:ssz", that is the default one you have exporting DateTime values "val": contains the values as Str Inputs: - hisPoint: the point where you want to write histories to - csvUri: the URI of the csv, it should be something like `io/fileName.csv` - parseFunc: is the function used to parse the value stored in csv file as a Str. (parseNumber, parseBool, ..) - format: is the format of the DateTime value in the "ts" column. An example could be:"YYYY-MM-DDThh:mm:ssz" NOTE: THIS IS JUST AN EXAMPLE. J2 DOESN T ENSURE THAT THIS FUNC IT'S USABLE IN A REAL ENVIRONMENT src: (hisPoint, csvUri, parseFunc:parseNumber, format:"YYYY-MM-DDThh:mm:ssz") => do hisPoint= hisPoint.toRec csv:ioReadCsv(csvUri) csv.map(row => do ts:parseDateTime(row->ts, format, hisPoint->tz) val:parseFunc(row->val) return {ts:ts, val:val} end).hisWrite(hisPoint) end

Open

Example of His configuration on a point

Open

Example of hisEnergy.csv

Open

Example of hisOccupancy.csv

• Read: Populate the 4 points his with

  • read(navName=="Imported Power").writeHisFromCsv(`io/hisPower.csv`)

  • read(navName=="Imported Occupancy").writeHisFromCsv(`io/hisOccupancy.csv`, parseBool)

  • read(navName=="Imported Setpoint").writeHisFromCsv(`io/hisSetpoint.csv`)

  • read(navName=="Imported Energy").writeHisFromCsv(`io/hisEnergy.csv`)

• Test the results using in Folio

  • read(navName=="Imported Power").hisRead(today())

  • read(navName=="Imported Occupancy").hisRead(lastWeek())

  • read(navName=="Imported Setpoint").hisRead(pastMonth())

  • read(navName=="Imported Energy").hisRead(thisYear(), {-limit})

His Collected

Usually these kind of points are sensors that you need to historicize.

There are 3 main types of collecting data like these:

• Sampled

• Change Of Value [COV]

• Consumption

Based on these types, a point have different tags

Read Raw his data in span:date..date

Here we are reading history data with hisRead → opts:{raw}

• Span: 2021-10-08

In the hisRead documentation you can find these notes:

- if start is Date, then we use midnight of that day