This section is designed to guide you through the process of setting up and managing state ingest from your various devices to the Okos Polip platform. Our goal is to make it as straightforward as possible for you to connect and monitor your devices, regardless of their complexity or capabilities.
TLDR; An introduction to the concept of device state ingest, explaining what it means, why it’s important, and how Okos Polip handles this process efficiently.
Overview
Device state ingest is the process of getting data (state, sensors, etc.) from your physical device to the cloud. At its most basic it is a one-way uplink of device state data. Think of it as a way for your device to “talk” to the cloud and get responses back.
Okos Polip support the following channels:
- State Data (bi-directional UP/DOWN)
- Example: The RGB color of a light bulb controlled by a microcontroller
- Sensor Data (uni-directional UP)
- Example: Ambient noise level in the room captured by an embedded microphone
- Remote Procedure Calls (bi-directional UP/DOWN)
- Example: Setting a timer event on hardware which will signal back to cloud when complete
- Meta Data (uni-directional DOWN)
- Example: Description of the device stored on the cloud that device can request
- Manufacturer Data (uni-directional DOWN)
- Example: Configuration data stored on the cloud that device can request
- Errors and Notifications (uni-directional UP)
- Example: Device battery voltage dropped and needs to send an alert
Where UP is from device to cloud and DOWN is cloud to device.
For small teams and independent hobbyist getting a well-defined generalized device-to-cloud (and cloud-to-device) solution is expensive to build in house. Furthermore, building a robust pipeline is not in-of-itself a differentiator for a specific home automation product. But device-to-cloud is needed; developers can leverage third-party software solutions to bridge the gap. Often these systems are hard to set up and maintain, have a hard vendor lock-in, and may force particular hardware controllers into your product.
Okos Polip strives to be a simple solution that can run on anything with an HTTP library
Supported Devices
A core value of Okos Polip is to be platform agnostic as far as reasonably possible. Anything that can eventually send an HTTP POST request to a JSON REST API is capable of using the device state ingest service. That being said there are some things to consider.
Okos Polip maintains device state ingest client libraries for:
- C/C++ (for example Arduino)
- Python (with ROS support)
- Javascript / Typescript
Devices generally need:
- HTTP library and means to resolve ingest service routes. C/C++ client library relies on callbacks to generalize against user supplied HTTP libraries. Python uses requests and Javascript uses axios to make HTTP POSTs.
- Enough RAM to store JSON buffers and HTTP message buffers. Actual size depends on application and libraries used.
Nice to have:
- Additional RAM to support HTTPS protocol
- Cryptography support to compute hashed message tag (and support HTTPS efficiently)
- Real-Time Clock (RTC) or use Network Time Protocol (NTP) clock for timestamps
Picking a Client Library
Step one of integrating with Okos Polip is picking the right client library for your system.
If you are writing in C or C++ on baremetal or an RTOS then check out the the C/C++ client library. For instance, if you are using an ESP32 or Arduino development board you would want to use this library.
Running Linux (such as on a Raspberry Pi or Nvidia Jetson)? We recommend starting with the Python client library for ease of development. If you need something more performant you can always build an application against the C/C++ library.
Working with ROS? Check out this Python wrapper.
If you are building a project with Javascript or Typescript Okos supports it.
Don’t see your projects language or want to write something custom, refer to the HTTP REST API documentation here.