SwitchThat One User Guide

SwitchThat Technical Support


1. Welcome
2. Getting Started
2.1. Assembling your One Hub
2.2. Setting up your One Hub
2.3. Connecting to your One Hub
2.4. Discovering and connecting your smart devices
2.5. iPhone/iPad app
2.6. Android app
3. Home Screen
3.1. Your Devices
3.2. All On / All Off Buttons
3.3. Shortcuts
3.4. Notifications
3.5. Filtering the Home Screen
3.6. Customising the Layout of the Home Screen
4. Controlling your Devices
5. Organising your Devices
5.1. Rooms
5.2. Shortcuts
6. Configuring your Devices
6.1. Device Settings
6.2. Change a Device’s Location
6.3. Dealing with Unavailable Devices
7. Your user page
7.1. Lighting scenes
7.2. Personalising SwitchThat One
7.3. Editing your user details
7.4. Signing out
8. Settings & Configuration
8.1. Location
8.2. Remote Access
8.3. Users
8.4. Alerting services
8.5. Calendars
8.6. API Users
9. My Devices
9.1. Adding New Devices to your One Hub
9.2. Forgetting all of your Devices
10. Administration
10.1. Updates
10.2. System Health
11. The HTTP API interface
11.1. API authentication
11.2. Making API requests
12. Interactions
12.1. Interaction Builder
12.2. The My Interactions screen
12.3. Further Interaction Builder examples
12.4. Dealing with Interaction Errors
13. Advanced Interactions
13.1. The Basics
13.2. Using the Advanced Interaction Editor
13.3. More complicated Interactions
13.4. Examples
A. Supported Devices
A.1. Philips Hue lights
A.2. LIFX lights
A.3. Belkin WeMo Switches
A.4. Belkin WeMo Smart Light Bulbs
A.5. Belkin WeMo Motion Sensor
A.6. Sonos Music Players
A.7. Nest®
A.8. Tado smart thermostat
B. HTTP API Reference
C. Interaction Reference
C.1. Precedence
C.2. Top level things
C.3. Other types
C.4. Actions
C.5. Operators

Chapter 1. Welcome

Welcome to SwitchThat One

We know how frustrating it feels having to use separate, incompatible Apps to control the different parts of your IoT smart home, and wouldn’t it be nice if all your smart devices worked well together? That's why we developed the SwitchThat One home automation system.

With a SwitchThat One Hub and your phone or tablet you can be in complete control of you smart home.

The rest of this user guide will cover all aspects of using SwitchThat One, including:

  • Connecting up your One Hub and getting started

  • Using the iPhone/iPad & Android apps

  • Discovering, controlling & organising your devices

  • Automating your smart home with Interactions.

Chapter 2. Getting Started

Getting started with SwitchThat One is very straightforward:

  1. First unpack your SwitchThat One Hub, or assemble it if you purchased SwitchThat One as a download or pre-installed Micro SD card.

  2. Plug your SwitchThat One Hub into your broadband router.

  3. Connect using either the mobile/tablet app or web browser.

  4. Sign in.

  5. Take control of your smart home!

These steps are covered in detail over the next few sections. If you already have your One Hub setup and the SwitchThat app installed on your phone or tablet, then you can skip straight to Chapter 3, Home Screen.

2.1. Assembling your One Hub

Note

If you purchased a pre-installed One Hub, you can skip this section and go to Section 2.2, “Setting up your One Hub” .

If you purchased SwitchThat One as a download or a pre-installed Micro SD card, you’ll need to install it on a Raspberry Pi 2 to get started.

The downloadable SwitchThat One image is the cheapest way to buy SwitchThat One and is only recommended for people with a technical background. If you have bought SwitchThat One as a downloadable image you’ll need to write it to a Micro SD card (minimum 4GB or larger). We recommend the Class 6 card or higher for the best performance.

We’ll assume that you are familiar with how to write the SwitchThat One image to your Micro SD card. If you need some help, you can refer to this Raspberry guide.

Once you have your Micro SD card ready, insert it into your Pi 2. You’re now ready to proceed!

2.2. Setting up your One Hub

Plug your One Hub directly into your broadband router with the Ethernet cable provided, and then connect the power supply. The red power LED should stay on and the green one will flash as it starts up. Allow 30 seconds or so for your One Hub to be fully functional.

A pre-installed One Hub

A pre-installed One Hub


2.3. Connecting to your One Hub

You can connect to your One Hub in a number of ways:

  1. iPhone or iPad (running at least iOS 7.1) – Covered in Section 2.5, “iPhone/iPad app”

  2. Android phone or tablet (running at least Android 4.0 Ice Cream Sandwich) – Covered in Section 2.6, “Android app”

  3. PC/Laptop with a modern standards-compliant web browser – Covered in Section 2.3.1, “Connecting to your One Hub using a web browser”

If you have an iPhone/iPad or an Android phone/tablet, we recommend using the SwitchThat app (available from the Apple App Store / Google Play Store) to locate your Hub.

When you first start the SwitchThat app you’ll be taken to the Hubs screen, and the app will begin searching for your One Hub.

Note

Your iPhone/iPad or Android phone/tablet must be connected to you local broadband network via wifi to find your One Hub.

When your One Hub appears in the Hubs screen, tap it and you will be asked to sign in. When you sign in for the first time you must use the name ‘owner’ with password ‘owner’. You can change the name or password of this user and add other users if you like — see Section 8.3, “Users” for full details.

Connecting to your One Hub using the SwitchThat iPhone/iPad app

Connecting to your One Hub using the SwitchThat iPhone/iPad app


If you purchased SwitchThat One as a download or pre-installed Micro SD card, you’ll be presented with a registration screen and you must register before you can continue.

The first time you sign in you’ll see a welcome screen:

The Welcome screen

The Welcome screen


Tap Continue to proceed to the Home Screen. See Chapter 3, Home Screen to start learning how to use SwitchThat One.

There’s more information about installing and using the SwitchThat mobile apps in Section 2.5, “iPhone/iPad app” and Section 2.6, “Android app”.

2.3.1. Connecting to your One Hub using a web browser

If you don’t have an iPhone/iPad or an Android phone/tablet, you can connect to your One Hub using a web browser on a PC or laptop. You should use a modern, web standards compliant browser; we recommend Firefox, Google Chrome or Safari.

To get started, you’ll need to type the address of your One Hub into the address bar of your web browser. Depending on your router configuration, one of the following addresses might work:

  • one-hub.local

  • one-hub.lan

  • one-hub.home

If none of these work however, then you’ll need to find out the IP address of your One Hub and type this into the address bar of your web browser.

Note

You can use the SwitchThat app on your phone/tablet to find the IP address of your One Hub – it’s shown on the Hubs screen. If you don’t have access to the SwitchThat app you should be able to use your broadband router’s admin pages to find out your One Hub’s IP address. Consult your router documentation for instructions on how to check the devices connected to your router.

Once your web browser has connected to your One Hub, you’ll be taken to the SwitchThat One user interface. Just like with the SwitchThat app, the first thing you’ll need to do is sign in.

When you sign in for the first time use the name ‘owner’ with password ‘owner’. You can change the name or password of this user and add other users if you like — see Section 8.3, “Users” for full details.

After signing in, you’ll be taken to the Home Screen. See Chapter 3, Home Screen to start learning how to use SwitchThat One.

2.4. Discovering and connecting your smart devices

SwitchThat One currently works with the following smart home products:

  • Sonos Music Players

  • Philips Hue Lights

  • LIFX Colour Light bulbs

  • Belkin WeMo LED Lighting

  • Belkin WeMo Switch

  • Belkin WeMo Motion Sensor

  • Tado smart thermostat

SwitchThat One will begin looking for your devices immediately and, in most cases, they will be automatically found and configured for use within a few seconds of your One Hub starting up. Some devices might, however, need a bit of extra configuration before they can be used with SwitchThat One. Full details of SwitchThat One’s support for all these devices, including discovery instructions and troubleshooting hints, can be found in Appendix A, Supported Devices.

When a device is discovered, a notification will be sent, which can be read by tapping Notifications in the menu at the top of the screen (see Section 3.4, “Notifications” for more details)

Adding a new device is usually as simple as installing the device according to the manufacturer’s instructions and then waiting for SwitchThat One to discover it. Again some devices need a bit of extra configuration before they can be used with SwitchThat One. Please consult Appendix A, Supported Devices for full details when adding a new device.

2.5. iPhone/iPad app

The SwitchThat app lets you control your One Hub using your iPhone or iPad. Both apps work in the same way, although we recommend the iPad app for the best experience. Download the SwitchThat app for free on the App Store.

2.5.1. Getting Started

After starting the SwitchThat app, you will be taken to the Hubs list. SwitchThat will search your local broadband network for your SwitchThat One Hub. Please note that your iPhone/iPad must be connected to this network via wifi for the app to find your One Hub. When your One Hub appears in the list, tap it and you will be asked to sign in. Enter your name & password to sign in to your One Hub.

Once you've signed in to your One Hub, the SwitchThat app will always try to automatically reconnect you at startup, returning to the last screen you were using.

If you prefer, you can turn this feature off:

  1. On the Hubs list tap the cog icon at the top-left to visit the Settings screen.
  2. Turn off the Restore last session setting.

There are a few cases where you will not be automatically connected to your One Hub at startup:

  • You are no longer signed in. In this case you will be taken back to Hubs list. Tap on your One Hub to sign in again.

  • You are on a different wifi network (or a 3G/4G mobile internet network) and the SwitchThat app cannot see your One Hub. In this case you will be taken back to Hubs list and your One Hub will be shown as 'unavailable'. In order to access your One Hub you must either re-connect to your wifi network, or enable remote access (see the next section).

2.5.2. Remote Access

The SwitchThat One Hub has a remote access feature that allows you to securely connect to your One Hub from outside your local network. See Section 8.2.1, “Setting up Remote Access” for guidance on enabling this feature.

If remote access is enabled, you will be able to connect to your One Hub using the SwitchThat app from anywhere your iPhone/iPad can connect to a wifi or mobile internet network (we recommend at least 3G for the best experience.)

In the Hubs list remote access to a Hub is indicated by a 'globe' icon and the label 'Remote access' in the Hub description.

You must already be signed in to your One Hub to access it remotely. If you are not signed in to your One Hub, and your iPhone/iPad is not on the same broadband network, then it will be listed as 'unavailable'.

Warning

If you sign out of your One Hub while accessing it remotely, you will not be able to sign in again (and your One Hub will show as ‘unavailable’) until you are back on your home wifi network.

Remote access will only be used if local wifi access is unavailable. If SwitchThat can access your One Hub over the local wifi network, then it will automatically choose this in preference to remote access.

When remote access is enabled, the SwitchThat app will do its best to maintain a connection to your One Hub at all times:

  • If you leave your local wifi network and connect to another wifi or 3G/4G mobile internet network, SwitchThat will attempt to reconnect to your One Hub using remote access.

  • If you rejoin your local wifi network, the SwitchThat app will attempt to re-establish a local connection to your One Hub.

2.6. Android app

SwitchThat provides a free app that you can use to access your One Hub using your Android phone or tablet. You can find the SwitchThat One app on the Google Play store.

You can find and install it directly on your mobile, or remotely from the store web page.

2.6.1. Getting Started

Whenever you start the Android SwitchThat app, it will show you a list of all the Hubs you have seen, and show a visual cue as to whether they are currently accessible locally or remotely.

If you have not seen any hubs yet, a ‘Searching’ screen will be shown while it continues to scan your local broadband network for your SwitchThat One Hub. Please note that your phone or tablet must be connected to this network via wifi for the app to find your One Hub.

Searching for your One Hub using the SwitchThat Android app

Searching for your One Hub using the SwitchThat Android app


When your One Hub has appeared in the list, tap it and you will be asked to sign in by entering your name & password, which will initially be ‘owner’ with password ‘owner’.. You will subsequently be able to connect without re-entering your details.

Selecting your Hub and logging in

Selecting your Hub and logging in


You will be returned to the hub list if:

  • You press the Android device Back button

  • You click on Back to Hub list within SwitchThat One

  • You log out

  • The connection to the hub is disrupted, e.g. if you lose network access

If you leave the SwitchThat app and return to it, it will do its best to resume where you left off.

When you are connected to a hub the screen will not turn off, so when you are done either return to the hub list, leave the app, or press the power button[1].

A popup menu will appear if you keep your finger held on a hub. The menu options allow you to

  • Forget the Hub, which is useful for hubs that you no longer have access to
  • Reset the local state of the Hub, which may be useful if you want to start on Home next time you connect

Android Hub popup menu

Android Hub popup menu


2.6.2. Remote Access

The SwitchThat One Hub has a remote access feature that allows you to securely connect to your One Hub from outside your local network. See Section 8.2.1, “Setting up Remote Access” for guidance on enabling this feature.

If remote access is enabled, and you have previously logged in, you will be able to connect to your One Hub using the SwitchThat app from anywhere your iPhone/iPad can connect to a wifi or mobile internet network (we recommend at least 3G for the best experience). Remote and Local access is checked every 15 seconds while the hub list is being shown.

Cues showing whether Remote and/or Local Access are available

Cues showing whether Remote and/or Local Access are available


If you leave home while using local wireless access, the app will show that you have lost the connection to your One Hub and take you back to the Hubs list. You can tap the hub again to reconnect remotely.

Warning

Please do not log out unintentionally while you are away from home as you will then lose Remote Access, and not be able to reconnect until you are back on your home network



[1] In future this will probably become a per-Hub option

Chapter 3. Home Screen

The Home screen is the control centre of your SwitchThat world. It’s always accessible by simply tapping the red SwitchThat logo at the top left of every screen.

Your view of your Home screen will depend on whether you are accessing your One Hub from a tablet, phone or using a web browser on a computer.

The following example pictures show how the Home screen might appear on a phone or a tablet.

Home screen on a phone

Home screen on a phone


Home screen on a tablet

Home screen on a tablet


3.1. Your Devices

Your devices are initially displayed as ‘tiles’ on the Home screen. A device tile shows you the name and manufacturer of the device, as well as an image illustrating what kind of device it is e.g. a light, music player, power socket, etc.

The right hand side of the tile will usually show you a summary of the status of the device and may also have a switch you can tap to turn the device on or off. Note that not all devices will have an on/off switch on their tile, only those devices for which being turned ‘on’ or ‘off’ makes sense, e.g. lights, switches, music players.

If your One Hub cannot access a device for some reason (e.g. the device has been powered off, or is not connected to your home network) then there will be an orange warning symbol over the device’s tile. This indicates that the device is currently unavailable. See Chapter 6, Configuring your Devices for tips on dealing with unavailable devices.

3.2. All On / All Off Buttons

You can quickly turn the devices in the current view on/off at once by tapping the All on or All off buttons (at the bottom left of the screen on phones and in the right-hand side control panel on larger displays.)

All On / All Off buttons on phone

All On / All Off buttons on phone


Only certain devices are affected by the All on and All off buttons:

Generally speaking, if a device has an on/off switch in its tile on the Home screen, then it will respond when the All on or All off buttons are tapped.

3.3. Shortcuts

A shortcut is a way to group together a number of devices according to certain criteria. For example, you can create shortcuts to show ‘all of my lights’, or ‘the devices that Helen might use most often’.

Shortcuts are stored in the shortcuts list. On larger displays, this is found in the control panel on the right hand side of the screen. On smaller tablets and phones this is found by tapping the Shortcuts button on the right hand side of the footer toolbar.

Shortcuts on phone

Shortcuts on phone


Simply tap on a shortcut to view the devices it groups together.

Your One Hub comes with a small number of predefined shortcuts, to give you instant access to common types of device, e.g. lights or power sockets. Your One Hub also comes with a special shortcut, called All devices. This shortcut gives you instant access to all of your devices in a single screen.

Shortcuts are described in more details in Section 5.2, “Shortcuts”

3.4. Notifications

The notifications area is where your One Hub will keep you informed about important events such as when new devices are discovered or when a software update is available and ready to install.

When a new notification arrives, the Notifications icon will flash briefly, and the number of unread notifications will be displayed. Tap the Notifications icon and a menu will appear listing all unread notifications.

Notifications icon

Notifications icon


Some notifications will just have a message for you to read, while others will inform you of some action you should complete. Tap each notification to either dismiss it or to complete the requested action.

Notification messages

Notification messages


3.5. Filtering the Home Screen

The Home screen can be filtered to quickly find particular devices. Tap the filter button, next to the label ‘Home’ at the top of the screen:

Filter button on Home screen

Filter button on Home screen


Two selection boxes will appear: one for choosing a room, the other for choosing a device category. As you change these selection boxes, the view updates to match the selected filters.

Filter selection on Home screen

Filter selection on Home screen


You can quickly filter the view to show, e.g. the lights in a specific room, the lights in all rooms, all devices in a specific room, etc.

When using the filter, the All on and All off buttons will work on just the devices in the filtered view.

Tap the filter button again to clear the filters and return to the Home screen.

3.6. Customising the Layout of the Home Screen

You can easily change the order of the tiles in the Home screen. These changes are personal settings, so each user can view the Home screen in their preferred order.

To customise the layout of the Home screen on a large display (e.g. desktop or larger tablet):

  1. Tap the Move Tiles button in the right-hand side control panel; the tiles will change to show drag buttons

  2. Drag the tiles to rearrange them.

  3. Tap Done in right-hand side control panel when you are finished.

To customise the layout of the Home screen on a smaller tablet or phone:

  1. Tap the Customise button on the left hand side of the footer toolbar. Choose Move Tiles or Move Tiles from the menu; the tiles will change to show drag buttons

  2. Drag the tiles up/down to rearrange them.

  3. Tap Done in the footer toolbar when you are finished.

Customising the Home screen

Customising the Home screen


Chapter 4. Controlling your Devices

Your devices can be controlled in a number of different ways.

Chapter 3, Home Screen described how many devices can be switched on or off directly from the Home screen (or when viewing a room or shortcut). To recap:

  • You can quickly turn a device on or off by by tapping the on/off switch at the right hand side of its tile.

  • You can turn all the devices in the current view on/off at once by tapping the All on or All off buttons (at the bottom left of the screen on phones and in the right-hand side control panel on larger displays.)

However, you will often require more sophisticated control over your devices than merely switching them on or off.

Find a device you want to control and tap on the name of that device. You will be taken to the Control screen for that device. One or more widgets will appear giving you control of different properties of the devices. For example, a colour light device might have two controls: an on/off switch and a widget for choosing the light colour:

An example of a Control

An example of a Control


Depending on the size of screen your are using, you may need to scroll down to find all of the device’s control widgets.

Chapter 5. Organising your Devices

The SwitchThat philosophy is to let you organise your devices your way. You can easily create rooms to mirror the layout of your own home, and place your devices in their respective rooms. You can filter the Home screen or the current room to quickly find specific devices. You can also create custom Shortcuts to provide persistent and instant access to groups of devices according to different criteria.

5.1. Rooms

Rather than having all of your devices in the Home screen, you can organise them into rooms. Rooms can mirror the physical rooms in your home, or can simply be a convenient way to group devices together.

You can also add controls to a room, allowing you to control the devices in that room collectively.

5.1.1. Adding a Room

On the Home screen, tap New Room, found in the right-hand side control panel on larger tablets or by tapping the Customise button on the left hand side of the footer toolbar on phones or smaller tablets.

You will be prompted to give the new room a name. Enter a name and tap OK to continue.

The new room will be created, and you will be taken to the Configure page for this room where you can:

  • Change the image used for this room in the Home screen
  • Rename the room
  • Choose which devices should be in this room
  • Add some controls to the room
  • Remove the room

Each of these topics is discussed later in this section, but first of all, let’s take a look at the new room.

Return to the Home screen by either tapping Home in the titlebar, or the SwitchThat logo at the top left. You can find your new room at the end of the tiles. Tap on the room’s name to open the room. The room is still empty, so you’ll see a message suggesting that you configure the room to add some devices.

Tap the Configure button to return to the Configure screen for this room.

Configuring a Room

Configuring a Room


5.1.2. Adding Devices to a Room

When first created, a room is empty, so you’ll almost certainly want to add some devices:

  1. Find the Device in this room section, tap Add devices and a list of all the available devices will appear.
  2. Check the box next to each device that should be moved to this room.
  3. Tap Update to finish.

Adding devices to Room

Adding devices to Room


The display will change to show the devices that are now in this room. You can change this list of devices by tapping Change these devices and following the same process. Note that:

  • If you select a device that is already inside another room, that device will be moved into the new room.

  • If you un-select a device then that device will be removed from the room and returned to the Home screen.

Now that you’ve moved some devices into your room, let’s view it again. You can switch between viewing the contents of a room and the configure screen for that room easily by tapping either the View or Configure buttons found in the right-hand side control panel on larger tablets or on the left hand side of the footer toolbar on phones or smaller tablets.

Tap the View button to view the room contents. You should now see the devices that you added to the room.

5.1.3. Change the Image Used for this Room

Rooms appear as tiles in the Home screen and, as with device tiles, they have an image to represent them.

A new room is given the image of a folder by default. This image can be changed to better illustrate the type of room, e.g. a TV for the lounge, a desk for the office or a bed for the bedroom. Make sure you are on the Configure screen for the room and then:

  1. Find the Details section, tap Change room image and a list of alternative room images will appear.
  2. Tap on your preferred image to select it for this room.

Changing a Room Image

Changing a Room Image


5.1.4. Rename a Room

A room can easily be renamed if required. Make sure you are on the Configure screen for the room and then:

  1. Find the Details section and tap on the Rename button, next to the room name.
  2. Enter the new name in the box and tap Save

5.1.5. Adding Controls to a Room

You can add controls to a room, which enables you to control the devices in that room collectively.

For example, if you have a number of coloured lights in a room, you could add a colour control to that room, which could be used to set the colour of each light simultaneously. This will work regardless of device manufacturer – you can have coloured lights from both Philips Hue and LIFX in the same room and set the colour of all the lights using the same room colour control. Some variation in colour between light bulbs from different vendors will exist due to their differing colour capabilities.

To add controls to a room, make sure you are on the Configure screen for the room and then:

  1. Find the Controls section, tap Add controls and a list of all the available controls will appear. (If you have previously added controls to this room, the button will be labelled Change these controls)
  2. Tap on each of the controls you would like to add to the room. Tap on a control again to remove it
  3. Tap Done to finish

Adding Controls to a Room

Adding Controls to a Room


Once you’ve added controls to a room, tap View to view the room. A button labelled Show room controls will be visible below the devices. Tap this and the control(s) will appear.

Note

An important thing to consider when adding controls to a room is that a device will only work with a room control if that device has the same kind of control. For example, if you add an on/off switch to a room, only the devices that also have on/off switches will be affected when you flick the switch. Similarly, if you add a light bulb colour control to a room, changing the colour will update any compatible light bulbs but will not affect other devices.

5.1.6. Removing a Room

A room can be removed if it is no longer required. Make sure you are on the Configure screen for the room and then:

  1. Find the Actions section and tap Remove this room
  2. You’ll be asked to confirm you want to remove the room. Tap OK to continue

Any devices that were inside the room will be moved back to the Home screen.

5.2. Shortcuts

A shortcut is a way to group together a number of devices according to certain criteria. Unlike rooms, which provide a fixed organisational structure, shortcuts allow more flexible ways to find and view your devices. For example, you can create shortcuts to show:

  • All of your lights.

  • The devices that Helen uses most often.

  • The 3 corner lights that you like to turn on/off together.

5.2.1. The Shortcuts List

Shortcuts are stored in the shortcuts list. On larger displays this is found in the control panel on the right hand side of the screen. On smaller tablets and phones this is found by tapping the Shortcuts button on the right hand side of the footer toolbar.

Simply tap on a shortcut to view the devices it groups together.

Your One Hub comes with a small number of predefined shortcuts, to give you instant access to common types of device, e.g. lights or power sockets. You are free to modify or remove these shortcuts according to your needs.

Your One Hub also comes with a special shortcut, called All devices. This shortcut gives you instant access to all of your devices in a single screen. The All devices shortcut cannot be modified or removed.

5.2.2. Adding a New Shortcut

On the Home screen, tap New Shortcut, found in the right-hand side control panel on larger tablets or by tapping the Shortcuts button on the right hand side of the footer toolbar on phones or smaller tablets.

You will be prompted to give the new shortcut a name. Enter a name and tap OK to continue.

The new shortcut will be created, and you will be taken to the Configure page for this shortcut where you can:

  • Rename the shortcut.
  • Choose which devices should be in this shortcut.
  • Add some controls to the shortcut.
  • Remove the shortcut.

Each of these topics will be discussed later in this section, but first of all, let’s take a look at the new shortcut.

Return to the Home screen by either tapping the Home in the titlebar, or the SwitchThat logo at the top left. You can find your shortcut at the bottom of the list of shortcuts. Tap on the shortcut name to open the shortcut. The shortcut is still empty, so you’ll see a message suggesting that you configure the shortcut to add some devices.

Tap the Configure button to return to the configure screen for this shortcut.

5.2.3. Adding Devices to a Shortcut

When first created, a shortcut is empty, so you’ll almost certainly want to add some devices.

Find the Device in this shortcut section, tap Add devices and a number of lists will appear. You can use these lists to select what devices will appear in this shortcut:

  • Devices lets you explicitly select individual devices.
  • Devices in Room lets you include any devices that are inside a particular room.
  • Device Types lets you include all the devices of a particular type.
  • Device Categories lets you include all the devices of a particular category.

Adding Devices to a Shortcut

Adding Devices to a Shortcut


You can tick the box next to as many options as you like to select which devices want to appear in this shortcut. When you are done, tap Update to finish.

The display will change to show the devices that are now in this shortcut. You can change this list of devices by tapping Change these devices and following the same process.

There are some important things to note when selecting which devices to include in a shortcut:

  • You can mix and match between the different lists to build up the exact selection of devices you want to see in your shortcut.

  • Even if a device matches more than one of the chosen selection criteria, it will only appear once in the shortcut.

  • If you select an item from either the Device Types or Device Categories lists, your shortcut will automatically update when new matching devices are discovered (or existing devices are forgotten.) For example, a shortcut that matches the device category ‘Light’ will always show all of the lights that your One Hub knows about.

  • If you select an item from the Devices in Room list, then, if devices are subsequently added to/removed from that room, they will also be added to/removed from the shortcut.

Now that you’ve chosen some devices to be grouped in your shortcut, let’s view it again. You can switch between viewing the contents of a shortcut and the Configure screen for that shortcut easily by tapping either the View or Configure buttons found in the right-hand side control panel on larger tablets or on the left hand side of the footer toolbar on phones or smaller tablets.

Tap the View button to view the shortcut contents. You should now see the devices that you selected.

5.2.4. Making Shortcuts Private

Shortcuts are visible to all by default. However, you can also make them private so that they only appear for you and the other people who use your One Hub don’t see them. This enables the various people in your home to make their own personal collections of devices.

To make a shortcut private, make sure you are on the Configure screen for the shortcut and tick the Visible only to me box.

Note that this setting only affects the shortcut; the actual devices will still be visible to all (Owner and Standard) users.

5.2.5. Adding Controls to a Shortcut

You can add controls to a shortcut, which enables you to control the devices in that shortcut collectively.

For example, if you have a number of coloured lights in a shortcut, you could add a colour control to that shortcut, which could be used to set the colour of each light simultaneously. This will work regardless of device manufacturer – you can have coloured lights from both Philips Hue and LIFX in the same shortcut and set the colour of all the lights using the same shortcut colour control.

To add controls to a shortcut, make sure you are on the Configure screen for the shortcut and then:

  1. Find the Controls section, tap Add controls and a list of all the available controls will appear. (If you have previously added controls to this shortcut, the button will be labelled Change these controls).
  2. Tap on each of the controls you would like to add to the shortcut. Tap on a control again to remove it.
  3. Tap Done to finish.

Adding Controls to a Shortcut

Adding Controls to a Shortcut


Once you’ve added controls to a shortcut, tap View to view the shortcut. A button labelled Show shortcut controls will be visible below the devices. Tap this and the control(s) will appear.

An important thing to consider when adding controls to a shortcut is that a device will only work with a shortcut control if that device has the same kind of control. For example, if you add an on/off switch to a shortcut, only the devices that also have on/off switches will be affected when you flick the switch. Similarly, if you add a light bulb colour control to a shortcut, changing the colour will update any compatible light bulbs but will not affect other devices.

5.2.6. Removing a Shortcut

A shortcut can be removed if it is no longer required. Make sure you are on the Configure screen for the shortcut and then:

  1. Find the Actions section and tap Remove this shortcut
  2. You’ll be asked to confirm you want to remove the shortcut. Tap OK to continue.

Chapter 6. Configuring your Devices

Each of your devices has a Configure screen, where you can change its settings, move it to a different room, or troubleshoot if the device is unavailable.

To visit the Configure screen for a device:

  1. Find the device tile on the Home screen or open the room where the device is located.
  2. Tap on the device tile to open the control page for the device.
  3. Tap the Configure button, found in the right-hand side control panel on larger tablets or on the left hand side of the footer toolbar on phones or smaller tablets.

Configuring a Device

Configuring a Device


6.1. Device Settings

The Details section at the top of the Configure screen contains a number of device settings you can change, each of which are described in this section.

6.1.1. Renaming a Device

It is important that your devices have unique names when they are used in SwitchThat One. If two or more of your devices have the same name it can cause problems because SwitchThat One may get these devices confused. This might mean, for example, that your Interactions fail to work correctly.

When a device is first discovered and added to SwitchThat One it will automatically be given the same name used for that device in its official app. As a result it may be that a newly-discovered device is given a name that is already in use by another device. If this happens, you should rename one of these devices as soon as possible.

To rename a device:

  1. Go to the Configure screen for your device
  2. Find the Details section and tap on the Rename button, next to the device name.
  3. Enter the new name in the box and tap Save.

Note that the Rename button may not appear for some devices. This might be because:

  • The device must be renamed using the official manufacturer-supplied app. For example, Sonos players must be renamed using the official Sonos app. When this happens, SwitchThat One will automatically update the name of the device accordingly.
  • The device is currently unavailable. Make sure your device is powered on and connected to your home network.

Note

SwitchThat One will periodically check for devices with duplicate names and warn you if any are found.

6.1.2. Making a Device Visible to Guests

When a device is first discovered by your One Hub it will be hidden from guest users. However, you can choose to make some, or all, of your devices visible to guest users. This gives you complete control over which devices your guests can control.

To make a device visible to guest users, go to the Configure screen, find the Details section and tap the Visible to guests setting. A tick will appear, indicating that this device is now visible to guests.

To hide the device from guests, tap the Visible to guests setting again, and the tick will disappear.

6.1.3. Works with All on/All off Buttons

The All on and All off buttons are used to quickly turn the devices in the current view on/off at once. There may, however, be situations where you prefer that a particular device isn’t affected when you tap All on or All off,

You can easily configure a device to stop working with the All on and All off buttons: go to the Configure screen find the Details section and tap the Works with All on/All off buttons setting so that the tick disappears. Tap it again to restore the device to working with the All on and All off buttons.

6.1.4. Keeping Devices in Sync with External Changes

Most of your devices within SwitchThat are automatically kept up to date with changes made using other apps, or made to the device directly.

There are some devices that your One Hub must periodically check on to make sure it accurately shows the state of the device. The Keep in sync with external changes setting can be used to control whether or not your One Hub keeps these devices up to date.

There is usually no reason to change this setting.

6.2. Change a Device’s Location

SwitchThat One allows you to organise your devices into rooms. See Chapter 5, Organising your Devices for details. The Configure screen for a device provides a number of ways to move that device into a room.

6.2.1. Move a Device in an Existing Room

To move a device into a room, go to the Configure screen for the device and find the Location section. This will show the current location of the device: either the Home screen, or the name of the room it is already inside.

Tap Move and a list of all available rooms will appear. Tap on the room you wish to move the device into (or tap on Home if you wish to move the device back to the Home screen.) Tap Update location to finish.

Moving a Device to another Room

Moving a Device to another Room


The page will reload to show that the device has been moved to the selected location.

6.2.2. Creating a New Room for a Device

If you want to create a new room specifically for a device, then go to the Configure screen for the device and find the Actions section.

Tap Create a new room for this device, enter a name for the new room when prompted and tap OK to create the room.

The page will reload to show that the device is inside the newly-created room.

6.3. Dealing with Unavailable Devices

From time to time your One Hub may report a device as ‘unavailable’. This means that your One Hub cannot communicate with the device over the network, and attempts to control that device will fail.

Unavailable devices are shown with an orange warning symbol on the device tile, and next to the device name in the title bar of the Control and Configure screens.

There are a few reasons why a device might show as unavailable:

  • The device has become disconnected from your home network
  • The device has been temporarily powered off
  • SwitchThat One has lost its link to the device
  • You no longer use or own this device

The first thing to check is that your device is powered on and that it’s connected to your home network – these are the most common reasons why a device might show as unavailable. You should also try to access the device using the manufacturer-supplied app to make certain that the device is functioning correctly.

If you are certain that the device is powered on, connected to your home network and is otherwise functioning correctly, but SwitchThat is still showing it as unavailable, then it’s possible that your One Hub has lost its link to the device.

6.3.1. Refreshing a Device

You can try to restore your One Hub’s link to the device by ‘refreshing’ it.

To refresh your One Hub’s link to a device, go to the Configure screen for the device and find the Actions section.

Tap Refresh this device and your One Hub will start searching for the device. If the link between your One Hub and the device is restored, the page will update to show the device as available once again.

6.3.2. Forgetting a Device

Another reason why a device might show as unavailable is that you no longer use or own that device. You may have sold it, or it may have broken or otherwise no longer be in use.

In such cases, you will probably want to remove the device from your SwitchThat One environment. You can do this by instructing your One Hub to ‘forget’ the device.

To forget a device, go to the Configure screen for the device and find the Actions section. Tap Forget this device to remove the device.

There may also be an option to forget this device and all other devices associated with it. For example a Philips Hue light will have options to forget that light and to forget all of your Philips Hue lights.

Chapter 7. Your user page

Your user page is where you can find things like lighting scenes, personalise SwitchThat One, and where you can change your user details.

You can reach your user page by tapping the Your name button in the main menu. On smaller displays your user name will not be visible, just the user icon.

The user icon in the main bar

The user icon in the main bar


7.1. Lighting scenes

Lighting scenes let you store your favourite lighting setups so they can be instantly recalled, for when you want to relax in front of a film, or set the mood for a party.

You can create lighting scenes that include any of your SwitchThat enabled lights, regardless of manufacturer.

Note

Lighting scenes are only be available if you use SwitchThat One to control your lights.

7.1.1. Add a new lighting scene

Creating a new lighting scene is simple. First of all you need to set up your lights the way you want them for this scene. Then go to your user page and and find the Lighting scenes section.

The Lighting scenes section of your user page

The Lighting scenes section of your user page


Tap the Add new button and you’ll be taken to a screen where you can configure the lighting scene

Adding a new lighting scene

Adding a new lighting scene


You should enter a name for the lighting scene and then you need to tell SwitchThat One which lights should be included. You’ll see a list of all your lights, organised by room, with a preview of each light’s current colour or brightness.

Tap on all of the lights you want to include in this scene. Once you're done tap Add and the scene will be created.

You’ll be taken back to your user page and there will be a new icon in the Lighting scenes section, for the lighting scene you just created.

7.1.2. Apply a lighting scene to your lights

To apply one of your lighting scenes simply tap on the lighting scene icon. Each light in the scene will be instantly set to the correct colour / brightness setting.

Tap on the lighting scene icon to apply it to your lights

Tap on the lighting scene icon to apply it to your lights


7.1.3. Deleting a lighting scene

Currently you can delete lighting scenes, but you can’t change them (so to change an existing lighting scene, you’ll need to delete it and add a new one).

To delete a lighting scene:

  1. Go to your user page and find the Lighting scenes section.
  2. Tap the Edit icon at the top-right of the Lighting scenes section. A red cross will appear on each lighting scene
  3. Tap a lighting scene to delete it
  4. Tap Done when you’re finished.

7.1.4. Importing Philips Hue scenes

If you use Philips Hue lights and already have some scenes that you’d like to use in SwitchThat then they can be easily imported.

Go to your user page and find the Lighting scenes section. Tap Import and you’ll see a list of all the scenes found on your Hue bridge.

Import your Philips Hue scenes

Import your Philips Hue scenes


Note

The list will show every scene found on your Hue bridge. There may be duplicates if you use more than one app to control your Hue lights.

To try out a scene, tap on its name, and the scene will be applied to the appropriate lights (these lights will also be listed below the scene name).

Importing a Philips Hue scene

Importing a Philips Hue scene


You can tap on the lights shown below the scene name to include them or remove them from the imported scene.

Note

IMPORTANT: make sure all of the lights you are including in the scene are on before importing! If necessary, switch the lights on and tap on the scene name again to apply the scene. The scene will only import correctly if all the lights you want to include have been set to the appropriate colour by following this procedure.

To import the scene, you need to give it a name and tap the Import button. The name will default to the original Hue scene name, but this could clash with a lighting scene you have previously created; if so you’ll be warned and you must change the name before importing.

The scene will take approx 30 seconds to import, so be patient. A progress bar will show the status of the import. Once complete, if you return to your user page and there will now be a new icon for the imported lighting scene. As before, tap this scene to apply it to your lights.

7.2. Personalising SwitchThat One

7.2.1. Changing the interface style

Changing the interface style lets you alter the way the SwitchThat One user interface looks. Each user can set their own interface style.

To change the interface style:

  1. Go to your user page and find the My account section.
  2. Tap Change interface style
  3. You’ll see a preview of each interface style available.
  4. Tap on an interface style to activate it

7.3. Editing your user details

You can change your user name and your password from your user page:

  1. Go to your user page and find the My account section.
  2. Tap Change my details
  3. Change your name and password as required. Leave the password boxes empty if you don’t need to change it.
  4. Tap Update when you’re finished.

7.4. Signing out

To sign out from SwitchThat One:

  1. Go to your user page and find the My account section.
  2. Tap Sign me out.

If you’re accessing SwitchThat One via a web browser, you be taken to the sign in screen.

If you’re using the SwitchThat app on you phone or tablet, you’ll be taken back to the Hub list. Tap on your One Hub to sign in again.

When using the SwitchThat app, you can also tap Back to Hub list to return to the Hub list without signing out. This is useful if you have more than one Hub and want to switch between them without signing in each time.

Chapter 8. Settings & Configuration

The Settings screen is where you can set the behaviour of your SwitchThat One hub. Many of these settings will just be set once when you initially set it up. Only an ‘Owner’ will have access to these screens.

8.1. Location

Setting your location is important for the correct functioning of your One Hub. Your One Hub will come preset to a sensible location (e.g. London in the UK), but it’s worth changing this to your nearest city or town. Similarly, if you move and install your One Hub in a new city or even country, you should tell your One Hub where it is located.

Location is used to determine your timezone, what time sunrise and sunset are, local weather and can be used in conjunction with location services on your phone/tablet.

To update your location tap Settings in the menu at the top of the screen. Find the Configuration section and tap Location. You’ll see a summary and map of the current location settings.

Setting your Location

Setting your Location


Tap Change my location and three selection boxes will appear to allow you to find your current location, in terms of the continent, country and nearest city or town. When you choose a new location the map will update to help you confirm your selection. Once you’re happy, tap Set location to confirm your new location.

8.2. Remote Access

Remote access provides a secure and encrypted way for you to connect to your One Hub from outside your home network. Remote access works with the SwitchThat app on your iPhone, iPad or Android phone/tablet.

8.2.1. Setting up Remote Access

Tap Settings in the menu at the top of the screen. Find the Configuration section and tap Remote access.

Remote Access Settings

Remote Access Settings


To enable remote access check the Enable remote access box. You can simply uncheck the box to disable remote access again, should you wish to do so.

You can also customise the name and the image of your One Hub, as it appears in the Hubs list in the SwitchThat app on your phone/tablet. If you use multiple One Hubs in different locations (e.g. at home and at the office) then you can give each Hub a different name & image to make it easy to distinguish between them.

Changes to the name and image will update on your mobile device when you are next on the local network.

8.2.2. Accessing your One Hub on the Move

You need to use the SwitchThat app on your iPhone, iPad or Android phone/tablet to access your One Hub remotely. You must also already be signed in to your One Hub – you cannot use remote access unless you have already previously signed in ‘locally’, and you will lose remote access if you subsequently sign out. This is a key part of the security measures used to protect access to One.

Once you’re signed in, the SwitchThat app will connect to your One hub remotely whenever you have Internet access outside your home (we recommend a minimum of 3G access). You can easily tell if you’re connected to your One Hub using remote access by the presence of a globe icon at the top-right of the page.

Globe confirming Remote Access

Globe confirming Remote Access


Note that the SwitchThat app will choose ‘local’ access to your One Hub wherever possible and will only use remote access when it cannot connect to your One Hub directly over a wifi connection. The iPhone/iPad app will switch automatically between ‘local’ and remote access as appropriate.

8.3. Users

SwitchThat One supports three types of user, each with different levels of control over your devices and access to your One Hub: Owner, Standard and Guest. You are encouraged to create users for all of the people who will have frequent access to your One Hub.

8.3.1. Owner Users

An Owner user has full control of all of your devices and full control of the One Hub. Only an Owner user can add, configure and remove devices, create & edit rooms, create Interactions, or change the configuration of your One Hub.

You can create as many Owner users as your like, but you must have at least one. Your One Hub comes with one Owner user out of the box, initially called ‘Owner’. You are free to rename this user if you prefer.

8.3.2. Standard Users

Standard users can see and control all of your devices, but they cannot change the configuration of devices, or of the One Hub itself.

A Standard user can customise the layout of the Home page, rooms and Shortcuts; these customisations will be visible only to that user. Standard users can also create their own Shortcuts.

8.3.3. The Guest User

The Guest user is intended to allow someone temporary or restricted access to your One Hub. For example if you have a friend staying and want to give them control of some of the devices in your home.

The Guest user can only see and control devices that an Owner user has granted Guest access to. See Chapter 6, Configuring your Devices for details on controlling Guest user access to a device.

The Guest user does not need a password, and several people can be signed in as a Guest at the same time.

8.3.4. Adding a New User

Tap Settings in the menu at the top of the screen. Find the Users section and tap Add a new user.

Adding a User

Adding a User


Enter the name and password of the new user. If the new user is to be an Owner, then check the This user is an owner box; leave this box unchecked to create a Standard user. When you’re ready, tap Create user to save this new user.

8.3.5. Managing Users

Tap Settings in the menu at the top of the screen. Find the Users section and tap Manage users. You will see a list of the the users of your One Hub. You can edit or remove these users from this list.

Managing Users

Managing Users


8.3.6. Editing a User

Find the name of the user in the list and tap it; a menu will appear below the user’s name. Tap Edit user to edit it.

User menu

User menu


You can change the user’s name and password and also change whether they are an Owner user or a Standard user. Once you are happy, tap Update to save your changes.

Note

You can quickly edit your own user account by tapping your name in the menu at the top of the screen.

8.3.7. Removing a User

Find the name of the user in the list and tap it; a menu will appear below the user’s name. Tap Remove user to remove it.

You cannot remove your own user account.

8.4. Alerting services

If you want to send external alerts (emails, tweets or SMS text messages) from your Interactions, then you’ll need to configure one or more alerting services. Once setup, an alerting service can be accessed from within an Interaction and used to send an email, tweet or text in response to some event.

See Section 12.3.1, “Sending alerts” for instruction on how you can send alerts from your Interactions.

Currently you can set up the following alerting services:

  • Email over SMTP

  • Twitter

  • SMS text messaging

To set up an alerting service,Tap Settings in the menu at the top of the screen. Find the Configuration section and tap Alerting. You’ll see a row of buttons near the top of the screen, one for setting up each type of alerting service. The remainder of this section will cover setting up, and testing, each of the support alerting service.

8.4.1. Setting up an email alerting service

To set up an email alerting service, tap Setup Email alerting. You’ll be taken to a screen where you can enter the configuration details of your SMTP account.

Setting up an email alerting service

Setting up an email alerting service


Firstly, give the alerting service a name. Make this short and memorable – ‘email’ will do fine.

Note

If you want to refer to the alerting service from within the Advanced Interaction Editor you’ll need to use this name.

You can use the Description box to add a more detailed description of the alerting service (e.g. ’Send email using my gmail account’).

Next, you’ll need to enter the specific details of your email account. You can get these details from your email provider (If you use gmail, then do a search for ‘gmail smtp settings’. Try something similar for other email providers). Once you’ve found the appropriate settings, you’ll need to enter the SMTP server and port.

You must also enter a From address for the emails that are sent; usually this will be your own email address.

If your email account requires authentication to send messages (and most do) then you’ll also need to enter your Username and Password. Finally, if your SMTP server uses TLS encryption, then make sure the Use ‘starttls’ box is ticked.

Note

If you want to use your Gmail account to send alerts with SwitchThat One, you’ll probably need to change your Gmail security settings to ‘allow less secure apps to access your account’. See https://support.google.com/accounts/answer/6010255?hl=en for details of how to do this.

Once you’ve entered all the details, tap Save, and you’ll be taken back to the main Alerting services screen. Your new email alerting service will be shown in the list of available alerting services.

8.4.1.1. Testing your email alerting service

After setting up an email alerting service, you should test it to make sure everything is working correctly. On the Alerting screen, find the name of the alerting service in the list and tap it; a menu will appear below the alerting service name. Tap Test and you’ll be taken to a screen where you can send a test email.

Testing an email alerting service

Testing an email alerting service


Enter the destination email address in theTo box, complete the Subject and Body of the email and then tap Send. If everything is configured correctly you’ll see the message Sent appear, and the email should arrive at its destination. If there was a problem then you’ll see an error message explaining why the email couldn't be sent. If you think you’ve entered some of the configuration details incorrectly, you can edit your alerting service to fix the problem.

8.4.1.2. Editing your email alerting service

On the Alerting screen, find the name of the alerting service in the list and tap it; a menu will appear below the alerting service name. Tap Edit and you will be taken to a screen where you can edit the configuration details of this alerting service.

Once you’ve edited your alerting service configuration, tap Save and then run another test to make sure you’ve fixed the problem.

8.4.2. Setting up an SMS alerting service

You’ll need to have an account with a SMS gateway in order to send SMS alerts from SwitchThat One. Currently the following types of SMS gateway are supported:

  • Kapow

  • SNPP Pager/SMS gateways. This will provide support for Vodafone, Page One and others

To setup an SMS alerting service, tap Setup SMS alerting. You’ll be taken to a screen where you can enter the configuration details of your SMS gateway account.

Setting up an SMS alerting service

Setting up an SMS alerting service


Firstly, give the alerting service a name. Make this short and memorable – ‘sms’ will do fine.

Note

If you want to refer to the alerting service from within the Advanced Interaction Editor you’ll need to use this name.

You can use the Description box to add a more detailed description of the alerting service (e.g. ’Send SMS text using my Kapow account’).

Next, you’ll need to enter the specific details of your SMS gateway account. You can get these details from your service provider. What information you need to enter depends on the type of gateway you use:

  • For Kapow, you'll need to enter your Kapow username and password.

  • For an SNPP gateway, you'll need to enter the Server name or IP address, and your Username.

Once you’ve entered all the required configuration, tap Save, and you’ll be taken back to the main Alerting services screen. Your new SMS alerting service will be shown in the list of available alerting services.

8.4.2.1. Testing your SMS alerting service

After setting up an SMS alerting service, you should test it to make sure everything is working correctly. On the Alerting screen, find the name of the alerting service in the list and tap it; a menu will appear below the alerting service name. Tap Test and you’ll be taken to a screen where you can send a test SMS text message.

Testing an SMS alerting service

Testing an SMS alerting service


Enter the destination number in the To box, the message you want to send in the SMS text box, and then tap Send. If everything is configured correctly you’ll see the message Sent appear, and the SMS text message should arrive at its destination. If there was a problem then you will see an error message explaining why the SMS couldn't be sent. If you think you’ve entered some of the configuration details incorrectly, you can edit your alerting service to fix the problem.

8.4.2.2. Editing your SMS alerting service

On the Alerting screen, find the name of the alerting service in the list and tap it; a menu will appear below the alerting service name. Tap Edit and you will be taken to a screen where you can edit the configuration details of this alerting service.

Once you’ve edited your alerting service configuration, tap Save and then run another test to make sure you’ve fixed the problem.

8.4.3. Setting up a Twitter alerting service

You’ll need to have a Twitter account in order to send Tweets from SwitchThat One. When setting up a Twitter alerting service you’ll be asked to grant SwitchThat One access to your Twitter account.

Note

Only your One Hub will have access your twitter account and be able to send tweets on your behalf. SwitchThat One will only send Tweets when explicitly instructed to do so as part of an Interaction.

To setup a Twitter alerting service, tap Setup Twitter alerting.

The first step is to grant SwitchThat One access to your Twitter account and get an authorization PIN.

Setting up a Twitter alerting service part 1

Setting up a Twitter alerting service part 1


Tap Get an authorization PIN and a web browser will open up taking you to a page on the Twitter website where you will be asked to authorize SwitchThat One to access your account. You may have to sign in to Twitter at this point. After granting access to your account you’ll be shown an authorization PIN – you should write this down, or highlight and copy it, so that it can be entered during the next step of the setup process. After obtaining your authorization PIN you should return to SwitchThat One

Note

If you’re using the SwitchThat app on an iPad, iPhone or Android device, the authorization page will open up in your default web browser (e.g. Safari on iOS). Once you have obtained your authorization PIN, simply return to the SwitchThat app to continue the setup process.

To proceed to the next step of the setup process you should tap I have an authorization PIN and you will be taken to a screen where you can enter your PIN.

Setting up a Twitter alerting service part 2

Setting up a Twitter alerting service part 2


Note

If for any reason you were unable to return directly to the initial Twitter alerting service setup screen, you can get back to it by visiting the Alerting screen and tapping Setup Twitter alerting again. In this case you will be taken directly to the second step of the setup process.

Firstly, give the alerting service a name. Make this short and memorable – ‘twitter’ will do fine.

Note

If you want to refer to the alerting service from within the Advanced Interaction Editor you’ll need to use this name.

Next, you’ll need to enter the authorization PIN you were given when you granted SwitchThat One access to your Twitter account.

Once you’ve entered your PIN, tap Save. If the setup process was successful, you’ll be taken back to the main Alerting services screen. Your new Twitter alerting service will be shown in the list of available alerting services. The Description will contain the name of your Twitter account.

However, if setup fails with the error message that Twitter has rejected your authorization PIN, then double-check you have entered the PIN correctly and try again. If setup still fails, then tap I need an authorization PIN to get a new PIN and start again.

8.4.3.1. Testing your Twitter alerting service

After setting up a Twitter alerting service, you should test it to make sure everything is working correctly. On the Alerting screen, find the name of the alerting service in the list and tap it; a menu will appear below the alerting service name. Tap Test and you’ll be taken to a screen where you can send a test tweet.

Testing a Twitter alerting service

Testing a Twitter alerting service


Enter the message you want to send in the Tweet box, and then tap Send. If everything is configured correctly you’ll see the message Sent appear, and the tweet should appear in your Twitter timeline. If there was a problem then you’ll see an error message explaining why the tweet couldn't be sent.

8.4.3.2. Editing your Twitter alerting service

The only thing you can change for a Twitter alerting service is its name. If you wish to send tweets from a different account, you’ll need to setup a new Twitter alerting service specifically for that account.

On the Alerting screen, find the name of the alerting service in the list and tap it; a menu will appear below the alerting service name. Tap Edit and you will be taken to a screen where you can edit this alerting service.

8.5. Calendars

SwitchThat One enables you to schedule events to happen using an iCal server based calendar such as Google Calendar. At the time of writing, no other calendars have been tested, but should work if they conform to the standards.

This could be useful if you are going to be away for a couple of weeks, as you could set up a calendar that has lights switching on and off periodically, or your music system playing during the evening. You could even tweak the calendar entries while you are away.

Calendar repeat rules will also be respected, so that you can have an event that ‘repeats every Tuesday at 3pm’ or trigger your Sonos to play ‘Happy Birthday to you’ every year to wake you up.

8.5.1. Adding a calendar

Tap Settings in the menu at the top of the screen. Find the Configuration section and tap Calendars. Tap Setup a new calendar and you’ll be taken to a screen where you can enter the details of your calendar.

You need to enter the iCal URL for the calendar, and give it a name, to help you distinguish it from any other calendars you might add.

Note

To find the iCal URL of a Google Calendar, open the Calendar Details for your calendar, and click the Private Address button.

The contents of the calendars you add will be scanned whenever you make changes on this screen, and then every hour thereafter. You can also click the “Synchronise Now” button to trigger a rescan of your events if you are impatient!

8.5.2. Using a calendar

What can you schedule using your calendar? Basically anything you can write in the ‘Then That’ box of an Interaction, as covered in Section 13.2.2, “Then That”. If you’re not already familiar with writing your own Interactions, then take a look at Chapter 13, Advanced Interactions before starting to use calendars.

To create a calendar-based event:

  1. Add a new event to your calendar at the appropriate date/time
  2. Enter the ‘Then That’ Interaction script as the event title

For example, if you wanted your Sonos player to wake you up at 6am tomorrow morning, you would create a new calendar event for 6am and set the event title to be:

   devices['My Sonos'].play

You can also include an action to occur at the end of the calendar event, by separating the actions with a ‘|’ symbol. So, if your calendar event has 1 hour duration you can stop the music at the end by changing the event title to:

   devices['My Sonos'].play | devices['My Sonos'].pause

However, as it is quite common to match on/off, play/pause, mute/unmute etc., you can just use the ~ symbol as shorthand, e.g.:

   devices['my sonos'].play | ~

Take a look at Chapter 13, Advanced Interactions for full details of the kinds of events you can schedule using a calendar.

8.6. API Users

SwitchThat One features a rich API to enable automation using external scripts and applications. See Chapter 11, The HTTP API interface for full details of the One API.

The One API is secured using basic access HTTP authentication. If you want to use the One API you must create one or more API users on your One Hub.

8.6.1. Adding an API User

Tap Settings in the menu at the top of the screen. Find the Configuration section and tap API users. You will see a list of the active API users for your One Hub, which will be empty initially.

Tap Add a new API user to create a new one. Enter the name and password of the new API user and then tap Update API user to save.

8.6.2. Editing or Removing an API User.

Tap Settings in the menu at the top of the screen. Find the Configuration section and tap API users. Find the name of the API user in the list and tap it; a menu will appear below the API user’s name. Tap Edit API user to edit it, or Remove API user to remove it.

Chapter 9. My Devices

9.1. Adding New Devices to your One Hub

Your One Hub will discover most of your supported devices automatically, and will notify you when a new device is discovered.

However, some devices can’t be discovered automatically, and you will either need to tell your One Hub to look for them, or you’ll need to go through some simple manual steps to add & configure the device.

9.1.1. Search for New Devices

You will need to tell your One Hub to search for the following devices, as they can’t be discovered automatically:

  • LIFX bulbs.

  • Philips Hue bulbs that have been added since your Hue bridge was originally discovered by your One Hub.

  • Belkin WeMo bulbs that have been added since your Belkin WeMo lights bridge was originally discovered by your One Hub.

See Appendix A, Supported Devices for full details of how these device are discovered.

To search for new devices, tap Settings in the menu at the top of the screen. Find the My Devices section and tap Search for new devices.

9.1.2. Add a New Device

Some devices must be explicitly added to your One Hub, usually because they require you to enter some configuration information before your One Hub is able to access the device.

You will need to explicitly add the following devices to be able to use them with your One Hub:

  • Tado thermostat
  • Nest® devices

See Appendix A, Supported Devices for full details of how these device are added to your One Hub.

To add a new device, tap Settings in the menu at the top of the screen. Find the My Devices section and tap Add a new device. Find the device in the list and tap the appropriate button to begin adding your device.

9.2. Forgetting all of your Devices

In certain circumstances, you may want to have your One Hub forget all the devices it has discovered. For example, if you move your One Hub in a new location and intend to use it to control a new set of devices at that location.

To forget all of your devices, tap Settings in the menu at the top of the screen. Find the My Devices section and tap Forget all of my devices.

Note

The Forget all of my devices feature should be used with caution. Your One Hub will need to rediscover any devices that you still want to use.

Chapter 10. Administration

The Administration page has a number of options for updating and administering your One Hub. This section describes the various options available on the Administration page.

10.1. Updates

Your SwitchThat One Hub will occasionally receive system updates bringing new and improved functionality. Your One Hub will automatically check for system updates on a daily basis, and a notification will appear when an update is ready to be applied.

10.1.1. Checking for Updates

You can also ask your One Hub to check for updates at any time. You might use this feature if, e.g. you have heard about an update via our website or social media channels, but your One Hub has not yet notified you about it.

To ask your One Hub to check for updates now:

  1. Tap Settings
  2. Find the System section and tap Administration
  3. Find the Updates section and tap Check for updates

Note

It can take upto 5 minutes before you are notified of a new update. If you are not notified within this time, then there are no new updates available for your One Hub.

10.1.2. Updating your SwitchThat One Hub

You’ll receive a notification once an update is ready to be applied to your One Hub. Tapping the link in this notification will take you to the Update SwitchThat One page.

Tap Update to start updating. The update will take approximately 5 minutes and you’ll lose access to your One Hub during this time. All Interactions will temporarily stop running during the update process. A notification will appear as soon as the update has completed and your One Hub is fully functional again.

If you prefer you can choose to delay the update and apply it at a more convenient time. Tap I’ll update later and you’ll be taken back to the Home screen without applying the update.

When you’re ready, you can return to the page to apply the update:

  1. Tap Settings
  2. Find the System section and tap Administration
  3. Find the Updates section and tap Update SwitchThat One

10.1.3. Updating the Base Software

Warning

Updating the base software on which SwitchThat One runs has the potential to stop your One Hub from functioning correctly. Do not attempt to do so unless instructed to by SwitchThat Limited.

Occasionally, we might issue a recommendation to update the base software that powers your SwitchThat One Hub. We’ll let you know via our website and social media whenever a base software update is required.

To update the base software on your One Hub:

  1. Tap Settings
  2. Find the System section and tap Administration
  3. Find the System Health section and tap Update base software
  4. You’ll be asked to confirm that this is what you want to do. Tap OK and your One Hub will begin the update process.

The update will take approximately 5-10 minutes and you’ll lose access to your One Hub during this time. All Interactions will temporarily stop running during the update process. A notification will appear as soon as the update has completed and your One Hub is fully functional again.

10.2. System Health

10.2.1. Shutdown

If you need to disconnect your One Hub from its power source, it’s a good idea to shut it down first. To shutdown your One Hub:

  1. Tap Settings
  2. Find the System section and tap Administration
  3. Find the System Health section and tap Shutdown

You’ll be asked to confirm that this is what you want to do. Tap OK and your One Hub will shut itself down.

The process will take approximately 1 minute, after which it is safe to unplug your One Hub from its power source, or to restart it.

10.2.2. Restart

If your One Hub starts to behave unexpectedly, or if you seem to have lost the ability to control one or more of your devices, it’s worth doing a restart to see if that fixes the problem. To restart your One Hub:

  1. Tap Settings
  2. Find the System section and tap Administration
  3. Find the System Health section and tap Restart

You’ll be asked to confirm that this is what you want to do. Tap OK and your One Hub will restart itself.

The process will take approximately 2 minutes and you will receive a notification when your One Hub has restarted and is fully functioning again. You will temporarily lose access to your One Hub and all Interactions will temporarily stop running during the restart process.

10.2.3. Show Running Processes

Warning

This page is intended for customer support purposes only and allows users to provide us with information when troubleshooting any issues you may have.

The screen shows a list of the vital system processes, how many instances are running, and highlights any that are not running as expected.

Chapter 11. The HTTP API interface

SwitchThat One provides a powerful API that allows you to access and control your devices using simple RESTful HTTP requests. You could use the One API to integrate SwitchThat One with other systems, such as a Voice recognition module, or perhaps write UNIX shell scripts to control or automate your devices.

11.1. API authentication

The One API is secured using basic access HTTP authentication.

If you haven’t already done so, you’ll need to create an API user, specifying the username & password you’ll use in your API requests. The process of creating an API user is described in Section 8.6.1, “Adding an API User”.

11.2. Making API requests

All API requests are made with a URL of the form: http://one-hub.local/api/type/name_or_id/action

where:

  • one-hub.local needs to be replaced by the name or IP address of your One Hub. We will use one-hub.local in this document to refer to the One Hub

  • type can be one of 'device', 'shortcut', or 'room'

  • The name_or_id will be either the name or id of a thing in your system, of the type you have specified. Names are case insensitive.

    If you want to use a name that has spaces (or other characters that are reserved in URLs), then they must be ‘encoded’. e.g. “my light” would become “my%20light” or “my+light”. See Wikipedia for more information.

  • action will be one of the Actions listed in the table in Appendix B, HTTP API Reference

You would get the current state of a device with a HTTP GET request, and you would use a HTTP POST request to update the state of a device. The same URL will generally be used for both getting and updating a device’ state.

Some example URLs are shown below:

  • GET http://one-hub.local/api/device/corner%20light/on would return whether the 'Corner Light' is on.

  • GET http://one-hub.local/api/device/corner%20light/colour would return whether the current colour of the 'Corner Light'.

  • POST http://one-hub.local/api/shortcut/all%20lights/on turns on all your lights

  • POST http://one-hub.local/api/room/living%20room/on turns on all your lights in the living room

  • POST http://one-hub.local/api/device/music%player/play would start playing music on your Sonos player

  • POST http://one-hub.local/api/device/music%player/mute would mute your player

  • POST http://one-hub.local/api/device/corner%20light/colour/255/0/0 will set your corner light to red

You can also use the HTTP ‘Accept’ header to control whether you get back a plain text response or one encoded in JSON (JavaScript Object Notation) interchange format.

We’ll now look at some examples of accessing the API using some common tools:

  • Your web browser
  • The command-line wget utility
  • The command-line curl utility

First of all, choose a device that has an on/off switch, such as a light bulb or power socket. We’ll use a Belkin WeMo Switch, called ‘WeMo Switch’, in this example, but you’ll need to use the name of your own device instead.

11.2.1. Making API requests with a web browser

You should be able to point your web browser at a URL such as: http://one-hub.local/api/device/WeMo%20Switch/on

You’ll get a login popup on your first attempt, and you should enter the username & password of the API user you created earlier. When the page loads you’ll see a ‘1’ or a ‘0’ which will tell you whether your ‘WeMo Switch’ device is on or off.

You won’t be able to do very much more with a standard web browser, but by using browser plugin you should be able to send POST requests and alter the ‘Accept’ header.

For example, using the HttpRequester plugin for Firefox:

  1. Open HttpRequester from the Tools menu (Ctrl+Alt+P)
  2. Enter http://one-hub.local/api/device/WeMo%20Switch/on as the Request URL
  3. Click the GET button to retrieve the current status of the switch
  4. Click POST to turn the switch on, if it isn’t already
  5. Change the end of the URL to be ‘off’, and send another POST request to turn the switch off again
  6. Click on the Headers tab and find the Accept header. Enter ‘application/json’ as the value, and click Add
  7. You will now get additional information in the Response shown in the right, such as {"success":1,"message":"OK","result":1}. This response will be more suitable for some applications and toolkits

Other plugins for Firefox and other browsers such as Chrome and Internet Explorer will work similarly.

11.2.2. Making API requests using wget

Here are some examples that use wget. You will need to add --user and --password to each example to specify the username & password of your API user.

# Get whether light is already on, saving 0 or 1 to output.txt
wget -q -O output.txt http://one-hub.local/api/device/47/on

# Get whether light is already on, returning a JSON structure
wget -q -O output.txt http://one-hub.local/api/device/47/on --header "Accept: application/json"

# Turn light on
wget -q -O output.txt http://one-hub.local/api/device/47/on --post-data=''

# Turn hall lights light off
wget -q -O output.txt http://one-hub.local/api/room/hall/off --post-data=''

# Toggle light status
wget -q -O output.txt http://one-hub.local/api/device/47/toggle --post-data=''

# Blink light 3 times
wget -q -O output.txt http://one-hub.local/api/device/47/blink/3 --post-data=''

11.2.3. Making API requests using curl

Similarly using curl, omitting ‘--user name:password’ for brevity.

# Get whether light is already on, displaying 0 or 1
curl http://one-hub.local/api/device/47/on

# Get whether light is already on, saving 0 or 1 to output.txt
curl -o output.txt http://one-hub.local/api/device/47/on

# Get whether light is already on, returning a JSON structure
curl -o output.txt http://one-hub.local/api/device/47/on -H "Accept: application/json"

# Turn light on
curl -X POST http://one-hub.local/api/device/47/on

# Toggle light status
curl  -X POST http://one-hub.local/api/device/47/toggle

# Blink light 3 times
curl -X POST http://one-hub.local/api/device/47/blink/3

# Shell script which uses curl
if [ `curl -s http://one-hub.local/api/device/my%light/on --user USER:PASS ` == 1 ]
then
  echo 'My Light is On'
else
  echo 'My Light is Off'
fi

Chapter 12. Interactions

SwitchThat One Interactions allow you to harness and combine your smart devices to automate your smart home in ways that would be impossible just by using the manufacturers’ apps.

With Interactions, you can:

  • Have lights come on automatically in the evening, or when you walk past a motion sensor

  • Send yourself an email or SMS if a motion detector picks up an intruder in your garage at night

  • Simulate occupancy – when on holiday have your lights / music behave as if you were still at home

  • Start playing your favourite radio station in the kitchen at breakfast time

There are two ways you can create Interactions:

  1. Interaction Builder: an easy-to-use visual tool that allows you to quickly build simple Interactions. This approach is recommended for getting started, and a detailed step-by-step guide is presented in Section 12.1, “Interaction Builder”.

  2. Advanced Interaction Editor: for when you need to create more sophisticated Interactions than are possible with Interaction Builder. This approach is for more advanced users who feel comfortable writing simple scripts. You can learn how to use the advanced editor in Chapter 13, Advanced Interactions.

12.1. Interaction Builder

The best way to get started with Interactions is to start creating them, and the easiest way to do this is by using the Interaction builder. The basic principle behind an Interaction created in Interaction Builder is:


An event can be something like ‘at a specific time every day’ or ‘when a motion sensor detects motion’. An action can be something like ‘turn that switch on’, or ‘set my light to that colour’.

12.1.1. Getting Started

To start working with Interaction Builder tap Settings in the menu at the top of the screen, find the Interactions section and tap Interaction Builder You’ll now see the Interaction Builder interface:

The Interaction Builder

The Interaction Builder


Tip

If you can’t see the Settings menu item, make sure you are signed in as an Owner user.

First, enter a name for your Interaction in the Interaction Name box. You can change this name later, so don’t worry if you can’t think of the perfect name now.

Below Interaction Name there are two sections, labelled If This and Then That. This is where you’ll create your Interaction, and we’ll discuss these sections in detail next.

12.1.2. If This

The If This section is where you define an event to trigger your desired action. We’ll take a quick step-by-step look at how this works.

To start with, you can choose between a device event or a general event. Device events are things that might happen to one of your devices, for example a light is turned on or a motion sensor detects motion. General events are to do with things like time or the weather.

Tap Event to select a general event. Event will now be selected and a choice of event types will appear below it.

Choosing an If This event type

Choosing an If This event type


Currently only time-based general events are supports, so tap Times, Days & Dates You’ll be presented with a choice of time-based events:

Choosing a time-based If This event

Choosing a time-based If This event


Tap At this time every day to select your event. Some events can be customised and, when selected, will show a widget to allow you to change the event settings. In this case, you are shown a control that lets you set the specific time of day you want your action to fire.

An If This event is selected

An If This event is selected


For the purposes of this walkthrough, set a time in the near future.

Customising the If This event

Customising the If This event


And that’s it, you’ve now defined your If This event!

Tip

If you make a mistake or change your mind, simply tap the < symbol on the right-hand-side of the selection you wish to change and you will be taken back a step.

12.1.3. Then That

The Then That section is where you choose the action(s) you want to trigger when the If This event occurs. You can define up to 5 actions as part of a single Interaction.

We’ll continue the step-by-step look at how this works.

To start with, you must choose a ‘thing’ to perform the action. You can choose either a device, room or shortcut. For example, you might want to turn a specific device on, or perhaps have all the devices contained in the shortcut ‘Downstairs lights’ turn on. There’s a further category of things, called Other, and this allows you to do things such as send alerts.

For this example, we’ll choose a device so tap Device and a list of devices will appear.

Choosing a Then That device

Choosing a Then That device


Note

Most, but not all, types of device can be used in Interaction Builder. If a device doesn’t appear in this list, then it can’t be used in Interaction Builder.

Tap a device to select it. You’ll be presented with a choice of actions that device can perform. What actions are available will depend on the type of device; for example, a light will have actions to turn it on, off, set the brightness and perhaps its colour. A media player will have actions to play or pause, and perhaps set the volume.

Choosing a Then That action

Choosing a Then That action


Some actions can be customised and, when selected, will show a widget to allow you to change the action settings. For example you might choose the colour that a light should be set to. Choose an action you’d like to test and change its settings as appropriate.

Customising the selected Then That action

Customising the selected Then That action


12.1.3.1. Multiple Then That actions

You might want to do more than one thing in the Then That part of your Interaction, e.g. turn several lights on at once. Interaction Builder let you define upto 5 Then That actions in a single Interaction.

To add a further Then That action you should tap the Add another button, found below the existing Then That action. A new set of Then That buttons will appear allowing you configure the additional action. Further actions can be added in the same way.

The following image shows the Then That section of an Interaction where two lights are configured to switch on when the Interaction is triggered.

Defining more than one Then That action

Defining more than one Then That action


If you need to get rid of one or more of the existing Then That actions, then tap the Edit list button, found at the bottom of the list.

Editing the list of Then That actions

Editing the list of Then That actions


Tap the Remove button below any action you wish to remove from the list. Tap Done when you have finished.

12.1.4. Saving and Running the Interaction

The final step is to save your Interaction and (optionally) start it running. If you want this Interaction to start running immediately, then check the Start this interaction running box. The following image shows how the completed Interaction looks in Interaction Builder.

The finished Interaction

The finished Interaction


Tap Save to finish creating your Interaction. You’ll be taken to the My Interactions screen, where you’ll see the newly-created Interaction.

12.2. The My Interactions screen

The My Interactions screen shows all of your Interactions, and allows you to control and edit them. To access My Interactions, tap Settings in the menu at the top of the screen. Find the Interactions section and tap My interactions

The My Interactions screen

The My Interactions screen


Your Interactions are shown as tiles. If an Interaction is running, it will have a green border and a green ‘playing’ symbol in the top-left corner. An Interaction that is not running will have a grey border, and no ‘playing’ symbol.

To access one of your Interactions, tap its tile. The other Interactions will be hidden, and a menu will appear showing the various things you can do to the selected Interaction. You can start, stop, edit & remove an Interaction from this menu, control quick access, and deal with Interaction errors, should they arise. We’ll discuss each of these in the following sections.

Tap an Interaction to show the menu

Tap an Interaction to show the menu


12.2.1. Starting / Stopping an Interaction

To start an Interaction:

  1. Tap on the Interaction to show the menu.

  2. Tap Start

To stop an Interaction:

  1. Tap on the Interaction to show the menu.

  2. Tap Stop

12.2.2. Editing an Interaction

To edit an Interaction:

  1. Tap on the Interaction to show the menu.

  2. Tap Edit in Interaction Builder to open the Interaction in Interaction Builder.

Alternatively you can tap Edit in advanced editor to edit the Interaction using the advanced editor. This is recommended for experienced users only – see Chapter 13, Advanced Interactions for full details.

Note

Note if you edit and save an Interaction using the advanced Interaction editor then you will no longer be able to open it in Interaction Builder.

12.2.3. Quick access to Interactions

Quick access allows you to easily turn an Interaction on/of from anywhere in the SwitchThat One UI, rather than just from the My Interactions screen. This can be useful if you have some Interactions that you frequently enable/disable.

To enable quick access to an Interaction:

  1. Tap on the Interaction to show the menu.

  2. Tap the Quick access item and a tick will appear next to it.

Enable quick access to an Interaction

Enable quick access to an Interaction


You’ll now see a list of Interactions next to the Shortcuts list, visible in the control panel on the right hand side of the screen on larger displays, or, on smaller mobile devices, from the menu accessible by tapping the button on the right hand side of the bottom toolbar.

Quick access to an Interaction using a tablet

Quick access to an Interaction using a tablet


Only the Interactions for which you’ve enabled Quick access will appear in this list.

You can tap on an Interaction to start it running, or to stop it. Interactions that are running will have a little ‘play’ symbol next to them.

If you want to stop an Interaction from appearing in the quick access list, then follow the same procedure for adding it, but this time make sure that the tick does not appear next to the Quick access item in the menu.

Note that if you have not enabled quick access for any Interactions, the quick access list will not appear in the UI.

12.2.4. Removing an Interaction

To remove an Interaction:

  1. Tap on the Interaction to show the menu.

  2. Tap Remove to remove the Interaction. You’ll be asked to confirm you want to do this.

12.3. Further Interaction Builder examples

12.3.1. Sending alerts

You can send an external alert, such as an email, SMS text message or even a tweet, as the Then That action of an Interaction. This enables you to create interactions to do things like warn you by text or email if a motion sensor in your garage is triggered at night.

To user alerts in your Interactions, you must first set up one or more alerting services, which integrate SwitchThat One with your email, SMS or Twitter accounts. See Section 8.4, “Alerting services” for full details of how to setup an alerting service.

Let’s look at an example of how to send an alert from an Interaction. Create a new Interaction in Interaction Builder and, first of all, configure the If This section for whatever event you’d like to trigger sending an alert.

In the Then That section, tap Other and then tap Alerts. If you don’t see the Alerts button then that means you haven’t setup any alerting services (See Section 8.4, “Alerting services” for details of how to do this).

You’ll see an action for each type of alerting service you’ve configured: Send email, Send SMS and/or Send tweet. Each action only appears in the list if at least one corresponding alerting service has been setup.

Using alerts in Interaction Builder

Using alerts in Interaction Builder


Tapping on an action will show a widget allowing you to configure the alert that will be sent when the If This event of the Interaction is triggered.

12.3.1.1. Configure sending an email

Tap Send email and a widget will appear where you can enter the To address, subject line and the body text of the email you’d like to be sent.

If you’ve set up more than one email alerting service, there’ll also be a box where you can choose which one to use to send the email.

12.3.1.2. Configure sending an SMS text message

Tap Send SMS and a widget will appear where you can enter the destination telephone number and the body of the text message you’d like to be sent.

If you’ve set up more than one SMS alerting service, there’ll also be a box where you can choose which one to use to send the text message.

12.3.1.3. Configure sending a tweet

Tap Tweet and a widget will appear where you can enter the text of the tweet you’d like to be sent.

If you’ve set up more than one Twitter alerting service, there’ll also be a box where you can choose which one to use to send the tweet.

Note that Twitter places restrictions on how often you can tweet the same message (or ‘status’ as Twitter describe it.) Generally speaking, attempting to tweet the same message more than once within a 24 hour period will fail (consult Twitter’s documentation for full details). You should bear this in mind when creating an Interaction that generates tweets.

If an Interaction causes multiple tweets within a short period of time, all but the first will be rejected by Twitter, and the rejected tweets will cause your Interaction to generate errors. In such cases you should consider changing your Interaction to either avoid sending tweets too frequently, or to use an alternative alerting service (e.g. email or SMS).

See Section 12.4, “Dealing with Interaction Errors” for full details of Interaction errors and how to deal with them.

12.4. Dealing with Interaction Errors

If SwitchThat One encounters a problem with an Interaction while it is running then it will generate error messages, which can be used to understand the cause of the problem and, if possible, fix it.

Some possible reasons for an Interaction to generate errors are:

  • A device used in the Interaction has been renamed. The Interaction will no longer be able to find the device, as it will still be using the original name. You’ll need to edit the interaction to make sure it’s working with the correct device.

  • A device used in the Interaction has been removed from SwitchThat One. You’ll need to edit the Interaction to work with an alternative device, or remove the Interaction entirely.

  • The Interaction was meant to send an alert, but sending failed for some reason. Perhaps SwitchThat One was unable to contact your email SMTP server, or Twitter rejected a duplicate tweet.

If one or more Interactions have errors, a warning will be shown in a number of places within SwitchThat One:

  • Next to Settings in the menu at the top of the screen.

  • Next to My interactions on the Settings page

  • The Interaction itself will be highlighted in red in the My Interactions screen

Interaction errors shown in the menu and on the Settings screen

Interaction errors shown in the menu and on the Settings screen


Interaction errors as seen on the My Interactions screen

Interaction errors as seen on the My Interactions screen


12.4.1. Viewing an Interaction’s errors

To view the errors that an Interaction has generated, visit the My Interactions screen, find the Interaction and tap it to show the menu.

Viewing Interaction errors

Viewing Interaction errors


Tap View Errors and you’ll be taken to a screen listing all the errors that have been generated by this Interaction.

Detailed list of errors generated by an Interaction

Detailed list of errors generated by an Interaction


The list shows each unique error message, the number of times the error has occurred and the first and last times that it occurred.

You should use this information to determine whether (and how) the Interaction needs be edited to fix the problem, or if the Interaction must be removed entirely.

Tap Edit in Interaction Builder or Edit in advanced editor to edit the Interaction. Tap Remove if you can’t fix the Interaction and it must be removed entirely.

If you choose to edit the Interaction, you’ll also need to clear the errors, otherwise they’ll still be visible. You can clear the Interaction errors in a couple of ways:

  • When editing the Interaction tick the Clear all Interaction errors box before saving the Interaction.

  • Visit the View Errors screen for the Interaction and tap Clear errors

Chapter 13. Advanced Interactions

You've already seen how to create simple Interactions between your devices using the Interaction Builder (Section 12.1, “Interaction Builder”). Much more sophisticated Interactions can be created using SwitchThat One's dedicated Interaction scripting language.

This section introduces the scripting language and explains how to write Interactions using the Advanced Interaction Editor. Some example Interactions are given in Section 13.4, “Examples”. There's also a reference guide to the Interactions scripting language: Appendix C, Interaction Reference

13.1. The Basics

13.1.1. Things and actions

The basic principle behind the SwitchThat One Interaction language is very straightforward: You perform an 'action' on a 'thing'. This is written as:

 thing.action

The 'thing' might one of your devices, a room, a shortcut or the current time. A 'thing' might also be a collection, such as all of your devices or rooms. Interactions are built around 'top level things' (see Section C.2, “Top level things” for a list of all top level things.) Let's look at a simple example:

 Devices

This is a 'collection' that refers to all of your devices. We can then retrieve a single device from the collection with:

 Devices['My light']

This now represents just the device called ‘My light’. You'll usually want to refer to a device by its name (which is case-sensitive), but you can also use its SwitchThat ID. You can find this ID by tapping more on the device's Configure page. This is how you'd refer to the device with SwitchThat ID 2:

 Devices[2]

Now that we have our 'thing', we'll want to do something to it. We can turn the 'My light' on by using the on action:

 Devices['My light'].on

Let's recap: Devices has a special meaning, and returns all your devices. As it's a collection, we use square brackets to return a single device called 'My light', and finally we called the action on to set the device's state to 'on'.

Actions that set the state of a device are often passed additional values. For example you might want to change the light's colour to a specific value:

 Devices['My light'].colour('red')
 Devices['My light'].colour(255,228,206)

There are also 'getter' actions, which end in a ?, and these actions let you query the state of a thing. For example we can ask whether a light is on, or find out its current colour:

 Devices['My light'].on?
 Devices['My light'].colour?

The results of these 'getter' actions can be used as input to the corresponding 'setter' actions, e.g.

 Devices['Light A'].on(Devices['Light B'].on?)
 Devices['Light A'].colour(Devices['Light B'].colour?)
 Devices['My light'].on(Devices['Motion sensor'].on?)

This last example illustrates how we can use the state of a motion sensor to control a light: if the motion sensor is 'on' (i.e. detects motion) the light will also be set to on.

There are many other actions that you can perform on a Device, and they are described in full in Section C.4, “Actions”.

13.1.2. Operators

As with other programming languages, Interactions can make use of operators. The following table shows the simple arithmetic and logical operators that can be used when writing an Interaction. Operators will only work with certain types of 'thing', and you should read Section C.5, “Operators” for full details on how operators can be used

Operator Description
a + b Add a and b
a - b Subtract b from a
a * b Multiply a and b
a / b Divide a by b
a div b Integer division of a by b
a == b True if a equals b
a != b True if a is different from b
a < b True if a is less than b
a <= b True if a is less than or equal to b
a > b True if a is greater than b
a >= b True if a is greater than or equal to b
!a 'Not a'. If a is true, then return false. If a is false return true

Table 13.1. Interaction Operators


If you've come across any other scripting languages before, you should start to feel comfortable with this very quickly!

Armed with the tables in Appendix C, Interaction Reference, you should be able to write useful Interactions. We've also collected together a set of example Interactions to help inspire you - take a look at the Section 13.4, “Examples”.

13.2. Using the Advanced Interaction Editor

Now that we've learned the basics, let's look how to write your own Interactions using the Advanced Interaction Editor. To start working with Advanced Interaction Editor tap Settings in the menu at the top of the screen, find the Interactions section and tap Write a new Interaction You'll now see the editor interface:

The Advanced Interaction Editor

The Advanced Interaction Editor


The Advanced Editor has a similar interface to Interaction Builder. The Interaction Name box is were you enter the name of your Interaction. Below Interaction Name are the If This and Then That boxes, and this is where you'll write your Interaction using the Interactions scripting language.

We'll look at how to write the If This and Then That part of an Interaction in more detail over the rest of this section.

13.2.1. If This

As with the Interaction Builder, the If This section is where you define an event to trigger your desired action. An If This event must evaluate to a Boolean, i.e. true or false. If true, it will trigger the Then That action.

Tip

You cannot perform actions that affect the state of things as part of your If This event. For example, an If This event cannot turn a device on or off. These are called 'side effects' and are not permitted in the If This rule.

Let's consider a simple example. If we want something to happen at the same time every evening, we can write the following in the If This box:

Now.hm becomes "19:30"

This should be read as 'when the current time, just considering hours and minutes, becomes 19:30' . Note that we use the operator 'becomes' , rather than '=', as we want the event to occur once as soon as the time is 19:30, and not for the whole duration of that minute.

Interactions are run approximately every second so the If This event should be quick to check and should not evaluate to true (and trigger the Then That event) more often than it needs to. For this reason, it's always better for the If This event to trigger once when the state of a thing changes, rather than for the entire period that the thing is in that state. As with the example above, ample, the If This event should trigger when a switch is turned on, rather than while it is on.

To help us achieve this, we can use becomes and also the changes and leaves operators. The following table gives some example If This events using these operators.

If This event Meaning
time.hour changes
Fires on the hour, every hour
time.nighttime? becomes true
Fires when it becomes nighttime
devices['Motion sensor'].on? becomes true
Fires when device 'Motion sensor' turns on (i.e. detects motion)
devices['Kitchen switch'].off? becomes true
Fires when device 'Kitchen switch' is turned off
Now.hm leaves "9:00"
Fires when the current time stops being 9:00, i.e. at 9:01.
time.minute div 5 changes
Fires once at 0:00, 0:05, 0:10, 0:15 ... 23:55
time.cumulative_seconds div 10 changes
Fires once every 10 seconds

Table 13.2. Some example If This events


Using becomes and changes also helps us avoid timing problems, as we cannot guarantee that the If This event of an Interaction will be evaluated precisely every second. Although the following If This rule will normally fire at the start of each minute:

   time.seconds == 0

Unfortunately there is no guarantee that the Interaction will be checked within the first second of every given minute. There is a small chance that it will be checked when time.seconds is 59, and again when time.seconds is 1. If this happens, the Interaction won't run. Instead, it is much safer to use an If This rule like:

  time.minutes changes

Which is guaranteed to fire at the start of every minute, within a second or so.

You can build more sophisticated If This events by making use of the and & or operators. For example, consider the following If This event:

 (time.hour > 20 or
 time.hour <  6) and
 devices['motion sensor'].on? becomes true

This will only fire when the 'motion sensor' device detects motion and the current time is after 8pm or before 6am.

Another advanced feature that you may find yourself requiring is being able to either smooth out events from an input device, or require an event to reach a threshold time before responding it. For this we provide the clamp and threshold operators, and you can find more details about them in Section 13.3.1, “The clamp and threshold operators”.

13.2.2. Then That

The Then That box is where you define the action you want to trigger when the If This event occurs. The basic approach is to pick a thing and specify an action that should happen to that thing. For example, to turn on a light, you could write the following in the Then That box:

 Devices['my light'].on

Or to turn off all the devices in the Kitchen:

 Rooms['Kitchen'].off

You can perform multiple actions, separating them with a ; e.g.

 devices['upstairs lamp'].on ; devices['downstairs lamp'].on ; devices['sonos'].play ;

Note that the final ; is optional.

For convenience most actions return the thing you call it on, allowing you to chain multiple actions. e.g.

  devices['sonos'].unmute().volume(25).play

You can see a full list of all the supported actions in Section C.4, “Actions”.

You can even use if - then - else expressions to adapt your Then That rules according to changing circumstances. For example, you might have an Interaction that switches your Kitchen Sonos player on at 6pm and plays BBC Radio 4. The Then That rule might be

  devices['Kitchen Sonos'].play_favourite('Radio 4')

But what if someone else is already listening to music on that player? You can modify the rule to account for this:

  if devices['Kitchen Sonos'].pause? 
  then devices['Kitchen Sonos'].play_favourite('Radio 4') 
  endif

Finally, note that the becomes, changes, leaves, clamp and threshold operators can't be used in a Then That rule.

13.3. More complicated Interactions

13.3.1. The clamp and threshold operators

The clamp and threshold operators are used to alter the way that your Interactions respond to input from devices. For example, you could use clamp or threshold to:

  • Make a light come on, and stay on, for 5 minutes if there is motion in the room

  • Make other lights in your house come on if the hall light is turned on and left on for a minimum period of time

  • Have the temperature stay over 21°C for 10 minutes before you turn off the heating

13.3.1.1. Using clamp

The clamp operator lets us persist the state of a device when an event is triggered.

Let's consider an example to help illustrate how this might be used. Imagine you have a motion sensor and want to use it to turn the light on automatically when you enter a room. However, you'd like the light stay on for 5 minutes and, once the 5 minutes is up, the light should turn off again (assuming motion is no longer detected.)

We can achieve this by 'clamping' the motion sensor to stay 'on' (i.e. detecting motion) for the desired time period. Our Interaction might look like this:

If This:

devices['Motion sensor'].on? clamp true for 5.minutes, false for 0.seconds changes

Then That:

devices['Landing light'].on(devices['Motion sensor'].on?);

The Interaction engine will continually check whether 'Motion sensor' is on (detecting motion). If this event becomes true, then it will stay true for at least 5 minutes. During this period, 'Motion sensor' is considered to be 'on' regardless of whether the device is detecting motion in the room. After 5 minutes, the clamp is set to false (returning the motion sensor to its default state) and then immediately released. If there is still motion in the room, the event will fire again, and the process will repeat.

To ensure this Interaction works as efficiently as possible, we add the changes operator to the end of the If This event, so that the Then That action only triggers when there's a change (in this case, when the motion is initially detected, and again at the end of the 5 minutes when the clamp is set to false.)

When the The That action is triggered, The device 'Landing light' is set to the current state of 'Motion sensor'. Thus, 'Landing light' is turned on when motion is first detected and stays on for 5 minutes. After 5 minutes, 'Landing light' will turn off again if there is no longer motion detected in the room. If there is still motion in the room, 'Landing light' will stay on and the process will repeat.

Note that there can be as many of the VALUE for TIME_PERIOD clauses as is required:

devices['Motion sensor'].on? clamp true for 5.minutes, false for 2.minutes, true for 5.minutes, 
                             false for 0.seconds changes

13.3.1.2. Using threshold

The threshold operator can be used to delay the triggering of the Then That action until the If This event has fired for some minimum period of time. If the threshold time isn't reached the Then That action will not be triggered at all.

For example, you might want your motion sensor to turn the light on only if it detects motion for a minimum of 20 seconds. This would avoid the light coming on unnecessarily if someone entered the room and left it again almost immediately.

Let's look at how this simple example might be written:

If This:

(devices['Motion sensor'].on? threshold for 20.seconds) becomes true

Then That:

devices['Landing light'].on

i.e. if 'Motion sensor' detects motion ('turns on') and stays on for 20 seconds then 'Landing light' is turned on.

As with clamp, there can be as many of the VALUE for TIME_PERIOD clauses as is required. This allows you to create some sophisticated Interactions:

If This:

(devices['thermostat'].temperature threshold    for 0.seconds,
                                             21 for 5.minutes,
                                             22 for 3.minutes,
                                             23 for 1 minute) >= 21 becomes true

Then That:

  alerts['email'].send('me@aol.com', 'Alert', 'The house is overheating')

13.4. Examples

This section provides some example Interactions to experiment with. You can use examples to help you get confident, and see what's possible.

Take a look at Appendix C, Interaction Reference for a full reference to the Interactions scripting language.

If This ... Then That ... Comment
time.hour changes
devices['light 2'].colour
(
 ['red', 'green', 'blue', 'purple'].pick
)
Let's have a different colour every hour!
time.minute div 5 changes
devices['light 2'].colour
  (random.random(256),
   random.random(256),
   random.random(256)) 
Let's frequently have a new random colour!
devices['light 1'].colour? changes
devices['light 2'].colour
(devices['light 1'].colour?)
Have 'light 2' track 'light 1's colour
time.nighttime?
  becomes true
devices['light 2'].on
Turn 'light 2' on as it becomes night time
(time+10.minutes).nighttime?
  becomes true
devices['light 2'].on
Turn 'light 2' on 10 minutes before dusk
(time.hour >= 20 or
 time.hour <  6) and
 devices['motion sensor'].on? becomes true
devices['bedside light'].blink
Blink bedside light if there's an intruder during the night
now.hour becomes 8
devices['sonos player'].play
Automatically play music at breakfast time
Random.random(100) == 0
devices['light 1'].toggle
Turn the light on/off at random to simulate occupancy

Table 13.3. Advanced Interaction Examples


Appendix A. Supported Devices

This section covers all of the devices that are supported by SwitchThat One, providing details of how the devices are discovered by your One Hub, configuration options, and any other device-specific information.

A.1. Philips Hue lights

A.1.1. Supported devices

SwitchThat One supports the following Philips Hue products:

  • Hue 9W multicolour connected bulb
  • Hue 6.5W GU10 multicolour connected bulb
  • Hue Lux 9W warm-white connected bulb

A.1.2. Discovery

Your Philips Hue bridge and light bulbs must be installed according to the manufacturer's guidelines before they can be used with SwitchThat One.

Your Philips Hue bridge should be discovered automatically, but an additional step is required before SwitchThat One can access your lights.

A notification will appear when your Philips Hue bridge is discovered. Acknowledge the notification, and then follow the on-screen instructions to allow your One Hub to pair with the bridge. You’ll need to be able to get to your bridge to be able to press the centre link button during the pairing process.

You can use multiple Philips Hue bridges with SwitchThat One.

A.1.3. Using Philips Hue lights

You’ll be able to switch your Philips Hue lights on/off and adjust either their colour or brightness, depending on whether you are controlling a multicolour or white bulb.

You are encouraged to use your Philips Hue lights exclusively from within SwitchThat One whenever possible, rather than controlling them from other apps.

If you access your Philips Hue lights from another app, SwitchThat One will make sure it keeps up-to-date with changes to the lights as quickly as possible. Note, however, that it can sometimes take up to 1 minute for these changes to register within SwitchThat One.

A.1.4. Adding additional bulbs

When you purchase additional Philips Hue bulbs you must first add them to your Hue bridge by following the manufacturer's instructions. Make sure to confirm that the new bulb(s) are connected to your bridge and are accessible using the official Philips Hue app before attempting to add them to SwitchThat One.

To add the new bulb(s) to your One Hub:

  1. Tap Settings
  2. Find the My Devices section and Tap Search for new devices
  3. After a few seconds, the new bulb(s) should appear

A.1.5. Troubleshooting

If one of your Philips Hue lights appears as unavailable, or you otherwise have trouble controlling it from SwitchThat One, then first make sure that the light is powered on, and confirm that it is working correctly with the official Philips Hue app.

If you are sure that your Philips Hue light is working correctly, but you still cannot control it from SwitchThat One, then try the following steps:

  1. Open the Configure screen for the Philips Hue light
  2. Find the Actions section and tap Refresh this Philips Hue Light
  3. SwitchThat One will try to re-establish its connection to the Philips Hue light.

A.1.5.1. Philips Hue Bridge software updates

Immediately after applying a software update to your Philips Hue Bridge, SwitchThat One will sometimes lose access to your Hue lights for a short period of time. Please allow at least 30 mins for SwitchThat One to re-establish its connection to your Hue bridge.

A.1.6. Limitations

Note that the colour of Philips Hue bulbs cannot be changed while they are off. This should be apparent while controlling them, but may not be obvious when used in an Interaction. If an interaction uses a bulb that might be switched off, we recommend that the interaction first switch the light on before changing its colour.

A.2. LIFX lights

A.2.1. Supported devices

SwitchThat One supports the following LIFX products:

  • LIFX Original A21 Wi-Fi Smart LED Light Bulb

A.2.2. Discovery

Your LIFX lights must be installed according to the manufacturer's guidelines before they can be used with SwitchThat One.

Once you’ve got your LIFX lights installed and working, they should be automatically discovered by SwitchThat One. When a LIFX light is discovered, you’ll receive a notification, and the light will appear in Home screen with a New label.

If your LIFX lights aren’t automatically discovered, then you can tell your One Hub to search for them:

  1. Make sure your LIFX light(s) are powered on and are working
  2. Tap Settings
  3. Find the My Devices section and Tap Search for new devices
  4. After a few seconds, your LIFX light(s) should appear

A.2.3. Using LIFX lights

You’ll be able to switch your LIFX lights on/off and adjust their colour.

You are encouraged to use your LIFX lights exclusively from within SwitchThat One whenever possible, rather than controlling them from other apps. If you access your LIFX lights from another app, SwitchThat One should keep up-to-date with changes to the lights as quickly as possible.

LIFX lights can’t be renamed from within SwitchThat One. If you need to change the name of one of your LIFX lights, you must do this from within the official LIFX app. SwitchThat One will automatically pick up the new name within a few seconds.

A.2.4. Adding additional bulbs

When you purchase additional LIFX lights you must first install them by following the manufacturer's instructions. Make sure to confirm that the new light(s) are accessible using the official LIFX app before attempting to add use them with SwitchThat One.

Once installed & working, your new LIFX light(s) should be automatically discovered by SwitchThat One. If your new LIFX light(s) aren’t automatically discovered, then you can tell your One Hub to search for them:

  1. Make sure your LIFX light(s) are powered on and are working
  2. Tap Settings
  3. Find the My Devices section and Tap Search for new devices
  4. After a few seconds, your additional LIFX light(s) should appear

A.2.5. Troubleshooting

If one of your LIFX lights appears as unavailable, or you otherwise have trouble controlling it from SwitchThat One, then first make sure that the light is powered on, and confirm that it is working correctly with the official LIFX app.

If you are sure that your LIFX light is working correctly, but you still cannot control it from SwitchThat One, then try the following steps:

  1. Open the Configure screen for the LIFX light
  2. Find the Actions section and tap Refresh this LIFX Light
  3. SwitchThat One will try to re-establish its connection to the LIFX light.

A.3. Belkin WeMo Switches

A.3.1. Supported devices

SwitchThat One supports the following Belkin WeMo Switch products:

  • Belkin WeMo Home Automation Switch

A.3.2. Discovery

Your Belkin WeMo Switches must be installed according to the manufacturer's guidelines before they can be used with SwitchThat One.

SwitchThat One will discover your Belkin WeMo Switches automatically, and you will be notified when they are ready for use.

A.3.3. Using Belkin WeMo Switches

You’ll be able to switch your Belkin WeMo Switches on and off.

If a Belkin WeMo Switch is switched on/off using another app, or via the physical switch on the unit itself, SwitchThat One will be updated instantly to reflect the new switch state.

You are discouraged from setting up scheduled actions using the Belkin WeMo app, as it may get confusing when you start using SwitchThat One Interactions.

A.3.4. Troubleshooting

If one of your Belkin WeMo Switches appears as unavailable, or you otherwise have trouble controlling it from SwitchThat One, then first make sure it’s powered on and confirm that it’s working correctly with the official Belkin WeMo app.

If you are sure that the Belkin WeMo Switch is working correctly, but you still cannot control it from SwitchThat One, then try the following steps:

  1. Open the Configure screen for the Belkin WeMo Switch
  2. Find the Actions section and tap Refresh this Belkin WeMo Switch
  3. SwitchThat One will try to re-establish its connection to the switch.

A.4. Belkin WeMo Smart Light Bulbs

A.4.1. Supported devices

SwitchThat One supports the following Belkin WeMo lighting products:

Belkin WeMo Smart LED Light Bulbs & WeMo Link

A.4.2. Discovery

Your Belkin WeMo Link and Smart Light Bulbs must be installed according to the manufacturer's guidelines before they can be used with SwitchThat One.

SwitchThat One will discover your Belkin WeMo Link and Smart Light Bulbs automatically, and you will be notified when they are ready for use.

A.4.3. Using Belkin WeMo Smart Light Bulbs

You’ll be able to switch your Belkin WeMo Smart Light Bulbs on/off and adjust their brightness.

If a Belkin WeMo Smart Light Bulb is adjusted using another app SwitchThat One will be updated instantly to reflect the changes.

You are discouraged from setting up scheduled actions using the Belkin WeMo app, as it may get confusing when you start using SwitchThat One Interactions.

A.4.4. Adding additional bulbs

When you purchase additional Belkin WeMo Smart Light Bulbs you must first install them by following the manufacturer's instructions. Make sure to confirm that the new bulb(s) are accessible using the official Belkin WeMo app before attempting to add them to SwitchThat One.

To add the new bulb(s) to your One Hub:

  1. Make sure your Belkin WeMo Smart Light Bulbs(s) are powered on
  2. Tap Settings
  3. Find the My Devices section and Tap Search for new devices
  4. After a few seconds, your additional Belkin WeMo Smart Bulb(s) should appear

A.4.5. Troubleshooting

If your Belkin WeMo Smart Light Bulbs appear as unavailable, or you otherwise have trouble controlling them from SwitchThat One, then first make sure that both the WeMo Link and the bulbs are powered on, and confirm that everything is working correctly with the official Belkin WeMo app.

If you are sure that your Belkin WeMo Link and Smart Light Bulbs are working correctly, but you still cannot control them from SwitchThat One, then try the following steps:

  1. Open the Configure screen for one of your Belkin WeMo Smart Light Bulbs
  2. Find the Actions section and tap Refresh this Belkin WeMo Smart Light Bulb
  3. SwitchThat One will try to re-establish its connection to the light bulb.

A.5. Belkin WeMo Motion Sensor

A.5.1. Discovery

Your Belkin WeMo Motion Sensor must be installed according to the manufacturer's guidelines before it can be used with SwitchThat One.

SwitchThat One will discover your Belkin WeMo Motion Sensor automatically, and you will be notified when it is ready for use.

A.5.2. Using a Belkin WeMo Motion Sensor

Belkin WeMo Motion Sensors are ‘input only’ devices when used with SwitchThat One. You can use them in your Interactions as events that trigger actions involving other devices. For example, you might want a light to come automatically in in response to motion being detected.

See Chapter 12, Interactions for full guidance on creating Interactions.

You are discouraged from configuring motion actions using the Belkin WeMo app, as it may get confusing when you start using SwitchThat One Interactions.

A.5.3. Troubleshooting

If one of your Belkin WeMo Motion Sensors appears as unavailable, then first make sure it’s powered on and confirm that it’s working correctly with the official Belkin WeMo app.

If you are sure that the Belkin WeMo Motion Sensors is working correctly, but you still cannot control it from SwitchThat One, then try the following steps:

  1. Open the Configure screen for the Belkin WeMo Motion Sensor
  2. Find the Actions section and tap Refresh this Belkin WeMo Motion Sensor
  3. SwitchThat One will try to re-establish its connection to the motion sensor.

A.6. Sonos Music Players

A.6.1. Supported devices

SwitchThat One supports the following Sonos products:

  • Sonos PLAY:1, PLAY:3 & PLAY:5
  • Sonos CONNECT & CONNECT:AMP
  • Sonos PLAYBAR

A.6.2. Discovery

Your Sonos Music Player must be installed according to the manufacturer's guidelines before it can be used with SwitchThat One.

SwitchThat One will discover your Sonos Music Player automatically, and you will be notified when it is ready for use.

A.6.3. Using Sonos Music Players

SwitchThat One does not attempt to replace the official Sonos app but supports the following core functions:

  • Play/pause, select next track or previous track
  • Adjust or mute player volume
  • Play/remove tracks from the queue
  • Access your playlists and favourites

You’ll need to use the official Sonos app for more advanced functionality such as searching and navigating your music sources, creating playlists or changing the way your players are grouped.

A.6.3.1. Using the Queue

The Queue widget shows the current queue for this Sonos player. You may need to scroll up/down to see all the tracks in the queue. You can tap on an item in the queue and choose to either play that track, or remove it from the queue.

A.6.3.2. Accessing playlists & favourites

The Media Library widget gives you access to your Sonos playlists and favourites. Select a playlist or favourite from the appropriate list and choose either:

  • Play now to replace the player’s queue with the chosen playlist/favourite and start playing it immediately

  • Add to queue to append the playlist/favourite to the end of the current queue. Note that the player will not start playing if it is currently paused.

A.6.3.3. Grouping players

You’ll need to group or ungroup you players from within the official Sonos app. However, if you change the way your players are grouped, these changes will be automatically reflected within SwitchThat One.

If you group one or more players together, the ‘master’ player will take responsibility for the majority of media player, queue and playlist functionality. You’ll be restricted to making volume adjustments for the other players in the group.

If you combine two players as a stereo pair, only the ‘master’ player will be visible from within SwitchThat One; the other half of the pair will be hidden. If you subsequently split the stereo pair up then both players will be visible again within SwitchThat One.

A.7. Nest®

A.7.1. Supported Devices

SwitchThat One currently provides beta support for the following Nest products:

  • Nest Learning Thermostat™
  • Nest Protect: Smoke + Carbon Monoxide™

A.7.2. Adding your Nest device(s)

A.7.2.1. Setting up a Works with Nest connection

In order to use your Nest device(s) with SwitchThat One, you must create a Works with Nest connection between SwitchThat One and your Nest account.

To create a Works with Nest connection, first tap Settings, find the My Devices section and tap Add a new device. Now tap Add your Nest device and you should see the following screen.

Adding your Nest device(s) step 1

Adding your Nest device(s) step 1


The first step is to grant SwitchThat One access to your Nest account and get a Pincode.

Tap on Get a Pincode and a web browser will open up taking you to a page on the Nest website where you'll be asked to authorise SwitchThat One to access your account (you may need need to sign in at this point). You’ll be given a Pincode - write this down and return to SwitchThat One.

If you’re still on the Add your Nest devices' screen, then tap ‘I have a Pincode’. You should now see the 2nd step of the setup process:

Adding your Nest device(s) step 2

Adding your Nest device(s) step 2


If, when you returned to SwitchThat One, you weren’t already on the the 'Add your Nest devices' screen, the next time you return to it you’ll automatically be taken to the 2nd step of the setup process.

Enter your pincode in the box and tap Continue. After a second or so you should see an 'All done!’ message. Tap Home to continue. Your Nest device(s) will now appear as tiles on the Home screen.

Note

If your Nest devices haven't appeared, wait a few seconds and then tap the red SwitchThat logo at the top-left to refresh the Home screen.

However, if setup fails with the error message that Nest has rejected your Pincode, then double-check you have entered the Pincode correctly and try again. If setup still fails, then tap I need a Pincode to get a new Pincode and start again.

A.7.2.2. Multiple homes

If you have more than one home associated with your Nest account, you will need to choose which one of these homes is connected to SwitchThat One.

After following the process to set up a Works with Nest connection you will be sent a notification telling you that an additional step is required. Tap on the notification and you will be taken to a screen where you can choose which home to connect to SwitchThat One.

Choosing a home to connect to SwitchThat One

Choosing a home to connect to SwitchThat One


Tap on the home you want to connect and then tap Continue. We recommend you choose the home where your One Hub is installed.

If you want to change which home you use with SwitchThat One, you'll need to remove the Works with Nest connection first. You can do this from the official Nest app. You can then add your Nest devices to SwitchThat One again, and choose the desired home.

A.7.3. Using your Nest Thermostat

The dashboard tile gives a brief overview of the thermostat state:

  1. At the top an icon indicates whether the thermostat is set to home (a house) or away (a man walking)
  2. Below this is a box showing the current target temperature. The box colour is grey when your central heating system is idle/off, orange when heating or blue when cooling.
  3. The Leaf with also be displayed when applicable.

Tapping on the dashboard tile takes you to the Thermostat control screen, which is divided into two sections: Thermostat Settings and Thermostat Controls.

The Thermostat Settings section gives you a more detailed summary, with the current inside temperature / humidity on the left and the central heating mode / target temperature on the right. Again, the box colour is grey when your system is idle/off, orange when heating and blue when cooling. Below this is a control where you can switch between home and away mode. Tap on it to change the mode.

The Thermostat Controls section gives you controls to change the central heating mode (e.g. between 'Heat' and 'Off') and for setting the target temperature.

A.7.4. Using your Nest Protect

The dashboard tile gives a brief overview of the current status of your Nest Protect. Under normal conditions, there should a be green box labelled 'OK', indicating that no issues have been detected. If a 'heads-up' alert is raised, the box will turn amber and will indicate the source of the alert - smoke or carbon monoxide. Similarly, if an emergency alert is raised, the box will turn red and will indicate the source of the alert.

Tapping on the dashboard tile takes you to the Nest Protect control screen, which provides a more detailed version of the dashboard summary.

A.7.5. Using your Nest devices in Interactions

A.7.5.1. Nest Thermostat

Using Interaction Builder you can create Interactions that trigger when:

  • The home/away state of your Nest Thermostat changes.
  • Your central heating system starts heating (or cooling, if applicable)
  • Your central heating system stops heating (or cooling)
  • The ambient temperature of your home rises above, or falls below, some value

For example, you could create an Interaction to automatically turn off your lights when your Nest Thermostat spots that you've left home, or to turn your lights on again when you return.

Note

If you create an interaction that works according to the state of your central heating system (e.g. when it starts heating) bear in mind that it might trigger several times within one scheduled period of 'heating'. This is because your Nest Thermostat will automatically turn your heating system on/off as appropriate in order to maintain the desired target temperature.

A.7.5.2. Nest Protect

Using Interaction Builder you can create Interactions that trigger when your Nest Protect detects smoke, carbon monoxide or if the battery needs replacing.

A.7.6. Adding new Nest devices

If you want to add a new Nest Thermostat or Nest Protect device, you must first add it to your Nest account. The device will then automatically appear in SwitchThat One.

A.7.7. Removing the Works with Nest connection.

If you choose to remove the SwitchThat One Works with Nest connection then your Nest devices will be automatically removed from your SwitchThat environment. You will also be sent a notification telling you that this has happened.

Before removing the Works with Nest connection, you should stop and/or remove any Interactions that make use of your Nest devices.

Once you've removed the Works with Nest connection, if you want to use your Nest device(s) with SwitchThat One again, you will have to add them using the process described at the beginning of this section.

A.8. Tado smart thermostat

A.8.1. Adding your Tado smart thermostat

Your Tado smart thermostat must be added to your One Hub manually, as the process requires you to enter your Tado account details.

  1. Tap Settings
  2. Find the My Devices section and tap Add a new device
  3. Tap Add your Tado thermostat
  4. Enter your Tado account username & password. These are the account details your used to register your Tado thermostat, and the account details you use to sign in to the Tado app on your phone/tablet.
  5. Choose the correct type of heating installation: heating control for a boiler only (i.e. a combination boiler) or separate heating and hot water controls (i.e. boiler and cylinder.)
  6. Tap Add your tado to finish.

A.8.2. Using your Tado smart thermostat

Depending on the nature of your central heating system you’ll see one or two devices in the Home screen for your Tado installation:

  • Heating (all systems)
  • Hot Water (boiler and hot water cylinder systems only)

A.8.2.1. The Heating device

The heating device allows you to monitor and control your central heating. The Thermostat Settings widget gives you a summary of the current thermostat settings:

  1. Current heating mode, Off, Auto or Manual
  2. Current house temperature (top right of widget)
  3. Current set point temperature (bottom right of widget)

The Heating Mode widget lets you change the boiler heating mode. The Manual Temperature widget lets you adjust the manual set point temperature. Note that this only takes effect when the boiler heating mode is set to ‘Manual’.

The device tile for the Heating device also shows a brief summary of the thermostat settings, displaying the current heating mode and house temperature.

A.8.2.2. The Hot Water device

The Hot Water device allows you to change your hot water heating mode. You can choose between Off, Auto, Schedule & Manual.

The device tile for the Hot Water device also shows the current hot water heating mode.

Appendix B. HTTP API Reference

This section provides a reference to all the actions in the HTTP API. For further information and examples using it, see Chapter 11, The HTTP API interface.

HTTP Action API Action Description
GET on Return whether a Device is on
GET off Return whether a Device is off
GET brightness Return the brightness of a Device (0-100)
GET colour Return the Colour of a Device as an Array of RGB values 0-255.
GET play Return whether a Music player is playing
GET pause Return whether a Music player is paused
GET volume Return the Music player volume (0-100)
GET mute Return whether the Music player is muted
GET group_volume Return the Group Volume of a Music player
GET group_mute Return whether a grouped Music player is muted
POST on Turn a Device on
POST off Turn a Device off
POST toggle Toggle the state of a Device
POST blink/times Blink the device times times. Defaults to 1 if omitted.
POST brightness/value Set the brightness of a Device (0-100)
POST colour/r/g/b Set the Device colour (0-255 values)
POST colour/colour_name Set the Device to the colour name (e.g. red, green, skyblue, etc.)
POST play Start a player playing
POST play_playlist/playlist_name Start the named play list playing
POST play_favourite/favourite_name Start the named favourite playing
POST append_playlist/playlist_name Append the named play list to the queue
POST append_favourite/favourite_name Append the named favourite to the queue
POST pause Pause a player
POST toggle_play Stop a playing player, or start a paused one
POST volume/value Adjust the volume on a player
POST mute Mute a player
POST unmute Unmute a player
POST toggle_mute Unmute a muted player, or mute an already unmuted one
POST next Advance to the next scheduled track
POST previous Skip to the previous scheduled track
POST group_volume/value Set the Group volume
POST group_mute Apply Group mute
POST group_unmute Apply Group unmute
POST toggle_group_mute Toggle the Group mute
POST press/button_name Press a button on a Remote Control

Table B.1. API Actions


Appendix C. Interaction Reference

This section provides a reference to all the methods in the One Interaction Language. For help and examples writing advanced interactions, see Chapter 13, Advanced Interactions.

C.1. Precedence

This table lists the precedence of the language operators.

Operator Precedence   
and, or Lowest   
changes, becomes, leaves   
clamp, threshold   
==, !=   
<, <=, >, >=   
-, +   
*, /, div, %   
!   
.   
[ ... ]   
Unary - Highest   

Table C.1. Precedence


Using this table you will see that an earlier example,
(time.hour >= 20 or time.hour <  6) and devices['motion sensor'].on? becomes true
is actually
(time.hour >= 20 or time.hour <  6) and (devices['motion sensor'].on? becomes true)
rather than
((time.hour >= 20 or time.hour <  6) and devices['motion sensor'].on?) becomes true
There's a subtle difference between the two. In the latter version the If Then can trigger at 8pm if the sensor is already true, since the time test is part of the becomes true test.

C.2. Top level things

The first table lists all the 'top level things', whose names can be used anywhere in an Interaction. They are case insensitive.

Top level thing Description
DateTime Returns a representation of the current date and time
Devices A list of all your Devices
DateTime Returns a representation of the current date and time
Devices A list of all your Devices
GPS Alias for GPSLocations
GPS_Locations Alias for GPSLocations
GPSLocations Provides access to GPS data
Now Alias for DateTime
Random Gives you access to Random numbers
Remotes A list of all your Remote Controls
Rooms A list of all your Rooms
Shortcuts A list of all your Shortcuts
Time Alias for DateTime
Weather Provides access to your local weather

Table C.2. Interaction top level things


C.3. Other types

The first table lists other types that you'll encounter.

Type Description
Number Numbers can be integers or floating point
4
-9
12.34
String Strings are enclosed in either single or double quotes
"hello world"
"fred's sonos"
'hello world'
Boolean You can create a boolean using true or false
true
false
Array You can create an array with square brackets. e.g.
["red", "green", blue"]

Table C.3. Other Interaction types


C.4. Actions

This second table lists all the actions that can be performed on things. The emphasised thing type is a placeholder for a thing of that type. Both of the following will work.

      DateTime.day_name 

This example will give you tomorrow's day name:

      (DateTime+1.day).day_name 

Interaction Action Description
Alerts
Alerts[...] Retrieves a single Alert by (case insensitive) name. The Alert will be of type EmailAlert
Array
Array[...] Access the elements in an array
Array.pick Picks a random item from an array
DateTime
DateTime.cumulative_seconds Alias for DateTime.epoch
DateTime.day See DateTime.days
DateTime.day_abbr Return the abbreviated day name (e.g. Mon, Tue, ...)
DateTime.day_name Return the day name (e.g. Monday, Tuesday, ...)
DateTime.day_of_week Return the day of the week number (1-7, 1=Monday)
DateTime.day_of_year Returns the day of year (1-366)
DateTime.days Return the day in the month (1-31)
DateTime.daytime? Returns true/false to say whether it is currently day time
DateTime.dmy Return Date, Month, Year (e.g. 06-12-2002)
DateTime.epoch Return the number of seconds since 1st January 1970. It is most useful as a number that counts upwards every second
DateTime.format(String) Format a DateTime using a custom format (advanced)
DateTime.hm Return the time as Hours and Minutes (e.g. 14:02)
DateTime.hms Return the time as Hours, Minutes, Seconds (e.g. 14:02:29)
DateTime.hour See DateTime.hours
DateTime.hours Return hour (0-23)
DateTime.mdy Return Month, Date, Year (e.g. 12-06-2002)
DateTime.minute See DateTime.minutes
DateTime.minutes Return the time minute field (0-59)
DateTime.month See DateTime.months
DateTime.month_abbr Return an abbreviated month (e.g. Jan, Feb, ...)
DateTime.month_name Return the month name (e.g. January, February, ...)
DateTime.months Return the time month field (1-12)
DateTime.nighttime? Returns true/false to say whether it is currently night time
DateTime.second See DateTime.seconds
DateTime.seconds Return the time second field (0-61)
DateTime.year See DateTime.years
DateTime.years Return the year
DateTime.ymd Return Year, Month, Date (e.g. 2002-12-06)
Device
Device.blink Blink the device once
Device.blink(Number) Blink the device the specified number of times
Device.brightness(Number) Set the brightness of a Device (0-100)
Device.brightness? Gets the brightness of a Device
Device.colour(String) Set the colour of a Device using a colour name. Any colour name should be known
Device.colour(Number,Number,Number) Set the colour of a Device using R, G and B values (0-255)
Device.colour([Number,Number,Number]) Set the colour of a Device using R, G and B values (0-255) in an array
Device.colour? Return the colour of a Device as an array of RGB values
Device.mute Mute a Device
Device.mute(Boolean) Allow you to mute a device if passed true, else play
Device.mute? Returns whether a device is muted
Device.next Advance to the next track being played
Device.off Turns a device off
Device.off? Returns whether a device is off
Device.on Set a device on
Device.on(Boolean) Set a device on by passing true, else off
Device.on? Returns whether a device is on
Device.pause Pause a device
Device.pause? Returns whether a device is paused
Device.play Start a device playing
Device.play(Boolean) Allow you to start a device playing if passed true, else pause
Device.play_playlist(String) Start the named play list playing
Device.play_favourite(String) Start the named favourite playing
Device.append_playlist(String) Add the named play list to the queue
Device.append_favourite(String) Add the named favourite to the queue
Device.play? Returns whether a device is playing
Device.previous Skip to previous track
Device.toggle Toggle whether a device is on or off
Device.toggle_mute Toggle whether a device is muted or not
Device.toggle_play Toggle whether a device is playing or not
Device.unmute Unmute a device
Device.volume(Number) Sets the volume (0-100)
Device.volume? Gets the current volume
Devices
Devices[...] Retrieves a single Device either by (case insensitive) name or internal id
Devices.count Returns how many devices there are
EmailAlert
EmailAlert.send(String,String,String) Allows you to send an email. The arguments are: 'recipient', 'subject', 'message body'
GPSLocation
GPSLocation.accuracy Return the location accuracy. This is the approximate accuracy in meters
GPSLocation.altitude Return current altitude, though rarely known
GPSLocation.bearing Return bearing, though rarely known
GPSLocation.latitude Location latitude
GPSLocation.longitude Location longitude
GPSLocation.nearby?(GPSLocation) Is this location within 1Km of another location?
GPSLocation.nearby?(GPSLocation,Number) Is this location within the specified meters of another location?
GPSLocation.speed Return speed, though rarely known
GPSLocations
GPSLocations[...] Retrieve the most recent GPSLocation for specified user (by name or id), device (device id) or hub location (string 'one')
GPSLocations.count The number of history location samples held in the database
GPSLocations.last_update The timestamp of the most recent location sample
Direction
Direction.direction The direction, in degrees
Direction.distance Distance, in meters
Number
Number.string Convert the Number to a string. You can use this for things like time.hour.string + ':' + time.minute becomes "12:32"
Number.day Convert a Number to the equivalent number of seconds
Number.days
Number.hour
Number.hours
Number.minute
Number.minutes
Number.month
Number.months
Number.second
Number.seconds
Number.year
Number.years
Random
Random.random(Number) Return a random integer between 0 and up to the supplied number.
Remote
Remote.press(String) Press the specified key on a Remote Control
Remotes
Remotes[...] Retrieves a single Remote control either by (case insensitive) name or internal id
Remotes.count Return the number of remote controls
Room
Room.blink Blink the lights in a room once
Room.blink(Number) Blink the lights in a room the specified number of times
Room.brightness(Number) Set the brightness of all the devices in a room (0-100)
Room.colour(String) Set the colour on all the devices in a room using a colour name
Room.colour(Number,Number,Number) Set the colour on all the devices in a room using R, G and B values (0-255)
Room.colour([Number,Number,Number]) Set the colour on all the devices in a room using R, G and B values (0-255) in an array
Room.devices Return all the devices in a room
Room.mute Mute all the devices in a room
Room.mute(Boolean) Mute all the devices in a room if true, else unmute
Room.next Skip all players in a room to the next track
Room.off Turn all the devices off in a room
Room.on Turn on all the devices in a room
Room.on(Boolean) Set all the devices in a Room on, or off
Room.pause Pause all your players in a room
Room.play Set all your players in a room playing
Room.play(Boolean) Request all devices in a room to play if true, else pause
Room.previous Skip all players in a room to the previous track
Room.unmute Unmute all your players in a room
Room.volume(Number) Set the volume on all your players in a room
Rooms
Rooms[...] Retrieves a single Room either by (case insensitive) name or internal id
Rooms.count Return the number of rooms
Shortcut
Shortcut.blink Blink the lights in a shortcut once
Shortcut.blink(Number) Blink the lights in a shortcut the specified number of times
Shortcut.brightness(Number) Set the brightness of all the devices accessed through a shortcut (0-100)
Shortcut.colour(String) Set the colour on all the devices accessed through a shortcut using a colour name
Shortcut.colour(Number,Number,Number) Set the colour on all the devices accessed through a shortcut using R, G and B values (0-255)
Shortcut.colour([Number,Number,Number]) Set the colour on all the devices accessed through a shortcut using R, G and B values (0-255) in an array
Shortcut.devices Return all the devices accessed through a shortcut
Shortcut.mute Mute all the devices accessed through a shortcut
Shortcut.mute(Boolean) Mute all the devices in a shortcut if true, else unmute
Shortcut.next Skip all players in a shortcut to the next track
Shortcut.off Turn all the devices off accessed through a shortcut
Shortcut.on Turn on all the devices accessed through a shortcut
Shortcut.on(Boolean) Set all the devices in a Shortcut on, or off
Shortcut.pause Pause all your players accessed through a shortcut
Shortcut.play Set all your players accessed through a shortcut playing
Shortcut.play(Boolean) Request all devices in a shortcut to play if true, else pause
Shortcut.previous Skip all players in a shortcut to the previous track
Shortcut.unmute Unmute all your players accessed through a shortcut
Shortcut.volume(Number) Set the volume on all your players accessed through a shortcut
Shortcuts
Shortcuts[...] Retrieves a single Shortcut either by (case insensitive) name or internal id
Shortcuts.count Return the number of shortcuts
Weather
Weather.detail A detailed weather description, such as 'broken clouds'
Weather.humidity Returns the humidity %
Weather.pressure Returns atmospheric pressure hPa at sea or ground level
Weather.summary A weather summary, such as 'Clouds'
Weather.temp See Weather.temperature
Weather.temp_max See Weather.temperature_max
Weather.temp_min See Weather.temperature_min
Weather.temperature Return temperature in Centigrade
Weather.temperature_max Return the maximum daily temperature
Weather.temperature_min Return the minimum daily temperature
Weather.wind_direction Returns the wind direction in degrees
Weather.wind_speed Return wind speed in m/s

Table C.4. Interaction Actions


C.5. Operators

This table lists all operators that can be applied to things.

Operator Description
! Boolean true becomes false, and false becomes true
Boolean == Boolean Compare two Booleans, return true if the same
Boolean != Boolean Compare two Booleans, return true if different
Boolean and Boolean true is both Booleans are true
Boolean or Boolean true is either Booleans is true
DateTime + Number Return a DateTime advanced by Number seconds
DateTime - Number Return a DateTime rewound by Number seconds
- Number Negate the number
Number - Number Subtract one Number from another
Number * Number Multiply two Numbers together
Number / Number Divide two Numbers
Number div Number Integer divide two Numbers
Number % Number Calculate the modulo of two Numbers (the remainder when divided)
Number < Number Compare two Numbers
Number <= Number Compare two Numbers
Number > Number Compare two Numbers
Number >= Number Compare two Numbers
Number == Number Compare two Numbers
Number != Number Compare two Numbers
String + Number Append Number to String
String + String Append one String to another
String == String Compare two Strings
String != String Compare two Strings

Table C.5. Interaction Operators