Moving advanced API to own Markdown-file

aholstenson · Jan 28, 2018 · 186d0fb · 186d0fb
1 parent 3a3cad0
commit 186d0fb
Show file tree

Hide file tree

Showing 2 changed files with 108 additions and 101 deletions.
diff --git a/README.md b/README.md
@@ -116,10 +116,6 @@ 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. Detailed documentation of the core API is
-available in the section [Using things in the abstract-things documentation](http://abstract-things.readthedocs.io/en/latest/using-things.html).
-
 ## Tokens and device management
 
 A few miIO devices send back their token during a handshake and can be used
@@ -165,44 +161,13 @@ devices.on('unavailable', device => {
 * `useTokenStorage`, if tokens should be fetched from storage (see device management). Default: `true`
 * `tokens`, object with manual mapping between ids and tokens (advanced, use [Device management](docs/management.md) if possible)
 
-Example using `miio.browse()`:
-
-```javascript
-const browser = miio.browse({
-  cacheTime: 300 // 5 minutes. Default is 1800 seconds (30 minutes)
-});
-
-const devices = {};
-browser.on('available', reg => {
-  if(! reg.token) {
-    console.log(reg.id, 'hides its token');
-    return;
-  }
-
-  // Directly connect to the device anyways - so use miio.devices() if you just do this
-  reg.connect()
-    .then(device => {
-      devices[reg.id] = device;
+See [Advanced API](docs/advanced-api.md) for details about `miio.browse()`.
 
-      // Do something useful with the device
-    })
-    .catch(handleErrorProperlyHere);
-});
-
-browser.on('unavailable', reg => {
-  const device = devices[reg.id];
-  if(! device) return;
-
-  device.destroy();
-  delete devices[reg.id];
-})
-```
+## Device API
 
-You can also use mDNS for discovery, but this library does not contain a mDNS
-implementation. You can choose a mDNS-implementation suitable for your
-needs. Devices announce themselves via `_miio._udp` and should work for most
-devices, in certain cases you might need to restart your device to make it
-announce itself.
+Check [documentation for devices](docs/devices/README.md) for details about
+the API for supported devices. Detailed documentation of the core API is
+available in the section [Using things in the abstract-things documentation](http://abstract-things.readthedocs.io/en/latest/using-things.html).
 
 ## Library versioning and API stability
 
@@ -245,67 +210,6 @@ To activate both namespaces set `DEBUG` to both:
 $ DEBUG=miio\*,thing\* miio discover
 ```
 
-## Advanced: Raw API-usage and calling the Xiaomi 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);
-```
-
-**Important**: `call` is advanced usage, the library does very little for you
-when using it directly. If you find yourself needing to use it, please open
-and issue and describe your use case so better support can be added.
-
-## 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);
-
-// 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
-API.
-
-Discover the token of a device:
-```javascript
-device.discover()
-  .then(info => console.log(info.token));
-```
-
-Get internal information about the device:
-```javascript
-device.management.info()
-  .then(console.log);
-```
-
-Update the wireless settings:
-```javascript
-device.management.updateWireless({
-  ssid: 'SSID of network',
-  passwd: 'Password of network'
-}).then(console.log);
-```
-
-Warning: The device will either connect to the new network or it will get stuck
-without being able to connect. If that happens the device needs to be reset.
-
 ## Protocol documentation
 
 This library is based on the documentation provided by OpenMiHome. See https://github.com/OpenMiHome/mihome-binary-protocol for details. For details

diff --git a/docs/advanced-api.md b/docs/advanced-api.md
@@ -0,0 +1,103 @@
+# Advanced API
+
+## `miio.browse()`
+
+`miio.browse()` can be used to discover devices on the local network.
+
+```javascript
+const browser = miio.browse({
+  cacheTime: 300 // 5 minutes. Default is 1800 seconds (30 minutes)
+});
+
+const devices = {};
+browser.on('available', reg => {
+  if(! reg.token) {
+    console.log(reg.id, 'hides its token');
+    return;
+  }
+
+  // Directly connect to the device anyways - so use miio.devices() if you just do this
+  reg.connect()
+    .then(device => {
+      devices[reg.id] = device;
+
+      // Do something useful with the device
+    })
+    .catch(handleErrorProperlyHere);
+});
+
+browser.on('unavailable', reg => {
+  const device = devices[reg.id];
+  if(! device) return;
+
+  device.destroy();
+  delete devices[reg.id];
+})
+```
+
+You can also use mDNS for discovery, but this library does not contain a mDNS
+implementation. You can choose a mDNS-implementation suitable for your
+needs. Devices announce themselves via `_miio._udp` and should work for most
+devices, in certain cases you might need to restart your device to make it
+announce itself.
+
+## `device.call(method, args)` - Raw API-usage and calling the Xiaomi 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);
+```
+
+**Important**: `call` is advanced usage, the library does very little for you
+when using it directly. If you find yourself needing to use it, please open
+and issue and describe your use case so better support can be added.
+
+## 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);
+
+// Fetch the last value of a monitored property
+const value = device.property('temp_dec');
+```
+
+## Device management
+
+Get information and update the wireless settings of devices via the management
+API.
+
+Discover the token of a device:
+```javascript
+device.discover()
+  .then(info => console.log(info.token));
+```
+
+Get internal information about the device:
+```javascript
+device.management.info()
+  .then(console.log);
+```
+
+Update the wireless settings:
+```javascript
+device.management.updateWireless({
+  ssid: 'SSID of network',
+  passwd: 'Password of network'
+}).then(console.log);
+```
+
+Warning: The device will either connect to the new network or it will get stuck
+without being able to connect. If that happens the device needs to be reset.