Link Search Menu Expand Document

heyOOCSI!

There is no end to funny names in the OOCSI system. This time we talk semantics.

What is heyOOCSI?

The heyOOCSI extension allows to annotate your OOCSI clients with extra information, meta-data. And this information can be used in other clients, a data canvas or in the HomeAssistant system (see below).

The extra information captures:

  • location (“kitchen” or pixels (123,456))
  • properties (“power_consumption=12.3W”)
  • components (“I’m a sensor and I measure light.” or “I’m a LED lamp with dimmer.”)

With the location you can put your device on a map, such as a data canvas. Properties can be useful in discovering other clients and perhaps even negotiating communication or functionality.

While the location and properties of an OOCSI client are straightforward, the components need more explanation: Imagine you are designing a lamp that produces light with a range of LEDs and also has an integrated sensor for temperature and humidity. (Strange idea? Why not.) So, how to tell the OOCSI system what your prototype is and can do? In this case, we can add three components (or “entities”) to the device, a light and two sensors. You can read more about the information structure in the heyOOCSI entities page.

Adding heyOOCSI information to your prototypes

How to add this information? As usual, the code for adding heyOOCSI information depends a bit on your client platform. We have included examples in all libraries for reference. Let’s check out how to do this in Processing:

// standard connection to OOCSI
OOCSI oocsi = new OOCSI(this, "testHeyOOCSI-Processing", "server IP");

// create an OOCSI device for heyOOCSI information
OOCSIDevice doorLock = oocsi.heyOOCSI();

// add named location 'hallway' with pixel coordinates (on data canvas)
doorLock.addLocation("hallway", 200, 200);

// add property
doorLock.addProperty("creator", "Bob");
doorLock.addProperty("contact", "bob@example.com");

// configure this device with a switch 
// first parameter: name of the device
// second parameter: channel on which this component receives input and sends output
// third paramter: switch type (OUTLET, SWITCH)
// fourth: default state (true/false) --> here it's true to show that the door is by default locked
// fifth: icon name (see: https://materialdesignicons.com/)
doorLock.addSwitch("front_door_lock", "hallway_channel", OOCSIDevice.SwitchType.SWITCH, true, "door");

// don't forget to send the heyOOCSI information around
doorLock.sayHi();

Shall we do Arduino and ESP directly?

#include <OOCSI.h>
#include <OOCSIDevice.h>

// standard connection to OOCSI
oocsi.connect("testHeyOOCSI-Python", "server IP", "ssid", "password");

// create an OOCSI device for heyOOCSI information
OOCSIDevice light = oocsi.heyOOCSI();

// add property
light.addProperty("creator", "Eve");
light.addProperty("contact", "eve@example.com");

// configure the light with a textual location label and numerical coordinates
light.addLocation("living_room", 340, 240);

// add a light
// parameters: name, channel for updates, LED type (RGBW), spectrum type (0), default off, default brightness 150 and a "lightbulb" icon
light.addLight("ceiling_light", "living_room", "RGBW", 0, false, 150, "lightbulb");

// don't forget to send the heyOOCSI information around
light.sayHi();

And one more for Python?

from oocsi import OOCSI

# standard connection to OOCSI
o = OOCSI('testHeyOOCSI-ESP', 'server IP')

# create an OOCSI device for heyOOCSI information
device = o.heyOOCSI()

# add property
device.addProperty("creator", "Alice");
device.addProperty("contact", "alice@example.com");

# add example for location
device.addLocation("kitchen")

# create entities for the device:
# a sensor with name, channel, type, unit and default value 100
device.addSensor("sensor_name", "sensor_channel", "sensor_type", "sensor_unit", 100)
# a light with name, channel, LED type, spectrum, default value, brightness default, min/max, and icon name
device.addLight("light_name", "light_channel", "RGBW", "WHITE", False, 0, [0, 255], "lamp")

# don't forget to send the heyOOCSI information around
device.sayHi()

After creating the prototype properties we need to submit everything on the heyOOCSI! channel. We do this with the sayHi() function. As you can see, the examples look similar and work in similar ways. Check out the heyOOCSI entities page for further information on entity types and the different parameters that you need.

Using heyOOCSI with the OOCSI directly

Any heyOOCSI information is captured by the OOCSI server which is running an internal client called “heyOOCSIClient”. Over time, this client gathers information on the devices around in the OOCSI system and you can use this client as a service to inquire about a particular client’s info or location.

To get the latest heyOOCSI info for a given client, just send a message on OOCSI to “heyOOCSIClient” with the following content (fill in the client name that you are interested in):

// retrieve heyOOCSI information for a client
{"clientHandle": "client name for which you need the heyOOCSI info"}
// returns: standard heyOOCSI info JSON

You can also use the heyOOCSIClient to search for clients by location. The first option is to provide x, y pixel coordinates on the data canvas and a distance for the search radius. The heyOOCSIClient will then return a list of client names that have heyOOCSI info placing them in this area.

// retrieve all heyOOCSI clients/devices within distance from a location
{"x": 100, "y": 100, "distance": 50}
// returns: x, y, distance, and a list of clients in "clients"

The second option is to search by named location. Just send the following message to the heyOOCSIClient with a named location filled in, and you will get a list of client names that have heyOOCSI info placing them in this named location.

// retrieve all heyOOCSI clients/devices in a named location
{"location": "name of the location"}
// returns: location, and a list of clients in "clients"

Using heyOOCSI with HomeAssistant

HeyOOCSI is a new OOCSI feature to open up OOCSI devices to HomeAssistant! This allows you to control your prototypes and other smart devices more easily. Because HomeAssistant has a lot of integrations this makes your prototype compatible with even more data and actuators for you to work with. Create a new light switch for your brand new Philips Hue bulb or use your solar energy data to control your prototype!

What do you need? For heyOOCSI! to work you need a device running HomeAssistant and an OOCSI device. To set up HomeAssistant check this link.. After installing your fresh new HomeAssistant build you need to add the OOCSI component into the HomeAssistant folder (the same folder as the configuration.yaml file). To add the OOCSI server to HomeAssistant, go to the supervisor section in the bottom left. After that in the add-on store click on the three little dots in the top right corner. Here click add repository and fill in this link:

https://github.com/iddi/oocsi-web-docker

Please check the reference for the heyOOCSI! entities.

Copyright © 2013-2022 Mathias Funk.