Connect devices using a proprietary protocol via a third party protocol adapter

[mhemmeter]

Currently projects in the IoT often use proprietary protocols for connecting devices to the respective backend systems. After such projects are deployed to production it is often hard to change their firmware and switch to a different protocol like MQTT.

Eclipse Hono provides a concept to connect such devices via a custom protocol adapter (see Implement a Custom Hono HTTP Protocol Adapter). My understanding is that such a protocol adapter is supposed to be operated by the Eclipse Hono service provider and connects directly to the AMQP 1.0 messaging network. This concept is however not applicable in a setup where a third party deploys and operates the protocol adapter (e.g. due to the fact that the service provider cannot force tenant specific limits in that setup).

Therefore I think it makes sense to provide support for third party operated protocol adapters in order to connect devices via a proprietary protocol (let's call this a "third party adapter" contrary to the "custom protocol adapter"). I see the following requirements:

• Third party adapters are scoped to a single tenant
• The third party adapter is authenticating devices and can but doesn’t need to use the device registry for persisting credentials
• As a service provider I have insights in the traffic that is sent by the third party adapter to northbound applications
• As a service provider I'm able to force limits for a customer connecting devices via a third party adapter (e.g. max processed data volume for this tenant)
• Third party adapters can be used in setups where devices connect directly to the third party adapter and where devices connect via a gateway to the third party adapter (e.g. smart home scenario where the smart home gateway connects via a proprietary protocol to the third party adapter)
• Third party adapters can be scaled dynamically, when and how adapters do scale is in the responsibility of the third party adapter provider
• All requirements must be fulfilled by Eclipse Hono and not by the AMQP 1.0 messaging network implementation (just for the sake of completeness as it would be probably possible to fulfill the requirements on the messaging network level)

Looking forward to your feedback to this issue.

[calohmn]

A straightforward solution for this would be to implement the "Third party adapter" as a gateway, connecting to a Hono AMQP adapter instance.
Devices would send telemetry/event messages via their own proprietary protocols to the "third party adapter" gateway which will then send the messages via AMQP to the Hono AMQP adapter.
A prerequisite for this is that the devices are registered in Hono and are configured in such a way that the gateway can act on their behalf (with a device registration "via" property containing the gateway id).

To support scaling the third party adapters dynamically, ie. using multiple instances of them, each third party adapter instance would need to be registered as a gateway in Hono and also be configured in the "via" entry of the devices.
In order to prevent having to add a new gateway instance to the "via" entry of all devices, the Third party adapter gateway instances could be grouped in a "gateway group".
The devices would then only need to reference the gateway group in their "via" property. There is already #1072, requesting such a gateway groups feature.

---

Concerning the requirements:

Third party adapters are scoped to a single tenant

The gateway belongs to a single tenant.

The third party adapter is authenticating devices and can but doesn’t need to use the device registry for persisting credentials

If the third party adapter needs access to the device registry, the corresponding device registry AMQP endpoint would need to be exposed (normally access is only needed from Hono adapters), along with having created corresponding credentials in the Hono Auth Server to be used for accessing the Device Registry.
If that has been done, using the device registry for authenticating devices would be possible.

As a service provider I have insights in the traffic that is sent by the third party adapter to northbound applications

Such insights would come from the AMQP adapter that the gateway is connected to.

As a service provider I'm able to force limits for a customer connecting devices via a third party adapter (e.g. max processed data volume for this tenant)

Done via the AMQP adapter.

Third party adapters can be used in setups where devices connect directly to the third party adapter and where devices connect via a gateway to the third party adapter (e.g. smart home scenario where the smart home gateway connects via a proprietary protocol to the third party adapter)

Having another gateway in front of the "Third party adapter" gateway only seems relevant for the discussion here if the devices in front of this other gateway shall also be managed via Hono.
If that is the case, this extra gateway would send device telemetry/event messages to the "Third party adapter" gateway. In line with how a Hono adapter handles gateway messages, the "Third party adapter" gateway should probably check the "via" property of the device to see whether the originating gateway is allowed to do that.
That would require the "Third party adapter" gateway to be able to access the device registry (see above).

Third party adapters can be scaled dynamically, when and how adapters do scale is in the responsibility of the third party adapter provider

Scaling can be done by creating multiple third party adapter gateway instances, as described above.

All requirements must be fulfilled by Eclipse Hono and not by the AMQP 1.0 messaging network implementation (just for the sake of completeness as it would be probably possible to fulfill the requirements on the messaging network level)

That is fulfilled.

---

What should/could be done in Hono to support such a scenario or to make it easier to implement:

• add support for gateway groups (Reference a group of gateways through which a device can send messages #1072)
• if all devices of a tenant shall be handled via such a gateway (group), it would be convenient to define a default "via" device registration property in the tenant configuration, referencing the gateway (group).
• provide a maven module containing utility classes for sending messages to the AMQP adapter (and potentially also for accessing the device registry). That shall make it easier to implement the "Third party adapter" gateway.
• consider adding the possibility to define one set of credentials shared by each of the "Third party adapter" gateway instances of one gateway group (used for authentication against the AMQP adapter). Would make handling of multiple gateway instances easier.

[sophokles73]

@calohmn

consider adding the possibility to define one set of credentials shared by each of the "Third party adapter" gateway instances of one gateway group (used for authentication against the AMQP adapter). Would make handling of multiple gateway instances easier.

I have a hard time imagining how this could work since the authentication identifier determines the device (gateway) ID. If all adapter instances would use the same credentials (and thus the same authentication identifier) then we would no longer be able to route a command to the correct gateway instance, would we?

[sophokles73]

Here's an idea that might work regarding the credentials shared by all gateway instances.

We could allow the protocol gateway instances to include a property in their AMQP connection which indicates their (stable) identifier. This identifier might be the identifier provided by kubernetes for pods of a StatefulSet. All gateway instances would use the same credentials for authentication with the AMQP adapter.

In the device registry, a single set of credentials is registered for the gateway instances. Let's assume the instances use a client certificate with subject DN CN=protocol gateway and a device ID of gateway.
Two gateway instances could then include connection property gateway-id with values gateway-0 and gateway-1 respectively. They would both be authenticated using the same client certificate and thus, during authentication, be mapped to (gateway) device ID gateway. However, the AMQP adapter could use the gateway-id value provided by the gateways instead of the device ID when it opens a receiver link for a device connected to one of the gateway instances, thus creating a unique mapping the Device Connection service for the device. This feature could be configured in the adapter configuration for a Tenant. The via property of devices registered might be set to a value that includes a wildcard, e.g. gateway-* in order to authorize a gateway instance's publishing of telemetry on behalf of a device.

[mhemmeter]

The proposed solution in this issue looks good to me. So nothing to add.

I did not have this as a priority in mind up to now but I think this concept could also be applied to scenarios where you want to connect another IoT cloud to Eclipse Hono. Therefore one would need to build an integration based on this concept in the respective IoT cloud (e.g. for TTN see https://www.thethingsnetwork.org/docs/applications/integrations.html). I need to check that in detail but this sounds very interesting to me.

[eriksven]

After reading through this issue I am slightly confused. @sophokles73 is your comment intended as alternative or as extension to the gateway group idea raised by @calohmn ?

Your comment seemed to only be targeted on the aspect of how to share the credentials among all instances of such a third party adapter. However, my understanding is that your proposal of adding the gateway-id as property in the AMQP connection and "sharing" the credentials among the gateway instances might already cover the requirements regarding the support of third party protocol adpaters.

You further mentioned:

The via property of devices registered might be set to a value that includes a wildcard, e.g. gateway-* in order to authorize a gateway instance's publishing of telemetry on behalf of a device.

For the communication and its authorization from the device through a third party protocol adatper/gateway instance to Eclipse Hono, I see no real difference between sharing the same credentials among all gateway instances and creating a group for all gateway instances. The gateway group is then either implicit through the gateway instances that share the same credentials or it is explicit through a gateway group concept.
As you already mentioned, the difference would be the opposite direction of sending commands through the gateway instance because you want to make sure to pick the gateway instance that is actually communicating with the device. Did I get that right? I am fairly new to the overall concept of how Eclipse Hono handles gateways and chances are that I am missing something.

Is this really needed or would it be sufficient to have gateway in the via property based on the @sophokles73's example? My understanding was that for the communication from the device to Eclipse Hono the via property is only needed to assert that the gateway is registered to act on behalf of the device. If they share the same credentials for gateway, every instance of the third party protocol adater/gateway would be authorized anyway. If we want to communicate from Eclipse Hono to the device there might be a last know gateway which one would identify through the gateway-id connection property. If there is no last known gateway and one has no choice than to guess which gateway instance from the know gateways suits best to reach the device, right? For both cases, I do not see a need to store the gateway-id connection property in the via list of the device. What am I missing?

This gateway-id could be stored within the AMQP adapter since your proposal seems to be pretty specific for that adapter. Or would you store that gateway-id through the Device Connection API (https://www.eclipse.org/hono/docs/api/device-connection/#set-last-known-gateway-for-device)? In that case the gateway_id for the last know gateway would not be a registered device but the gateway-id AMQP connection property, right?
I am not sure how good that would work e.g. for the case when another protocol adapter retrieves that gateway_id and is not aware that the id is not a device id but a connection property that is only known in the scope of the AMQP protocol adapter.

[sophokles73]

After reading through this issue I am slightly confused. @sophokles73 is your comment intended as alternative or as extension to the gateway group idea raised by @calohmn ?

It serves a complimentary purpose, namely that of being able to share credentials among third party protocol translator instances while still being able to route commands to devices connected to one specific protocol translator instance. It has nothing to do with the general idea of having gateway groups where each gateway has its own identity (and thus credentials). Gateways in a gateway group usually represent a physical entity, e.g. a Raspberry PI class device that is close to the edge devices. The approach outlined in my comment is more targeted at software components that need to scale out horizontally and for which we do not want to require the provider of the component to register each instance individually with Hono.

[eriksven]

@sophokles73 thank you for the clarification. I understand that the general concept of having gateway groups has no direct link to the adaptation of the AMQP 1.0 protocol adapter to allow the sharing of credentials. This is especially the case for gateway devices having individual identities.
My question was more related to the specific use case discussed in this issue of how to support third party protocol adapters. What caused my confusion is that at least my understanding of such third party protocol adapters exactly matched your description in:

The approach outlined in my comment is more targeted at software components that need to scale out horizontally and for which we do not want to require the provider of the component to register each instance individually with Hono.

So I was unsure whether we actually need gateway groups to support such third party protocol adapters or whether the adaptation to the AMQP 1.0 adapter and adding that (virtual) adapter device to the via list would be sufficient to solve this issue (#1478). But probably my understanding of third party protocol adapters was to specific to scaling software systems and one also needs to support cases where the instances of the third party adapter have individual identities?

If that is the case, which I assume for now, and we still decide for the gateway group solution to support third party protocol adapters, my summary of this discussion and the next steps to realize the core functionality for supporting third party adapters is then as already mentioned by @calohmn:

• add support for gateway groups (Reference a group of gateways through which a device can send messages #1072)
• provide a maven module containing utility classes for sending messages to the AMQP adapter (and potentially also for accessing the device registry). That shall make it easier to implement the "Third party adapter" gateway.

In addition, there are two features that make handling gateway groups of third party protocol adapters more convenient.

• if all devices of a tenant shall be handled via such a gateway (group), it would be convenient to define a default "via" device registration property in the tenant configuration, referencing the gateway (group).

This depends one the way gateway groups are implemented. But one can generalize this point to: "allow tenant wide reference to gateway groups". And then there is:

• consider adding the possibility to define one set of credentials shared by each of the "Third party adapter" gateway instances of one gateway group (used for authentication against the AMQP 1.0 adapter). Would make handling of multiple gateway instances easier.

As @sophokles73 described, this could be solved with a custom solution in the AMQP 1.0 adapter and is "only" needed when the third party protocol adapters scale out. Even though the scaling of the third party protocol adapters was among the requirements from @mhemmeter, I still prefer to create separate issues for this as it would allow to first focus on the general support of third party protocol adapters within this issue (#1478).

What do you think @calohmn, @sophokles73, @bs-jokri?

[sophokles73]

But probably my understanding of third party protocol adapters was to specific to scaling software systems and one also needs to support cases where the instances of the third party adapter have individual identities?

Yes, this is still necessary. The use case is simply: edge devices connect to a particular (physical) gateway device that is close by and use it to connect to Hono. However, the edge devices may roam around and connect to different gateway devices depending on where they are physically located. In this case it is much more convenient to add a gateway group ID to the edge devices' via property instead of configuring each of the gateway IDs individually ...

I still prefer to create separate issues for this as it would allow to first focus on the general support of third party protocol adapters within this issue

IMHO that is a great idea 👍

[calohmn]

Concerning the proposal above towards sharing credentials:

In the device registry, a single set of credentials is registered for the gateway instances. Let's assume the instances use a client certificate with subject DN CN=protocol gateway and a device ID of gateway. Two gateway instances could then include connection property gateway-id with values gateway-0 and gateway-1 respectively. They would both be authenticated using the same client certificate and thus, during authentication, be mapped to (gateway) device ID gateway.
[...] The via property of devices registered might be set to a value that includes a wildcard, e.g. gateway-* in order to authorize a gateway instance's publishing of telemetry on behalf of a device.

I think that could be a solution here, yes.
I'd suggest one change: As also noted by @eriksven above, I don't think we need to let the gateway instance id (e.g. gateway-0) be referenced in the via property. IMHO, the device id (gateway in the above example) should be in there, thereby removing the need for adding wildcard support to the via property.
The gateway instance id would then only be used as part of the Device Connection API methods ("set/get last known gateway" and soon the new methods for mapping the adapter instance id to a command subscription - #1272).

[eriksven]

Added a PR in #1670 for a 'memberOf' property for devices in the device registry to support gateway groups. As described above this could also be used to support third party protocol adapters.

[mhemmeter]

Thanks for the effort all of you put into this contribution. The features make Eclipse Hono more interesting for existing IoT solutions as it tackles the challenge of connecting devices that are already out in the field and use proprietary protocols.