Application Porting Guide for ADC

Follow

Exosite's Advanced Device Connectivity (ADC) feature was enabled for all new Businesses created on Murano after it was released on May 25. This feature brings with it a few changes that may require updates to Application Solutions. Application Solutions that were created before the ADC release will need to be modified in order to be deployed into Businesses that have ADC enabled. This article describes how to port Application Solutions to work with ADC.

 

Note: ADC includes a wealth of new connectivity features. It is likely that any solution would benefit from an update to use these new features. However, this article covers only the minimal port path to work with ADC.

 

What Changed?

The following describes what changed with ADC.

Product Endpoint Domain

ADC enforces devices connecting to Murano to use their specific Product Endpoint. Previously a Product Endpoint domain took the form of <product-id>.m2.exosite.com, and while not supported, devices could also connect to the base m2.exosite.com domain. With ADC, devices must connect to the Product Endpoint domain which is retrievable from the Product UI or via the Murano CLI.

For existing products that used a ‘<product-id>.m2.exosite.com’ domain, that domain will continue to work without any change required for devices connecting to Murano.  However, if your devices were connecting to the unsupported ‘m2.exosite.com’ domain, then the devices need to be updated to use the domain endpoint specified in the Product UI.

 

Device Service API

Before ADC, there was a single Service, Device, that provided a single unified Event Handler and API for interacting with all Products associated with an Application Solution. It provided an API that was extremely simple but also limited in functionality. ADC introduces a new Device Service, Device2, that is specific to each Product that is associated with an Application Solution. This new Device Service has an expanded, much richer API.

Version 1 Device Service API: http://docs.exosite.com/reference/services/device

Version 2 Device Service API: http://docs.exosite.com/reference/services/device2

Calls that Applications make to the Version 1 Device Service must be changed to the equivalent Version 2 Service calls. Shown in the table below are the Version 1 APIs and their equivalent Version 2 APIs. See the porting steps at the end of this document for an Adapter Module you may add to your solution that will perform this mapping for you. 

Device Service Function

Device2 Service Equivalent

Comments

Device.create() - Whitelists a new device.

Device2.addIdentity()

Device2.addIdentities()

 

Device.list() - Get the list of devices for a product.

Device2.listIdentities()

 

Device.write() - Write data to a device.

Device2.setIdentityState()

Device2.setIdentityState() does not trigger a Device Service Event, though Device.write() did. See ADC Resources.

Device.productInfo() - Get product information.

Device2.getGatewaySettings()

For resource information use Config.solution().

 


Note:
The Device2 service must be called using your Lua Product Alias, e.g. Lightbulb.setIdentityState() rather than Device2.setIdentityState(). This will be shown in greater detail in the porting steps below.

 

Device Service Event

Another change with ADC is that when devices connect, disconnect, or write to ADC, the event is routed to a Event Handler specific to that Product's Device Service. Previous to ADC, the Event Handling code was shared between Products. Additionally, the name of the incoming table providing event information changed from "data" to "event" and its structure was modified.

Version 1 service event: http://docs.exosite.com/reference/services/device/#datapoint

Version 2 service event: http://docs.exosite.com/reference/services/device2/#event

 

Porting Steps

In order to fully port your Application Solution, there are two overarching changes that will need to be made:

  1. Modify the location of your Product Event Handler code as well as its contents
  2. Switch from using the Device Service API Version 1 to Version 2 across all Application code

 

Porting the Product Event Handler

  1. Move your existing Product Event Handler code into a new module
    • The code should be moved into a function that takes a single parameter: 'event'
    • In the module handler code, build-out the 'data' object that your existing code is expecting from the 'event' object (see attached file event_wrapper_example.lua at the bottom of this page for the wrapper)
  2. In the Product Event Handler from which you removed your code (Services > Products via the UI), call the new module function and pass it the event object
    • This step should be done for each Product associated with the Application

For an example of how the steps above have been employed, see the Home Automation Example Application.

 

Porting from Device Service API Version 1 to Version 2

Note: For the purposes of illustrating the necessary changes and reducing the time it takes to port, Exosite has created a DeviceAdapter module which we will discuss in the steps below. This should be thought of as a temporary solution to keep things working, but over time, best practice will be to rewrite your code to use the Device2 Service directly rather than passing calls through this module. 

  1. Create a new module for your DeviceAdapter module code (see attached file device_adapter_module.lua at the bottom of this page for the provided code)
  2. Update the config table in the DeviceAdapter module
    • If more than one Product is associated with your Application, there should be one table entry for each.
    • If your business is ADC Enabled, set adcEnabled = true
    • Update the 'adcProductServices' table to specify your Product ID and the corresponding Lua Script Alias (found via the UI under Services > Products)
  3. Go through all of your Application code to identify each place the Device Service is invoked. (i.e. Device.<function>’)
    • Update these calls to Device functions to their equivalent DeviceAdapter functions. For example, a call to Device.list(...) should change to DeviceAdapter.list(...). The parameters remain the same.

Note that some small details regarding how the Device API worked have changed in DeviceAdapter. For example, previously list() provided a table of device tables that included an RID that was a 40 character unique ID for that device. The adapter provides that RID but it is variable length, based on the product and serial number. Because any application code that is dependent on the RID field is unlikely to rely on the specific format of device RIDs and only their uniqueness, this is unlikely to affect you.

Also note that the DeviceAdapter module is intended to simplify porting Application Solutions-- it does not take advantage of new ADC features. ADC's Device Service Version 2 provides a wealth of new APIs that can be used for things like firmware and device management. Additionally the Event Handler can respond to device connect and disconnect events. However, by starting with the DeviceAdapter service, it is possible to gradually port a Solution to make calls directly to the Device Version 2 Service functions.

 

If you have questions about porting your solution to ADC, please contact support@exosite.com.

Have more questions? Submit a request

Comments

Powered by Zendesk