doc update

microhomie · Mar 16, 2018 · 21ce13e · 21ce13e
1 parent f61ed37
commit 21ce13e
Show file tree

Hide file tree

Showing 9 changed files with 154 additions and 122 deletions.
diff --git a/README.rst b/README.rst
@@ -7,8 +7,6 @@ Microhomie
 
 A MicroPython implementation of the `Homie <https://github.com/marvinroger/homie>`_ MQTT convention version ``2.1.0``.
 
-Version: ``0.2.0``
-
 This project is in beta stage.
 
 
@@ -19,101 +17,12 @@ Known issues
 * In lost of Wifi connection, there is a chance MQTT qos==1 will hang forever
 
 
-Examples
---------
-
-Please find multiple examples in the ``examples`` folder.
-
-
 Install
 -------
 
-Setup WIFI for installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Microhomie handles WIFI setup for you, but for installation from PyPi you have to manual setup WIFI once from REPL.
-
->>> import network
->>> wlan = network.WLAN(network.STA_IF)
->>> wlan.active(True)
->>> wlan.connect('wifi-name', 'wifi-secret')
-# wait a few seconds
->>> wlan.isconnected()  # test if wlan is connected
-True
->>> wlan.ifconfig()  # get wlan interface config
-('192.168.42.2', '255.255.255.0', '192.168.42.1', '192.168.42.1')
-
-Install from PyPi
-~~~~~~~~~~~~~~~~~
-
-We provide PyPi packages for easier installation on your device. Open the REPL from your device, make sure your device wlan is up and your device has access to the internet, import upip and install microhomie:
-
->>> import upip
->>> upip.install('microhomie')
-
-Manual copy the files
-~~~~~~~~~~~~~~~~~~~~~
-
-Use your favorite MicroPython remote shell like `rshell <https://github.com/dhylands/rshell>`_, `mpfshell <https://github.com/wendlers/mpfshell>`_ or `ampy <https://github.com/adafruit/ampy>`_ to copy Microhomie to your device.
-
-Create a directory ``homie`` on your device ``lib`` directory and copy the file ``__init__.py`` from the ``homie`` directory. Then create a ``node`` directory in ``homie`` and copy ``__init__.py``, ``led.py``, ``simple.py`` from the ``homie/node`` directory to the device.
-
-Your file system structure should now look similar like this::
-
-    ├── lib
-    |   ├── homie
-    │   |   ├── __init__.py
-    |   │   ├── node
-    │   │   |   ├── __init__.py
-    │   │   |   ├── led.py
-    │   │   |   ├── simple.py
-    ├── boot.py
-    ├── main.py
-
-
-Install with mpfshell
-~~~~~~~~~~~~~~~~~~~~~
-
-With mpfshell you can execute our mpfshell-script ``install.mpf`` to install Microhomie on your device. Clone this repository and run::
-
-    mpfshell ttyUSB0 -s install.mpf
-
-
-Configuration
--------------
-
-Microhomie use a ``settings.py`` file to configure the device. See ``settings.example.py`` as an example. Modify this file for your needs and copy it to your device root directory as ``settings.py``.
+You can get the detailed installation instructions here: http://microhomie.readthedocs.io/
 
 
-ESP8266 example device
-----------------------
-
-In this example we use the on-board LED from the ESP8266. Copy the ``example-led.py`` file from the ``examples`` diretory to your device and rename it to ``main.py``.
-
-You can now connect a MQTT client to your MQTT Broker an listen to the ``homie/#`` topic, or whatever you set as base topic.
-
-Reset your ESP8266 and watch incoming MQTT messages.
-
-The on-board LED status is reversed to the pin status. On start the on-board
-LED is on. To turn it off send *on* or *toggle* via MQTT. Replace ``<DEVICEID>`` with the ID from the MQTT topic:
-
-.. code-block:: shell
-
-    $ mosquitto_pub -t 'homie/<DEVICEID>/led/power/set' -m on
-    $ mosquitto_pub -t 'homie/<DEVICEID>/led/power/set' -m off
-    $ mosquitto_pub -t 'homie/<DEVICEID>/led/power/set' -m toggle
-
-
-Add a node
-----------
-
-We provide some example nodes in the `microhomie-nodes <https://github.com/microhomie/microhomie-nodes>`_ repository. Most of these nodes can be used out of the box to publish data. If you want to use a DHT22 sensor in example, copy the files ``__init__.py`` and ``dht22.py`` from ``homie/node`` to the ``lib/homie/node`` directory on your device. In the ``dht22.py`` file you see an example ``main.py`` as docstring. Copy this example to ``main.py`` on your device and on next reset it starts publishing temperature and humidity. In this example the DHT22 sensor is wired to GPIO PIN 4, on ESP8266 this is PIN D2.
-
-You can also install nodes from PyPi:
-
->>> import upip
->>> upip.install('microhomie-nodes-dht22')
-
 
 Local Development setup
 -----------------------
@@ -129,33 +38,7 @@ After that, you can install the required libraries.
     micropython -m upip install micropython-machine
 
 
-Simple node
------------
-
-In most cases you write your own node classes. But if you just want to test publishing or have a simple use case, you can use the ``SimpleHomieNode`` class. The ``SimpleHomieNode`` does not provide all homie properties, but can be used as a fast start, when you don't want to write anything in a class:
-
-.. code-block:: python
-
-    import utime
-    import settings
-
-    from homie.node.simple import SimpleHomieNode
-    from homie import HomieDevice
-
-
-    homie_device = HomieDevice(settings)
-
-    n = SimpleHomieNode(node_type=b'dummy', node_property=b'value', interval=5)
-    n.value = 17
-
-    homie_device.add_node(n)
-    homie_device.publish_properties()
 
-    while True:
-        homie_device.publish_data()
-        n.value = utime.time()
-        print(n)
-        utime.sleep(1)
 
 
 

diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,58 @@
+
+Examples
+--------
+
+Please find multiple examples in the ``examples`` folder.
+
+
+
+
+Example: ESP8266 example device
+_________________________________
+
+In this example we use the on-board LED from the ESP8266. Copy the ``example-led.py`` file from the ``examples`` diretory to your device and rename it to ``main.py``.
+
+You can now connect a MQTT client to your MQTT Broker an listen to the ``homie/#`` topic, or whatever you set as base topic.
+
+Reset your ESP8266 and watch incoming MQTT messages.
+
+The on-board LED status is reversed to the pin status. On start the on-board
+LED is on. To turn it off send *on* or *toggle* via MQTT. Replace ``<DEVICEID>`` with the ID from the MQTT topic:
+
+.. code-block:: shell
+
+    $ mosquitto_pub -t 'homie/<DEVICEID>/led/power/set' -m on
+    $ mosquitto_pub -t 'homie/<DEVICEID>/led/power/set' -m off
+    $ mosquitto_pub -t 'homie/<DEVICEID>/led/power/set' -m toggle
+
+
+
+
+
+Example: Simple node
+_______________________
+
+In most cases you write your own node classes. But if you just want to test publishing or have a simple use case, you can use the ``SimpleHomieNode`` class. The ``SimpleHomieNode`` does not provide all homie properties, but can be used as a fast start, when you don't want to write anything in a class:
+
+.. code-block:: python
+
+    import utime
+    import settings
+
+    from homie.node.simple import SimpleHomieNode
+    from homie import HomieDevice
+
+
+    homie_device = HomieDevice(settings)
+
+    n = SimpleHomieNode(node_type=b'dummy', node_property=b'value', interval=5)
+    n.value = 17
+
+    homie_device.add_node(n)
+    homie_device.publish_properties()
+
+    while True:
+        homie_device.publish_data()
+        n.value = utime.time()
+        print(n)
+        utime.sleep(1)
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,9 +1,30 @@
-.. Microhomie documentation master file, created by
-   sphinx-quickstart on Fri Mar 16 11:42:09 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
 .. include:: ../README.rst
 
 
+Base Installation
+------------
 
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   installation_base/*
+
+Node Installation
+------------
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   installation_node/*
+
+Examples
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+
+   examples
diff --git a/docs/installation_base/_index.rst b/docs/installation_base/_index.rst
@@ -0,0 +1,27 @@
+Prerequisite
+~~~~~~~~~~~~
+
+
+Setup WIFI for installation
+-----------------------------
+
+Microhomie handles WIFI setup for you, but for installation from PyPi you have to manual setup WIFI once from REPL.
+
+>>> import network
+>>> wlan = network.WLAN(network.STA_IF)
+>>> wlan.active(True)
+>>> wlan.connect('wifi-name', 'wifi-secret')
+# wait a few seconds
+>>> wlan.isconnected()  # test if wlan is connected
+True
+>>> wlan.ifconfig()  # get wlan interface config
+('192.168.42.2', '255.255.255.0', '192.168.42.1', '192.168.42.1')
+
+
+
+
+
+Configuration
+-------------
+
+Microhomie use a ``settings.py`` file to configure the device. See ``settings.example.py`` as an example. Modify this file for your needs and copy it to your device root directory as ``settings.py``.
diff --git a/docs/installation_base/manual.rst b/docs/installation_base/manual.rst
@@ -0,0 +1,18 @@
+Install manually
+~~~~~~~~~~~~~~~~~~~~~
+
+Use your favorite MicroPython remote shell like `rshell <https://github.com/dhylands/rshell>`_, `mpfshell <https://github.com/wendlers/mpfshell>`_ or `ampy <https://github.com/adafruit/ampy>`_ to copy Microhomie to your device.
+
+Create a directory ``homie`` on your device ``lib`` directory and copy the file ``__init__.py`` from the ``homie`` directory. Then create a ``node`` directory in ``homie`` and copy ``__init__.py``, ``led.py``, ``simple.py`` from the ``homie/node`` directory to the device.
+
+Your file system structure should now look similar like this::
+
+    ├── lib
+    |   ├── homie
+    │   |   ├── __init__.py
+    |   │   ├── node
+    │   │   |   ├── __init__.py
+    │   │   |   ├── led.py
+    │   │   |   ├── simple.py
+    ├── boot.py
+    ├── main.py
diff --git a/docs/installation_base/mpfshell.rst b/docs/installation_base/mpfshell.rst
@@ -0,0 +1,6 @@
+Install with mpfshell (experimental)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With mpfshell you can execute our mpfshell-script ``install.mpf`` to install Microhomie on your device. Clone this repository and run::
+
+    mpfshell ttyUSB0 -s install.mpf
diff --git a/docs/installation_base/pypi.rst b/docs/installation_base/pypi.rst
@@ -0,0 +1,7 @@
+Install with PyPi
+~~~~~~~~~~~~~~~~~
+
+We provide PyPi packages for easier installation on your device. Open the REPL from your device, make sure your device wlan is up and your device has access to the internet, import upip and install microhomie:
+
+>>> import upip
+>>> upip.install('microhomie')
diff --git a/docs/installation_base/wizzard.rst b/docs/installation_base/wizzard.rst
@@ -0,0 +1,2 @@
+Install with Wizzard (experimental)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/installation_node/index.rst b/docs/installation_node/index.rst
@@ -0,0 +1,10 @@
+
+Add a node
+~~~~~~~~~~~
+
+We provide some example nodes in the `microhomie-nodes <https://github.com/microhomie/microhomie-nodes>`_ repository. Most of these nodes can be used out of the box to publish data. If you want to use a DHT22 sensor in example, copy the files ``__init__.py`` and ``dht22.py`` from ``homie/node`` to the ``lib/homie/node`` directory on your device. In the ``dht22.py`` file you see an example ``main.py`` as docstring. Copy this example to ``main.py`` on your device and on next reset it starts publishing temperature and humidity. In this example the DHT22 sensor is wired to GPIO PIN 4, on ESP8266 this is PIN D2.
+
+You can also install nodes from PyPi:
+
+>>> import upip
+>>> upip.install('microhomie-nodes-dht22')