Improving documentation about use and devices

kingkong123 · Apr 17, 2017 · f37da07 · f37da07
1 parent 945a58d
commit f37da07
Show file tree

Hide file tree

Showing 2 changed files with 111 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -50,40 +50,19 @@ miio.device({ address: '192.168.100.8', token: 'token-as-hex' })
 Call methods to interact with the device:
 
 ```javascript
-// Call any method via call
-device.call('set_mode', [ 'silent' ])
-	.then(console.log)
-	.catch(console.error);
-
-// Fetch some properties
-device.getProperties([ 'power', 'mode', 'aqi', 'temp_dec', 'humidity' ])
-	.then(console.log)
-	.catch(console.error);
-
-// Or if a model has been specified use some of its methods
-device.setPower(false)
+// Switch the power of the device
+device.setPower(! device.power)
 	.then(on => console.log('Power is now', on));
 ```
 
-Monitor and transform properties:
-```javascript
-// Define a property that should be monitored
-device.defineProperty('mode');
-
-// Define that a certain property should be run through a custom conversion
-device.defineProperty('temp_dec', v => v / 10.0);
+Listen to events such as property changes and actions:
 
-// Listen for changes to properties
+```javascript
+// All devices have a propertyChanged event
 device.on('propertyChanged', e => console.log(e.property, e.oldValue, e.value));
 
-// Activate automatic property monitoring (activated by default for most devices)
-device.monitor();
-
-// Stop automatic property monitoring
-device.stopMonitoring();
-
-// Fetch the last value of a monitored property
-const value = device.property('temp_dec');
+// Some devices have custom events
+device.on('action', e => console.log('Action performed:', e.id));
 ```
 
 If you are done with the device call `destroy` to stop all network traffic:
@@ -92,6 +71,9 @@ If you are done with the device call `destroy` to stop all network traffic:
 device.destroy();
 ```
 
+Check [documentation for devices](docs/devices/README.md) for details about
+the API for supported devices.
+
 ## Tokens
 
 A few miIO devices send back their token during a handshake and can be used
@@ -168,6 +150,44 @@ device.init()
 	.catch(console.error);
 ```
 
+## Advanced: Call a miIO-method directly
+
+It's possible to call any method directly on a device without using the
+top-level API. This is useful if some aspect of your device is not yet
+supported by the library.
+
+```javascript
+// Call any method via call
+device.call('set_mode', [ 'silent' ])
+	.then(console.log)
+	.catch(console.error);
+```
+
+## Advanced: Define custom properties
+
+If you want to define some custom properties to fetch for a device or if your
+device is not yet supported you can easily do so:
+
+```javascript
+// Define a property that should be monitored
+device.defineProperty('mode');
+
+// Define that a certain property should be run through a custom conversion
+device.defineProperty('temp_dec', v => v / 10.0);
+
+// Listen for changes to properties
+device.on('propertyChanged', e => console.log(e.property, e.oldValue, e.value));
+
+// Activate automatic property monitoring (activated by default for most devices)
+device.monitor();
+
+// Stop automatic property monitoring
+device.stopMonitoring();
+
+// Fetch the last value of a monitored property
+const value = device.property('temp_dec');
+```
+
 ## Advanced: Device management
 
 Get information and update the wireless settings of devices via the management

diff --git a/docs/devices/README.md b/docs/devices/README.md
@@ -12,7 +12,7 @@ Id                    | Description
 ----------------------|------------------------------------------------------------|---------------------
 [`switch`](switch.md) | Switchable devices such as power plugs and light switches. | Mi Smart Socket Plug, Aqara Plug, Aqara Light Control
 [`controller`](controller.md) | Devices that are primarily used to control something else. | Aqara Button, Aqara Cube, Aqara Light Switch
-[`gateway`](gateway.md) | Mi Home Smart Gateway that pulls in sub devices of the Aqara type | Mi Smart Home Gateway 2, Mi Smart Home Gateway 3
+[`gateway`](gateway.md) | Mi Smart Home Gateway that pulls in sub devices of the Aqara type | Mi Smart Home Gateway 2, Mi Smart Home Gateway 3
 [`air-purifier`](air-purifier.md) | Air purifiers and air filtering devices. | Mi Air Purifier, Mi Air Purifier 2 and Mi Air Purifier Pro
 [`vacuum`](vacuum.md) | Robot vacuums. | Mi Robot Vacuum
 
@@ -23,6 +23,68 @@ Id                         | Description
 [`power`](cap-power.md)  | Device supports being switched on or off.
 [`power-channels`](cap-power-channels.md) | Device has one or more channels that can be switched on or off. Used for type `switch`.
 
+## Models
+
+The table below indicates how well different devices are supported. The support
+column can be one of the following:
+
+* None - this device is not a miIO-device or has some quirk making it unusable
+* Generic - this device is supported via the generic API but does not have a high-level API
+* Basic - the basic functionality of the device is implemented, but more advanced features are missing
+* Good - most of the functionality is available including some more advanced features such as settings
+* Excellent - as close to complete support as possible
+
+If your device is not in this list, it might still be a miIO-device and at
+least have generic support. See the next section for details about how to find
+out if that is the case. If your device needs a manual token and the table says
+it should not, something has probably changed in the firmware, in that case please
+open an issue so the table can be adjusted.
+
+Name                          | Type                            | Auto-token | Support   | Note
+------------------------------|---------------------------------|------------|-----------|--------
+Mi Air Purifier 1              | [`air-purifier`](air-purifier.md) | Yes        | Good      |
+Mi Air Purifier 2              | [`air-purifier`](air-purifier.md) | Yes        | Good      |
+Mi Air Purifier Pro            | [`air-purifier`](air-purifier.md) | Yes        | Basic     | Some of the new features and sensors are not supported.
+Mi Flora                      | -                               | -          | None      | Communicates using Bluetooth.
+Mi Lunar Smart Sleep Sensor   | -                               | Yes        | Generic   |
+Mi Robot Vacuum               | [`vacuum`](vacuum.md)           | No         | Basic     | DND, timers and mapping features. are not supported
+Mi Smart Socket Plug          | [`switch`](switch.md)           | Yes        | Good      |
+Mi Smart Socket Plug 2        | [`switch`](switch.md)           | Yes        | Good      |
+Mi Smart Home Gateway 1       | -                               | Yes        | Generic   | API used to access sub devices not supported.
+Mi Smart Home Gateway 2       | [`gateway`](gateway.md)         | Yes        | Basic     | Light, sound and music features not supported.
+Mi Smart Home Gateway 3       | [`gateway`](gateway.md)         | Yes        | Basic     | Light, sound and music features not supported.
+Mi Smart Home Cube            | [`controller`](controller.md)   | Yes        | Excellent | Aqara device via Smart Home Gateway
+Mi Smart Home Light Switch    | [`controller`](controller.md)   | Yes        | Good      | Aqara device via Smart Home Gateway. Needs testing.
+Mi Smart Home Light Control   | [`switch`](switch.md)           | Yes        | Good      | Aqara device via Smart Home Gateway. Controls power to one or two lights. Needs testing.
+Mi Smart Home Temperature and Humidity Sensor | `sensor`        | Yes        | Excellent | Aqara device via Smart Home Gateway.
+Mi Smart Home Wireless Switch | [`controller`](controller.md)   | Yes        | Excellent | Aqara device via Smart Home Gateway.
+Mi Smart Home Door / Window Sensor | `magnet`                   | Yes        | Good      | Aqara device via Smart Home Gateway. Needs testing.
+Mi Smart Home Occupancy Sensor | `motion`                       | Yes        | Good      | Aqara device via Smart Home Gateway. Needs testing.
+Mi Smart Home Aqara Plug      | [`switch`](switch.md)           | Yes        | Good      | Aqara device via Smart Home Gateway. Needs testing.
+
+## Finding devices on your network
+
+In certain cases your device might not be listed under models but still be a
+miIO-device, for example if it's a new device or something that no one using
+the library has tested yet.
+
+The command line application can help with discovery of devices. Get started by
+install the command line application:
+
+`npm install -g miio`
+
+Run the app in discovery mode to list devices on your network:
+
+`miio --discover`
+
+This will start outputting all of the devices found, with their address,
+identifiers, models and tokens (if found). If your device can be supported it
+will show up in this list.
+
+If the device shows up feel free to open an issue about supporting the device.
+Be sure to include the name of the device model and the model id output by the
+discover command.
+
 ## Generic devices
 
 The `generic` type is used when a device is of an unknown model. All properties