Overview

Device modeling defines the capabilities of a device using models. These models describe the set of commands that a device can execute, and eliminate the need to define customized protocols for every new device connected to the system.

Devices are modeled in Droplit ecosystems by using service classes. Service classes are templates that define device capabilities in a standardized way. They can define events, methods, or properties. The information pieces defined by a service class are collectively known as service members.

Service classes group related functionalities into a single template, and they provide a common interface to those functions. The specific implementation of a service class on a given device is simply called a service. A device may implement a single service, multiple different services, or multiple instances of the same service for different uses, depending on how the device operates.

Service Members

Properties

Properties describe the state of a single device attribute. For example, a “switch” property could indicate if a device is on or off. Properties are stateful, because they have a value that can be both read and written. Writing to a device property will cause the device to change state, and any changes to a device’s underlying state will propagate a state change notification through its exposed properties. This state change may simply be a change in internal information, or it may cause a visible external change in the device, such as turning the device on.

Methods

Methods execute a device action. For example, a “brew” method on a coffee maker could cause the brewing process to begin. Methods are not stateful, because they do not have any stored values associated with them. They may cause the values of properties to change, but are not required to, and it is not necessary to always associate a method with a specific property. Some methods can accept parameters. No methods can accept return values at the present time, but they will be able to in the future.

Events

Events indicate when something takes place on a device. For example, a “motion” event on a motion sensor could indicate that the device detected motion. Events are not stateful. They fire only once, when the event first takes place on the device. Defining events for property changes is not necessary, because all property changes automatically fire an event.

Defining Services

Services are defined with a single JSON file. The service definition is a JSON object, which must have the following structure:

{
	"name": "SERVICE-CLASS-NAME",
	"properties": {},
	"methods": {},
	"events": {}
}

The simplest possible service class contains only a name, and no keys which describe members. A service class name may not contain spaces, and the definitions of service members must be valid JSON.

The name of the JSON file does not matter, because the name defined in the JSON object is what defines the internal name of the service. Service names must meet the following format requirements.

• Between 1 and 23 characters
• Only contains characters A-Z, a-z, 0-9, _
• No speaces
• Case-sensitive

By convention, a service class name is written using the PascalCase capitalization style. Other keys should be written in the camelCase capitalization style.

Service definitions can be viewed and updated using the Droplit command line console or the Droplit REST API.