Skip to content

BLL Examples

Arie J. Godschalk edited this page Nov 15, 2026 · 6 revisions

BLL coding and expression examples

Home · BLL coding · Formatting · Supported apps

Use the examples in a field that explicitly supports BLL coding. In a text field, wrap each expression in {[ ... ]}. In Execute BLL-expression or a BLL expression condition, enter only the JavaScript inside the brackets. See syntax and troubleshooting.

The examples below include adaptations of the app settings and community coding guide, plus additional examples. Results depend on input, locale, time zone and app versions. Try them in BLL's Coding settings or Execute Text (as Tag). For detailed examples by method, see date, time, number, Math.js and Lodash, and custom functions.

Example collections

I want to... Examples
Combine tags, choose a random message, search or split text Text and messages
Store lists, total rainfall or maintain rolling history Lists and JSON
Timestamp events, check stale sensors or calculate time fractions Time calculations
Extract MQTT data, report timer states or send fixed-decimal HTTP values Multi-app workflows
Build an illustrated AVD status, slider or timer display Device Capabilities and AVD

These collections link to the original community discussions and distinguish forum examples from adaptations. The sections below are a quick reference for basic expressions.

Text and calculations

Supported text input Example result or purpose
The answer is {[ 6 * 7 ]}. The answer is 42.
Total: {[ 10 + 3.5 ]} Total: 13.5
Half: {[ 25 / 2 ]} Half: 12.5
Remainder: {[ 17 % 5 ]} Remainder: 2
Rounded: {[ math.round(3.14159, 2) ]} Rounded: 3.14
Range: {[ math.min(7, 3, 10) ]} to {[ math.max(7, 3, 10) ]} Range: 3 to 10
Average: {[ math.mean([10, 20, 30]) ]} Average: 20
Root: {[ math.sqrt(144) ]} Root: 12
Result: {[ 18 >= 20 ? "high" : "normal" ]} Result: normal
Value: {[ Math.round(12.345 * 100) / 100 ]} Round a value to two decimal places.

math is Math.js; Math is JavaScript's standard object. To format a number for a particular locale rather than perform arithmetic, use number below. Arithmetic output is not necessarily formatted like a price.

Strings and lists

Supported text input Example result
{[ "homey".toUpperCase() ]} HOMEY
{[ " kitchen ".trim() ]} kitchen
{[ "bedroom".replace("bed", "bath") ]} bathroom
{[ "one,two,three".split(",")[1] ]} two
{[ ["hall", "kitchen", "garden"].join(" / ") ]} hall / kitchen / garden
{[ _.first(["one", "two"]) ]} one
{[ _.last(["one", "two"]) ]} two
{[ _.uniq(["a", "b", "a"]).join(", ") ]} a, b
{[ _.sortBy([3, 1, 2]).join(", ") ]} 1, 2, 3
{[ JSON.stringify({ room: "kitchen", on: true }) ]} JSON text for the object.

_ is Lodash. Arrays substituted directly in text are converted to strings; use join when you want a specific separator. Use JSON.stringify when a later card expects JSON text.

Dates and clock time

These use the configured locale and time zone unless supplied explicitly. Codes are case-sensitive: MM is month, mm is minutes.

Supported text input Purpose
Today is {[ date("dddd") ]}. Full weekday name, localized.
Date: {[ date("yyyy-MM-dd") ]} Year, month and day.
Time: {[ date("HH:mm") ]} 24-hour time.
Part of day: {[ date("PERIOD") ]} Long, locale-specific day-period text.
Updated: {[ date("dd-MM-yyyy HH:mm") ]} Date and time in one text.
{[ date("yyyy-MM-dd", "2026-11-12T13:08:00Z", "en-US", "UTC") ]} 2026-11-12, using a fixed instant and UTC.
{[ date("dddd", "2026-11-12T13:08:00Z", "en-US", "UTC") ]} Thursday, using the explicit locale.
{[ now ]} Current Unix time in milliseconds at evaluation.
{[ Math.floor(now / 1000) ]} Current Unix time in seconds.
{[ date("yyyy-MM-dd", now + 86400000) ]} Format the instant 24 hours from now.
{[ date("yyyy-MM-dd", now - 7 * 86400000) ]} Format the instant seven 24-hour periods ago.
{[ date("shorttime", now + 90 * 60000) ]} Format the time 90 minutes from now.

Adding 24 hours is not always the same as the next local calendar day around daylight-saving changes. now is milliseconds, not seconds. Configure and preview custom date formats in app settings; see Formatting. The 90-minute example is adapted from this community answer.

Durations

Use time for elapsed time, not a date of day. The second argument is milliseconds; the optional third argument is seconds.

Supported text input Purpose
{[ time("D", 1000000000) ]} Format a duration as a day count, as in app settings.
{[ time("H:mm:ss", 90061000) ]} 25:01:01: total hours, minutes and seconds.
{[ time("hh:mm:ss", 90061000) ]} 01:01:01: hour component, minutes and seconds.
{[ time("H:mm:ss", 3600000) ]} One hour expressed as a duration.
{[ time("H:mm:ss", null, 90) ]} Format 90 seconds; seconds are supplied as the third argument.

Choose a format that matches the total or component you need, and preview it in settings. Duration codes are distinct from calendar-date codes.

For a numeric difference between two known instants, enter this in Execute BLL-expression (as Tag):

time("M", new Date("2023-07-03T16:45:12+01:00") - new Date("2023-07-03T15:15:12+00:00"))

The first instant is 30 minutes after the second. time returns text; the card converts it to 30 in the number tag, so parseInt is unnecessary. Replace one instant with now to compare with the current time; use explicit time-zone offsets to avoid ambiguity. This is adapted from the community time-difference example. Test negative differences and zero values in your installed app version: the forum reports version-specific formatting issues for those cases.

Number formatting

These examples follow the number-method guide and app settings. Outputs vary by locale and may include locale-specific spaces.

Supported text input Purpose
{[ number(1.45, 2) ]} Two decimal places, using the default locale.
{[ number(1.45, 2, "nl") ]} Two decimal places using Dutch conventions.
{[ number(1.45, "percent") ]} Format 1.45 as 145%.
{[ number(0.145, "percent", null, "nl") ]} Format 0.145 as a Dutch percentage.
{[ number(1.45, "currency", "EUR", null, "nl") ]} Format an amount in euros.
{[ number(1.45, "currency", "EUR", "name", "nl") ]} Use the currency name instead of its symbol.
{[ number(1.45, "unit", "kilometer", "narrow", "nl") ]} Format a distance using a narrow unit label.
{[ number(1234.5, "decimal", "scientific") ]} Scientific notation.
{[ number(1234567, "decimal", "compact_short") ]} Compact notation, such as a localized million abbreviation.
{[ number(21, "unit", "celsius", "short", "en") ]} A localized temperature with a unit.

Styles include decimal, currency, percent and unit. Currency requires a currency code; unit requires a supported unit. number() produces formatted text, not a number for further calculations.

Custom function: split a message

The community split-text example shows using a custom function to return multiple parts. In Functions, create split3words and save:

(function (s) {
  const words = s.split(" ");
  return { words: words, splits: [words[0] + " " + words[1], words[2]] };
})

In Execute BLL-expression (as Tag) enter:

JSON.stringify(split3words("hello there friend"))

The JSON result contains words and splits, including "hello there" and "friend". A later JSON-capable card or app can extract the parts. This particular function expects three space-separated words; add validation if your input can differ. To embed the call in supported text instead, wrap the expression in {[ ... ]}.

The forum also shows a custom function for appending to an array. For example, save this function as appendItem:

(function (items, value) {
  items.push(value);
  return JSON.stringify(items);
})

Use appendItem(["apple", "pear"], "plum") in an expression-only card. The result is JSON text: ["apple","pear","plum"]. If your input is JSON text rather than an array, parse it first with JSON.parse; handle invalid input rather than assuming it always succeeds.

Expressions for conditions

These are bare expressions for the BLL expression condition, not text with {[ ]}:

math.mean([18, 20, 22]) > 19
"homey".startsWith("home") && 5 < 10

For JavaScript expressions use && for AND, || for OR, and === for equality. For conditional output in text, for example use {[ 18 >= 20 ? "high" : "normal" ]}. This differs from the syntax of the legacy Math.js cards below.

Using Flow tags and variable values

Select Homey tags using the Flow editor in the supported field. A tag's value and type are supplied by Homey at runtime; test with real values. For numeric calculations, insert a numeric tag into an expression where a number is expected, and use Execute BLL-expression (as Tag) if the next card needs a number tag. Do not copy a tag's visible label as if it were JavaScript.

Text inserted into JavaScript source may need quoting and escaping, especially when it contains quotes or comes from an untrusted source. Do not construct code from untrusted input or put secrets in shared Flow examples.

Legacy Math.js cards

These examples are for BLL's Math.js expression action or condition, not {[ ... ]} JavaScript. $DoorCount$ is a BLL number variable:

Math.js card input Purpose
$DoorCount$ + 1 Calculate the next count in an action.
$DoorCount$ > 10 Test a threshold in a condition.
$DoorCount$ >= 5 and $DoorCount$ <= 10 Test an inclusive range.
$#timenow$ + 1800 A Unix time 30 minutes from now, in seconds.
$#timestamp$ Current Unix time in milliseconds.
$#HH$ Current hour using the legacy time substitution.

The app substitutes the $...$ values before Math.js evaluates the expression. See the older Better Logic topic and BLL coding.

Clone this wiki locally