Introduction


The energy consumption estimates are calculated for “dimmable” and on-off entities in a lighting network. Thus, entities which do not support the concept of dimming are not supported. The calculation maps the dimming level into energy level (Watts) within the range from zero to the entity’s maximum energy consumption using a dimming curve. Each luminaire or node on the Casambi network is metered according to the wattages provided. The only nodes that will be available for energy consumption are Casambi nodes that are displayed in the luminaires tab, so only loads that are connected to a luminaire.  The maximum energy consumption values and the dimming curve are defined by the lighting network administrator as part of the energy configuration for the network maintained using the Energy Monitoring Administration application. The energy monitoring API service is currently a separate service than the existing API console.  



Required Hardware/Software


Software

Casambis energy monitoring data is retrieved via the Casambi API. Therefore, any 3rd party or Ecosystem software that can display this data is not required but can be used to graphically display data. Please see the Casambi Ecosystem webpage for a list of softwares that are able to utilize this data. 


Hardware

The energy monitoring service is utilized via the Casambi API, therefore there must be a cloud connected device that will transfer the Bluetooth data to the cloud. This device can be any 'gateway' added to the associated Casambi network. These options include:

  • A phone/tablet running the Casambi app and the gateway is "on this device"
  • Casambi gateway (See the Ecosystem page for a list of possible hardware options)


Instructions


To utilize Casambis energy monitoring feature, there are 2 parts to this process. Users will be required to obtain the maximum wattage of each luminaire or zone and type of dimming curve of the associated LED drivers. 

Once these values have been determined and documented, Casambi will be able to deliver the energy data via API requests.


Below is the process for setting up and using the energy monitoring service. 



a. Import Luminaire Wattages



1. Head to the Energy Monitoring portal and login to the network with the administrator credentials by going to this link: Casambi Energy Monitoring Portal


2. Press 'Export' to download the .csv file of the associated network



   The .csv file will display the following properties for each luminaire of the network:


Column 

Editable 

Value 

NetworkEntityId 


Unique ID of the lighting network. 

NetworkName 

Administrator defined name of the lighting network. 

ChannelId 

Logical channel within the unit. 

ChannelName 

Name of the logical channel. 

UnitIndexId 

Index of the unit in the network. 

UnitName 

Administrator defined name for the unit. 

UnitVendor 

Manufacturer/vendor of the unit. 

UnitModel 

Model name of the unit. 

MaxConsumptionW 

Maximum energy consumption in Watts. 

Set to 0 (zero) in order exclude the entity from energy monitoring.  

DimCurve 

Curve type used to map dimming level to energy consumption. Mandatory if a positive MaxConsumptionW value is given. Valid values are: 

  • lin”: Linear dimming curve  

  • “log”: Logarithmic dimming curve 


3. For each of the luminaires on the network, input the maximum wattage and the dimming curve of the driver:

   For dimming curve, input "lin" for linear dimming curve or "log" for logarithmic dimming curve. 


4. Once all values have been inserted into the .csv file, save the file and upload it back into the online portal:


 from your computer, then


the populated .csv document.






b. Utilizing the energy monitoring API


Now that the values have been uploaded to the portal, users will be granted an API key for the energy values as shown below:



The energy consumption estimates for a lighting network can be queried through a web API endpoint described below.



API Request Specification 

HTTP Method 

HTTP GET 

URL 

https://door.casambi.com/v2/energyconsumption/<network-id>?from=<period-start>&to=<period-end> 

Parameters 

 

 

    <network-id> 

The unique ID of the target network. 

    <period-start> 

Start time of the period, inclusive. ISO 8601 compatible format with time zone defaulting to UTC if omitted. 

    <period-end> 

End time of the period, exclusive. ISO 8601 compatible format with time zone defaulting to UTC if omitted. 

Request headers 

 

    X-API-KEY 

Energy Monitoring API key of the network defined in the network configuration. 

Response code 

2xx on success. or a non-success HTTP response code indicating a failure. 

Response content 

application/json 






Request Example

 


HTTP GET https://door.casambi.com/v2/energyconsumption/ doTckqSSpC15JJod2Q770BHgAMBkxggU?from=2022-01-01 00:00:00&to=2022-01-02 00:00:00 

X-API-KEY: fuBSLFwNsyXLd8cEXLbEyBj4lrVZXDwrKcYvMLwGtxs 

<additional headers> 


Response Specification


Success is indicated in the response HTTP status code 200 OKA non-success HTTP status code indicates a problem in routing or processing the request. 

The body of the successful response is a JSON document with the following structure: 


Field 

Description 

Values 

manufacturer 

Manufacturer of the NLC system 

“Casambi” 

productid 

The unique ID of the lighting network 

From query parameter 

product 

Administrator defined name of the network 

 

timestamp 

Timestamp at server for the query 

 

periodStart 

Start time of the period, inclusive 

From query parameter 

periodEnd 

End time of the period, exclusive 

From query parameter 

energyData

Array of energy consumption estimates 

 

unitId 

Unit id/channel name combination 

For example, “1/dimmer” 

energykWh 

Energy consumption over the query period 

 

minutes 

Number of minutes within the period for which consumption data exists 

 



 

Response Example

 

200 OK 

    Content-Type: application/json 

    <additional headers> 

    ---body--- 

{ 

    "manufacturer": "Casambi", 

    "productId": "doTckqSSpC15JJod2Q770BHgAMBkwaiU", 

    "product": "Rigado 3", 

    "timestamp": "2022-10-25T10:18:47.8277705+00:00", 

    "periodStart": "2022-10-21T00:00:00+00:00", 

    "periodEnd": "2022-10-22T00:00:00+00:00", 

    "energyData": [ 

        { 

            "unitId": "1/dimmer", 

            "energykWh": 0.03862723, 

            "minutes": 1440 

        }, 

        { 

            "unitId": "2/dimmer", 

            "energykWh": 0.00070198, 

            "minutes": 1440 

        } 

    ] 

} 

Response example

 

200 OK 

    Content-Type: application/json 

    <additional headers> 

    ---body--- 

{ 

    "manufacturer": "Casambi", 

    "productId": "doTckqSSpC15JJod2Q770BHgAMBkwaiU", 

    "product": "Rigado 3", 

    "timestamp": "2022-10-25T10:18:47.8277705+00:00", 

    "periodStart": "2022-10-21T00:00:00+00:00", 

    "periodEnd": "2022-10-22T00:00:00+00:00", 

    "energyData": [ 

        { 

            "unitId": "1/dimmer", 

            "energykWh": 0.03862723, 

            "minutes": 1440 

        }, 

        { 

            "unitId": "2/dimmer", 

            "energykWh": 0.00070198, 

            "minutes": 1440 

        } 

    ] 

} 

 




FAQ



How long is energy monitoring data stored?

Casambi will retain energy consumption data for at least 2 years.


How often is the energy monitoring data available?

The energy data will be polled at a 15 minute interval. 


Why cant I see the energy consumption data?

The energy consumption data is not available immediately after configuration, there may be up to 2-hour delay before the energy consumption values are calculated, stored, and available through the 

Energy Consumption Data Access API.

 

What data is available via the Casambi API?

The energy monitoring API is currently a separate service from the existing Casambi API. At the moment, the energy monitoring service will provide the following datapoints:

  • Product ID Number
  • Product Name
  • Timestamp
  • Start/End time of the request
  • Dimmer Name
  • Wattage 
  • Time Period


Casambi REST & Websocket API can also provide a wide variety of datapoints other than energy:


REST API (for monitoring):

  • Network IDs
  • Network State
  • Scene Status
  • Luminaire Status
  • Luminaire Outputs
  • Sensor Status
  • Unit Icons
  • Network Icon
  • Gallery Information


Websocket API (control):


  • Change luminaire state (brightness)
  • Activate scene
  • Control a group
  • Control entire network 
  • Change color temperature 
  • Control brightness
  • Change color values