Implement a Custom Hono HTTP Protocol Adapter
Eclipse Hono™ comes with a default HTTP Adapter which can be used to interact with devices via HTTP. The default HTTP Adapter also serves as a blueprint for implementing a custom HTTP protocol adapter.
This section will guide you through the steps to build your own custom HTTP protocol adapter.
You should be familiar with the setup and start of Hono. Refer to the Getting Started guide.
The standard HTTP Adapter
Hono’s HTTP Adapter supports telemetry and event data processing. Please refer to the HTTP Adapter User Guide and HTTP Adapter Admin Guide for details regarding the usage and configuration of the HTTP Adapter.
You can find the source of the HTTP Adapter at https://github.com/eclipse-hono/hono/tree/master/adapters/http.
Anatomy of the standard HTTP Adapter
Like many other Hono components, the HTTP Adapter is built on top of the Vert.x framework.
The HTTP Adapter’s
VertxBasedHttpProtocolAdapter class is derived from an abstract base class. This base class implements the
standard functionality for component initialization, receiving HTTP requests from devices or external clients, and forwarding
of data to the downstream AMQP Messaging Network.
Derive a custom HTTP Protocol Adapter
Use the standard HTTP Adapter as a blueprint.
In Vert.x, a route is a mapping of an HTTP request to a handler. Inside a route, Vert.x provides a
instance which gives access to the HTTP request (and response) object containing the HTTP headers.
The standard HTTP Adapter overrides the abstract method
addRoutes(), provided by the base class, and adds routes for
processing telemetry data and events.
// route for uploading telemetry data router.route(HttpMethod.PUT, String.format("/telemetry/:%s/:%s", PARAM_TENANT, PARAM_DEVICE_ID)) .handler(ctx -> uploadTelemetryMessage(ctx, getTenantParam(ctx), getDeviceIdParam(ctx)));
The route for telemetry data parses the HTTP request, extracts the tenant and deviceId parameters from the
request URL path, and forwards the message payload to the method
uploadTelemetryMessage(), provided by the base class.
Note the Vert.x place holder indicators
: inside the URL path pattern
/telemetry/:%s/:%s. Vert.x makes matching
place holders available as request parameters.
See Capturing path parameters in the Vert.x documentation.
The route for events looks very similar to the route for telemetry data. It forwards the event message payload to the
In the custom HTTP protocol adapter adapt the routes according to your needs.
Build and run the custom HTTP Protocol Adapter
If you have Hono running, you can launch your custom HTTP protocol adapter as a Docker Container or a Quarkus application.
You may adopt the Maven profile
build-docker-image from the Maven POM file of the standard HTTP Adapter into your
custom adapter’s Maven POM file.
Follow the guidelines for running the HTTP Adapter in HTTP Adapter. Don’t forget to configure the custom protocol adapter to bind to a different port than the standard HTTP Adapter if you intend to run them both at the same time. See the Port Configuration section of the HTTP Adapter documentation for details.
Using the custom HTTP Protocol Adapter
Now that you have your custom HTTP protocol adapter up and running, you can use any HTTP client, like
HTTPie, to publish data to your custom adapter.
Note that before publishing data to your custom HTTP protocol adapter, you need to start a consumer for the tenant you intend to publish data for. Otherwise you will not be able to successfully send data. For this purpose, you may use the example consumer as described in the Getting Started guide.
Further extend the custom HTTP Protocol Adapter
The abstract base class includes additional hooks which you may use to plug into the adapter’s life cycle:
||called before start of adapter’s HTTP server|
||called after successful start of adapter|
||called before stop of adapter’s HTTP server|
||called after successful stop of adapter|