Skip to content

# 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:

1. 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.
2. Stop Reactor completely using `pkill -QUIT node` if you are using the run script, or if using a Docker container, by stopping the container.
3. Open the configuration file `reactor.yaml` and go to the `controllers` section;
4. 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.

5. 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

6. 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.

7. Before you save the file, take a note of which controller class is used by looking at the value of the `implementation` key.

8. 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

9. Save the file.

10. If you want to change the log level for the controller or entity, do so now, then come back here and continue.
11. 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