Lights#

Every entity in picoides.io has it related state object. It s a representation of device state describing basic and more specific properties of a device.

State#

Example

light device state object

{
  "attributes": {
    "alert": 0,
    "brightness": 255,
    "brightness_pct": 100,
    ...
    "last_set_state": "",
    "last_update": "2018-12-13T11:23:41.192940+00:00",
    "locked": false,
    ...
    "platform": "picoides",
    "problem": false,
    "state_pending": false,
    "status": 0,
    "supported_features": 1,
    "temperature": null
  },
  "entity_id": "light.s5a_nema_06_01_2",
  "last_changed": "2018-12-12T12:10:14.171368+00:00",
  "last_updated": "2018-12-13T11:23:41.193961+00:00",
  "state": "off"
}

Note

entity_id - links state object to entity

state param#

the state param of state object describes the most basic status of device if it's on or off...

Example

state property of state object

{
  ...
  "state": "on"
  ...
}

picoides.io devices of light domain can take states values listed below:

on - device is on and emits light *
off - device is off and does not emit light *
unknown - state was not set *
~~problem - state is or should be known to the system but device reports errors~~
~~unavailable - device is registered in system but not yet connected~~

Note

state of light may equal to real on or off or to last_set_state

state attributes#

state attributes describe additional device parameters

Example

state attributes of light

{
  ...
  "attributes": {
    "alert": 0,
    "area": "",
    "brightness": 255,
    "friendly_name": "dev no 3",
    "latitude": 0,
    "longitude": 0,
    "power": 100,
    "problem": false,
    "state_pending": false,
    "status": 1,
  },
  ...
}

picoides.io devices of light domain can take state attributes values listed below:

status - value from 0 to 15 listed in table of status codes
alert - value from 0 to 15 listed in table of alert codes
brightness - takes values from 0 to 255 represents current brightness where 0 is off and 255 is 100%
power - power consumed by device in Watt (W)
problem - boolean True or False value related to state and alert. If set to True indicates possible error
[DROPED] ~~rssi - RSSI value of radio module~~
state_pending - boolean True or False. When set to true indicates that last request for it's entity was not confirmed yet

Extra features attributes#

Some light devices are installed with extra module like power metering chip or termometr. Parameters monitored by additional equipment extend state attribute object. Details may vary on implementation on equipment used and it setup.

Supported features are described by supported_features filed. It is a 16-bit bitfield value. Id bit is set device supports feature

bit	feature	description
0	BRIGHTNESS	light can be dimmed
1	COLOR_TEMP	can change temperature of emitted light
2	EFFECT	supports additional effects like ex. fading
3	FLASH	can flash
4	RGB_COLOR	is RBG LED
5	TRANSITION
6	XY_COLOR
7	WHITE_VALUE
8	HW_TOGGLE	if set light is turned on/off separately from dimming
9	DIMM	light can be dimmed
10
11
12
13
14	TEMPERATURE	can read temperature
15	POWERMETER	can return power supply related information

Example

{
  "current": "17.27A",
  ...
  "friendly_name": "Panel LED",
  ...
  "last_set_state": "on",
  "last_update": "2018-12-13T12:59:18.186661+00:00",
  ...
  "mean_active_power": "37.99W",
  "nominal_power": "30.00W",
  "platform": "picoides",
  "power_factor": "0.95",
  "problem": false,
  "state_pending": false,
  "status": 1,
  "supported_features": 1,
  "temperature": "14.62°C",
  "voltage": "231.57V",
  "voltage_sag": false
}

status codes#

Code	Name	Description
0	Off
1	On
2	Problem	Indicates error
3
4
5
6
7
8
9
10
11
12
13
14
15

** - codes not set in table above are reserved for future use

alert codes#

Code	Name	Description
0	Ok	Device is ok, no errors
1
2
3
4
5
6
7	comm_error	Device response indicates error on communication
8
9
10
11
12
13
14	No_Answer
15	Not_connected

** - codes not set in table above are reserved for future use

Services#

light services work same way as all services. In some cases services support additional service_data params.

turn_on#

fields#

brightness : Number between 0..255 indicating brightness example: 120

brightness_pct : Number between 0..100 indicating percentage of full brightness example: 47

Example

$ curl -X POST -u "testuser:YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       -d '{"entity_id": ["light.dev_unique_name_2"], "brightness": 105}' \
       http://localhost:8123/api/services/light/turn_on

Tip

to dim the light (change brightness) use turn_on service with brightness param

turn_off#

Example

$ curl -X POST -u "testuser:YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       -d '{"entity_id": ["light.dev_unique_name_2"]}' \
       http://localhost:8123/api/services/light/turn_off

toggle#

Example

$ curl -X POST -u "testuser:YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       -d '{"entity_id": ["light.dev_unique_name_1", "light.dev_unique_name_2"]}' \
       http://localhost:8123/api/services/light/toggle

poll#

fields#

state_attr : Name(s) of entity state attributes to poll example: mean_active_power, state

Example

poll state of light

$ curl -X POST  -u "testuser:YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       -d '{"entity_id": ["light.dev_unique_name_2"]}' \
       http://localhost:8123/api/services/light/picoides_poll

poll current attribute of light

$ curl -X POST  -u "testuser:YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       -d '{"entity_id": ["light.dev_unique_name_2"], "state_attr": "current"}' \
       http://localhost:8123/api/services/light/picoides_poll

poll temperature

$ curl -X POST  -u "testuser:YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       -d '{"entity_id": ["light.dev_unique_name_2"], "state_attr": "temperature"}' \
       http://localhost:8123/api/services/light/picoides_poll