Troubleshooting Entities

Focusing on a Single Device

Sometimes, particularly when trying to do mappings for new entities, it's expeditious to reduce the set of entities (for devices) that Reactor publishes. This reduces the "noise" in the logs from other entities.

To focus on a single entity (or a small number), we'll use an entity filter. If your controller configuration includes an accept_entity section, only entities listed in this section will be accepted from the hub. Entities are listed in this section by providing the entity's ID (not the canonical ID — the canonical id shown in the Entities list shows you the controller ID, which is the part before the ">" character, and the entity ID, which is the part after). Armed with this information, you can configure Reactor for focus:

Consider making a copy of your reactor.yaml and logging.yaml files before doing this, to make it easier to undo the changes you will be making.
Stop Reactor completely using pkill -QUIT node if you are using the run script, or if using a Docker container, by stopping the container.
Open the configuration file reactor.yaml and go to the controllers section;
Change enabled to false on each of the listed controllers, except the controller that publishes your target entity. Leave that one enabled. You can tell which controller is which by matching the value of the id key.

Go the to config subsection for the controller that publishes the entity, and add the lines indicated below (use your own entity's ID where device_123 is shown):

config:
  source: ...  # placeholder; DO NOT add this line
  # Add the lines below, or add entries to the "accept_entity" and
  # "dump_entity" sections if they are already there.
  accept_entity:
    "device_123": true
  dump_entity:
    "device_123": true

Confirm that in the previous step, you have indented properly, using only spaces (no tabs), with the entity IDs indented two spaces (only) from the accept_entity and dump_entity lines.
Before you save the file, take a note of which controller class is used by looking at the value of the implementation key.
Disable the engine by setting the enabled key under engine, which is under the reactor key. This will prevent your rules from running when most entities are missing (because they are now filtered out). That change looks like this:
```
reactor:
  baseurl: ...etc...
  # "location" and other config things not shown for brevity/clarity
  engine:
    enabled: false
```
Save the file.
If you want to change the log level for the controller or entity, do so now, then come back here and continue.
Start Reactor. If you are using a Docker container, start the container as usual. Otherwise, from the reactor directory (where app.js is located), type node app.js -N to start Reactor in stand-alone mode with no engine.

After 15 seconds or so, the log will have captured the initial data, and a dump of the initial data received from your hub/endpoint will also be created in your logs directory. You can stop then Reactor.

Copy or archive the reactor.log files and any device dump files in the logs subdirectory (when in doubt, take it all) before continuing.

When you are ready, restore normal operating by undoing the reactor.yaml changes (or copy your backups over the modified versions), and then restarting Reactor in the usual way.

Don't forget to re-enable the engine!

Don't forget to re-enable the Engine! Your rules won't run if you don't re-enable it.

Device Dump Files

The above procedure both configures entity filtering/focusing, and enables a dump of the data received from the hub/gateway for the subject entity. This can be very useful in troubleshooting problems with entity attributes in particular. The dump files are placed in the logs directory, and are JSON formatted data named controllerid-entityid.json. You can (and should) attach these to any requests for new device support, or problems with existing device support.

Updated 2021-Aug-13