Device Protocol » History » Version 1
Hammel, 09 Mar 2016 21:39
| 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 | http://<ipaddress>/im/<version>/<command> |
||
| 16 | |||
| 17 | POST variables are used for arguments to the command. |
||
| 18 | |||
| 19 | Some commands are common to all devices. |
||
| 20 | |||
| 21 | <pre> |
||
| 22 | get: arguments include config, identity, features |
||
| 23 | set: arguments include config |
||
| 24 | </pre> |
||
| 25 | |||
| 26 | Other commands are specific to the device and can be identified in the config response. |
||
| 27 | |||
| 28 | h2. Query Response |
||
| 29 | |||
| 30 | A query response is provided as JSON text in the body of the page returned to the caller. |
||
| 31 | |||
| 32 | h3. Identify |
||
| 33 | |||
| 34 | The identity is the device name. This is free format and is used to identify the device to the server. |
||
| 35 | |||
| 36 | h3. Features |
||
| 37 | |||
| 38 | A device can specify a set of features. The set is a collection of names and associated data type. 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. |
||
| 39 | |||
| 40 | 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. |
||
| 41 | |||
| 42 | h3. Config |
||
| 43 | |||
| 44 | The config response contains the current settings for the named features. |
||
| 45 | |||
| 46 | h2. Control |
||
| 47 | |||
| 48 | 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. |