Device Protocol » History » Version 8
Hammel, 04 Apr 2016 14:24
| 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 | 8 | Hammel | A device can specify a collection of features. A feature is a set of names and associated data types and values. The feature is defined by its *name*. The feature name cannot have the "-" character. All other names prefixed with that name are associated with that feature. The data type (re: the JSON value) for the name and is one of _num_, _text_, _range_, or _set_. 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 current setting for that feature is presented as the _name-value_. The following is an example using the underlying JSON formatted structure. |
| 41 | 4 | Hammel | |
| 42 | <pre> |
||
| 43 | { |
||
| 44 | 7 | Hammel | "identity": "vent", |
| 45 | 4 | Hammel | "features": { |
| 46 | "damper": "set", |
||
| 47 | "damper-display": "Vent Damper", |
||
| 48 | "damper-set": "0,25,50,75,100", |
||
| 49 | 6 | Hammel | "damper-value": "25", |
| 50 | 4 | Hammel | } |
| 51 | } |
||
| 52 | </pre> |
||
| 53 | 1 | Hammel | |
| 54 | 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. |
||
| 55 | |||
| 56 | h3. Config |
||
| 57 | |||
| 58 | The config response contains the current settings for the named features. |
||
| 59 | |||
| 60 | h2. Control |
||
| 61 | |||
| 62 | 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. |