[Collaboratively] Device capabilities, help needed!

Emile · December 2014

Hi all!

I would like to give this amazing community a chance to help with defining a very important part of Homey. Hear me out.

Homey has apps, and an app has a driver. A driver is a piece of code that controls a device. For example, a Philips Hue light bulb is a driver.

A driver belongs to a category (in the Philips Hue example the category 'light'), and has capabilities, e.g. things that it can do. So for the Philips Hue light bulb a driver would look like this:


{
			"name": "bulb",
			"category": "light",
			"capabilities": [ "onoff", "brightness", "hue", "temperature" ]
		}

Now I'm working on compiling a list of capabilities, which a device within a category can have. This is very useful, for when I say for example "Hey Homey, turn the lights to red", Homey searches for lights with the capability `hue` and then turns those to red.

The following list I have just started working on, but I'd like to hear suggestions so we can together make it complete!


light.onoff
light.brightness
light.hue
light.temperature

socket.onoff
socket.dim

climate.temperature.heat
climate.temperature.cool
climate.temperature.measure

appliance.

security.access.lock.open
security.access.lock.close
security.monitor.camera.view
security.monitor.camera.move
security.monitor.entered
security.monitor.left

media.tv.channel
media.tv.onoff
media.tv.volume
media.video.play
media.video.receive
media.audio.speaker
media.audio.receiver

So.. discuss!

MarcoF · December 2014

How abstract or details do you want/need this to be?

security.access.door.open example; garage door up/down
security.access.door.close example; garage door up/down

appliance.onoff
appliance.startstop some machine need to be power on first and then push an start button

cjvs · December 2014

Hi, nice to see that input can be given! With your example I was wondering how Homey would be aware of the setup you may be using. For instance:

I would say, "Homey, turn on the living room lights". My livingroom has 2 lights, one driver is a hue bulb, the other driver is a socket with an ordinary lamp plugged into it. Homey would have to trigger:

light.onoff
socket.onoff

Homey would have to know that the socket should then be part of the category "light", rather than only the category "socket". Or, would I define the socket as part of the category "light" since I have a lamp plugged into it?

Further to above, I was thinking off:

energy.p1.measure
energy.gas.measure
energy.solar.measure

somfy.open
somfy.close
somfy.my

climate.humidity.measure

Just to be sure, is it the first (e.g. issues) or the latter (e.g. examples) you are looking for?

MarcoF · December 2014

@cjvs;
Currently i'm using a Vera3 and here i also have the lighting issue. Several lights are behind a Greenwave socket switch(kitchen Leds, small reading light) and also i have Philips Hue in the livingroom. I created a scene with an LUA table that contains all lights in the livingroom and when i fire that scene, all the devices in that table are switch on/off. I solved it this way, because the Vera isn't knowing that the sockets are switching lights...

I don't known how this could be solved...

MarcoF · December 2014

1 minuted to late to change my previous post;

[edit]
Associated devices, automatically get an Category and Subcategory number.
These number represent (sub)device types and users can change these numbers. Theoretically an Socket switch could be moved/changed to another type.

The greenwave socket switches initially were created with
Cat=3 (DEVICE_CATEGORY_SWITCH)
SubCat = 0 (DEVICE_SUBCATEGORY_NONE)

This could be change to for example;
DEVICE_CATEGORY_DIMMABLE_LIGHT

But getVera has no "real" light category, only Switch of DimLight.

http://wiki.micasaverde.com/index.php/Luup_Device_Categories

So i don't known if its an good idea to create an "fixed" driver for an certain device. In my case i have several Fibaro 2x1,5kW relays in my home;
- One in the bathroom and switches the LED lights and a small fan in the shower-area
- One in the backyard switching Lights and an small fountain

2 the same modules, with 4 the same relays and switching 3 different devices.

JeroenKleijn · December 2014

I think it should be possible to edit the category when added a device.
so a dropdown menu or something.

example:
on a kaku or fibaro socket it can be 2 categories (maybe more?). light or just a switch.

My two cents for the list:
security.monitor.camera.snapshot
security.monitor.camera.recordStart
security.monitor.camera.recordStop

Question about the capabilitie security.monitor.camera.view.Where will it be view since the Homey has no screen?

Emile · December 2014

A little clarification on the socket would've been good I suppose

Right now, a socket is a special kind of category, and is merely a placeholder for a 'virtual' device. So when you tell Homey to set up a socket, it then asks you what's behind it. You will be able to choose from every device from every category that has an `onoff` capability, or `Other ...` and you just give it a name yourself (e.g. lawn sprinkler).

@cjvs, thanks for the suggestions. Also for @everyone, somfy in this case is too specific. We will replace it by `appliance.curtains`, `appliance.blinds` and `appliance.sunscreen`.

I hope that clears something up. Good suggestions, keep 'em coming!

Nattelip · December 2014

i have philips hue, but also a lot other rgb leds with other drivers.
so hue as the only controllable rgb led driver gives troubles when you also want to turn other then philips hue to red. maybe rgb as capability. ?

why use arrays, stick to the way philips hue uses json , property with value's like "name" : "bulb" ie "rgb " : "true".)
they have one array (ct) which gives little problems in javascript but big ones in XX.net

Emile · December 2014

@nattelip, hue does not refer to philips hue, but to the capability to 'change the light's hue' (e.g. color, but a color consists of hue/brightness/saturation/temperature)

RobinVanKekem · December 2014

In addition to your:

climate.temperature.heat
climate.temperature.cool
climate.temperature.measure

climate.control.onoff
climate.control.mode -- auto/cool/dry/wind/heat
climate.control.setTemp
climate.control.setSleepTimer
climate.control.cancelSleepTimer
climate.control.windLevel -- auto/low/mid/high/turbo

Emile · December 2014

Great Robin, thanks!

RuudVroon · January 2015

I'm not sure how, these are going to work:
media.audio.speaker
media.audio.receiver

but maybe these capabilities are also necessary:
media.audio.mode (surround, stereo etc)
media.audio.input (channel eg. optical, coax)

Do you also need new capabilities to send commands like: teletekst, menu, up, down, left right, red etc to the TV?

Emile · January 2015

That would then become:

media.audio.receiver.mode
media.audio.receiver.channel
media.tv.teletext

PeterGroeneweg · January 2015

Hi Emile,

For my job I worked with stuff which used a .mib file for all there variables. This is a kind of tree-structure where it is very easy to navigate to the right variables. If you want I can add a picture of the looks. This way it is very easy for the programmers and make life much easier.

MariusBrand · January 2015

For my gas fireplace:

fireplace.fire.on/off
fireplace.fire.up/down
fireplace.control.setTemp

JaapPelt · January 2015

Hij Emile,
Thank you for sharing thuis question with community. I enjoy reading the comments and I can't wait to see what the final product can do.

Personally, I would like more distinction between setting or reading a value. Some switches are senders, others are receivers and others are both. My thermostat is even more complex as I can set the target temperature, read the target temperature, read the actual temperature indoors and outdoors.

Is there a reason a socket an light are different? Both can switch on-off and/or dim. Can't they both be switches?

Kind regards,
Jaap

Emile · January 2015

@Jaap,

All capabilities have read and write possibilities, where applicable. You can then select which apps have access to do what.

The sockets are different because they do not nescessarily control a light. If you connect a coffee machine, it becomes a coffee machine. So these are a 'virtual' device, configurable by the user.

JaapPelt · January 2015

Hi Emile,

It makes sense that the driver takes care of the read/write capabilities and that it does not need to be distinctly specified in the definition of a device.
I like Robin's Sleep timer suggestion. It would be nice to say "Hey Homey, I'm going shopping" which would turn the heater low for an hour. My thermostat supports a temporary override like that.

security.access.lock.open and security.access.door.open would be a nice distinction. Lock can apply to the cylinder lock while door can indicate if the door is actually open or closed. Both can also apply to windows which can be opened, closed, locked and unlocked remotely.

Sockets are still interesting. I see little added value of a socket group over a appliance group as a appliance (or a light) is generally connected to a socket. I guess it all depends on how everything comes to gather as a whole and you guys are the ones with the full picture.

Who will be writing these definitions? I have looked at OpenHAB in the past which used a similar definition system, but I thought it was not user friendly to write the definition yourself for each device. I really like what they are doing with a device having one or more connected things (a philips hue bridge has multiple lamps). Is this similar to what you are doing with drivers and these definitions?

[Collaboratively] Device capabilities, help needed!

Comments