Skip to content

BLL Lists JSON

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

Lists, JSON and rolling history

Examples · Custom functions · Workflows

BLL variables do not have a separate array type. Store a list as JSON in a text variable, then evaluate or parse it when you need its contents. The array walkthrough and rainfall discussion demonstrate this approach.

The expressions below are bare BLL JavaScript. Fixed arrays make them directly testable; select actual Homey tags when adapting them. A variable name typed into JavaScript does not automatically retrieve a BLL variable.

Initialize, append and read

  1. Create a text variable called RainHistory in settings.
  2. Set its text to [] once to initialize an empty list.
  3. Use a variable-setting BLL expression to append a reading.
  4. Save the returned JSON text back into RainHistory.

Use the appendItem function for appending. For example, appendItem([1, 0], 2) returns [1,0,2] as JSON text. The original post calls its function pushAsString; the behavior is the same. This screenshot shows the community's setup:

BLL custom function and expression cards used to append to an array

Community example: a custom function appends a value and returns JSON text for storage in a BLL text variable.

If a controlled variable contains [1,0,2], inserting its tag unquoted in an expression makes that content a JavaScript array literal. The forum uses this technique. Alternatively, JSON.parse("[1,0,2]") explicitly converts JSON text into an array. Do not wrap arbitrary JSON-containing tags in quotes: embedded quotes or backslashes can break the expression. Use JSON-capable cards for data that cannot safely be inserted as code.

Read, total and select readings

These adaptations extend the forum's rainfall use case:

Bare expression Result Purpose
[1, 0, 2, 4][0] 1 First reading; indexes start at zero.
_.last([1, 0, 2, 4]) 4 Most recent reading when appending at the end.
[1, 0, 2, 4].length 4 Number of stored readings.
_.sum([1, 0, 2, 4]) 7 Total stored rainfall.
_.sum(_.takeRight([1, 0, 2, 4], 3)) 6 Total of the latest three readings.
JSON.stringify([1, 0, 2, 4].slice(-2)) [2,4] Keep the latest two as JSON text.
JSON.stringify([1, 0, 2, 4].map((value, index) => index === 2 ? 7 : value)) [1,0,7,4] Replace the third reading.

Store numeric readings, not localized strings such as "1,5". A rolling list represents days only if your Flow adds exactly one daily reading. Missed runs, repeated runs and cumulative sensor readings need explicit handling; do not treat a partial history as a complete rainfall record.

Keep only the latest ten daily readings

The rainfall thread asks for a FIFO list with ten places. The following adaptation implements a bounded history instead of allowing an array to grow indefinitely. Save it as rollingReadings:

(function (items, value, limit) {
  if (!Array.isArray(items) || !items.every(Number.isFinite) ||
      !Number.isFinite(value) || !Number.isInteger(limit) || limit < 1) {
    throw new Error("Expected numeric readings and a positive integer limit");
  }
  return JSON.stringify(items.concat(value).slice(-limit));
})

Example:

rollingReadings([1, 0, 2], 4, 3)

This returns [0,2,4] as text. For a ten-day history, call the function with limit 10, the current history and that day's reading, then store the result. Perform the append-and-save steps sequentially: simultaneous updates can both read an old list and overwrite each other.

For watering decisions, check history completeness and sensor freshness before comparing a recent total with your chosen threshold. See stale-sensor checks.

Build JSON for another card

Use JSON.stringify instead of manually concatenating JSON strings:

JSON.stringify({ room: "Kitchen", temperature: 21.5, online: true })

This adaptation produces valid JSON text and preserves number/boolean types. A later JSON reader can select room, temperature or online. Use BLL's JSON result tag when the receiving card supports it; otherwise pass text in the shape that card expects.

Do not confuse JSON data with JavaScript source. JSON.parse requires valid JSON, including double-quoted property names. Invalid JSON should raise an error rather than silently becoming an empty list.

Split records without losing the structure

The pipe-splitting example shows why the function's returned property names and the JSON reader's paths must agree. For MQTT sensor objects and looping over timer names, see the multi-app workflows.

For table output rather than individual values, use BLL's JSON-to-CSV and Excel actions.

Clone this wiki locally