Project

General

Profile

Device Protocol » History » Version 5

Hammel, 04 Apr 2016 11:49

1 1 Hammel
h1. Device Protocol
2
3
The device protocol defines the messaging that occurs between an IoT device and the PiBox server.  
4
5
h2. Registration
6
7
Registration is initiated by the IoT device.  It sends a multicast packet to the PiBox server.  The packet does not need to contain any information.  It's purpose is to advertise the IP address of the IoT device.  
8
9
The server captures the message and then queries the device for type, features and configuration which is stored in the piboxd daemon and to file as needed.
10
11
h2. Queries
12
13
A query is made from the server to the IoT device using a web URL.  The URL is of the format
14
15 2 Hammel
<pre>
16 1 Hammel
  http://<ipaddress>/im/<version>/<command>
17 2 Hammel
</pre>
18 1 Hammel
19
POST variables are used for arguments to the command.
20
21
Some commands are common to all devices.
22
23
<pre>
24 3 Hammel
  get: arguments include config, registration
25 1 Hammel
  set: arguments include config
26
</pre>
27
28
Other commands are specific to the device and can be identified in the config response.
29
30
h2. Query Response
31
32 3 Hammel
A query response is provided as JSON text in the body of the page returned to the caller.  For a registration request the device returns it's identity and feature list.  For a config request the device returns its current settings associated with the features it supports.
33 1 Hammel
34
h3. Identify
35
36
The identity is the device name.  This is free format and is used to identify the device to the server.
37
38
h3. Features
39
40 5 Hammel
A device can specify a collection of features.  The feature is a set of names and associated data types and values.  The data type for the feature and is one of num, text, range, or set which is specified as the value for the feature name.  If a feature is of type of range then the range is specified as name-range.  If the type is set then the set is specified as name-set. A feature can have a display name separate from the feature name, which is represented as name-display.  The feature name cannot have the "-" character.  All other names prefixed with that name are associated with that feature.
41 4 Hammel
42
<pre>
43
{
44
    "identity": "abcd", 
45
    "features": {
46
        "damper":             "set", 
47
        "damper-display":     "Vent Damper", 
48
        "damper-set":         "0,25,50,75,100", 
49
    }
50
}
51
</pre>
52 1 Hammel
53
Features are the way a device specifies how it can be configured and what data it provides.  The server can use this to dynamically build a UI for the device.
54
55
h3. Config
56
57
The config response contains the current settings for the named features.  
58
59
h2. Control
60
61
Control of a device is through a config object.  The configuration is changed by a UI application and forwarded to the IoT device.  The device attempts to apply the configuration changes, which may or may not succeed.  Success is not specified on a configuration change.  The only way to know if the change was applied is to query the current configuration and compare it to the change request.