Availability: Not all APIs were readily available (e.g., described in an unrestricted webpage or downloadable document). Some required contacting the CLS developer, who in some instances provided the API readily, and in others required an explanation of why the API was being requested and how it would be used. Some required a signed nondisclosure agreement in order to obtain API access or documentation.

Authentication schemes: APIs used a wide variety of authentication schemes – some over unencrypted HTTP, others over secured HTTPS; some with a simple cleartext key, and others with a cryptographic hash authentication key. Integration required support of multiple schemes, subjecting the integrated environment to different cybersecurity vulnerabilities.

Resource structure: System resources described in APIs were named and organized in myriad – and, in some cases, inconsistent – ways, with significant variation in structure, nomenclature, and complexity. Although some APIs had a logically consistent resource-tree structure, others were apparently developed incrementally over multiple version releases, as more features were added over time; incremental extensions were not always implemented consistently or logically.

Data models: APIs used a wide variety of data models, each apparently custom-developed. Custom data models are not always well designed or documented, or even self-consistent. Data might exist in very different locations within API resource trees : (e.g., /devices/< device_id >/resources, /reports/api/monitoring), and very different naming conventions or labels (e.g., /lt/dim, LuxLevel, brightness, dimming), units (e.g., absolute lux, relative % illuminance), and data types (e.g., integer, floating point) are used for seemingly similar or at least related parameters. In some cases, models from different systems may be functionally incompatible.

CORS support: Some API developers supported CORS, while others either did not, or did not do so readily (i.e., it was difficult to find the vendor staff who could whitelist access from specific domains).

Historical data access: Some CLS did not provide API access to historical data outside a certain time window, or only provided real-time data. In some cases, the real-time update rate was unspecified, seemingly inconsistent, or asynchronous, and was dependent on how frequently the CLS could be queried through the API.

RECOMMENDATIONS

• CLS developers should make their APIs readily available and ensure that documentation is synchronized with software updates. Further, they should facilitate easy, efficient bug reporting.
• The lighting industry, and perhaps the IoT industry as well, should consider developing and adopting a common approach to authentication, with some minimum level of resistance to cybersecurity vulnerabilities.
• CLS developers should enable CORS, secured by the use of HTTPS together with authentication and authorization schemes.
• CLS developers should name and organize API resources in readable, logical, and consistent ways.
• CLS developers should fully document API data models, including reporting unit (when applicable), data type, resolution, and accuracy.
• The lighting industry, and perhaps the IoT industry as well, should consider developing and adopting a well-thought-out, modern, and evolving common resource organization.
• The industry should consider developing and adopting well-thought-out, maintained common information and/or data models. These models should be created by entities with application expertise specific to the information or data model.

Software coding: Such integration requires some degree of software coding. Although the type and amount of coding required can vary by the approach pursued, integration via APIs requires more than configuration and validation. Integration via an existing “platform” might require less development time – in particular, if the platform was designed for, or has been previously used to implement, intended use-cases. However, the use of such “platforms” typically comes with tradeoffs between user-friendliness, functionality, and flexibility. Further, they must be maintained to address hardware, firmware, and software updates, and ideally support new systems as they enter the market.

Harmonization: In lieu of sufficient documentation, system integrators may have to ascertain, sometimes through crude trial-and-error experimentation, what an available API resource represents and what information and data model it uses. Converters or translators may need to be developed to handle inconsistent data models. Further, an information model that suitably encompasses the myriad data models to be integrated may need to be inferred, in order to effectively aggregate data or broadcast commands, for example.

Maintenance: Integrating multiple CLS through APIs does not result in a homogenous system; at best, it yields a common user interface and experience. However, effectively hiding the underlying complexity can require a significant amount of backend integration work. Managing what functionally remains a distributed system at one or more layers can be challenging and effortful. Differences between network protocols, device representations, and access policies that affect performance must be understood, addressed (if possible), and managed – not only initially, but over the course of hardware, firmware, and software upgrades.

RECOMMENDATIONS

• API developers should explore approaches to reducing system integrator effort – for example, by providing support for multiple measurement units and time aggregations for reported data, and support for controls schemes beyond switching between or pushing out of new device profiles.
• API developers should consider the implementation of publish-subscribe models for reported data.
• API developers should consider the implementation of override or prioritization schemes that support adaptive control of configurable system devices.
• DOE intends to continue to identify and explore viable interoperability approaches. System integrators, industry consortia, and CLS developers should inform DOE when existing or new interoperability approaches reach new levels of functionality, viability, or market adoption.

The implementation of real-life use-cases can expose previously unseen or unanticipated issues. Often, this occurs when a design constraint, boundary condition, or tradeoff is challenged by the functional or performance requirements of the use-case. Implementation can also lead to the identification of new or additional API functionality or features that might support, or better support, both the use-case under investigation as and other use-cases.

In this study, implementation of an energy data aggregation use-case exposed issues beyond the impact of working with different data models. Energy measurement accuracy and resolution were generally unspecified in marketing literature and API documentation, raising concern as to how to statistically treat data from different sources. Further, the lack of API access, in some cases, to historical energy data required the system integrator to query the CLS in real time and log energy or power data, thereby requiring dedicated storage and computing resources.

In this study, the implementation of a broadcast lighting command use-case exposed latency differences between systems that might arguably compromise both the functionality and performance needs of the use-case.

RECOMMENDATIONS

• CLS developers should support user exploration of new and previously unproven use-cases and facilitate easy, efficient bug reporting.
• DOE intends to continue to identify potentially high-value use-cases and explore how well they can be implemented by integrated heterogeneous CLS using available interoperability approaches, as well how they might be enabled by interoperability between CLS and other systems. Lighting-industry stakeholders should provide DOE with suggestions for use-cases to explore and estimates of their relative value.