Services

picoides platform supports it's own domain and associated services. Services from other domains (light, switch, ...) executed on devices that belong to picoides platform are handled by services described below.

Tip

both picoides and entity domain like light services can be used to control same device

GET /api/services/

JSON string of services defined within picoides domain

{
  "domain": "picoides",
  "services": {
    "picoides_service": {
      "description": "Domain top level service",
      "fields": {}
    },
    "poll": {
      "description": "Request to poll data from device",
      "fields": {
        "entity_id": {
          "description": "Name(s) of entities poll data",
          "example": ["light.unique_name", "sensor.powermeter_id"]
        },
        "state_attr": {
          "description": "Name(s) of entity state attribute to poll",
          "example": "mean_active_power"
        }
      }
    },
    "toggle": {
      "description": "Toggle device output state",
      "fields": {
        "entity_id": {
          "description": "Name(s) of entities to toggle",
          "example": ["light.unique_name", "switch.some_switch"]
        }
      }
    },
    "turn_off": {
      "description": "Set device output to off state",
      "fields": {
        "entity_id": {
          "description": "Name(s) of entities to turn off",
          "example": ["light.unique_name", "switch.some_switch"]
        }
      }
    },
    "turn_on": {
      "description": "Set device output to on state",
      "fields": {
        "brightness": {
          "description": "[light domain only] Number between 0..255 indicating brightness",
          "example": 120
        },
        "brightness_pct": {
          "description": "[light domain only] Number between 0..100 indicating percentage of full brightness",
          "example": 47
        },
        "entity_id": {
          "description": "Name(s) of entities to turn on",
          "example": ["light.unique_name", "switch.some_switch"]
        }
      }
    }
  }
}

POST /api/services/picoides/<service>

picoides_service

Top level service of picoides domain. This is internal service intendent to use within domain it self.

Danger

although it is possible to use picoides_service directly from API it should be avoided!!! use one of services described below instead!

turn_on

Turn on picoides platform device. Service sends request to target device to set "on" state on hardware output. For light devices this is to set the relay on (close circuit) and optionality set desired dimming for the device if supported. In case of switch only state of relay is supported.

fields

entity_id : Name(s) of entities to turn on example: light.kitchen

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

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

Example

(no brightness)

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

(with brightness)

$ 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/picoides/turn_on

turn_off

Turn off picoides platform device. Service sends request to target device to set "off" state on hardware output. For light or switch devices this is to set the relay off (open circuit).

fields

entity_id : Name(s) of entities to turn on example: light.kitchen

Example

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

toggle

"Toggles" state of device. Sets device output to state opposite to it's current state. Set on if state is off and set off if state is on.

Note

For multiple devices or group entity all devices in list would be set to state equal to state of first device or group state.

fields

entity_id : Name(s) of entities to turn on example: light.kitchen

Example

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

poll

Service makes request to get data from target device(s). Data to poll will depend on device type. For some lights it would be only state, if it's set on or off. Some light devices comes with power meter chip installed or ADC connected this kind of devices would support more data params.

Parameters additional to state that can be polled from device are listed here

fields

entity_id : Name(s) of entities to turn on example: light.kitchen

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

<domain>/picoides_poll

Some domains supported by picoides platform have additional service picoides_poll registered. This service is alias for services/picoides/poll that can be called within domain.

Example

poll state

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

poll mean_active_power parameter

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

poll state of switch within it's domain

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

Using services

When picoides.io instance receives request to change state of device from supported service the request is routed to desired device. Many things can happen on the way from Your request to device taking action. It is very likely that executing this request will take some undefined time, for many reasons like ex. slow network or queue of other tasks to be done first. For this reason after passing forward Your request instance assumes the job was done and sets local state object of entity to desired state even before the job actually done. After device gets and executes the job it sends back confirmation or failure information. When instance of picoides.io receives this information state object is modified accordingly.

State attribute named state_pending can be used as request confirmation flag. When set to true indicates that last request for it's entity was not confirmed yet.

For more details on devices state attributes see picoides/platform_states/