Overview
Welcome to the Casambi Developer Documentation. This guide provides comprehensive information about integrating with the Casambi platform using our REST API and WebSocket services.
This documentation covers Casambi REST API and WebSocket Service (beta version). In addition related javascript code examples and web console services are provided. Please note that to use REST API or Casambi WebSocket one must have valid developer API key.
Casambi WebSocket and API web consoles support Chrome browser. Functionality with other browsers is expected but not guaranteed.
To acquire API key contact Casambi Support.
This version of API and WebSocket services are still under development and that availabilty of API keys are limited until further notice. Feedback and feature requests are welcome.
Terminology
| Casambi mesh network | A network of Casambi devices that are connected via bluetooth connection. Each device can work independently and be connected to the Casambi cloud service via gateway application. |
| Casambi cloud service | Cloud service that enables information flow and data control of connected Casambi devices over secure internet connection. |
| Gateway | Casambi app that works as a gateway for Casambi devices and networks to connect to Cloud service. Gateway forwards bluetooth messages to Cloud service via secure internet connection. Gateway is required to receive real-time event data from a network. |
| Casambi app | Mobile app used to connect and control different Casambi devices. App connects to close by devices via bluetooth connection. Is used to create named virtual presentations and networks of these different devices. App can be used as a gateway to connect close by devices to Casambi cloud service. |
| Unit | Physical Casambi device that is part of the mesh network. For example LED light, light switch or sensor device. |
| Fixture | Casambi device hardware configuration information. Fixture defines in which way device will be used/work. |
| Network | Network is a term used in Casambi app and in Casambi systems. Network is a named virtual presentation of defined set of physical Casambi devices. Network can be created with Casambi app. |
| Scene | Virtual control/animation setting for some network or devices. Can control how the devices are animated/turned on/turned off in specified scenario based on timing, sensor information and other factors. |
| Group | Virtual group of Casambi light devices that is connected to a network and can be controlled via Casambi app. |
| Luminaire | Casambi light device. Can be connected to a network and can be controlled via Casambi app. |
| API web console | Web page that can be used for testing API requests and responses. Use requires valid API key. Web console can be found from here: web console. |
| API key | The API key is a unique identifier that is used to authenticate requests associated with the API. Developer can request API key from Casambi Support. Please note that availabilty of API keys are limited until further notice. |
| User session | When user logs in to Casambi API with Casambi (site) user credentials a user session is created with related session ID. This session is not same as the network session and has access to all networks, sites and related data of that user. User session and site user session mean the same thing and have access to all related sites (if any). |
| Network session | When user logs in to Casambi API with network (admin) credentials a network session is created with related session ID. This session is not same as the (site) user session and has access only to all networks and related data of used network credentials. This session has only access to networks created with the related credentials. |
| WebSocket wire | After WebSocket connection to server has been created server is waiting for a OPEN message from the client. In this OPEN message client defines the wire ID to be used in addition to some other details related to network and the connection. If OPEN message is successful wire identified by given ID will be created to the server and related event messages will be sent to it. Wire is unique to the Websocket connection. One websocket connection can have multiple wires at the same time. |
| Control | Casambi device can have one or many "controls" that relate to state and functionality of the device. Basically one "control" is presentation of specific functionality/state of the device. Information about device state, in other words "control" values can be received via WebSocket event messages. |
Datalogging and API
The Casambi REST API and WebSocket service provide access to various datalogging features. For comprehensive information about datalogging capabilities, please refer to the Casambi Data Logging and API guide.
For detailed datalogging documentation, contact Casambi Support.
Quick Links
- REST API - Complete REST API reference and examples
- WebSocket Service - Real-time event streaming with WebSocket
Resources
- API Console - Test REST API endpoints (external link)
- WebSocket Console - Test WebSocket connections (external link)
- Casambi Support - Customer support portal