Fundamentals - constructing data to HS4 devices

[Furious]

Hi all,
I just thought I'd post this to try and help those trying to get their heads around the new HS4 support in node red.
The HS4 documentation really doesn't give much away, and certainly doesn't help those new to JS and JSON control devices, so may be off-putting.

The HS4 device nodes do not accept a standard payload currently from what I can see. What do I mean by "standard"?
Well, take the output from the alexa remote node - if you control a light to turn on, you get:

msg.payload = on
msg.on = true
msg.bri = 254
etc

Now, if you link that up to the device node of HS, that will be ignored, as the node doesn't handle msg.payload in that way for some reason. I've not deep dived into what the JSON is supported as there's only so much I really need to do, but it's not helpful for new people to use as the example is not very clear:
msg.payload = {} {"value":"255"}

In JS terms, what the above actually means is that HS device is expecting a msg.payload with a sub key of "value", and that has a value of "255"
or in other words:
msg.payload.value = 255

So you can do the example and literally hard code using a switch node or a trigger node, but I'd prefer if the HS4 devices were a bit more intelligent and handled on/off based on the usual msg.payload.
Alternatively, for those wanting to not have specific switch nodes, you can just use a function node. Here's an example to convert msg.payload to a value HS device nodes can work with. It's set up for clarity, not elegance:

var temp = msg.payload;
var payload = {value:0};
if (temp === "on") {
payload = {value:99};
}
if (temp === "off") {
payload = {value:0};
}
node.send({payload});

Breakdown:
1. Set temp variable to msg.payload ("on" or "off")
2. Sets the payload variable to a JSON pair of "value":"0"
3 if temp = "on", set payload to "value":"99"
4 if temp = "off", set payload to "value":"0"
5 Send the msg object as msg.payload.value as 0 or 99
[/code]
Now, if your device needs 0 and 254, you just change the 99 to 254.

Here's the function to be cut/pasted into your node red instance:

[{"id":"9a59ac73.bc0e4","type":"tab","label":"Sample function for HS4 conversion","disabled":false,"info":""},{"id":"f2c31336.d0441","type":"function","z":"9a59ac73.bc0e4","name":"Convert payload to expected value","func":"var temp = msg.payload;\nvar payload = {value:0};\nif (temp === \"on\") {\n    payload = {value:99};\n}\nif (temp === \"off\") {\n    payload = {value:0};\n}\nnode.send({payload});","outputs":1,"noerr":0,"x":200,"y":60,"wires":[[]]}]

Hope this helps, and it's a useful exercise into how the msg object is easily converted into what you need. Would welcome anyone else adding examples or tips like the above so people can really use node red to help integration with the many tech types in HA

[ksum]

Hi all,
I just thought I'd post this to try and help those trying to get their heads around the new HS4 support in node red.
The HS4 documentation really doesn't give much away, and certainly doesn't help those new to JS and JSON control devices, so may be off-putting.

The HS4 device nodes do not accept a standard payload currently from what I can see. What do I mean by "standard"?
Well, take the output from the alexa remote node - if you control a light to turn on, you get:

msg.payload = on
msg.on = true
msg.bri = 254
etc

Now, if you link that up to the device node of HS, that will be ignored, as the node doesn't handle msg.payload in that way for some reason. I've not deep dived into what the JSON is supported as there's only so much I really need to do, but it's not helpful for new people to use as the example is not very clear:
msg.payload = {} {"value":"255"}

The problem here is that no two nodes output items in the same format. There is no "Standard Format" for messages in Node Red. From the Node Red Concepts Documentation:

Message

Messages are what pass between the nodes in a flow. They are plain JavaScript objects that can have any set of properties. They are often referred to as msg within the editor.

By convention, they have a payload property containing the most useful information.

In JS terms, what the above actually means is that HS device is expecting a msg.payload with a sub key of "value", and that has a value of "255"
or in other words:
msg.payload.value = 255

So you can do the example and literally hard code using a switch node or a trigger node, but I'd prefer if the HS4 devices were a bit more intelligent and handled on/off based on the usual msg.payload.

Since there is no standard format this is not feasible. Messages coming from a music service are very different than those coming from an Alexa contrib. Messages coming from two different Alexa contrib's can be formatted differently. The incoming format for HomeSeer nodes works well

Alternatively, for those wanting to not have specific switch nodes, you can just use a function node. Here's an example to convert msg.payload to a value HS device nodes can work with. It's set up for clarity, not elegance:

var temp = msg.payload;
var payload = {value:0};
if (temp === "on") {
payload = {value:99};
}
if (temp === "off") {
payload = {value:0};
}
node.send({payload});

Breakdown:
1. Set temp variable to msg.payload ("on" or "off")
2. Sets the payload variable to a JSON pair of "value":"0"
3 if temp = "on", set payload to "value":"99"
4 if temp = "off", set payload to "value":"0"
5 Send the msg object as msg.payload.value as 0 or 99
[/code]
Now, if your device needs 0 and 254, you just change the 99 to 254.

Here's the function to be cut/pasted into your node red instance:

[{"id":"9a59ac73.bc0e4","type":"tab","label":"Sample function for HS4 conversion","disabled":false,"info":""},{"id":"f2c31336.d0441","type":"function","z":"9a59ac73.bc0e4","name":"Convert payload to expected value","func":"var temp = msg.payload;\nvar payload = {value:0};\nif (temp === \"on\") {\n payload = {value:99};\n}\nif (temp === \"off\") {\n payload = {value:0};\n}\nnode.send({payload});","outputs":1,"noerr":0,"x":200,"y":60,"wires":[[]]}]

Hope this helps, and it's a useful exercise into how the msg object is easily converted into what you need. Would welcome anyone else adding examples or tips like the above so people can really use node red to help integration with the many tech types in HA

A function node should be used as a last resort. This statement was made by Nick O'Leary in the Node Red Slack. They are slower than using Nodes and use more resources. Sure, you only have one now, but later, when you have many, you will be taking a hit. Your choice to use them, but the official recommendation is to use a Node when you can. A Change node easily handles the needs, so the recommendation should be to use such.

Please don't get me wrong here, I only mean this as an intended education of Node Red. I had a difficult time getting my head wrapped around some of the concepts when I initially started using Node Red. I have a strong JavaScript background and my first couple flows were a node to gather data, a function node to manipulate things, and a node to output data. It made a nice neat little flow and I was happy. But once you understand working with the message, it is not difficult to use Change nodes to send things from one node to the next.

[Furious]

Exactly the kind of response I was looking for, always good to get other perspectives .

Since there is no standard format this is not feasible. Messages coming from a music service are very different than those coming from an Alexa contrib

I should have put "standard" in quotes - most nodes do actually use on/off for switching, and I feel the primary purpose for HA is setting states on or off based on rules, so feel that nodes should by default accept the payload as on/off and apply the "controldevicebylabel" method - it's supported natively in the HS JSON API.

I think it makes more sense that way, then you can link quite a lot of nodes direct to a HS device and not need any kind of changing. The least amount of nodes is always the most efficient in my mind.

A function node should be used as a last resort.

I won't argue on that. However, I use them more just because most of my flows have programmatically set values.
I currently run node red on a RPI 4 under docker which is also running pihole and 7 other containers, I've not seen any speed difference from when I used to run node red on a windows server with way more horsepower.

Thanks for your reply, and I hope others reading can find something of value here - the platform is very powerful and understanding the msg object is key to a successful deployment.
I just want to diffuse any potential frustration with how the HS nodes handle data, as like I mention above, the example given in the HS doc is very basic.

[dev120v]

not sure if it matters to HS4 nodes, but there is a difference between msg.payload = {} {"value":"255"} string and msg.payload = {} {"value":255} number

I am using 255 number ( msg.payload = {} {"value":255} ), but it is possible they both work when sent to hs4 node, not sure

***edit: both number and string work

[ksum]

Considering that on my HomeSeer installation far more of the 377 items are not On/Off items I cannot agree with your assessment. I am guessing MAYBE 3 dozen of my items are On/Off only. I need the ability to set Dim Levels, Volumes, Temperatures, Date/Time, etc. The HomeSeer Node is extremely flexible in the ability to do this with very straightforward settings. Otherwise we would need multiple nodes for different devices.

I can run many wires from various nodes in a flow into a Change node for a consistent change and then use a Switch node to move the flow to different HomeSeer Nodes based on a value inside the message. I also do this going out of HomeSeer Nodes. What would be NICE is if I could define the HomeSeer Device in the message. Then I would only need one HomeSeer node and could push all sorts of stuff into that. Outside of this, I believe the Node Red implementation has been done very well. There have been a couple of capabilities added since initial implementation but as a whole I only need understand 2 nodes and I have been able to send status of all sorts of devices in InfluxDB for charting temperatures, humidity, lumens, On/Off and Dim levels of lights, volume levels of devices, and more.

[spud]

Exactly the kind of response I was looking for, always good to get other perspectives .

I should have put "standard" in quotes - most nodes do actually use on/off for switching, and I feel the primary purpose for HA is setting states on or off based on rules, so feel that nodes should by default accept the payload as on/off and apply the "controldevicebylabel" method - it's supported natively in the HS JSON API.

a HS Device node is already capable of that, assuming you have a device with a "on" control then just send

msg.topic = "control"
msg.payload.status = "on"

you can even omit the msg.topic = "control" part, because the default topic is "control"

[Furious]

Considering that on my HomeSeer installation far more of the 377 items are not On/Off items I cannot agree with your assessment. I am guessing MAYBE 3 dozen of my items are On/Off only. I need the ability to set Dim Levels, Volumes, Temperatures, Date/Time, etc. The HomeSeer Node is extremely flexible in the ability to do this with very straightforward settings. Otherwise we would need multiple nodes for different devices.

That's fair, as everyone has different usage and requirements - my own experience is that on/off is primary, temperature control is a must, sensors are read only, and the dim or colour requirements are never used - I've entire flows set to do everything that devices support, but they are never used either by rules or voice command as when people want light, it tends to be they want it full on. My approach is automate where possible unless it's not reliable, coupled whether the amount of work needed to do so and how often its used.

What would be NICE is if I could define the HomeSeer Device in the message

That would satisfy an optimisation itch for me. I will say that you seem to think I'm being very critical of the node when I'm not - it's a great implementation, works very fast, this is just me trying to suggest a few tweaks and get more people onboard to node red. A lot of people here are tech savvy, but a lot aren't, and I've learnt a lot from others posts here where documentation is lacking.

[Furious]

a HS Device node is already capable of that, assuming you have a device with a "on" control then just send

msg.topic = "control"
msg.payload.status = "on"

you can even omit the msg.topic = "control" part, because the default topic is "control"

Cheers Spud, that's the kind of info needed. Can you do a brain dump of all supported topics and properties in the payload so we can play

[spud]

Cheers Spud, that's the kind of info needed. Can you do a brain dump of all supported topics and properties in the payload so we can play

It's all documented here: https://github.com/HomeSeer/node-red-contrib-homeseer

Controlling a Device

To control a device the node needs to receive on its input, a message with msg.topic set to control and either msg.payload.value property set to the control value to use, or the msg.payload.status property set to the control text status to use.