First, the en.map fine and de.map file are a part of the distro. They just come by default and are there whether you have the map add-on installed or not.
I don’t know of a specific tutorial covering everything you ask for but I can probably help.
A profile lives on the Item channel link. It will intercept updates coming from the channel and modify them before they get to the Item. It will intercept commands from the Item and modify them before they get to the channel. The sorts of things a profile can do includes:
- detect single press, double press, long press of buttons
- convert a sensor reading to on/off with hysteresis (e.g. for controlling an AC)
- send a command to a second channel when an Item updates from a second channel
- take a timestamp when an event or command is received at an Item through a channel
- apply a transformation.
The key is that a profile exists between a channel and an item. If you just have an Item, a profile cannot be used because there is no link.
To apply a profile navigate to the Thing Channel and click on the link. At the bottom you can apply a profile. You can also get to the link from the Item’s page.
Only those profiles which make sense based on the Item type will be shown (e.g. you won’t see the timestamp profile unless the Item type is DateTime).
Selecting one of the profiles will present the options available for that profile, since each has different options.
Most of the profiles you see above are script as each automation add-on is listed separately instead of just one Script transform being shown.
A transformation can be used in a number of places:
- some Things support applying a transformation at the Channel level. These tend to be low level bindings like MQTT, HTTP, Modbus, KNX, etc.
- there is a transform profile that let’s you apply a transformation at the Link, modifying the states or commands as they pass between the items and the things or the things and the items
- at the Item label/state description for display of the Item’s state
- in a rule through the transform action
A transformation takes in a String input and converts it to something else. There are a number of options with Map, JSONPATH, and Script being the must commonly used. Script is probably the most complex one. Any automation add-on can be used to create a script transform (prior to 3.4 only Nashorn JS could be used). The Item state is passed into the transform as a String and a String is expected as the output. What ever the last line of the transform evaluates to is what the transform returns.
Each of the automation add-on docs should have a section showing how to write a transform in that language. For example JavaScript Scripting - Automation | openHAB. For Rules DSL, guys know that the incoming data is a String input and the last line evaluated is the return value.
In the UI, you can create a transformation config, where necessary (e.g. map and script) under Settings → Transformations. The format of what you need to put into the config is documented in the transformation add-on docs.
For a map example:
A JS Scripting transformation example:
Full text:
(function(data, id, threshold) {
// If threshold doesn't have a unit, ONE will be assumed
// For now, unit ONE doesn't print so the number will be returned without units
console.loggerName = 'org.openhab.automation.transformation.filter.'+id;
console.debug('Data: ' + data + ' Threshold: ' + threshold);
const thresh = Quantity(threshold);
const curr = Quantity(data);
const last = cache.private.get(id, () => curr);
const delta = curr.subtract(last);
if(delta.greaterThanOrEqual(threshold) || delta.lessThanOrEqual(thresh.multiply(-1))) {
console.debug('Threshold exceeded, updating item with ' + curr);
cache.private.put(id, curr);
return data;
};
console.debug('Delta too small at ' + delta);
return last;
})(input, id, threshold)
In the UI, you refer to a managed transformation by ID. In some places you can select a transformation through a dialog (e.g. when using a transform profile). when a dialog is not available, you use the transformation ID. The ID is shown on each entry at Settings → Transformations and there is a convenient little icon to copy the ID from there.
I assume you will still have questions so please ask and I’ll do my best to answer.
