epdoc-node-red-utils
General purpose utilities for use with Node-RED and Home Assistant.
-
Service
wrapper, to generate payloads for use with the Call Service node. -
HA
wrapper, to retrieve state from home assistant
Utilities for my personal use of Node-RED with Home Assistant. Included are:
- A
setFan
function that is specific to my RF control of fans using both a Bond Bridge to control speed (0 to 6), and wall switches to decouple the fans from power when they are off. I do this to prevent mains noise from blowing the susceptible controllers on my Minka fans. -
LocationHistory
andLocationMoving
classes that I use to monitor movement from our house, for gate automation purposes. These are at a pre-release level of quality.
Developer Notes
This module was originally written in ES6 and transpiled using Babel to generate
a module that could be loaded using require
or import
. Soon thereafter it
was migrated to TypeScript (developer hint: this resulted in catching quite a
few bugs). It was also migrated to Bun for build and unit
testing. Bun generates a different type of module that can only be loaded in
Node-RED using a dynamic
import,
as you will see in the next section.
git clone epdoc-node-red-utils
cd epdoc-node-red-utils
bun install
bun test
bun run build
Installation and Use
Perhaps the most predictable way to install this package with Home Assistant is
to add this dependency to the Node-RED package.json
file and restart Node-RED.
Node-RED is restarted from Settings > Add-ons > Node-Red. The restart should
cause the module to be installed and available. For module updates you can edit
the version number in package.json
, delete
node_modules/epdoc-node-red-utils
, then restart Node-RED.
For convenience you can add the module to globals, so that you don't need
to specify the module in each Function Node
where it is used. Here are the
required changes to /config/Node-RED/settings.json
for this to work:
// Don't set module.exports yet
let settings = {
// No need to touch any of the settings
};
// Must use dynamic import because of the nature of how bun generates this module
async function loadModules() {
const utils = await import('epdoc-node-red-utils');
settings.functionGlobalContext['epdoc-node-red-utils'] = utils;
}
loadModules();
module.exports = settings;
Then, to use the following code in a Function Node, it's simply a matter of accessing the global context to get the module. In this example, the Function Node has two outputs, with the 2nd output wired to a Call Service node.
const u = global.get("epdoc-node-red-utils");
const payload = u.newLightService('master_bedroom').on().payload();
node.send([null,{payload:payload}]);
node.send([msg,null]);
node.done();
Unfortunately there is no code completion in Node-RED's Function Node editor.
You can find a more exhaustive discussion of various ways to use your own libraries in Node-RED here.
Service Class
The
Service
object is used to build a payload that can be passed to the Call Service
node.
Provided too are a number of subclasses for specific types of entities,
including SwitchService
, LightService
, AlarmService
, CoverService
,
FanService
and, finally FanSpeed6Service
, which is a 6-speed fan that uses a
Bond Bridge to set the fan speed and
a smart switch to turn the fans on and off.
There is the possibility for many more subclasses to be written, or you can
build your service payload directly using the base Service
class, or one of
the other subclasses.
The following shows the code for a function node that uses three equivalent implementations to tell a Cover to stop.
let payload = newService('cover.garage').service('stop_cover').payload();
payload = new CoverService('garage').stop().payload();
let payloadBuilder = newCoverService('garage');
payload = payloadBuilder.stop().payload();
msg.payload = payload;
return msg;
The following function node code creates a payload that can be used to set a light's brightness to 50%.
msg.payload = new LightService('bedroom').percentage(50).payload();
return msg;
The following function node code shows several ways to create a payload that turns a light on.
// In this example we directly use the LightService,
// which will set the domain to `light` for us.
// The LightService is a subclass of SwitchService.
msg.payload = new LightService('bedroom').on().payload();
// In this example we use the SwitchService, but change it's default
// domain from `switch` to `light` by specifying the full `entity_id`.
msg.payload = new SwitchService('light.bedroom').on().payload();
// Override the default domain using the `domain` method.
msg.payload = new SwitchService('bedroom').domain('light').on().payload();
return msg;
HA Class
The HA class is again meant for use in Function Nodes. It provides a wrapper for a Home Assistant instance, and has methods to access the state of Home Assitant entities.
Example retrieves the state of a light.
const gHA = global.get('homeassistant');
const ha = new HA(gHA);
const lightEntity = ha.entity('light.bedroom');
const isOn = lightEntity.isOn();
node.warn(`The ${lightEntity.id} is ${isOn?'on':'off'}`)
HA retrieveSensorsData method
This method takes a dictionary containing an id
field and optional type
field and retrieves sensor data for the listed sensors. This is a shortcut that
you might use when you have multiple sensors that you efficiently want to get
data for, and you need to access that data more than once.
const gHA = global.get('homeassistant');
const ha = new HA(gHA);
const sensorDict = {
sensor1: { id: 'input_boolean.evening', type: 'boolean' },
sensor2: { id: 'sensor.outdoor_temperature', type: 'number' }
};
ha.retrieveSensorsData(sensorDict);
if( sensorDict.sensor1.on ) {
console.log('It is the evening');
}
if( sensorDict.sensor2.val > 30 ) {
console.log('It is hot today');
}
The above code is equivalent to the following:
const gHA = global.get('homeassistant');
const ha = new HA(gHA);
if( ha.entity('input_boolean.evening').isOn() ) {
console.log('It is the evening');
}
if( ha.entity('sensor.outdoor_temperature').asNumber() > 30 ) {
console.log('It is hot today');
}