Values

A value is what a signal carries. A sensor sends one with emit(), an actuator receives one in run(), and Loxone Miniserver inputs and outputs use the same shapes. Every value is plain data: a union tagged by type, so it can be copied between threads, compared structurally and stored. Import it from @lox-nexus/plugin-sdk/values.

Most plugins only need number, boolean and string. The other types exist because Loxone lights are driven with fade times, colours and button masks, and a plain number cannot carry those.

Creating values

Value is both a type and an object with one factory per type. Use the factory rather than writing the object literal: the structured factories also normalise their input.

import { Value } from "@lox-nexus/plugin-sdk/values"

Value.boolean(true)
Value.number(21.5)
Value.string("on")
Value.null()
Value.singleChannel({ channel: 40, fadeTime: 1 })
Value.rgbw({ red: 100, green: 0, blue: 0, white: 0, fadeTime: 0.2, flags: 0 })
Value.tunableWhite({ temperature: 2700, brightness: 80, fadeTime: 2 })
Value.t5({ buttons: 1 })

A sensor sends the result with this.emit(Value.number(watts)). An actuator that accepts a type receives that variant of the union.

What the factories do to their input

null, boolean, number and string keep what you give them. The structured factories round to what the wire to the Miniserver can carry:

• percent values (channel, red, green, blue, white, brightness) are rounded to whole percent and clamped to 0-100;
• fadeTime is limited to 0 to 6553.5 s in steps of 0.1 s (an invalid one becomes 0.2 s);
• temperature is rounded and clamped to 0 to 65535;
• flags is rounded and clamped to 0 to 65535;
• a t5 mask that is not a whole number 0-31 becomes 0 (no button).

They never throw and never validate. For input from outside (HTTP, a device's JSON, persisted data) check it with ValueSchema, which accepts only what a Miniserver can carry, or convert it with Converter.

Value.singleChannel({ channel: 140, fadeTime: 0.04 })   // channel 100, fadeTime 0

Comparing and the type guard

Value.equals(Value.number(1), Value.number(1))   // true: structural
Value.equals(Value.number(NaN), Value.number(NaN))   // true, so repeated NaN readings dedupe
Value.isType("rgbw")                              // true: a type guard for strings from outside
Value.types                                       // every type name, in a stable order

equals is what the bus uses to drop equal consecutive values, so you do not need to compare before you emit().

Using the union in types

In type positions Value is the union, and ValueOf<"rgbw"> is one variant:

import type { Value, ValueOf } from "@lox-nexus/plugin-sdk/values"

function brightness(value: ValueOf<"singleChannel">) {
  return value.value.channel
}

Conversions

Signals declare a type, and the runtime converts to it, so your plugin rarely has to:

• an actuator's accepts: values are converted before run() is called;
• a sensor's valueType: what you emit() is converted to it before it reaches the bus;
• a Miniserver signal's data type, when a wire connects the two.

The conversion never throws. What cannot be converted becomes the target type's default (false, 0, empty string, a light at 0 % with a 0.2 s fade), so a bad value cannot stall the bus. A value that already has the target type is returned unchanged. You can call the converter yourself, for example to predict what an actuator will receive, or to read a loosely typed value:

import { Converter, Value } from "@lox-nexus/plugin-sdk/values"

Converter.convert(Value.string("on"), "boolean")       // { type: "boolean", value: true }
Converter.convert(Value.string("20%"), "number")       // { type: "number", value: 0.2 }
Converter.convert(Value.number(60), "singleChannel")   // 60 %, fade 0.2 s

Choosing types for your signals

• Declare valueType on sensors and accepts on actuators as exactly as you can. The wire editor hides targets and sources that would convert uselessly.
• Use number for measurements, boolean for states, string for text.
• Use singleChannel, rgbw and tunableWhite for lights that you want to drive with fade times. A plain number sent to a light type becomes a percentage.
• Use "any" only when the type varies (a generic "attribute" sensor).
• Pick the type the data is, not the one you expect the user to want. Wires convert for them: a number sensor can drive a Miniserver boolean input (true when non-zero).

An actuator that wants a number, whatever arrives:

export class SetpointActuator extends Actuator<MyPlugin, { id: string }, ValueOf<"number">> {
  static readonly id = "setpoint"
  static readonly accepts = "number"      // "21,5" or true or a dimmer all arrive as a number

  async run(value: ValueOf<"number">) {
    await this.plugin.api.setTemperature(this.params.id, value.value)
  }
}

Helpers

These are small, stateless classes in the same import. Use them instead of rewriting the logic.

import { Numbers, Value, ValueFormatter } from "@lox-nexus/plugin-sdk/values"

const percent = Numbers.scale(raw, 0, 1023, 0, 100)
this.emit(Value.number(percent))
this.plugin.log.debug("emitted", { value: new ValueFormatter().format(Value.number(percent)) })

See the values reference for every signature, and SDK at a glance for the compact list.