This page is part of archived documentation for openHAB 4.0. Go to the current stable version
# Scale Transformation Service
The Scale Transformation Service is an easy to handle tool that can help you with the discretization of number inputs. It transforms a given input by matching it to specified ranges. The input string must be in numerical format.
The file is expected to exist in the transform configuration directory and its ending has to be .scale.
It should follow the format given in the table below.
Range expressions always contain two parts. The range to scale on, which is located left from the equality sign and the corresponding output string on the right of it. A range consists of two bounds. Both are optional, the range is then open. Both bounds can be inclusive or exclusive.
| Scale Expression | Returns XYZ when the given value is |
|---|---|
[12..23]=XYZ | between (or equal to) 12 and 23 |
]12..23[=XYZ | between 12 and 23 (12 and 23 are excluded in this case.) |
[..23]=XYZ | lower than or equal to 23 |
]12..]=XYZ | greater than 12 |
These expressions are evaluated from top to bottom. The first range that includes the value is selected.
# Special entries
Some special entries can be used in the scale file.
# Catchall Entry
[..]=Catchall
This entry will match all numeric values not met by a previous range. Obviously, this one should be put at the very end of the scale definition file.
# Not A Number
Scale transform is designed to work with numeric or quantity states. When the value presented to scale transform does not match this (most of the time with NULL or UNDEF states) it will not be handled and a warning is raised in the openhab.log . This case can be smoothly avoided with a
NaN=Non Numeric State presented
# Formatting output
At last, Scale transform can take care of formatting an output with this entry :
format=%label% (%value%) !
Where :
%label%will be replaced by transformed value and%value%is the numeric value presen
# Example
The following example shows how to break down numeric UV values into fixed UV index categories.
We have an example UV sensor that sends numeric values from 0 to 100, which we then want to scale into the UV Index (opens new window) range.
Example item:
Number Uv_Sensor_Level "UV Level [SCALE(uvindex.scale):%s]"
Referenced scale file uvindex.scale in the transform folder:
[..3]=1
]3..6]=2
]6..8]=3
]8..10]=4
]10..100]=5
Each value the item receives, will be categorized to one of the five given ranges.
Values lower than or equal to 3 are matched with [..3]=1.
Greater values are catched in ranges with 2 values as criteria.
The only condition here is that the received value has to be lower or equal than 100 in our example, since we haven't defined other cases yet.
If none of the configured conditions matches the given value, the response will be empty.
Please note that all ranges for values above 3 are opened with a ].
So the border values (3, 6, 8 and 10) are always transformed to the lower range, since the ] excludes the given critera.
# Usage as a Profile
The functionality of this TransformationService can be used in a Profile on an ItemChannelLink too.
To do so, it can be configured in the .items file as follows:
String <itemName> { channel="<channelUID>"[profile="transform:SCALE", function="<filename>", sourceFormat="<valueFormat>"]}
The filename (within the transform folder) of the scale file has to be set in the function parameter.
The parameter sourceFormat is optional and can be used to format the input value before the transformation, i.e. %.3f.
If omitted the default is %s, so the input value will be put into the transformation without any format changes.
Please note: This profile is a one-way transformation, i.e. only values from a device towards the item are changed, the other direction is left untouched.