Tyba logo
Documentation Powered by Redocly

Turn 2 Public API Documentation (1.3.1)

Download OpenAPI specification:Download

Tyba Home Limited: hello@tybahome.com URL: https://www.tybahome.com/

General

The REST API for Turn is split into two domains; public and private. The private API is used to set the page configuration and other device settings such as network configuration, sleep timeout etc. The public API exposes all the control aspects of turn and is the focus of this document.

Page and Channel Configuration

The public API is served at http://{host}:55555/api/v1.0/ on each Turn device and returns responses in JSON format. Each controllable page on Turn (e.g. lighting scenes, temperature etc) contains one or more channels exposed on the control/channels endpoint. Conceptually, a channel is a communication pathway for a single piece of data, e.g. selected scene, brightness percentage value or setpoint temperature. Pages have an ID of the format {pageType}/{pageNumber} e.g. light/1 and the channels associated with that page have an ID made up of {channelType}/{pageNumber}/{channelNumber} e.g. light/1/1.

Page Type Section Number of Pages Channels per page Channel IDs
Light Lights 0-5 1 LIGHT/x/1
Light Scenes Lights 0-1 1 LIGHT_SCENES/1/1
Shade Shades 0-5 1 SHADE/x/1
Shade Scenes Shades 0-1 1 SHADE_SCENES/1/1
Temperature Climate 0-1 2 TEMPERATURE/1/1-2
Humidity Climate 0-1 2 HUMIDITY/1/1-2
Modes Climate 0-1 1 MODES/1/1
Fans Climate 0-1 1 FAN/1/1
Air Quality Climate 0-1 1 INFO/1/1
Air Pressure Climate 0-1 1 INFO/2/1
Sources Media 0-1 10 MEDIA/1/1-6, SOURCE/1/1-4

Table 1 - Page and Channel Configuration

There are limits on the maximum number of pages of each type, although every page is optional and may therefore be omitted if that page is not required. The channel configuration for a given page type is generally fixed. Table 1 shows the maximum number of pages that are allowed in the configuration and outlines some details on the channel configuration for each page type.

The Turn configuration describes the details of each how each page is set up and can be obtained from the REST API. The properties that may appear in the page configuration are given in Table 2.

Property Description Permitted Values
id The page id. This is unique and takes the format of pageType/pageNumber e.g. light/1 is the first light page. light/<1-5>, shade/<1-5>, light_scenes/1, shade_scenes/1, fan/1, temperature/1, info/<1-2>, modes/1, humidity/1, source/1
name The name of the page. This is for reference and does not appear on screen. Unrestricted
icon The name of the icon that appears on the page. air_pressure, air_quality, window_treatments, blackout_blinds, blinds, curtains, down_lights, fans, lighting_scenes, main_lights, modes, underfloor_heating, water_drop, table_lights, pendant, wall_lights, floor_lights, venetian, volume
pageType The page type as described above in id. See all valid ids
dialChannel The channel that is associated with the hardware dial. Any channel id
channels A list of the control channels for that page. See channels table
properties Properties that govern the appearance or behaviour of the page. Not used
sources Specific to the sources page. The list of selectable sources. See sources table

Table 2 - Page Properties

Each page may have one or more channels as shown in the channels property list. A channel has several properties such as ID, data type and write permissions. These are detailed in Table 3 and can be retrieved for all channels or for an individual channel using the REST API. A channel also contains a state object which maps out the last values sent to that channel. A channel state can be retrieved with a GET request and modified with a PUT request (assuming it has the write permission) or a POST action. The REST API also exposes SSE feeds for subscribing to each channel, as well as feeds for groups of channels such as channels of a given channel_type, or all channels.

Property Description Permitted Values
id The channel id. This is unique and takes the format pageType/pageNumber/channelNumber. See tables 1 & 2
description A description of the channel. By default this matches the id. Unrestricted
channelType The channel type determines which data types can be sent along the channel and aids how the data is interpreted. e.g. setpoint_temperature and current_temperature are different channel types which share the same data type of temperature. light, shade, light_scenes, shade_scenes, fan, modes, current_temperature, setpoint_temperature, current_humidity, setpoint_humidity, info, media_volume, media_transport_play_pause, media_transport_play_stop, media_transport_pause_unpause, media_transport_skip, media_mute, media_source_select, media_artwork, media_metadata, generic_string, generic_number, generic_switch
dataType The data type determines what data can be sent on the channel. Some data types have intrinsic limits such as percentage (0-100), preset (1-max_preset) percentage (0-100), temperature (0-212), preset (0-8), number, string, switch (true/false), action (string payload), image (string url)
channel_permission This is the read/write permission as viewed by the Turn device i.e. a channel which can be modified by the dial is "write". A channel which only displays incoming data is "read" read, write or read_write
properties A list of properties specific to that channel e.g. min, max, units, isSwitched
state A mapping of a control endpoint to a value value, on

Table 3 - Channel Properties

It should be noted that each channel on a page is usually configured with a specific id and type using the options from Table 3. The specific configuration for each channel is given in Table 4.

Channel ID Channel Type Data Type
LIGHT/1/1 light percent
SHADE/1/1 shade percent
LIGHT_SCENES/1/1 light_scenes preset
SHADE_SCENES/1/1 shade_scenes preset
FAN/1/1 fan preset
MODES/1/1 modes preset
INFO/1/1 generic_string string
INFO/1/1 generic_string string
TEMPERATURE/1/1 setpoint_temperature temperature
TEMPERATURE/1/2 current_temperature temperature
HUMIDITY/1/1 setpoint_humidity percent
HUMIDITY/1/2 current_humidity percent
MEDIA/1/1 media_volume percent
MEDIA/1/2 media_transport_play_pause switch
MEDIA/1/3 media_transport_play_stop switch
MEDIA/1/4 media_transport_pause_unpause switch
MEDIA/1/5 media_transport_skip action
MEDIA/1/6 media_mute switch
SOURCE/1/1 media_source_select preset
SOURCE/1/2 media_artwork image (URL)
SOURCE/1/3 media_metadata string (Artist)
SOURCE/1/4 media_metadata string (Track)

Table 4 - Specific Channel Configurations

Although a channel conceptually transfers a single piece of data, the REST API may expose multiple equivalent states for any given channel as well as some actions. These multiple interpretations of the channel data are known as control endpoints (See Tables 5 and 6). For example, the light/1/1 channel transfers a percentage data type which is exposed as a state called ‘value’. It also exposes an ‘on’ state, and may be modified with an ‘increment_decrement’ action. These states and actions are synchronised with each other so that a change to one will automatically update the others, maintaining a consistent view of the channel data. For example, setting the ‘value’ from 0 to 20 will also change the ‘on’ state to true.

Endpoint Type Payload
value state determined by channel data_type
on state true or false
increment_decrement action 0 for decrement, 1 for increment
play_action action 1
pause_action action 1
ppm_string state string
pa_string state string

Table 5 - Endpoint details

The ppm_string and pa_string endpoints receive a value as a string, integer or float, round it to an integer using half-up rounding and convert it to a string appended with “ppm” or "Pa" respectively. Making a GET request on these control endpoints will return the converted string value rather than the raw string, integer or float.

Channel value on inc_dec other
light/x/1 Y Y Y -
shade/x/1 Y Y Y -
light_scenes/1/1 Y Y Y -
shade_scenes/1/1 Y Y Y -
temperature/1/1 (setpoint) Y N Y -
temperature/1/2 (current) Y N N -
humidity/1/1 (setpoint) Y N Y -
humidity/1/2 (current) Y N N -
fan/1/1 Y Y Y -
modes/1/1 Y Y Y -
info/1/1 (air quality) Y N N ppm_string
info/2/1 (air pressure) Y N N pa_string
media/1/1 Y N Y -
media/1/2 (play/pause) Y N N play_action, pause_action
media/1/3 (play/stop) Y N N -
media/1/4 (pause/unpause) Y N N -
media/1/5 (next/prev) Y N N -
media/1/6 (mute) Y N N -
source/1/1 (select) Y N N -
source/1/2 (artwork) Y N N -
source/1/3 (metadata 1) Y N N -
source/1/4 (metadata 2) Y N N -

Table 6 - Endpoints for each channel.

Source Page

When the source page is configured, the page includes an additional 'sources' property listing up to 8 selectable sources. For each source the following properties are given:

Property Description Permitted Values
name Source name Unrestricted
power Whether the source has a power button true/false
transport Whether the source has transport controls true/false
controlType How the source is controlled main_bus or sonos

Table 7 - Source configuration

When the source page is configured with sources that take transport controls, there are three different methods of handling play and pause. It is recommended to select one of these methods to control play/pause state (usually option 1), however all methods keep in sync and will maintain a consistent state for play/pause.

  1. Channel media/1/2 has a ‘value’ state of true for play and false for pause. This channel may be used on its own to control play and pause using the standard GET and PUT requests for channel state as well as the SSE feed for subscribing to events.
  2. Channel media/1/2 also exposes two outgoing action control endpoints which publish a single event for play_action and a single event for pause_action, both have a payload of “1” and will be received by subscribing to the SSE feed for media/1/2. They can be used to control a Turn device by sending a POST request to http://{host}:55555/api/v1.0/control/channels/media/1/2/action with body {“play_action”:”1”} for example.
  3. The final method is to use media/1/3 (play/stop) and media/1/4 (pause/unpause) in tandem. In order to be in the playing state, media/1/3 must have a ‘value’ of true and media/1/4 must have a ‘value’ of false. All other combinations are considered to be paused. These channels can be used with the standard GET and PUT requests for channel state as well as the SSE feed for subscribing to events.

Integrations

Information and configuration specific to Turn integrations will be served at http://{host}:55555/api/v1.0/integrations. Currently, the only integration available is Sonos which exposes an endpoint for receiving the enabled status of next/previous transport controls in line with the Sonos control API policy. See API examples below for further detail.

API Endpoints

All http requests on the public API require the header to contain a key of “Sender-Id” with an identifier as the value. This key-value pair is included in the SSE events to identify to source of the event. The identifier can be any non-empty string. This enables users of the public API to ignore SSE events containing a Sender-Id that matches their own identifier and thus avoids creation of feedback loops.

Channels

All Channels

Get all the channels

header Parameters
Accept
string
Example: application/json
Sender-id
string
Example: TybaHome

Any non-empty string to identify the request sender.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • "...",
  • {
    }
]

Channels by Channel Type

Get all the channels for a given page type

path Parameters
channelType
required
string

The channel type

header Parameters
Accept
string
Example: application/json
Sender-id
string
Example: TybaHome

Any non-empty string to identify the request sender.

Responses

Response samples

Content type
application/json
Example
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Channels by Channel Index

path Parameters
pageId
required
string
header Parameters
Accept
string
Example: application/json
Sender-Id
string
Example: TybaHome

Any non-empty string to identify the request sender.

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Channel by Channel Id

Get the channel matching the supplied id

path Parameters
channelId
required
string

The channel to get.

header Parameters
Accept
string
Example: application/json
Sender-id
string
Example: TybaHome

Any non-empty string to identify the request sender.

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Channel State

Get the states of all endpoints on a channel

path Parameters
channelId
required
string

The channel to get.

header Parameters
Accept
string
Example: application/json
Sender-id
string
Example: TybaHome

Any non-empty string to identify the request sender.

Responses

Response samples

Content type
application/json
Example
{
  • "value": 0,
  • "on": "false"
}

Channel State

Modify the state of a particular channel. Can either send either 'value':{int} or 'on':{bool} to modify the state of a channel

path Parameters
channelId
required
string

The channel to modify.

header Parameters
Content-Type
string
Example: application/json
Sender-Id
string
Example: TybaHome

Any non-empty string to identify the request sender.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "value": 50,
  • "on": true
}

Channel Action

Gets the available actions on a channel (if any)

path Parameters
channelId
required
string

The channel to get.

header Parameters
Content-Type
string
Example: application/x-www-form-urlencoded
Sender-Id
string
Example: TybaHome

Any non-empty string to identify the request sender.

Responses

Response samples

Content type
application/json
Example
[
  • "increment_decrement"
]

Channel Action with Payload

POSTs an action on a channel with the given payload. Payloads are either 0 or 1.

path Parameters
channelId
required
string

The channel to modify.

header Parameters
Content-Type
string
Example: application/json
Sender-Id
string
Example: TybaHome

Any non-empty string to identify the request sender.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "increment_decrement": 0
}

Response samples

Content type
text/plain
Example
Events
Endpoints which can be subscribed to by listeners to receive server sent events.


All Channels 
Subscribe and listen to all channel events


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
By Channel Type 
Subscribe and listen to channel events by page type.


path Parameters
channelType
required
string
 
The channel type


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
By Channel Index 
Subscribe and listen to channel events by page


path Parameters
channelIndex
required
string
 
The channel type/index to listen to


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
By Channel 
Subscribe and listen to channel events by id.


path Parameters
channelId
required
string
 
The channel to listen to.


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
All Control States 
Subscribe and listen to global control state events.


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
By Control State 
Subscribe and listen to global control state events by state (i.e internal_temperature).


path Parameters
state
required
string
 
The state to listen to.


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
Global
Internal Temperature 
Get the internal temperature (value and fahrenheit).


header Parameters
Sender-Id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
 Response samples 
Content type
application/json
{
  • "value": "0.0",
  • "fahrenheit": "32.0"
}
Internal Temperature Value 
Get the internal temperature value.


header Parameters
Sender-Id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
 Response samples 
Content type
application/json
{
  • "value": "0.0"
}
Internal Temperature Fahrenheit 
Get the internal temperature fahrenheit value.


header Parameters
Sender-Id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
 Response samples 
Content type
application/json
{
  • "fahrenheit": "32.0"
}
State 
Get all control state values


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
 Response samples 
Content type
application/json
{
  • "internal_temperature": 0
}
State 
Put control state.


header Parameters
Content-Type
string
 
 Example:  application/json
Sender-Id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Request Body schema: application/json
object
 
Responses
 Request samples 
Content type
application/json
{
  • "ready": "false"
}
Action 
Posts a global action.


    

  • reset - resets all control states and channels to their initial state
    • 



path Parameters
action
required
string
 
The action to complete.


header Parameters
Content-Type
string
 
 Example:  application/x-www-form-urlencoded
Sender-Id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Request Body schema: application/x-www-form-urlencoded
object
 
Responses
 Response samples 
Content type
text/plain
Config
Config 
Get the page configuration.


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
 Response samples 
Content type
application/json
{
  • "pages": [
    ],
  • "layout": {
    },
  • "startPageId": "light_scenes/1"
}
Config Version 
Get the config version. The version number indicates which features (page and channel types) are available in the config and corresponds to the API documentation version number.


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
 Response samples 
Content type
application/json
"2.0.0"
Config Events 
Subscribe to get config update notifications.


header Parameters
Sender-id
string
 
 Example:  TybaHome
Any non-empty string to identify the request sender.


Responses
Integrations
Contains a collection of requests and workflows for Turn 2 external integrations (Sonos, Hue etc.).


Integrations > Sonos
Turn 2 integration with Sonos allows users to control their Sonos speakers directly from the Turn 2 device.


Transport Controls 
Get the transport controls policy (i.e. whether the actions to skip back to the previous track or skip to the next track are enabled for the current track).


Responses
 Response samples 
Content type
application/json
{
  • "previousEnabled": true,
  • "nextEnabled": true
}
Transport Controls Stream 
Get the transport controls policy SSE stream.


Responses
 Response samples 
Content type
text/plain
event: transportControls
data: {"previousEnabled":true,"nextEnabled":false}

event: transportControls
data: {"previousEnabled":false,"nextEnabled":false}

event: transportControls
data: {"previousEnabled":false,"nextEnabled":true}

event: transportControls
data: {"previousEnabled":true,"nextEnabled":true}