hub.scenes.expressions.set

Version: 1.
Classes: UI
Title: Scene manager categories
Description: Creates a new expression object or updates an existing one. The new expression will be evaluated using expression code and parameters. If no errors found, an expression will be created, assigned with the value, and an empty result will be returned. In case of error, an expression won’t be created, and an error will be returned. In case of existing expression modification, the new value or the error that occurred will be assigned with the expression. The Scenes engine will require expressions to be typed to use them more widely in comparisons for meshbot construction. For variable expression, value parameter should be set, variable should be true, and code parameter should be empty.

An expression with valueType property attached should be created. When a new value is first calculated, its output type should be checked (checking code should try to compose a value of a given type out of it).

For Scalable value types output should be in form of an object { value: NumericValue, scale: ScaleForTheValueType }.

Edit

Field	Type	Required	Description
name	string	+	An expression name. Should be unique across all the scenes.
code	string	+	Lua code snippet to be run within a scene (Max 5 kb for Linux and 1 kb for Atom)
params	object	–	Expression parameters
params.items	array of objects	–	An array of an expression parameter name and item identifier pairs.
params.items[index].name	string	+	A parameter name to use in an expression. A value of an item can be referred from an expression as params.name.
params.items[index]._id	string	+	An item identifier to get value from
params.device_item_names	array of objects	–	An array of an expression parameter name, device name and item item name objects.
params.device_item_names[index].name	string	+	A parameter name to use in an expression. A value of an item can be referred from an expression as params.name.
params.device_item_names[index].deviceName	string	+	A device name to get items from
params.device_item_names[index].itemName	string	+	An item name from the device pointed by deviceName, to use in an expression
valueType	string	–	A type of value returned by an expression. Required for expressions used by the Scenes Engine. If set, the Lua code should return only values, from which the variable of a given value type can be constructed. The valueType field can have any value the firmware exposes as an item value type.
metadata	object	–	Metadata bound to an expression. Can be JSON object type. If null, should not be stored.
variable	boolean	–	If true, the expression is a variable. Variables should be separated in the UI from other expressions. If a variable is true, the expression cannot get any data sources from outside (devices, items), and is supposed to save a constant never-changing value.
value	any type	–	Expression value

Edit

Broadcasts	Description
hub.expression.added	Broadcast when the expression was successfully added.
hub.expression.changed	Broadcast when the expression was changed.

Edit

Code	Message	Data
-32600	Wrong params, FIELD	rpc.params.invalid.{FIELD}
-32600	Field is too long: code	rpc.value.too.long
-32600	No item found	ezlo.item.notfound
-32600	No device found	ezlo.device.notfound

Edit

				
					{
   "id":"_ID_",
   "method":"hub.scenes.expressions.set",
   "params":{
      "name": "TwoPlusTwo",
      "code": "return 2 + 2"
   }
}

Edit

				
					{
    "error": null,
    "id": "_ID_",
    "result": {
    }
}

Edit

use item name by an item identifier (item with the id itemIdentifier should exist).

				
					{
   "id":"_ID_",
   "method":"hub.scenes.expressions.set",
   "params":{
      "name": "HalfOfSoundLevel",
      "code": "return params.sound_level / 2",
      "params": {
        "items": [
            { "name":  "sound_level", "_id": "sirenSoundLevelItemIdentifier"}
        ]
      }
    }
}

Edit

use device and item names to address the item (device with name siren and an item with name sound_level should exist).

				
					{
   "id":"_ID_",
   "method":"hub.scenes.expressions.set",
   "params":{
      "name": "HowLoudQuad",
      "code": "return params.how_loud * 4",
      "params": {
        "device_item_names": [
            { "name":  "how_loud", "deviceName": "siren", "itemName":  "sound_level" }
       ]
     }
   }
}

Edit

use an expression with a scalable item.

If the item addressed by a scene’s “when block” has a scale (has scalable value), then an expression to use with isItemState or compareNumbers methods should return value in format { value: number, scale: string } to be compatible with an item.

				
					{
   "id":"_ID_",
   "method":"hub.scenes.expressions.set",
   "params":{
      "name": "Temperature10F",
      "code": "return { value = 10, scale = \"fahrenheit\" }",
      "params": {}
   }
}

The expression will return constant JSON object with fields value = 10 and scale = “fahrenheit”. In the case of incompatible values, a scene event that uses an expression will never raise.

Edit

use a typed expression with a scalable item.

				
					    "id":"_ID_",
    "jsonrpc":"2.0",
    "method":"hub.scenes.expressions.set",
    "params":{
        "name": "kitchenHallTempAverage",
        "params": {
            "items": [
                {
                    "name": "kitchenTemperatureSetpoint",
                    "_id": "5fecdf73222aaa175f6d6be4"
                },
                {
                    "name": "hallTemperatureSetpoint",
                    "_id": "60c7696b933ffb710a8be319"
                }
            ]
        },
        "code": "return { value = (params.kitchenTemperatureSetpoint.value + params.hallTemperatureSetpoint) / 2, scale = params.hallTemperatureSetpoint.scale }",
        "valueType": "temperature",
        "metadata": {},
        "variable": false
    }
}

Edit

use a typed expression as a variable.

				
					{
    "id":"_ID_",
    "jsonrpc":"2.0",
    "method":"hub.scenes.expressions.set",
    "params":{
        "name": "maxValueOfSomeParam",
        "params": {},
        "code": "return 2526",
        "valueType": "int",
        "metadata": { "info": "maximum value of parameter" },
        "variable": true
    }
}

Edit

Typed variable expression.

				
					{
    "id":"_ID_",
    "jsonrpc":"2.0",
    "method":"hub.scenes.expressions.set",
    "params":{
        "name": "variableExpression",
        "params": {},
        "code": "",
        "value": 123,
        "valueType": "int",
        "metadata": { "info": "maximum value of parameter" },
        "variable": true
    }
}