[RELEASE] Hubitat Automation Map

[gordon.thelander]

Automation Map: App and device relationships, with Rule Machine flowcharts

Hubitat shows which apps use a device, but not how they use it, and reading a rule's logic means opening the rule. Automation Map builds a map of the relationships between apps and devices on a hub, classifies each relationship by role, and renders Rule Machine rules as flowcharts.

Relationship roles

Each connection between an app and a device is classified as one of the following:

Role	Meaning
Trigger	the app subscribes to this device's events
Constraint	a condition or required expression
Monitor	the app reads the device's state but cannot command it
Action	the app can command the device
Exposed	the device is published to an external system, such as Maker API
Owns	the app created the device

Roles are properties of the relationship rather than the device. EG: A motion sensor may be a trigger in one rule and an action target in another, so a device can carry different roles in different apps, and more than one role within the same app.

Rule flowcharts

Selecting a Rule Machine rule renders its structure: the trigger, the required expression, and the actions in execution order, including waits with their timeouts and IF / ELSE-IF / ELSE as branches.

Conflict and orphan detection

The Insights panel lists devices that more than one app can leave in a lasting state, and devices that no app references. Conflict detection is limited to stateful capabilities (switches, dimmers, locks, thermostats and similar) because two apps sending notifications to the same device is not a conflict, while two apps setting the same light is.

Whole-hub view

The unfiltered view shows all apps and devices at once. On a hub of thus can be too dense, and is intended as a starting point rather than a working view; selecting an app or device filters to that subset. Both selectors have search fields, and clicking a node navigates to it.

Implementation

There is no published API for enumerating installed apps and their device references. This app queries the hub's internal endpoints (the ones the administration UI uses) through a request the hub issues to itself on localhost.

Roles are derived from platform-level data: an app's child devices, its event subscriptions, and the capability type of each device setting. Rule Machine's own settings naming is used to separate triggers from conditions within a rule.

Tested configuration

• Hubitat C-8, platform 2.5.1.142
• 193 devices, 64 installed apps across 17 app types
• 41 Rule Machine 5.1 rules, each decoded flowchart verified against the rule's own page
• Integrations present during testing: CoCoHue, Chromecast, Google Home, Kasa, Tapo, Sensibo, Meross, LIFX, Maker API, Notifier, Averaging Master, and several custom apps
• Installation, removal and reinstallation through Hubitat Package Manager, from a hub with no prior state
• Hub Login Security disabled

The relationship graph is built from platform-level data and handled all 17 app types, including integrations it has no specific support for. Flowchart decoding is the component tied to a particular engine.

Limitations

• The app is read-only. It does not command devices or modify apps.
• OAuth must be enabled, as the map is served as a page from the hub. Package Manager enables it during installation; a manual Apps Code installation does not.
• The internal endpoints used are undocumented and may change in a future platform release. The app reports this rather than displaying an empty map.
• Flowcharts are produced for Rule Machine 5.1 and Notifier. Rules on other engines appear in the graph with their device relationships and are reported as undecoded.
• Desktop browsers only. Smaller screens are shown a redirect notice.
• The browser viewing the map requires internet access, as the graph and flowchart libraries are loaded from a CDN. The hub does not.
• Behaviour with Hub Login Security enabled has not been tested. The app detects the failure and identifies it as the likely cause.
• Only apps referencing at least one device are discovered, as discovery works by asking each device which apps use it.
• A scan of approximately 190 devices and 60 apps takes about two minutes and runs automatically on first installation.

Installation

EDITED: Hubitat Package Manager by searching for "Automation Map"

Notes

Two configurations remain untested: Hub Login Security enabled, and rule engines other than Rule Machine 5.1, including Rule 4.x, Room Lighting and Simple Automation. These appear correctly in the relationship graph but produce no flowchart. Reports from either would be useful.

[jlv]

@gordon.thelander

Hubitat Package Manager, Install from URL:

It would really make it simplier on users if you just added your package manifest to HPM's master list.

[gordon.thelander]

I know, but it has only had limited testing on my setup. I was hoping to get some feedback before submitting a PR to add it to HPM’s public manifest.

[jwjr]

Installed on all three C-8Pro hubs here, working fine on all. Very cool; "Insights" are very cool.

Text after scan on each hub reads: "Read [#] app(s), 1 could not be read." Is that the Automation Map app itself?

FYI, the busiest hub read "Map ready: 357 nodes, 999 relationships." I'm tempted to add 1 more...

[jabecker]

Where has this app been all my life! Very cool!

On a C-8 Pro, scanned 186 devices and 119 apps; 304 nodes, 1331 relationships. I didn't time it but it only took a couple of minutes.

I'm also getting the message "1 rule(s) on Rule-5.1 were not decoded". Not sure what this refers to?

[gordon.thelander]

Thanks both - that's exactly the kind of feedback I was hoping for.

Your setups are both significantly larger and more complicated than mine, so it's good to see discovery and rendering hold up at that size. On scaling: the graph costs roughly 80 bytes of app state per node or relationship, so those hubs are sitting at around 95–130KB. My best estimate is that it stays comfortable to somewhere around 2,500–3,000 combined nodes and relationship, approx 600 devices and 250 apps. The first limit to bite would probably be the Hubitat app-state size and the second would be the graph physics settling on overly dense layouts. If anyone gets near that though, I would be surprised.

@jwjr - you guessed right, that message is about Automation Map itself. It's a counting bug: an app was flagged "could not be read" whenever it had no device relationships, but that isn't a failure. Automation Map excludes itself from its own map, so it has no relationships, and so it reported itself as unreadable on every scan.

@jabecker - "1 rule(s) on Rule-5.1 were not decoded" almost certainly means a rule with no actions defined. It produces no flowchart, and I was counting "nothing to draw" as "can't decode this engine", which led to the contradiction with the line underneath saying Rule-5.1 is supported.

I have fixed both in an 1.0.1 update and you will pick it via your update schedule or you could just do a manual refresh.

Based on this positive feedback and taking @jlv's suggestion, the app is now listed properly in HPM, and can be found under the Public Repository by searching for 'Automation Map', you may want to uninstall the version pointed directly at my repo in favour of that one now.

Cheers,

Gordon

[jabecker]

Uninstalled and reinstalled via HPM. This time it told me: Decoded 41 Rule-5.1 flow(s). That seems about right. The "1 rule not decoded" message did not appear.

Thanks!

[Timbb]

Fantastic App!!!! So great to be able see all the interactions so easily

[gordon.thelander]

Cool!

[pomonabill220]

LOVE IT!!!

This is a HECK of an app and VERY useful to find possible problem and conflicts!

Thank YOU!

[jgbLC]

Looks like a great app, but has anyone tried on a C-7? I saw that the developer tested on a C-8.

[JimB]

Please add a connection where a rule runs another rule or a rule function

[jgbLC]

Self answered...all good on C-7.

[gordon.thelander]

I think that should be possible. The app builds its map by interrogating Hubitat's internal app data, looping back to 127.0.0.1 and parsing the returned JSON. This includes Rule Machine's runtime state. If a "Run Rule Actions" or Rule Function call exposes the target rule ID there, I should be able to map it as a Rule -> Rule connection. I'll test it during the week and get back to you.

[PunchCardPgmr]

I was just thinking about how Hubitat could add some real shine on the product by having tools that reliably build the "basis of documentation" for the monitoring, control, and topology of an installed environment.

Some footprint that gives you something to start building upon with notes and finer details of the intentions, operations, locations, and things that need regular attention like certain device batteries (maybe even picking up the comment fields on Devices & Rules that many of us DO use).

We know this is the last thing most folks tend to get around to and I recently read another case of a "the WAF" not being enough in Home Automation. Two examples, the passing of the main Automate-er, or less sad case of passing the environment on with the sale of a home. All that said, I know there are some folks in this Community that are very diligent about documentation.

So anyway, GOOD ON YA FOR WORKING TOWARDS THIS END !

I'll just leave this here as support of your efforts...

Serious question - If you were to die tomorrow, how long would your HA implementation last before

a) someone in the household takes on the hobby, errrr I mean management of it or b) it starts to need attention and someone in the household unplugs/circumvents it .... It's Autumn, the leaves are starting to fall, Winter is looming...time to ponder your immortality . Hey, it's a reasonable question ...that I bet more than a few of you have already pondered. Considering this the ultimate "WAF Test". #Weekend_Musings Adding this tidbit from a relevant thread: Another add; as fo…

[gordon.thelander]

@JimB

Done, and ready to test if you are willing.

What I found: I expected the "Run Rule Actions" step to carry its target, but the action holds only a method name. The target rule's ID is stored separately in the rule's settings, keyed by the action number, so it resolves to a real rule and can be mapped.

Changes applied: The same pattern turned out to cover four actions, so this test release does all of them: Run Actions, Cancel Timed Actions, Pause / Resume Rules, as well as Set Private Boolean of another rule. Each draws as a direct rule-to-rule link, and the rule flowchart now names the rule each step acts on. A new Rule to rule only option in the Show filter hides device edges and leaves just these automation chains, to simplify the view where required.

Rule Functions work too. A function reports itself identically to an ordinary rule, so the link resolves the same way. Worth noting it usually references no devices at all, and this app finds apps by asking devices which apps use them, so a function is normally invisible to the scan. It is still drawn when another rule calls it, as an outline node, so the relationship is never lost.

Test outcome: Just a dummy rule including all the various options

Where I need help: I barely use these type of actions. To test this at all I built a rule that calls all them, and doing that immediately found a few unexpected bugs that I had to correct. So everything is confirmed against one example I manufactured, rather than against a hub that contains many such rules, as yours likely does.

The test build below installs alongside your existing Automation Map under its own name. Both run on the same hub and your current install is untouched.

HPM, Install → From a URL:

https://raw.githubusercontent.com/GordonThelander/hubitat-automation-map/dev/packageManifest.json

It appears as Automation Map (Dev). Add the app, select devices, press Done, let the scan finish.

Could you please test it and let me know whether it finds the links you expect, and whether anything appears that is not real. One known gap: Pause and Resume share an action type and I cannot yet tell them apart, so both read "Pause / Resume Rules".

Next Steps: If it works properly for you I will merge it into the main branch. You can then uninstall the test build from HPM, and the feature will reach your normal install the next time you update Automation Map.

Thanks a mil,

Gordon

[gordon.thelander]

@JimB - I have also added a new feature, mapping external dependencies, please take a look at that as well if you can.

[JimB]

Had a chance to check it out.

All of the rules detected are correct, with the exception of one rule that has been deleted several months ago. It didn't resolve to a rule name. The reference to it from another app is bogus.

The app missed a number of rules that are called by other rules. Suggest that you check out the code of Rule References Rule Table by @thebearmay.

Edit: A couple comments about the legend. The app is shown as a circle when it is s square in the map. There is no reference to a device. It would be great to have a down arrow to collapse the legend that is replaced by an up arrow to bring it back in view.

[JimB]

Tried to load the update for external dependancies. Got this error:
Ambiguous expression could be either a parameterless closure expression or an isolated open code block; solution: Add an explicit closure parameter list, e.g. {it -> ...}, or force it to be treated as an open block by giving it a label, e.g. L:{...} @ line 1, column 1.

[gordon.thelander]

That error looks like Hubitat may be trying to compile JSON as Groovy, which would explain the line 1, column 1 message. I’m not sure where that path would be coming from in Automation Map itself.

Could you send me a screenshot showing exactly what you clicked or where you were when you got the error, ideally including the URL or import/update screen?