Auroral custom adapter example

This blog entry is describing how to create your custom adapter for AURORAL platform, in case when already built programatic and semantic adapters don't fill your needs. For simplifying this procedure we prepared a very basic adapter in Python, so it is easier to explain the required integration steps.

Adapters need to connect AURORAL Node with your infrastructure, so its main purpose is to provide requested data from your underlaying infrastructure. In this example we are retrieving only random values generated in Python, however, in a real example it would be necessary to connect with your data source.

Source code

Find here the GitHub repository

Preparing AURORAL Agent

Auroral Node needs to know where it should get data from when requested. Basically, the AURORAL Node acts as a proxy, relaying the requests coming from AURORAL network towards the adapter(s). For this purpose we use ADAPTER_MODE option in Agent .env properties.

There are three options:

DUMMY

SEMANTIC

"properties": {
    "room_temperature": {
      "title": "room_temperature",
      "monitors": "AmbientTemperature",
      "measures": "degreeCelsius",
      "readOnly": true,
      "type": "number",
      "forms": [
        {
          "op": [
            "readproperty"
          ],
          "href": "http://example.com:1234/<your_custom_API_endpoint>"
        }
      ]
    }
  }

PROXY

Agent uses these standard predefined HTTP calls to retrieve data from adapter: – GET: ADAPTER_HOST:ADAPTER_PORT/api/property/<OID>/<PID> for getProperty request – PUT: ADAPTER_HOST:ADAPTER_PORT/api/property/<OID>/<PID> for putProperty request

When you are registering items, given Thing Description is enriched with URLs pointing to your adapter (format described above)

In this custom adapter we are using PROXY mode, but it is also possible to use SEMANTIC mode. Then you need to take care of adding correct form URLs in your Thing descriptions.

Settings in .env Agent file:

ADAPTER_MODE=proxy
ADAPTER_HOST=http://myhost
ADAPTER_PORT=4444
USE_MAPPING="true"

Use of Mappings

Regardless the adapter mode chosen (proxy or semantic), the AURORAL Node can inject context data to enrich the measurements returned by your adapter. This is a builtin feature of the Agent, that's takes care of enriching your provided value with mapping, generated from Thing description. If you disable this feature, you need to build Auroral standard message format on your own (in adapter).

You can choose to disable this feature in the .env file —> USE_MAPPING = false

Preparing custom adapter

Note: This example uses the proxy mode, however could be easily adapted for the semantic mode by updating the API that the adapter exposes.

We setup connection from Agent to Adapter in previous step, so now we need to ensure, that Adapter will be accesible in this URL. We chose myhost (what is actually your machine running docker or localhost) and port 4444, so we need to start our adapter on this port.

The adapter in your infrastructure needs to match OIDs (Object IDs – Auroral object identifier) with some ID in your infrastructure. For this purpose you are allowed to choose AdapterId during item registration. This needs to be unique, and helps you to select proper object in your infrastructure. There is a prepared endpoint in Agent (/api/registration/oid/<adapterId>) for retrieving OID by AdapterId.

Your adapter needs to expose an API to respond requests from the AURORAL Node. In the case of the proxy mode the endpoint will look as follows.

GET <host>:<port>/api/property/:oid/:pid

So for example one strategy is to register things with known adapterId, and once your adapter is started, retrieve OIDs of your objects, store them, and use them later for matching correct object. This strategy is also used in this example of custom adapter.

For calling the API of the AURORAL Node Agent, the Adapter needs to know its URL. This is configured in adapter's .env file, together with array of monitored objects (by adapterId)

AGENT_URL="http://localhost"
AGENT_PORT=81
ADAPTER_IDS="testAdapter1, testAdapter2"

Running custom adapter

There are several ways how to run this adapter. We will describe running in python virtual enviroment and running inside docker:

Python virtual env

Docker

We also prepared simple Dockerfile, which allows you to run this adapter inside docker. In this case you need to change host settings in adapter and agent. – Building image: docker build -t customAdapter . – Running docker container: docker run -d --name MyAdapter -p 4444:4444 customAdapter

Brought to you by the AURORAL community, keep posted! 💪