Casambi - Developer site Beta

Documentation

API - Frequently Asked questions

General

When outside the EU, what is the policy on where and how we store data for the client in line with the API?

Currently all Casambi API data is stored in EU. Separate discussion have to be started if you want the data to be stored in some other area. In regards if you want to store data (received from API) related to your own networks currently there are no limits about that.

When using API and Gateway and there are 2 or more Casambi Mesh networks, do I need to have multiple API keys?

In general one API key is enough to use API services. To access multiple networks one must have related credentials for creating API sessions. But amount of building, gateways or networks does not affect the amount of API keys needed. API key is organization specific and is used to identify, monitor and limit API use on organization level.

In some cases might be good idea to have more than one API key to be used for different use cases show that API usage can be monitored on use case basis.

Is there a Standard dashboard for OEMs to use the API? It would be useful to have Casambi standard dashboard to manage the network without needing to develope a custom dashboard.

Possibily coming in the future. No timeline yet.

When will we have full D4i support through API? To be able to create a dashboard with all mandatory and non-mandatory memory bank fields covered by the DALI D4i standard.

This is in the backlog but there are obstacles. Firstly this will require update to Gateway, Server and API code. Also D4i is read only and performance will be an issue too. Timeframe for this is subject to 'roadmapping'. So best answer is in the future.

Rest API

Is it somehow possible to control light dimmers through REST API (instead of websockets)?

Currently no, but we are planning to add some support to control luminaires via REST API.

I made REST API request but got HTTP Status 404 as reponse, what does this mean??

HTTP Status 404 means that requested data was not found. Make sure that you were using the correct parameters for the data.

I got HTTP Status 401 as reponse to my REST API request, why??

HTTP Status 401 means that authentication failed, either given credentials or API key was invalid.

The session ID's created with REST API user (or network) session request, do they have a usage limit or do they expire like the KEY API?

Session ID's are long lived. Normally they can be used for months before they expire. Once Session ID has been created for user (or network) it can be used many times for other REST API requests and WebSocket Open message.
Anyway it is recommended to implement functionality to create a new session ID when old one has expired.

Does Casambi have a test environment with data I can use to test the REST API requests?

No, currently there is no test environment like this. Simply put to use the API one should have own network with needed devices. In some special situations it is possible to create temporary test network but in general that is not done unless there is a really good reason for it.

Datapoint requests

When requesting data from the "datapoints" endpoint of the REST API, the presence sensor value is a float number. When observing a presence sensor on the websocket connection the presence value is a string "present" or "absent". What causes these two values to be presented differently?

In datapoints REST API result set the float number value for presence sensor holds two different details (presence and duration history). Negative value tells how long sensor state was "absent" and positive value how long it was "present", value 0 can be ignored. Duration history is given with float value (other than 0) presenting the duration between events. The duration (float) value is set to the beginning of each state-interval and it is given in seconds. In other words the event is logged when the duration is known.
The event data received via WebSocket is delivered "in real-time" whenever the state of the presence sensor changes and thus the value is simplified to string values.

How often sensor data is pushed from the gateway to server?

Data is streamed without any delays whenever event occurs.

How long datapoint data is stored on the database, is there a time limit on how long that is available?

Datapoints are stored for 60 days on Casambi server. For longer storage it is recommended to fetch datapoint data once per week (or in shorter time period) and store them in client side.

How can I request the energy stats of an luminaire?

You can make REST API datapoints request with "dataType" filter option set to "energy". Energy related data is only available from devices that have support for this kind of functionality.

Note that full datapoint data are only available if both data logging options have been turned on (Gateway App -> Network -> Gateways -> Gateway -> Sensor Data & Usage of Devices).

About the "energy_total" data point, what are the units, kWh, mWh or other?

The energy_total value is given in Wh and is total energy consumed by the device. At the fixture level, there is total Energy --> sum of sub-devices. E.g. for total energy the results are Wh (double), even if device have kWh values. By the specification, devices provide VALUE and SCALE FACTOR, where the scale can be various multipiers x1, 0.1, 0.01, 10x, 100x etc.

Note that energy datapoint data is only available if related data logging option have been turned on (Gateway App -> Network -> Gateways -> Gateway -> Usage of Devices).

What do different options for datapoints filter option "dataType" mean?

DataType filter options:

Related info can be found here: Datalogging and API

Note that full datapoint data are only available if both data logging options have been turned on (Gateway App -> Network -> Gateways -> Gateway -> Sensor Data & Usage of Devices).

When datapoints are reported by the device is there any data processing/manipulation done?

No, datapoints come as they are sent from the devices.

WebSocket

Is there any other possibility to use the API to control Casambi-powered light appliances without having a phone/tablet gateway just for this purpose?

Currently no, but we are developing new Gateway device that would not require dedicated phone for this purpose.

Which has higher priority of operation, the instructions through the Casambi App or the control messages through the Casambi WebSocket service (with API Key)?

There is no difference. App and WebSocket are using the same method to control the devices so which ever comes first goes first.

Is unit that is only capable of On/Off toggling possible to control via WebSocket?

Currently no, but we are planning to add support for this in the future.

What’s the latency in the webSocket service? Are luminaires control commands sent via the WebSocket more or less instantaneous?

Yes they are happening in "real-time". The logged data appears in the database (becomes available in API queries) with about 1 min delay.

We no longer receive any control arrays or dimLevel information with WebSocket unitEvents. What is wrong?

This sounds like gateway has stopped functioning for some reason. Check that bluetooth connection is on and that the gateway device is not sleeping. Try disconnecting and reconnecting the gateway device and if that does not work then try resetting the gateway app or using a different smartphone as gateway.

If any of this does not work then contact Casambi Support.

Are motor-control devices supported through WebSocket control at all at the moment?

No, only luminaire control is possible via API.

We have a Luminaire unit with 2 dimmer controls (white balance) - how can we set the value for one the other in the WebSocket packet? It looks like current protocol does not support this scenario or maybe there is an alternate syntax for doing this?"

Currently not supported in API but this feature is on the list for next API version.

Is it possible to control integrated Hue lights through Casambi cloud API?

No, only luminaires that are part of the Casambi network can be controlled via Casambi API.

Gateway

In the "Data Collection" section of the gateway settings, what does the "Status update interval" slider adjust?

The slider adjusts how frequently (DALI) energy counters and other D4i information is retrieved.

What is the difference of Sensor Data and Usage of devices?

The "Sensor data" is for collecting and logging "default" data from sensors. The "Device usage data" is for collecting and logging of the "rest" of all supported data - dimming levels, DALI details, energy counters (D4i) data. Basically "Device usage data" is used to enable active periodic collection of data by the gateway in addition to data collected by "Sensor data" option.

How "full" data logging features can be enabled? Is it something done from the app or?

There option to enable "Sensor data" is in the apps Gateway settings page. Also there is option to enable "Usage of devices". It can be done only after the Gateway "On this device" option is activated, i.e. after connection is established as server applies logging policy upon connection.

Note that if this is not initially done in the right order then (for legacy reasons) it is required to disable/re-enable gateway to get it working as expected.

What exactly is "luminaire usage" in the app gateway settings? Does it report dimming levels and how long luminaires have been ON or..

Luminaire usage as "Usage of devices" refers to state of the controls (dimming levels, color, custom elements, etc); additionally energy counters, DALI details of devices in network fixtures is scanned and DALI diagnostics data are collected. The "control state" of devices is aggregated usually within 1 min intervals.

Is the data on the gateway buffered if the connection to our server drops? For example, what happens if the connection is down for several hours?

Data is not buffered in mobile gateway. Without connection it is not logged. That being said data buffering is something worth considering and something might be done about this in future.

Is the API able to receive the all values from the luminaire that a DALI D4i driver provides and can be seen in the app?

Some if not all D4i data that is received from devices (via mobile gateway) is included in the "details" part of the unitChanged events via API WebSocket service. This data is also decomposed into DATAPOINT entries and can be (at least in some parts) requested via REST API datapoints requests.

To enable this Dali data become visible via API the "Device usage data" option in the apps Gateway settings must be set on. It will activate background tasks in the gateway to scan all devices for DALI data periodically. There is slider to set interval between these scans (min 30min, max.. 1 week). After settings are changed, the gateway needs to be reconnected by disable/enable toggle in the app for full data logging to start working.

Related info can be found here: Datalogging and API