Node-RED Programming Tools (NRPT)
Tools to simplify the integration between Home Assistant and Node-Red
Todo
- Improve and move installing IntelliSense (d.ts files) to separate package. Load d.ts files from Node-Red config.
- Add functionalities:
- Retrieval of entities
- Enum for each service
- Add better error/exception handling:
- Catch errors
- Logging of exceptions
- Send exceptions to for example twitter
- Improve documentation
- Call service from entity example
Install package
Caution:
This package is only tested with the hassio addon (https://github.com/hassio-addons/addon-node-red)
Installation
To install this package in Node-Red you can import the following nodes.
It calls a function node each time Node-Red restarts or deploys. The function retrieves the NRPT package and saves the package in the Tools constant. After this node installs IntelliSense data in Node-Red.
[{"id":"aab650160f7d9808","type":"inject","z":"2f4d204a142d188b","name":"","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":true,"onceDelay":0.1,"topic":"","payload":"","payloadType":"date","x":110,"y":480,"wires":[["ddbfeababe97e8e1"]]},{"id":"ddbfeababe97e8e1","type":"function","z":"2f4d204a142d188b","name":"Install IntelliSense","func":"Tools.InstallIntelliSense.install();","outputs":1,"noerr":0,"initialize":"","finalize":"","libs":[{"var":"Tools","module":"node-red-programming-tools"}],"x":270,"y":480,"wires":[[]]}]
Update package
- In Home Assistant, navigate to the file editor.
- In the editor navigate to
/config/node-red/package.json
and update the version to the desired version number of the NRPT package. - Save the file.
- Restart the Node-Red container to update the package and the IntelliSense.
How to use the package in Node-Red
Initialization of the object
To retrieve the tool object, you can either use the create function or instantiate it yourself.
const tool = Tools.create(this); // Function
const tool = new Tools.Tool(this); // Instantiation
How to handle entity data
Retrieve data of an entity:
const entity = tool.entities.getEntity('sun.sun');
Retrieve multiple entities:
Call with array
tool.entities.getEntities([
'sun.sun',
'sensor.hacs'
])
// Outputs:
Collection([
{
key: 'sun.sun',
entityId: 'sun.sun',
// Other data
},
{
key: 'sensor.hacs',
entityId: 'sensor.hacs',
// Other data
}
])
// Retrieve an entity
entities.getByKey('sun.sun');
Call with object
tool.entities.getEntities({
sun: 'sun.sun',
hacs: 'sensor.hacs'
})
// Outputs:
const entities = Collection([
{
key: 'sun',
entityId: 'sun.sun',
// Other data
},
{
key: 'hacs',
entityId: 'sensor.hacs',
// Other data
}
]);
// Retrieve an entity
entities.getByKey('sun');
The collection object is from the package: https://www.npmjs.com/package/collect.js
How to work with outputs
Single call service output:
Connect the function
node to a call service
node to call a service.
return tool.output
.callService((cs) => {
cs
.setEntityId('switch.switch1')
.setService(Tools.Enums.Service.Switch.TURN_ON)
})
.output();
Get all entities of a certain domain
// Get all entities in een domain "switch"
tool.entities.getEntitiesByDomain('switch');
Get all entities of a certain domain
// Get all entities in domain switch except "switch.switch1".
tool.entities.getEntitiesByDomainExcept('switch', [
'switch.switch1'
]);
Multiple call service output:
Connect the function
node to a call service
node to call a service.
return tool.output
.callMultipleServices((cs) => {
cs.createPayload((cb) => {
cb
.setEntityId('switch.switch1')
.setService(Tools.Enums.Service.Switch.TURN_ON)
});
cs.createPayload((cb) => {
cb
.setEntityId('switch.switch2')
.setService(Tools.Enums.Service.Switch.TOGGLE)
});
})
.output();
How to log data
Log data to the debug console:
tool.logger.log(any);
Log data of an entity:
tool.entities.logEntityData('sun.sun');
How to create a collection
This project heavily relies on the collect.js collection. It is inspired by the Laravel collection and tries to imitate the same behavior in javascript. The following code is an example to create a collection in a Node-Red function node.
Tools.collect([
{value: 'one'},
{value: 'two'},
{value: 'three'},
]).pluck('value').toArray();
// Output:
['one', 'two', 'three']