Lets you control Node-Red via Google Assistant or the Google Home App
Table of Contents
- Setup Instructions
- Nodes in this package
- The config node
- Sending spoken notifications
- Inviting other users
- Troubleshooting local fulfillment
- Copyright and license
A collection of Node-RED nodes to control your smart home devices via Google Assistant or the Google Home app.
This is done by implementing a smart home provider that runs on your own host. So you don't have to rely on any third party services (other than Google) that can go offline, charge you, or leak your data.
What this module does NOT do:
- It does not talk to your physical devices. It only provides virtual devices in Node-RED. It's up to you to pass commands from the virtual to the physical devices.
- It is not an interface to Google devices (like Nest Thermostats, Nest Cams, etc.).
- It is for controlling devices only. It does not let you implement your own conversations with Google Assistant.
- You need your own domain. You can use a free domain from any DynDNS provider. The DNS record for this domain must point to your host.
- You need a 'real' SSL certificate, e.g. from Let's Encrypt. You must have either the certificate files (e.g. from Certbot). Or you can use a reverse proxy with automatic certificate management, such as Caddy or Traefik. Tip: There's a guide on how to use Caddy.
- You need to be able to forward incoming traffic from the internet to a specific port on your host. This may be difficult if your ISP uses carrier-grade NAT, or if you can't configure port forwarding on your router.
- This package requires at least NodeJS 10.0.0.
Follow our setup instructions.
Nodes in this package
onlineis set to
falsefor a node, Google SmartHome will not be able to control the node. It will also show up as
offlinein the Google Home app.
- Nodes will do their best to convert incoming payload data to the required type. For example, you can send a string of
ONand it will be converted to
- Topics must be either as listed below or prepended with one or more
my/topic/on. The nodes will only look for the part after the last
/, if any.
- Google device node
This is a generic node that supports the following Google devices:
- Air conditioning unit
- Air cooler
- Air freshener
- Air purifier
- Audio-Video receiver
- Carbon monoxide detector
- Coffee Maker
- Pet feeder
- Pressure cooker
- Remote control
- Security system
- Smoke detector
- Stand mixer
- Streaming box
- Streaming soundbar
- Streaming stick
- Water heater
- Water purifier
- Water softener
- Yogurt maker
and the following Google traits:
- App selector
- Camera stream
- Color setting
- Color temperature
- Energy storage
- Fan speed
- Humidity setting
- Input selector
- Light effects
- Media state
- Network control
- Object detection
- Run cycle
- Sensor state
- Software update
- Start stop
- Status report
- Temperature control
- Temperature Setting
- Transport control
Example flow: See the flow used for the automated tests here
topic can be
payload is not used for anything.
restart_server is used to stop and restart the built-in web server. Can be used if your SSL certificate has been
renewed and needs to be re-read by the web server.
report_state will force an update of all states to Google. Mostly useful for debugging.
request_sync will ask Google for a sync to learn about new or changed devices. This is usually done automatically.
The config node
Name: A name for your config node.
Enable Node Debug: If enabled, debug messages will be written to Node-RED's log output.
Default Language: The language of your project.
Use Google Login: If checked, use Google login authentication.
Login Client ID: If Google Login is enabled, the client ID you received from the Google Sign-In integration.
Authorized emails: If Google Login is enabled, the email addresses authorized to log in.
Password: If Google Login is disabled, a username and password used during account linking in the
Google Home app.
Actions on Google Project Settings
Client ID: The client ID you entered in the Actions on Google project.
Client Secret: The client secret you entered in the Actions on Google project.
Google HomeGraph Settings
Jwt Key: Path to the JSON file that you downloaded during setup. Can be an absolute path or a path relative to
Node-REDs user dir (where your settings.js, flows.json etc. are stored).
Web Server Settings
Port: TCP port of your choice for incoming connections from Google. Must match what you specified in the
Actions on Google project. If empty, it will use the same port as Node-RED.
URL subpath: URL subpath to add to the URL. If set, the URL will change from
Use http Node-RED root path: If enabled, use the same http root path prefix configured for Node-RED, otherwise use /.
Use external SSL offload: If enabled, the smarthome service will use HTTP instead of HTTPS. Check if you want to
do SSL termination on a reverse proxy.
Public Key: Full path to the SSL certificate file, e.g.
fullchain.pem from Let's Encrypt.
Private Key: Full path to private SSL key file, e.g.
privkey.pem from Let's Encrypt.
Scan Type: The service discovery method to use. Must match what is set in the Actions on Google project.
Discovery Port: A port number to use for UDP or MDNS service discovery.
HTTP Port: A port number to use for the connection from your smart speaker to Node-RED. If empty, it will use the
same port as Node-RED. If you are using Node-RED's built-in HTTPS encryption or have a httpAdminRoot set,
you need to set a port. Don't create a forwarding rule for this port!
Token Duration: The duration of the authorization token used by Google SmartHome to identify itself to the Node-RED
SmartHome plugin. Default is 60 minutes.
Report Interval (m): Time in minutes between sending report updates to Google (default is 60 minutes).
Request sync delay (s): Delay in seconds, for requesting devices sync after a deployment. 0 or empty for disable
(default is 0).
Set state delay (s): Delay, in seconds, for sending the set_state message after state changes, 0 or empty to disable
(default value 0).
Sending spoken notifications
Some devices support sending spoken notifications to your smart speaker. For example, you can play a notification on your speaker when someone rings at the front door or when the washing machine completes a cycle. Unfortunately, you cannot send custom notifications, you can only trigger predefined notifications.
- Using the "Google Device" node, create a device with one of the supported traits in Node-RED and deploy it. Currently, only the Object Detection, Run Cycle, and Sensor State traits support notifications.
- In the Google Home app, open your new device and enable Spoken Notifications.
- To trigger the notification, send a message with a specific payload to the device node. You can find examples for all supported notifications in the examples folder (examples/Spoken%20Notifications). Payloads are documented here.
Inviting other users
You can invite other people into your smart home in the app by following these steps.
Inviting people will not work in all cases. For example, it won't work if either you or the other person has a commercial Google Workspace account. If this is the case, you can share access to your Smart Home project as follows:
- If you are currently using username/password authentication, switch to Google Sign-In by following the instructions on Integrating Google Sign-In. Proceed only after you have successfully unlinked and relinked your own account.
- In "Authorized emails", add the email address of the account you want to add. Save and deploy.
- Open your project in the Google Actions Console.
- Select "Manage user access" from the menu (three dots on the top right) choose "Manage user access".
- Select "Add".
- Enter the email address for the account you want to add. Select at least "Viewer" as the role.
- Return to the Google Actions Console. On the
On device testing. Then click
- The person you just added should now able to link to your project by following the steps in Setup Account linking.
- Some devices can be controlled by voice, but not by the Google Home app. For example windows and sensors. These devices will only show a general page with their room assignments in the app, but they don't show their current state or any buttons to control them. There is nothing we can do about this. This has to be implemented by Google.
- Some errors and possible solutions are listed at Possible errors.
- Check Node-Red's debug panel for error messages.
- Unlink and relink your account in the Google Home app. Check Node-RED's debug panel for errors while doing so.
- If you are having trouble linking your account, try turning off Wi-Fi on your phone to use only the cellular network.
- If you are having trouble linking your account, disable "Use Google Login" and try logging in with username/password first. You can switch back to Google Login later.
- Restart your flows (using the
Restart Flowsoption in the dropdown menu of the deploy button) while the debug panel is open to see any error messages during initialization.
- Go to Actions on Google Console, in tab Test choose logs in Google Cloud.
- Check if your service is reachable from the outside. Use reqbin.com or a similar tool to send a GET request to https://example.com:3001/check (with your hostname and port). It should respond with status 200 (OK) and the message "SUCCESS: Smart Home service is reachable!" as one of the first lines. Use https://www.ssllabs.com/ssltest/ to check your SSL certificate.
- Check Node-RED's log output. Where you find it depends on how you installed Node-Red. Usually something like
journalctl -u nodered,
docker logs <container>or a file in
- Toggle "Enable Node debug" in the configuration node, connect a debug node to the output of the management node and look for debug messages. In the Node-Red UI select 'Restart Flows' on the 'Deploy' button to see messages during initialization.
- Go to Actions on Google Console, on tab
Reset Test. If this doesn't do anything, click the
Settingsbutton, disable and re-enable
On device testing.
- Check that you have only one single management node and one single config node.
- Go through the setup instructions again and compare your settings with what you see on the screenshots
For problems related to local fulfillment, see Troubleshooting local fulfillment.
Parts of this README and much of the code come from Google. In particular, Actions on Google: Smart Home sample using Node.js was of great value.
Copyright and license
Copyright 2018 - 2023 Michael Jacobsen and others under the GNU General Public License version 3.