Mac Home Automation

XTension Units support an “Advanced Label Syntax” that lets you include several points of information or data into the value field of a single unit. You can enter the Advanced Label text into the ON and Off Label fields of the Edit Unit Window - Display Tab.

Since the defaults of “On” and “Off” don’t make sense for everything these fields let you customize the unit value display. In the case of door sensor it might be as simple as “Open” and “Closed.”

The fields support an “Advanced Syntax” that lets you include many other data elements or labels without any scripting necessary at all. Any string that you place within these fields will be displayed in any Value field in the program or the web or other interfaces.

Any text not inside of <>’s will be passed through without changes.

Tags are not case sensitive. All tags support an optional parameter of unit=“some other unit name” and if included the value will be taken from that unit and not the unit that contains the label you are editing. Without this parameter the value is taken from the unit you’re editing.

The current numerical value with the Format String applied and the Unit Of Measure suffix added at the end.

• unit=“name of other unit”
• if included then the value will be taken from that unit.
• <value unit=“some other unit name”>
• type=“space|hex|degrees“
  • type=“space”
  • formats the value of the unit as if it were tb/gb/mb/kb or bytes.
  • <value unit=“some unit” type=“space”> displays “1.4tb” or “7.6gb” or “300b“
  • type=“hex”
  • displays the value of the unit as hex
  • <value unit=“some unit” type=“hex”> displays 05FF 0F2355B4 etc
  • type=“degrees“
  • translates degrees into compass directions.
  • <value unit=“some unit” type=“degrees”> displays N, NE, SSW etc

The raw, unprocessed value of the unit before the application of the format string or any other processing.

• unit=“name of other unit”
• if included then the unformatted value will be taken from that unit.
• <RawValue unit=“some other unit name”>

Replaced with the description of the unit

• unit=“name of other unit“
• if included the description inserted will be from the other unit.
• <description unit=“some other unit name”>

If no other parameters are returned then it is replaced with “On” or “Off” Many optional parameters can make this tag significantly useful.

• unit=“name of other unit”
• if included then the state description will be taken from the other unit.

• values=“open:closed“
• if the unit is not dimmable then 2 values may be passed separated by a colon. If the unit is off the first will be returned, if the unit is on then the second will be returned.
• <state values=“open:closed”>

• If the unit is dimmable then you can include multiple values that will be returned based on the value.
• A value of 0 returns the first entry, 1 the second and so forth.
• This is useful for translating a Thermostat state unit into readable text. Most thermostats will return 0 for idle, 1 for heat and 2 for AC. Some will also return 3 for Em Heat or 4 for second stage AC. To display that more useful text rather than a number you’d create a list like this:
• <state values=“Idle:Heat:AC:EM Heat:Stage 2”>

• ranges=“-100..35:36..46:47:48..200”
• ranges effect the choice from the values list by matching on the ranges (or individual numbers) passed within.
• A range of numbers is written 3..5 to match the number 3 to the number 5
• a single number may be included as well without the “..” indicating a range.
• <state values=“too cold:Temp OK:Perfect:too hot” ranges=“-100..35:36..46:47:48..200”>
• the above would display the text “Temp OK” if the value was between 36 and 46, “Perfect” if the value was 47 and one of the error messages if it was between the other ranges.
• If you include the ranges parameter it must have the same number of entries as the values parameter.

This includes the fully processed ON or OFF label from another unit. In this case the usually optional unit=“some other unit” parameter is not optional. You cannot embed the label from the current unit into it’s own label.

• unit=“some other unit”

• <label unit=“some other unit”>

The timestamp of the unit, at least some formatting data must be included to say how you want to format the date. These are the same date formatting options of the xtFormatDate verb.

• unit=“some other unit“

• DateType=
  • “long”
  • “short”
  • “abbreviated“
• TimeType=
  • “long”
  • “short“
• FormatString=”
  • “[Day]”
  • “[DayOfWeek]”
  • “[DayOfYear]“
  • “[hour]”
  • “[minute]“
  • “[second]”
  • “[month]“
  • “[WeekOfYear]”
  • “[year]“
  • “[sortable]”

• example <timestamp unit=“light” FormatString=“[minute]:[second]”>

Includes a unit property value as long as it’s a string or a number.

If the unit property is updated all value displays will be updated to reflect the new value.

• name=“the parameter name“

• unit=“some other unit”

Forces a line break or inserts a new line character. This will force a new line in a unit value display but may not format properly in a list window or a unit icon display.

The <br> tag has no optional or required parameters.

I have a mySensors based barometer. It returns the barometer value in one unit and the simple forecast that it does in another. I would like to see them together in one display so in the On Label of the value unit I’ve written:

<value> (<description unit="Barometer Forecast”>)

which results in an output of 1106.4hpa (stable)

to make a temperature/humidity display:

<value>°F <value unit=“humidity”>%

results in a display of “75°F 45%”