From 186d0fb09359ab52f1bc17d1c692c33446911bdd Mon Sep 17 00:00:00 2001 From: Andreas Holstenson Date: Sun, 28 Jan 2018 20:27:39 +0100 Subject: [PATCH] Moving advanced API to own Markdown-file --- README.md | 106 ++----------------------------------------- docs/advanced-api.md | 103 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+), 101 deletions(-) create mode 100644 docs/advanced-api.md diff --git a/README.md b/README.md index 4b0f4da..107f17d 100644 --- 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 new file mode 100644 index 0000000..4975eee --- /dev/null +++ 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.