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