Merge adapters and add-ons into one settings item.

[flatsiedatsie]

For a long time the difference between adapters and add-ons wasn't clear to me. There must be a reason I can get a list of them in the settings menu, I thought.

Now I know that adapters are basically just add-ons without settings. It's literally one setting in a json file that demarks them.

My question is: why tell the user about this conceptual difference? After all, what can I do on the adapter page? I can't add an adapter, I can't remove one, I can't change settings.

Adapters are confusing. When I wanted to create an add-on it turned out I had accidentally created an adapter instead. The two terms are used intermittently in the github pages, and as a new beginning developer it wasn't al that clear to me which one I should choose, and how that mattered in where I should get started.

It could be even more confusing for the end user. A user may already understand the add-on concept from Firefox and other software, but the term 'adapter' has fewer solid connotations and conventions to fall back on. What do users gain from this extra list, except confusion, and a sense of "this probably matters, but I don't know why"?

Merging them would have a lot of practical advantages.

• In the interface it would declutter the settings page, which already has a lot of options.
• If an adapter gains settings at a later moment in its development cycle it would currently jump to the add-ons page. That's what happened in my case too. But if it started out on the add-ons page it would already be there, and it would just gain a settings button.

Sidenote While on the subject: I mentioned that the difference between an adapter and add-on is basically a single toggle. To add to the confusion, this revealed that the term 'plug-in' is used somewhere under the hood as well:

"plugin": true,

The add-on system is great and generally well thought out. It could be used for more things that the gateway may want to add into the system in the future.

To that effect I would suggest a small change to the json file structure. From "plugin": true, change it to a list. Something like:

plugin: ["add-on"]

What this would do is create a list of ways that this tarball could expand the gateway.

For example:

plugin: ["add-on", "theme", "app", "notifier"]

In this case it would indicate:

• "add-on" would indicate it should show up in the add-on page.
• "notifier" would indicate that it even brings along new notification functionality.
• "app" could mean that it would like a place in the main menu and have a large page to show content/settings.
• "theme" would indicate that it has brought along a CSS file.
• "dashboard" would indicate that it brings along a new display type for the dashboard.
• "property" would indicate that it adds a new property to the gateway.
• "icon" would indicate that it brings a new icon pack with it.
• etc.

Related pages: Notifier: https://github.com/mozilla-iot/gateway/issues/1758 Dashboard: https://github.com/mozilla-iot/gateway/issues/1597 UX extension / app: https://github.com/mozilla-iot/gateway/issues/1505 Theme: https://github.com/mozilla-iot/gateway/issues/1827

[tim-hellhake]

Correct me if i'm wrong but aren't those two different things? The addon is an extension for the gateway. The adapter is an object which manages devices. For example the hue addon creates multiple adapters if you have multiple bridges. If you want to verify if all bridges are detected you can look in the adapter list in the settings.

[mrstegeman]

Let's clear up some terminology.

• Add-on: An extra bit of code that adds functionality to the gateway
• Adapter: Some code that interfaces with external hardware in some way
• Plugin: Really just an internal concept for the gateway. The gateway used to run add-ons in-process. If plugin was set to true, it would be run out-of-process. That distinction is only used for testing these days.

So, we can have adapter add-ons that interface with, say, Sonos devices, but in the near future we may have notifier add-ons and extension add-ons as well.

A better question for @benfrancis is whether or not we even need to show the adapters in Settings, as it's not super useful.

[benfrancis]

Thanks for explaining the terminology @mrstegeman.

@flatsiedatsie wrote:

Now I know that adapters are basically just add-ons without settings.

Hopefully it's now clear that this isn't quite correct, though I agree the representation in the UI has the potential to be confusing to users.

An adapter add-on is a type of add-on (currently the only type, but there will be more in future) which can theoretically handle multiple adapters (e.g. the Zigbee add-on can manage multiple instances of a Zigbee adapter). The add-ons view lists software packages which have been installed and the adapters view lists instances of adapters that are being managed by adapter add-ons.

The most simple case is that a single add-on manages a single software adapter which talks to a single hardware dongle (e.g. the Zigbee add-on manages a Zigbee adapter talking to a physical Zigbee dongle over a serial connection). However, more complex cases are possible like the Zigbee add-on managing two Zigbee adapter instances talking to two separate Zigbee USB dongles, or instances of two different software adapters sharing access to the same physical hardware (common with Wi-Fi or Ethernet, currently tricky with Bluetooth).

A better question for @benfrancis is whether or not we even need to show the adapters in Settings, as it's not super useful.

The rationale behind this separation was that an add-on may manage multiple instances of an adapter, therefore there needed to be a list of add-ons and a list of adapter instances (which don't have anything you can configure but may list unique identifiers individual adapters).

I was never quite happy with this rationale because in practice the distinction is usually irrelevant to the end user, but it was felt necessary because of the complex cases that are theoretically possible with DIY hardware. However, these cases are probably less likely with consumer hardware for which all the physical radios are likely to be built directly into the gateway hardware rather than separate USB dongles.

I'd therefore be quite happy to remove the adapter list from Settings to prevent confusion, or alternatively bury the list of adapters inside the configuration screens of individual add-ons to make them less prominent, which may actually also better represent the underlying architecture.

@dhylands Do you have any corrections to my explanation or objections to simplifying the UI in this way?

[dhylands]

That seems correct. I'd still like to be able to see information about an adapter instance. Like which serial port is being used? Which hardware identifier is associated with it (serial number)? Which devices are associated with it? Right now, if you rename a device you can't tell if its a zigbee device, or a zwave device, or something else.

[flatsiedatsie]

Thanks for the responses.

To be clear, I understand there is a distinction. But to me, as an outsider, it's.. small? technical?

As mentioned, I don't think it's very relevant to an average end user.

As an add-on/adapter/plugin developer, I also don't really care, since the codebase I use is exactly the same. The adapter manager is just another file in the folder to me that I can do something with, or not. I guess multiple instances of the same adapter aren't on my radar - I can't imagine why I would want to plug in two Zigbee/Bluetooth/etc USB sticks at the same time.

Perhaps there could be an option in the developer settings to enable the adapter page? Perhaps it could be expanded to make it more relevant to developers? For example, the items in the adapters list could become buttons that filter a log of internal messages that is shown along side it. Then it would truly be very helpful for development. (On the other hand, that could be a privacy nightmare.)

Another 'go big' idea would be to make it more relevant to end users. If the goal is to show which devices are connected to which dongles/hardware, then perhaps the page could be upgraded to show a nice graphical hierarchical map of all this? Perhaps with a toggle on the developer options this map could then also show the technical details @dhylands mentioned, and perhaps the latest few log messages for each add-on/adapter/device/thingimabob.

Overall though, the suggestions mentioned in the thread above sound terrific to me.

[tim-hellhake]

For me as a user the separate menu point in the settings makes the impression that addons and adapters are somehow equal. The relationship would be more clear if the adapters were located under the addons they belong to. I agree that they aren't entirely useful at the moment. But when they contain more info like the current state (available/unavailable) it would be useful to determine the source of an error.

[benfrancis]

@flatsiedatsie wrote:

If the goal is to show which devices are connected to which dongles/hardware, then perhaps the page could be upgraded to show a nice graphical hierarchical map of all this?

I do quite like the idea of a network map view which shows a graphical representation of the network topology. More of a power user feature, but could be useful on a router. I've filed #1842 for that.

In the meantime I think we can do something simpler by removing the Adapters option from the top level Settings menu and possibly moving adapters inside Add-on configuration screens.

[mrstegeman]

Duplicate of #1976.