Device Protocol » History » Version 4
Hammel, 10 Mar 2016 16:07
| 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 | 4 | Hammel | A device can specify a collection of features. The collection 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. 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 field can have a name and a display name, which is represented as name-display. |
| 41 | |||
| 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. |