Subject: [core] Binding attributes in draft-ietf-core-interfaces

From: Christian Groves <[email-masked]>
Date: Thu, 4 Feb 2016 17:48:32 +1100

Hello,

I'm reading clause 5.1/draft-ietf-core-interfaces on boundto attributes. 
It specifies the interaction between pmin/pmax attributes and the 
"change step", "Greater than" and "less than" attributes. The draft 
doesn't limit which attributes may appear so I take it its possible to 
specify all of them in a single binding. Is this correct?

If it is it leads to the issue of the interaction between the "change 
step" and "greater than" and "less than" attributes. I didn't see this 
described anywhere?

E.g. for a temperature reading if st=5, lt=10, gt=26 is set and the 
initial ambient temperature was 20 when set.
The temperature rises to 30.
I could assume there's a notification at 25 related to st=5
Then there's a notification at 26 related to gt=26
However is there a notification at 30?

The text for change step indicates "how much the value of a resource 
SHOULD change before sending a new notification (compared to the value 
of the last notification)". The last notification in this case is 26 
which would make the change step 31.

A possible alternate interpretation is that notifications only occur 
when the change step is below 10 or over 26. Alternatively a new change 
step notification above would seem superfluous if there's always a 
notification whenever the temperature changes above 26.

What was the intention with the attributes?

Regards, Christian G

---

From: Michael Koster <[email-masked]>
Date: Thu, 4 Feb 2016 05:58:16 -0800

Hi Christian,

Thanks for the question. I think we may need to clarify this some more in the text or with a figure. 

The notification is controlled by a state machine driven by new sample values.

I think the part we need to clarify is: 
*Whether a notification is generated depends on the state reported in the moss recent previous notification, as well as the current sample value, and the notification attribute values.

So saynig "the temperature rises to 30" we need to indicate the sequence of values which were sampled between 20 and 30, and follow the 
state machine.

You gave sample values of 20, 25, 26, and 30. Let's assume that these values are sampled in sequence. 

Assume that the initial value of 20 was the last reported value, and set the state of the state machine.

The next sample is 25, which causes a notification (report) to be generated due to the st=5 attribute. The new most recent value is now 25.

The next sample is 26, which generates a notification due to the gt=26 attribute, The new most recent value is now 26.

The next sample is 30, which does not generate a notification since the last reported value was 26 and no new reporting condition is met.

Does this make sense? If so, I will add this to the issue list for the next draft update.

Also, I see that we are not clearly defining what happens when a sampled value is exactly equal to a threshold value. In the analysis above, we assume that a threshold value is a reporting condition, but we will need to clearly specify "greater" vs. "greater or equal" instead of "crossing" as in the text.

Best regards,

Michael

PS there is some reference implementation code for OMA LWM2M which follows the definition in the CoRE Interfaces draft:

https://github.com/connectIOT/lwm2m-objects/blob/master/LWM2M_resource.cpp <https://github.com/connectIOT/lwm2m-objects/blob/master/LWM2M_resource.cpp>
https://github.com/connectIOT/lwm2m-objects/blob/master/LWM2M_resource_attributes.cpp <https://github.com/connectIOT/lwm2m-objects/blob/master/LWM2M_resource_attributes.cpp>

> On Feb 3, 2016, at 10:48 PM, Christian Groves <[email-masked]> wrote:
> 
> Hello,
> 
> I'm reading clause 5.1/draft-ietf-core-interfaces on boundto attributes. It specifies the interaction between pmin/pmax attributes and the "change step", "Greater than" and "less than" attributes. The draft doesn't limit which attributes may appear so I take it its possible to specify all of them in a single binding. Is this correct?
> 
> If it is it leads to the issue of the interaction between the "change step" and "greater than" and "less than" attributes. I didn't see this described anywhere?
> 
> E.g. for a temperature reading if st=5, lt=10, gt=26 is set and the initial ambient temperature was 20 when set.
> The text for change step indicates "how much the value of a resource SHOULD change before sending a new notification (compared to the value of the last notification)". The last notification in this case is 26 which would make the change step 31.
> 
> A possible alternate interpretation is that notifications only occur when the change step is below 10 or over 26. Alternatively a new change step notification above would seem superfluous if there's always a notification whenever the temperature changes above 26.
> 
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core

---

From: Michael Koster <[email-masked]>
Date: Thu, 4 Feb 2016 08:05:19 -0800

The code I pointed to makes an arbitrary distinction placing a sample value greater than the threshold setting in the band above the threshold, and a sample value less than or equal to the threshold setting (lt or gt) within the "band" below the threshold, and a places . It does this in order to generalize to an arbitrary number of threshold values. To more precisely implement the implied semantics of "gt" and "lt" the comparison should be done on 2 threshold values and compared for s < limits[0] and s > limits[1], where s is the sample value, limits[0] is "lt" and limits[1] is "gt".

If no one objects, I will create an issue to update the draft text to clarify that (s > gt) is the upper band and (s < lt) is the lower band, and provide reference implementation code to that effect.

/* 
Determine which band [0..num_limits] the provided sample is in
Works with any number of bands 2 to MAX_LIMITS+1 using an array of limit settings
*/
int band(sample s)
{
    if (s > limits[num_limits-1]){
        return num_limits;
    }
    else{
        for ( int limit = 0; limit < num_limits; limit++ ){
            if (s <= limits[limit]){
                return limit;
            }
        }
    }
    return -1;
}

> On Feb 4, 2016, at 5:58 AM, Michael Koster <[email-masked]> wrote:
> 
> Hi Christian,
> 
>> On Feb 3, 2016, at 10:48 PM, Christian Groves <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> Hello,
>> 
>> [email-masked] <mailto:[email-masked]>

---

From: Christian Groves <[email-masked]>
Date: Fri, 5 Feb 2016 13:09:00 +1100

Hello Michael,

Thanks for the response and the references. I agree I think its worth 
clarifying the text about this. Please see my responses below marked [CNG].

I think there's several more issues that are worth clarifying:

1. Whether multiple instances of the attributes are allowed. E.g. is 
setting st=5,st=4 allowed?  If so what would it mean?

2. For pmin it indicates wait time "even if it has changed" and for pmax 
it indicates wait time "regardless if it has changed".
My assumption is that pmax is basically being used as a keepalive and is 
used to generate a notification with a state synchronisation value 
whether a value has changed or not. Is that correct? Its also not clear 
whether the value is the current value or the last reported value. e.g. 
if have st=5 and the last reported value is 25. Should the notification 
due to pmax be the current value say 26, or the last reported step value?

For pmin I assume this is used to limit the number of notifications sent 
and only comes into play when something "has changed".

I wonder how this works in an alarm type scenario, where I want to know 
immediately when a threshold as been reached, but I don't need a 
keepalive very often and I don't want to be bombarded by notifications 
once the threshold is reached. e.g. pmin=x ,pmax=300, gt=90

If I receive a notification due to pmax the current text says that the 
system must wait X seconds (i.e. /This parameter has lower priority than 
the period parameters, thus even if the Greater Than limit has been 
crossed, the time since the last notification SHOULD be between pmin and 
pmax/) due to pmin=x before triggering the notification. If the 
threshold is reached immediately after sending the pmax notification 
then it means that for X seconds some undesirable action may be 
occurring before I receive notification. I could set X to be a small 
value to minimise the delay but this has the effect of generating more 
messages.

So I wonder if it would be possible to update the text in such a way 
that st,gt,lt are notified immediately when a value changes to meet the 
criteria but subsequent notifications related to the criteria are 
subject to pmin?

3. For the step value would it be possible to include a seed/start 
value? e.g. rather than being notified of initial value + step e.g.st=5 
initial value=21.34, leading to notification of 26.34, 31.54 but instead 
be notified based on seed value e.g. st=5, seed=20, leading to a report 
of 25, 30. I don't know if such a thing was considered before?

Regards, Christian

On 5/02/2016 3:05 AM, Michael Koster wrote:
> The code I pointed to makes an arbitrary distinction placing a sample 
> value greater than the threshold setting in the band above the 
> threshold, and a sample value less than or equal to the threshold 
> setting (lt or gt) within the "band" below the threshold, and a places 
> . It does this in order to generalize to an arbitrary number of 
> threshold values. To more precisely implement the implied semantics of 
> "gt" and "lt" the comparison should be done on 2 threshold values and 
> compared for s < limits[0] and s > limits[1], where s is the sample 
> value, limits[0] is "lt" and limits[1] is "gt".
>
> If no one objects, I will create an issue to update the draft text to 
> clarify that (s > gt) is the upper band and (s < lt) is the lower 
> band, and provide reference implementation code to that effect.
>
> /*
>> On Feb 4, 2016, at 5:58 AM, Michael Koster 
>> <[email-masked] <mailto:[email-masked]>> wrote:
>>
>> Hi Christian,
>>
>> *Whether a notification is generated depends on the state reported in 
>> the moss recent previous notification, as well as the current sample 
>> value, and the notification attribute values.
>>
>> So saynig "the temperature rises to 30" we need to indicate the 
>> sequence of values which were sampled between 20 and 30, and follow the
>> state machine.
>>
>> The next sample is 25, which causes a notification (report) to be 
>> generated due to the st=5 attribute. The new most recent value is now 25.
>>
>> The next sample is 26, which generates a notification due to the 
>> gt=26 attribute, The new most recent value is now 26.
>>
>> The next sample is 30, which does not generate a notification since 
>> the last reported value was 26 and no new reporting condition is met.
[CNG] Wouldn't 30 be notified because it meets the gt=26 attribute criteria?

     I assumed that gt didn't result in a single notification but 
notification of all value changes over 26. I think it has to be clear 
whether the attributes are ORed or ANDed together to produce a notification.

>> Also, I see that we are not clearly defining what happens when a 
>> sampled value is exactly equal to a threshold value. In the analysis 
>> above, we assume that a threshold value is a reporting condition, but 
>> we will need to clearly specify "greater" vs. "greater or equal" 
>> instead of "crossing" as in the text.
[CNG] I agree this needs to be clarified, I was going to bring this up. 
 From a user perspective wouldn't it be easier to say "greater than or 
equal to"? e.g. I want to set an alarm to trigger at 26. To me it's more 
logical to set it at 26 than to think I have to set it at 25.99 to 
report when 26 is hit.

>>
>> Best regards,
>>
>> Michael
>>
>> PS there is some reference implementation code for OMA LWM2M which 
>> follows the definition in the CoRE Interfaces draft:
>>
>> https://github.com/connectIOT/lwm2m-objects/blob/master/LWM2M_resource.cpp
>> https://github.com/connectIOT/lwm2m-objects/blob/master/LWM2M_resource_attributes.cpp
>>
>>
>>> On Feb 3, 2016, at 10:48 PM, Christian Groves 
>>> <[email-masked] 
>>> <mailto:[email-masked]>> wrote:
>>>
>>> Hello,
>>>
>>> I'm reading clause 5.1/draft-ietf-core-interfaces on boundto 
>>> attributes. It specifies the interaction between pmin/pmax 
>>> attributes and the "change step", "Greater than" and "less than" 
>>> attributes. The draft doesn't limit which attributes may appear so I 
>>> take it its possible to specify all of them in a single binding. Is 
>>> this correct?
>>>
>>> If it is it leads to the issue of the interaction between the 
>>> "change step" and "greater than" and "less than" attributes. I 
>>> didn't see this described anywhere?
>>>
>>> SHOULD change before sending a new notification (compared to the 
>>> value of the last notification)". The last notification in this case 
>>> is 26 which would make the change step 31.
>>>
>>> when the change step is below 10 or over 26. Alternatively a new 
>>> change step notification above would seem superfluous if there's 
>>> always a notification whenever the temperature changes above 26.
>>>

---

From: Michael Koster <[email-masked]>
Date: Sat, 13 Feb 2016 18:57:34 -0800

Hi Christian,

Thanks for the detailed review; my comments are in line.

Best regards,

Michael

> On Feb 4, 2016, at 6:09 PM, Christian Groves <[email-masked]> wrote:
> 
> Hello Michael,
> 
> Thanks for the response and the references. I agree I think its worth clarifying the text about this. Please see my responses below marked [CNG].
> 
> 1. Whether multiple instances of the attributes are allowed. E.g. is setting st=5,st=4 allowed?  If so what would it mean?

Multiple instances don't seem to be meaningful. Only one instance of each attribute are allowed. I will add an issue for this in the github.

I think it may be useful to add more limit values than gt, lt, for example lt, gt, lt2, gt2 for some cases.

> 
> 2. For pmin it indicates wait time "even if it has changed" and for pmax it indicates wait time "regardless if it has changed".
> My assumption is that pmax is basically being used as a keepalive and is used to generate a notification with a state synchronisation value whether a value has changed or not. Is that correct? Its also not clear whether the value is the current value or the last reported value. e.g. if have st=5 and the last reported value is 25. Should the notification due to pmax be the current value say 26, or the last reported step value?

Pmax is intended to eventually synchronize the state of the resource, so it needs to be the current value, or more precisely the most recent sample.
> 
> For pmin I assume this is used to limit the number of notifications sent and only comes into play when something "has changed".

Pmin is intended to limit the number of messages sent. In the usual case, it would be set to a value that is compatible with the expected response time of the system.
> 
> I wonder how this works in an alarm type scenario, where I want to know immediately when a threshold as been reached, but I don't need a keepalive very often and I don't want to be bombarded by notifications once the threshold is reached. e.g. pmin=x ,pmax=300, gt=90
> 

> If I receive a notification due to pmax the current text says that the system must wait X seconds (i.e. /This parameter has lower priority than the period parameters, thus even if the Greater Than limit has been crossed, the time since the last notification SHOULD be between pmin and pmax/) due to pmin=x before triggering the notification. If the threshold is reached immediately after sending the pmax notification then it means that for X seconds some undesirable action may be occurring before I receive notification. I could set X to be a small value to minimise the delay but this has the effect of generating more messages.

Pmin may not be the best way to specifically deal with a noisy sensor. The intention of pmin is to limit messages that would arrive at a rate faster than the rest of the system can process them. In this case, I would expect the pmin delay to be acceptable in handling the alarm. 
> 
> So I wonder if it would be possible to update the text in such a way that st,gt,lt are notified immediately when a value changes to meet the criteria but subsequent notifications related to the criteria are subject to pmin?

If pmin is set to a value that is within the expected response time of the system, it shouldn't matter if there was a notification just before an interesting state change occurs. This is the expected use of pmin.

Are you suggesting a second pmin type attribute for state changes where the observed value crosses particular limits in a particular direction? If there is a use case, we could add a critical minimum time, like cmin, that can be optionally added to induce this behavior. One could set cmin=0 in addition to pmin to enable "immediate" reporting of particular state changes.

Another approach is to add a new optional type of limit for critical reporting, like clt, cgt attributes that have priority over pmin, I suppose only when the value crosses in the outward direction.

> 3. For the step value would it be possible to include a seed/start value? e.g. rather than being notified of initial value + step e.g.st=5 initial value=21.34, leading to notification of 26.34, 31.54 but instead be notified based on seed value e.g. st=5, seed=20, leading to a report of 25, 30. I don't know if such a thing was considered before?

If the attributes are being used to control observe, the first GET will return a value and set the initial conditions for step. In the case of a push binding, we should probably specify an initial message since the client will need to be initialiazed anyway. I'll add another issue for this.
>>> On Feb 4, 2016, at 5:58 AM, Michael Koster <[email-masked] <mailto:[email-masked]> <mailto:[email-masked] <mailto:[email-masked]>>> wrote:
>>> 
>>> Hi Christian,
>>> 
>    I assumed that gt didn't result in a single notification but notification of all value changes over 26. I think it has to be clear whether the attributes are ORed or ANDed together to produce a notification.
> 
>>> 
> [CNG] I agree this needs to be clarified, I was going to bring this up. From a user perspective wouldn't it be easier to say "greater than or equal to"? e.g. I want to set an alarm to trigger at 26. To me it's more logical to set it at 26 than to think I have to set it at 25.99 to report when 26 is hit.
> 
>>> 
>>> Best regards,
>>> 
>>> Michael
>>> 
>>>> On Feb 3, 2016, at 10:48 PM, Christian Groves <[email-masked] <mailto:[email-masked]> <mailto:[email-masked] <mailto:[email-masked]>>> wrote:
>>>> 
>>>> Hello,
>>>> 
>>>> [email-masked] <mailto:[email-masked]> <mailto:[email-masked] <mailto:[email-masked]>>
>>>> https://www.ietf.org/mailman/listinfo/core <https://www.ietf.org/mailman/listinfo/core>

---

From: Michael Koster <[email-masked]>
Date: Sat, 13 Feb 2016 19:19:46 -0800

The intention is to produce one notification when a limit value, gt or lt, is crossed, not to continuously send notifications (at the sample rate? at pmin? ) when a value is in a particular state.  Pmax is intended to send repeat notifications for eventual consistency. Maybe there should also be a cmax to set a notification repeat intereval when the state is in a "critical" band.

Also your text below is "all value changes" ; what do you mean by all changes? do you mean all samples, or do you mean an additional change in value after a limit has been crossed? 

Perhaps it would be good if you would explain your use case in more detail with some concrete examples of when values change and when you do and do not expect notifications. If we want to add special alarm functionality, I think we may want to define some special attributes for that case, like amin, amax, agt, alt.

Best regards,

Michael

> On Feb 13, 2016, at 6:57 PM, Michael Koster <[email-masked]> wrote:
>

---

From: Christian Groves <[email-masked]>
Date: Mon, 15 Feb 2016 15:14:34 +1100

Hello Michael,

As part of a use case I've proposed an updates to the binding attributes 
which I think will handle both simple and complex cases with the same 
synyax.

Regards, Christian

On 14/02/2016 2:19 PM, Michael Koster wrote:
> The intention is to produce one notification when a limit value, gt or 
> lt, is crossed, not to continuously send notifications (at the sample 
> rate? at pmin? ) when a value is in a particular state.
[CNG] OK this wasn't clear. I was taking crossed to to mean 
notifications occurred once the value was crossed. So cs leads to 
multiple notifications but gt and lt only result in one notification?
>  Pmax is intended to send repeat notifications for eventual 
> consistency. Maybe there should also be a cmax to set a notification 
> repeat intereval when the state is in a "critical" band.
[CNG] This could be useful.
>
> Also your text below is "all value changes" ; what do you mean by all 
> changes? do you mean all samples, or do you mean an additional change 
> in value after a limit has been crossed?
[CNG] I meant all samples that met the attribute/s criteria.
e.g. pmin=x, pmax=y, gt=26 I would get a notification when 26 is 
crossed. Then if the sample was 26 at pmax the next notification would 
be 26. If the sample changed to 27 at the expiry of pmin the 
notification would include 27 and so on.
The addition of cs=5 would modify the behaviour.

>
> Perhaps it would be good if you would explain your use case in more 
> detail with some concrete examples of when values change and when you 
> do and do not expect notifications. If we want to add special alarm 
> functionality, I think we may want to define some special attributes 
> for that case, like amin, amax, agt, alt.
[CNG] I don't think special "alarm" functionality is needed. I think it 
just needs to be possible for a user to set the bindings and know what 
notifications will be expected.

Probably the simplest approach is to have a single attribute that 
indicates when a value is met or crossed (in either direction). This 
would allow the user to be explicit when it wants a notification. The 
downside is that multiple bindings would be needed, leading possibly to 
a large table.

An alternate approach could be to separate the value range specification 
from the notification rate specification. A strawman:

A binding would consist of a band, notification and timing attributes:

Band - Sets a value region that triggers a notification. When a sample 
is equal to or within this region notification is governed by the 
NotificationRate parameter. Band consists of two parameters: start and 
end (which are included in the notification range). Either start or end 
could be omitted essentially meaning through to the end or start of the 
number range, e.g. (,20) would mean 0 through to 20. (20,) would mean 20 
and over. If both start and end are omitted then the notifications are 
unbounded and the initial sample value is taken as the start value.

NotificationRate - Would consist of one of the following:
once - This would indicate that a notification is set only once on 
entering the band.
cs:value - This would indicate that a notification is set on entering 
the band and then when the sample changes value according to band:start 
+ (N * cs:value). If value is omitted then the samples are notified 
whenever sampling indicates a change (subject to pmin timing).

Timing - Two parameters:
Pmin: Minimum time between notifications. A notification is generated 
only if the sample value has changed and meets a particular binding 
criteria (band/notificationRate).

Pmax: Maximum time between notifications. A notification is generated 
irrespective whether the sample value has changed or not.

If multiple bindings relate to the same value band then the pmin and 
pmax values used for notifications related to those values should be the 
smallest values.

Band, NotificationRate, Pmin and Pmax are at most once per binding.

Use case
--------
Monitoring temperature in some plant process. Temp degC.

The following 3 bindings are made between two resources:
a) Notify once when process reaches 20c:
band(20,),notificationRate(once), pmin=60, pmax=300
b) Notify every 1c change in the range 40c to 49c:
band(40,49),notificationRate(cs:1), pmin=60, pmax=240
c) Notify immediately when meeting or exceeding 50c according to sample 
rate:
band (50,),notificationRate(cs),pmin=1, pmax=180.

A notification is received once the process meets/exceeds 20c. Whilst 
the temperature exceeds 20c notifications are sent according to pmin=60 
and pmax=x.
The temperature stays between 20 and 39 for some time with notifications 
being generated by pmax=x.
The temperature then jumps to 41 and a notification is generated. The 
notification is delayed for 30s because of the pmin=60 threshold. The 
temperature continues to rise and after another pmin its 45c so a 
notification is generated. The temperature then stablises at 45. A 
notification of 45c is then generated at pmax=240. 10 seconds later the 
temperature jumps to 60. A notification is immediately generated as pmin 
for that band is pmin=1. Then temperature again jumps to 70 and a 
notification is immediately generated subject to pmin=1.

The simplest use case would be:
band(,),notificationRate(once), pmin=x, pmax=y
Which indicates a notification with the current sample ise generated on 
setting the binding and then a notification will be generated according 
to pmax.

Thoughts?

>
> Best regards,
>
> Michael
>
>> On Feb 13, 2016, at 6:57 PM, Michael Koster 
>>>>> The next sample is 30, which does not generate a notification 
>>>>> since the last reported value was 26 and no new reporting 
>>>>> condition is met.
>>> notification of all value changes over 26. I think it has to be 
>>> clear whether the attributes are ORed or ANDed together to produce a 
>>> notification.
>>>
>>
>