Overview

The following examples of service classes illustrate how to group functionalities so they are reusable and modular, which are essential components of proper service classes.

Uniqueness: BinarySwitch

All service members must be unique within the service. For example, a service cannot have both a switch property and a switch method.

{
	"name": "BinarySwitch",
	"properties": {
		"switch": {
			"description": "On/off state of the switch",
			"enum": [
				"on",
				"off"
			],
			"type": "string"
		}
	},
	"methods": {
		"switchOn": {
			"description": "Sets switch to on"
		},
		"switchOff": {
			"description": "Sets switch to off"
		}
	}
}

Modularity: MediaControl, MediaInfo, and AudioOutput

Properly defined modular services should be re-usable for other devices. While a smart speaker might have volume, play/pause, and album info, each of these things may also exist independently on other devices. A traditional Bluetooth speaker would be able to change volume, and play/pause the media, but wouldn’t know what track is playing. Some Bluetooth speakers can simply change volume; and not pause or skip the track.

The MediaControl service controls the play queue of a smart speaker.

{
	"name": "MediaControl",
	"properties": {
		"state": {
			"description": "Media Control’s playing state",
			"enum": [
				"play",
				"pause",
				"stop"
			],
			"type": "string"
		}
	},
	"methods": {
		"next": {
			"description": "Plays next track"
		},
		"pause": {
			"description": "Pauses the audio"
		},
		"play": {
			"description": "Plays the audio"
		},
		"previous": {
			"description": "Plays previous track"
		}
	}
}

The MediaInfo service provides information about the current media.

{
	"name": "MediaInfo",
	"properties": {
		"albumArt": {
			"description": "URI to the media’s album art",
			"format": "uri",
			"type": "string",
			"readOnly": true
		},
		"albumTitle": {
			"description": "Album name of the media’s current track",
			"type": "string",
			"readOnly": true
		},
		"artist": {
			"description": "Artist name of the media’s current track",
			"type": "string",
			"readOnly": true
		},
		"nextAlbumTitle": {
			"description": "Album name of the media’s next track",
			"type": "string",
			"readOnly": true
		},
		"nextArtist": {
			"description": "Artist name of the media’s next track",
			"type": "string",
			"readOnly": true
		},
		"nextTrackName": {
			"description": "Name of the media’s next track",
			"type": "string",
			"readOnly": true
		},
		"trackName": {
			"description": "Name of the media’s current track",
			"type": "string",
			"readOnly": true
		}
	},
	"events": {
		"trackChanged": {
			"description": "Indicates the currently playing track has changed"
		}
	}
}

The AudioOutput service controls the volume of a speaker.

{
	"name": "AudioOutput",
	"properties": {
		"volume": {
			"description": "Audio volume",
			"minimum": 0,
			"maximum": 100,
			"type": "integer"
		},
		"mute": {
			"description": "Audio muted state",
			"enum": [
				true,
				false
			],
			"type": "boolean"
		}
	},
	"methods": {
		"mute": {
			"description": "Mutes the audio"
		},
		"stepUp": {
			"description": "Increment the volume one level"
		},
		"stepDown": {
			"description": "Decrement the volume one level"
		},
		"unmute": {
			"description": "Unmutes the audio"
		}
	}
}

Putting these three services together, it is clear how each service controls something different about a smart speaker, without overlap. These services together create the complete model of the speaker. The BinarySwitch service could be applied to the speaker as well to handle on/off switch states, depending on the capabilities of the speaker. This is possible because, like the existing speaker services, BinarySwitch has no overlap with other services modeled in the speaker.

Reusability: DimmableLight, MulticolorLight

A well-defined service definition should consider how it would be reused by other devices.

Using smart lighting as an example, some lights can change in brightness while others can change in both color and brightness, while others can change in brightness and color temperature within the white spectrum.

Indexed Services

As previously described, devices can implement multiple instances of the same service when there are multiple parts of the device that function in the same way. For example, in a power strip with 5 different BinarySwitch services defining the outlets, specifying specific service indexes with service selectors facilitates precise control over individual outlets.

For more on service selectors, see the next section.