X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=bundles%2Forg.simantics.history%2Fhistory.txt;h=d2a4b783d068e9b8397d73689163441e1a9e76ed;hb=241a1dddfbaa9c46832f443884ca1bbfd1beb2c9;hp=6fa06b097919a21d920e7c6ddec878cefb80ee9a;hpb=969bd23cab98a79ca9101af33334000879fb60c5;p=simantics%2Fplatform.git diff --git a/bundles/org.simantics.history/history.txt b/bundles/org.simantics.history/history.txt index 6fa06b097..d2a4b783d 100644 --- a/bundles/org.simantics.history/history.txt +++ b/bundles/org.simantics.history/history.txt @@ -1,102 +1,102 @@ -This plugin(org.simantics.history) contains a library for history service. - -== Details == - -HistoryManager manages persistent and stateful objects called "Subscription". -Subscription has globally unique id (GUID). - -When a subscription is recorded, it is opened and a handle is received. -To record the user supplies time code and values for each variable. - -A subscription consists of items that describe how a variable is to be recorded -and stored in a file. For each item: interval, deadband, variableId, enabled, -and the sample format are provided. - -Sample format describes the format how the data is stored in the stream file, the -primitive types and fields to record. There is a well-known set of -fields that the recording supports. Unknown fields are left unchanged. -Fields "time", "endTime", and "value" are mandatory. - -Sample = { - // Time - time : Double, // Time of the first sample (mandatory field) - endTime : Double, // Time of the last sample (mandatory field) - - // Values - value : Double, // First value (mandatory field) - lastValue : Double, // Last value - avg : Double, // Avg value of source valus within the band's time range - median : Double, // Median value - min : Double, - max : Double, - - quality : Byte, // 0-Good, -1=Novalue - count : Integer // The number of source values acquired -} - -One variable is typically subscribed with multiple items. For instance, simantics -chart subscribes the chart_raw, chart_1s, chart_10s, chart_60s, and chart_min-max -items. 1s, 10s, and 60s have corresponding interval value (eg. max. 1 entry per 10s of data). -"min-max" is an subscription item that tracks down the minimum and maximum -value of the variable. It has infinitely long interval value and thus records -only one sample (unless there is discontinuation). - -The sample entry is basically a band of values. The entry is packed even if -deadband and interval are disabled. The system packs the unchanged set of values -into a single entry. - -Simple = { - time : Double, - endTime : Double, - value : Double -} - -The system can write down any primitive fields. Even arrays, enums, records -and strings. Time and endTime fields must be numeric, values not. - -Example1 = { - time : Long, - endTime : Long, - value : Double, - avg : Float -} - -VectorSample = { - time : Long, - endTime : Long, - value : Double[ 3 ] -} - - -Discontinuation ---------------- - -The assumption is that two consecutive stream entries describe a data that is sampled -continuously from the source. If there is non-continuation in the source data or -if the recording was disabled temporarily, a discontinuation marker is added. - -To support discontinuation in the data stream, there must be quality-field. - -Example = { - time : Long, - endTime : Long, - value : Double, - quality : Byte // 0 Good, -1 No value -} - - -File History -================= - -File based implementation is the only existing implementation. Files are -managed in workarea (folder). Subscription state and recording metadata is in one -file, and all subscription items each in a separate file. - - Subscription - [SubscriptionId].dbb - SubscriptionItem - [SubscriptionId]-VariableId-[sampling hash hex]-[sampling name].stm - -When a subscription is created, it prepares all related files. If a subscription -is modified, it reflects to files by deleting and creating new. - -An open subscription recording can be closed and opened, the state data is persisted -when the handle is closed. +This plugin(org.simantics.history) contains a library for history service. + +== Details == + +HistoryManager manages persistent and stateful objects called "Subscription". +Subscription has globally unique id (GUID). + +When a subscription is recorded, it is opened and a handle is received. +To record the user supplies time code and values for each variable. + +A subscription consists of items that describe how a variable is to be recorded +and stored in a file. For each item: interval, deadband, variableId, enabled, +and the sample format are provided. + +Sample format describes the format how the data is stored in the stream file, the +primitive types and fields to record. There is a well-known set of +fields that the recording supports. Unknown fields are left unchanged. +Fields "time", "endTime", and "value" are mandatory. + +Sample = { + // Time + time : Double, // Time of the first sample (mandatory field) + endTime : Double, // Time of the last sample (mandatory field) + + // Values + value : Double, // First value (mandatory field) + lastValue : Double, // Last value + avg : Double, // Avg value of source valus within the band's time range + median : Double, // Median value + min : Double, + max : Double, + + quality : Byte, // 0-Good, -1=Novalue + count : Integer // The number of source values acquired +} + +One variable is typically subscribed with multiple items. For instance, simantics +chart subscribes the chart_raw, chart_1s, chart_10s, chart_60s, and chart_min-max +items. 1s, 10s, and 60s have corresponding interval value (eg. max. 1 entry per 10s of data). +"min-max" is an subscription item that tracks down the minimum and maximum +value of the variable. It has infinitely long interval value and thus records +only one sample (unless there is discontinuation). + +The sample entry is basically a band of values. The entry is packed even if +deadband and interval are disabled. The system packs the unchanged set of values +into a single entry. + +Simple = { + time : Double, + endTime : Double, + value : Double +} + +The system can write down any primitive fields. Even arrays, enums, records +and strings. Time and endTime fields must be numeric, values not. + +Example1 = { + time : Long, + endTime : Long, + value : Double, + avg : Float +} + +VectorSample = { + time : Long, + endTime : Long, + value : Double[ 3 ] +} + + +Discontinuation +--------------- + +The assumption is that two consecutive stream entries describe a data that is sampled +continuously from the source. If there is non-continuation in the source data or +if the recording was disabled temporarily, a discontinuation marker is added. + +To support discontinuation in the data stream, there must be quality-field. + +Example = { + time : Long, + endTime : Long, + value : Double, + quality : Byte // 0 Good, -1 No value +} + + +File History +================= + +File based implementation is the only existing implementation. Files are +managed in workarea (folder). Subscription state and recording metadata is in one +file, and all subscription items each in a separate file. + + Subscription - [SubscriptionId].dbb + SubscriptionItem - [SubscriptionId]-VariableId-[sampling hash hex]-[sampling name].stm + +When a subscription is created, it prepares all related files. If a subscription +is modified, it reflects to files by deleting and creating new. + +An open subscription recording can be closed and opened, the state data is persisted +when the handle is closed.