Adapter Overview

In Mortar.io adapters map building networks, devices, and transducers to the Mortr.io schema. Here XMPP Pubsub Event nodes store items that contain structured meta data and data streams for a device. Adapters live on the Driver Layer as can be seen in the Architecture diagram above.

Registration of Devices

The first step to start an adapter is to generate the event nodes that the adapter will listen and publish to. In Mortar.io, event nodes provide an abstraction of devices and transducers. Visit the Mortar.io Schema wiki to learn more about how to represent meta information and data.

First a UUID is generated that is the event node's address. Once a node is created with this address, it is possible to fill in the meta information. This meta information contains device and transducer descriptions.

The meta_tool was written to ease the generation of meta data for common devices, as well as to copy meta data from other devices. The meta_tool can be found in [mio]/adapters/register_tools/ . Make and read the readme to determine what devices and options are available.

User Considerations

If Respawn is to be used, the Respawn XMPP user must subscribe to each of the device event nodes. This way Respawn will receive data streams as well as updates to the device meta information. As a note, until IPC is fully functional it is recommended that each adapter have its own user associated with it. This means that the building or network administration user should also be given write access to these generated nodes.

Adapter Interface

Examples of this standard method of writing an adapter can be found in the adapter directory of the repository. The main reference file for adapter authoring can be found in the Mortar.io repository at [mio_path]/adapter/adapter.c. Refer to this file for the rest of this section.

Further information about running adapters in the context of an IPC Daemon can be found in the Services/IPC Daemon section.

Configuration

The responsibility of the adapter configuration function is to initialize adapter context based on meta information contained within event nodes.

To do this the configuration tool takes the adapter's reference node and then generates the context for the adapter to run. The adapted devices are the children of this event node and contain further configuration. This configuration is the necessary to communicate with the end device or service. It also determines how values are mapped to the Mortar.io Schema. This information is be stored in property fields of device and transducer metadata. The parser will also allocate resources the driver may use, and initializes the connection to the underlying network.

Once this process is completed the adapter parser should return the adapter context. The adapter parser should also spawn another thread that listens to this adapter node, so that as new devices are added they automatically added to the adapter's context.

Data

The data thread of an adapter periodically publishes transducer values. The periodicity depends on the underlying limitations of the native driver and how often the installer is interested in receiving data from the device. For example, in a low powered wireless sensor deployment the user may want to preserve battery by sending fewer messages, while a high frequency power monitor may produce many messages every second. More information on how to store high frequency data is detailed on the Respawn page. These transducer values are published, optionally batched together, to the transducer data items of the device's event node.

Actuation

Actuation requests are published to the [uuid]_act event node. This separates access control between being able to change device data and representation, and device state. The actuation thread listens for actuation requests and then acts upon them. If the actuation is performed succesfully, the new state is then published to the data node.

Drivers

Drivers provide an interface between your code and the native interfaces of the end device. Rather than directly writing this functionality within the interface code, it is suggested to use or write a library for your end protocol.

Drivers used in Mortar.io:
bacnet-stack
libmodbus
libpup see repository [mio_path]/adapters/drivers/libpup/
libhue see repository [mio_path]/adapters/drivers/libhue/

mio-arch.png (94.2 KB) Christopher Palmer, 11/13/2014 12:38 PM

Gateway_Node.png (55.9 KB) Christopher Palmer, 11/13/2014 03:01 PM

Adapter_Node.png (52.2 KB) Christopher Palmer, 11/13/2014 03:18 PM