Actions: Services

GET /api/services

Returns an array of service objects. Each object contains the domain and which services it contains.

Info

Services can be used for changing state of selected entity like ex. setting light (or group of lights) on or off. Picoides.io platform supports domains of light, switch and sensor. It inheritress services from this domains.

Most services will handle different service_data fields.

Request

Sample curl command

$ curl -X GET  \
     -u "testuser:YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
        http://localhost:8123/api/services

Response

[{
  "domain": "light",
  "services": {
    "toggle": {
      "description": "Toggles a light.",
      "fields": {
        "entity_id": {
          "description": "Name(s) of entities to toggle.",
          "example": "light.kitchen"
        },
        {
          ...
        },
      }
    },
    "turn_off": {
      "description": "Turn a light off.",
      "fields": {
        "entity_id": {
          "description": "Name(s) of entities to turn off.",
          "example": "light.kitchen"
        },
        {
          ...
        },
      }
    },
    "turn_on": {
      "description": "Turn a light on.",
      "fields": {
        "brightness": {
          "description": "Number between 0..255 indicating brightness.",
          "example": 120
        },
        "brightness_pct": {
          "description": "Number between 0..100 indicating percentage of full brightness.",
          "example": 47
        },
        "entity_id": {
          "description": "Name(s) of entities to turn on",
          "example": "light.kitchen"
        },
        {
          ...
        },
      }
    }
  }
}]

POST /api/services/<domain>/<service>

Calls a service within a specific domain. Will return when the service has been executed or after 10 seconds, whichever comes first.

You can pass an optional JSON object to be used as service_data.

Request

One or more entities are allowed in a single request. 'entity_id' field supports string or list type of data. To call a service on multiple devices at time just pass list of devices as param value.

Single entity

{
    "entity_id": "light.dev_unique_name_2"
    ...
}

Multiple entities

{
    "entity_id": ["light.dev_unique_name_2", "light.dev_unique_name_1"]
    ...
}

A group of entities

{
    "entity_id": "group.all_lights"
    ...
}

Returns a list of states that have changed while the service was being executed.

Sample curl commands

turn the light on

$ 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

turn the light off

$ 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

Response

[
  {
    "attributes": {
      "alert": 0,
      "area": "",
      "brightness": 105,
      "friendly_name": "dev_unique_name_2",
      "latitude": 0,
      "longitude": 0,
      "power": 100,
      "problem": false,
      "state_pending": true,
      "status": 1,
    },
    "entity_id": "light.dev_unique_name_3",
    "last_changed": "2018-04-19T08:20:23.359168+00:00",
    "last_updated": "2018-04-19T08:20:23.359168+00:00",
    "state": "on"
  },
]

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/

Picoides SERVICES

Picoides platform extends standard services provided by some domains with is own platform specific. Most of provided services extend or replace default ones, some would like ex. picoides_poll provide additional features. For details on Picoides platform services see Services: picoides