diff --git a/_config.yml b/_config.yml index 6275152702f..f06f05711b6 100644 --- a/_config.yml +++ b/_config.yml @@ -6,7 +6,7 @@ url: https://home-assistant.io title: Home Assistant subtitle: Open-source home automation platform running on Python 3 -author: Paulus Schoutsen +author: Home Assistant simple_search: https://www.google.com/search description: Home Assistant is an open-source home automation platform running on Python 3. diff --git a/source/_components/binary_sensor.http.markdown b/source/_components/binary_sensor.http.markdown index dff711e5709..8e96f517918 100644 --- a/source/_components/binary_sensor.http.markdown +++ b/source/_components/binary_sensor.http.markdown @@ -32,6 +32,7 @@ For a quick test `curl` can be useful to "simulate" a device. ```bash $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \ + -H "Content-Type: application/json" \ -d '{"state": "off", "attributes": {"friendly_name": "Radio"}}' \ http://localhost:8123/api/states/binary_sensor.radio ``` diff --git a/source/_components/camera.local_file.markdown b/source/_components/camera.local_file.markdown index 2cfff50676a..4fc2cb7cdcb 100644 --- a/source/_components/camera.local_file.markdown +++ b/source/_components/camera.local_file.markdown @@ -15,7 +15,7 @@ ha_release: 0.22 The `local_file` camera platform allows you to integrate any readable image file from disk into Home Assistant as a camera. If the image is updated on the file system the image displayed in Home Assistant will also be updated. -This can for example be used with various camera platforms that save a temporary images locally. It can also be used to display a graph that you render periodacally and will then be displayed in Home Assistant. +This can for example be used with various camera platforms that save a temporary images locally. It can also be used to display a graph that you render periodically and will then be displayed in Home Assistant. To enable this camera in your installation, add the following to your `configuration.yaml` file: diff --git a/source/_components/device_tracker.nmap_scanner.markdown b/source/_components/device_tracker.nmap_scanner.markdown index 06bd0210a45..cd9019b38f8 100644 --- a/source/_components/device_tracker.nmap_scanner.markdown +++ b/source/_components/device_tracker.nmap_scanner.markdown @@ -29,7 +29,7 @@ device_tracker: Configuration variables: -- **hosts** (*Required*): Thenetwork range to scan in CIDR notation, eg. 192.168.1.1/24 +- **hosts** (*Required*): The network range to scan in CIDR notation, eg. 192.168.1.1/24 - **home_interval** (*Optional*): The number of minutes nmap will not scan this device, assuming it is home, in order to preserve the device battery. See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. diff --git a/source/_components/hdmi_cec.markdown b/source/_components/hdmi_cec.markdown index 905c67f85fa..d5267e82308 100644 --- a/source/_components/hdmi_cec.markdown +++ b/source/_components/hdmi_cec.markdown @@ -8,7 +8,7 @@ comments: false sharing: true footer: true ha_category: Automation -featured: false +logo: hdmi.png ha_release: 0.23 ha_iot_class: "Local Push" --- @@ -23,11 +23,33 @@ The computer running Home Assistant must support CEC, and of course be connected ### {% linkable_title libcec %} -[libcec](https://github.com/Pulse-Eight/libcec) must be installed for this component to work. Follow the installation instructions for your environment, provided at the link. `libcec` installs Python 3 bindings, by default as a system Python module. If you are running Home Assistant in a Python virtual environment, make sure it can access the system module, by either symlinking it or using the `--system-site-packages` flag. +[libcec](https://github.com/Pulse-Eight/libcec) must be installed for this component to work. Follow the installation instructions for your environment, provided at the link. `libcec` installs Python 3 bindings by default as a system Python module. If you are running Home Assistant in a [Python virtual environment](/getting-started/installation-virtualenv/), make sure it can access the system module, by either symlinking it or using the `--system-site-packages` flag. #### {% linkable_title Symlinking into virtual environment %} -`ln -s /usr/local/lib/python3.4/dist-packages/cec /lib/python3.4/site-packages` +Create a symlink to the `cec` installation. + +```bash +$ ln -s /usr/local/lib/python3.4/dist-packages/cec /path/to/your/venv/lib/python3.4/site-packages +``` + +For the default virtual environment of a [Raspberry Pi AIO](/getting-started/installation-raspberry-pi-all-in-one/) the command would be as follows. + +```bash +$ ln -s /usr/local/lib/python3.4/dist-packages/cec /srv/hass/hass_venv/lib/python3.4/site-packages +``` + +If after symlinking and adding `hdmi_cec:` to your configuration you are getting the following error in your logs, + +```bash +* failed to open vchiq instance +``` + +you will also need to add the user account Home Asssistant runs under, to the `video` group. To add the Home Assisitant's user account to the `video` group run the following command. + +```bash +$ usermod -a -G video +``` ## {% linkable_title Configuration Example %} @@ -54,7 +76,15 @@ Call the `hdmi_cec/select_device` service with the name of the device to select, "device": "Chromecast" } ``` +So an Automation action using the example above would look something like this. +```yaml +action: + service: hdmi_cec.select_device + data: + device: Chromecast +``` + ### {% linkable_title Power On %} Call the `hdmi_cec/power_on` service (no arguments) to power on any devices that support this function. diff --git a/source/_components/http.markdown b/source/_components/http.markdown index 98a88766f12..3d984ed8861 100644 --- a/source/_components/http.markdown +++ b/source/_components/http.markdown @@ -13,6 +13,10 @@ ha_category: "Other" The `http` component serves all files and data required for the Home Assistant frontend. You only need to add this to your configuration file if you want to change any of the default settings. +

+It's HIGHLY recommended that you set the `api_password`, especially if you are planning to expose your installation to the internet. +

+ ```yaml # Example configuration.yaml entry http: diff --git a/source/_components/light.mqtt.markdown b/source/_components/light.mqtt.markdown index bf933f726cf..6a37f6273e2 100644 --- a/source/_components/light.mqtt.markdown +++ b/source/_components/light.mqtt.markdown @@ -79,3 +79,5 @@ Configuration variables: Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics.

+A basic example using a nodeMCU board (ESP8266) to control its built-in led (on/off) can be found [here](https://github.com/mertenats/open-home-automation/tree/master/ha_mqtt_light). [Here](https://github.com/mertenats/open-home-automation/tree/master/ha_mqtt_rgb_light) is another example to control a RGB led (on/off, brightness and colors). + diff --git a/source/_components/media_player.onkyo.markdown b/source/_components/media_player.onkyo.markdown index 3eb48758d93..950c1031bb2 100644 --- a/source/_components/media_player.onkyo.markdown +++ b/source/_components/media_player.onkyo.markdown @@ -31,7 +31,7 @@ media_player: ``` Configuration variables: - **host** (*Optional*): IP address of the device. Example:`192.168.1.2` If not specified, the platform will load any discovered receivers. -- **name** (*Optional, required if host is specified*): Name of the device +- **name** (*Required if host is specified*): Name of the device - **sources** (*Optional*): A list of mappings from source to source name. Valid sources can be found below. A default list will be used if no source mapping is specified. List of source names: diff --git a/source/_components/media_player.samsungtv.markdown b/source/_components/media_player.samsungtv.markdown index 10f179e0328..8b4f5ec3d62 100644 --- a/source/_components/media_player.samsungtv.markdown +++ b/source/_components/media_player.samsungtv.markdown @@ -44,8 +44,12 @@ Currently known supported models: - F6500 - EH5600 - F6400AF - + If your model is not on the list then give it a test, if everything works correctly then add it to the list on [GitHub](https://github.com/home-assistant/home-assistant.io). The two letters at the beginning of the model number represent the region, UE is Europe, UN is North America and UA is Asia & Australia. The two numbers following that represent the screen size. If you add your model remember to remove these before adding them to the list. There's currently a [known issue](https://github.com/home-assistant/home-assistant/issues/2098) with some TV's receiving a *Key press UP* that can interrupt certain applications. + +Currently tested but not working models: + +- KU6300 - Shows in GUI but unable to control. diff --git a/source/_components/notify.aws_sns.markdown b/source/_components/notify.aws_sns.markdown index f153ee11051..82ad8bc3a79 100644 --- a/source/_components/notify.aws_sns.markdown +++ b/source/_components/notify.aws_sns.markdown @@ -40,3 +40,23 @@ Configuration variables: AWS SNS is a notify platform and thus can be controlled by calling the notify service [as described here](/components/notify/). It will publish a message to all targets given in the notification payload. A target must be a SNS topic or endpoint ARN ([Amazon Resource Name](http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)). For more information, please see the [boto3 docs](http://boto3.readthedocs.io/en/latest/reference/services/sns.html#SNS.Client.publish). If one exists, the SNS Subject will be set to the title. All attributes from the payload except message will be sent as stringified message attributes. + +#### {% linkable_title Setting up SNS within AWS %} + +- Log into your AWS console and under "Security and Identity", select "Identity & Access Management". +- On the left hand side, select "Users" then click "Create New Users". Enter a name here and then click "Create". +- You can either download the credentials or click the arrow to display them one time. + +

+ If you do not download them you will lose them and will have to recreate a new user. +

+ +- Copy/Paste the two keys that you are provided here in your `configuration.yaml` file respectively. +- On the left hand side of the screen go back to "Users" and select the user you just created. On the "Permissions" tab click the "Attach Policy" icon. Search for "SNS" and attach the policy "AmazonSNSFUullAccess". +- Back to the AWS Console you now need to find "SNS" and click in to that service. It is under the Mobile Services group. +- On the left hand side, select "Topics" then "Create new topic". +- Choose a Topic Name and Display Name. +- Now check the box next to the Topic you just created and under Actions, select "Subscribe to topic". +- In the box that pops up, select the Protocol = SMS and enter in the phone number next to "Endpoint" you wish to SMS. Now click "Create". +- Repeat for additional numbers. +- Back in the "Users" section you will see a long alphanumeric line that starts with "arn:" and ends with the Topic Name you choose previously. This is what your "target" in Home Assistant will be. diff --git a/source/_components/sensor.speedtest.markdown b/source/_components/sensor.speedtest.markdown index 29b620cce14..95cd4a9e204 100644 --- a/source/_components/sensor.speedtest.markdown +++ b/source/_components/sensor.speedtest.markdown @@ -74,3 +74,5 @@ Configuration variables: - **day** (*Optional*): Specify the day(s) of the month to schedule the speedtest. Use a list for multiple entries. Default is None. This component uses [speedtest-cli](https://github.com/sivel/speedtest-cli) to gather network performance data from Speedtest.net. Please be aware of the potential [inconsistencies](https://github.com/sivel/speedtest-cli#inconsistency) that this component may display. + +When Home Assistant first starts up, the values of the speedtest will show as `Unknown`. You can use the service `sensor.update_speedtest` to run a manual speedtest and populate the data or just wait for the next regularly scheduled test. diff --git a/source/_cookbook/jupyther_notebooks_api.markdown b/source/_cookbook/jupyther_notebooks_api.markdown new file mode 100644 index 00000000000..4daaad35a5f --- /dev/null +++ b/source/_cookbook/jupyther_notebooks_api.markdown @@ -0,0 +1,13 @@ +--- +layout: page +title: "Notebook for Home Assistant Python API" +description: "Basic example how to work with the Home Assistant Python API in a Jupyter notebook." +date: 2016-07-23 09:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Jupyter Notebooks +ha_external_link: https://github.com/home-assistant/home-assistant-notebooks/blob/master/home-assistant-python-api.ipynb +--- + diff --git a/source/_cookbook/jupyther_notebooks_database.markdown b/source/_cookbook/jupyther_notebooks_database.markdown new file mode 100644 index 00000000000..22802cd0709 --- /dev/null +++ b/source/_cookbook/jupyther_notebooks_database.markdown @@ -0,0 +1,13 @@ +--- +layout: page +title: "Jupyter Notebooks Database" +description: "Basic example how to work with stored Home Assistant information in a Jupyter notebook." +date: 2016-07-23 09:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Jupyter Notebooks +ha_external_link: https://github.com/home-assistant/home-assistant-notebooks/blob/master/database-examples.ipynb +--- + diff --git a/source/_cookbook/jupyther_notebooks_graph.markdown b/source/_cookbook/jupyther_notebooks_graph.markdown new file mode 100644 index 00000000000..8e857c397e4 --- /dev/null +++ b/source/_cookbook/jupyther_notebooks_graph.markdown @@ -0,0 +1,13 @@ +--- +layout: page +title: "Jupyter Notebooks Graph" +description: "Basic example how to create a graph with a Jupyter notebook." +date: 2016-07-23 09:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Jupyter Notebooks +ha_external_link: https://github.com/home-assistant/home-assistant-notebooks/blob/master/graph-single-sensor.ipynb +--- + diff --git a/source/_cookbook/jupyther_notebooks_introduction.markdown b/source/_cookbook/jupyther_notebooks_introduction.markdown new file mode 100644 index 00000000000..2a3d714aa92 --- /dev/null +++ b/source/_cookbook/jupyther_notebooks_introduction.markdown @@ -0,0 +1,55 @@ +--- +layout: page +title: "Jupyter Notebooks Introduction" +description: "Setup and first steps for Jupyter Notebooks and Home Assistant." +date: 2016-07-23 09:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Jupyter Notebooks +--- + +The [Jupyter Notebooks](http://jupyter.org/) allows you to create and share documents that contain live code, equations, visualizations, and explanatory text directly in your browser. The web application what is formerly known as the IPython Notebook supports over 40 programming languages. + +Visit [https://try.jupyter.org/](https://try.jupyter.org/) to get a preview before you install it locally. + +The very first step is to install the requirement to run Jupyter Notebooks. + +```bash +$ pip3 install jupyter matplotlib +``` + +

+Certain notebooks hosted in the [Home Assistant notebooks repository](https://github.com/home-assistant/home-assistant-notebooks) require access to a running Home Assistant instance or parts of a Home Assistant installation. If you want to run those notebooks install Home Assistant with `$ pip3 install homeassistant` as well. +

+ +Now you are able to start the application. + +```bash +$ jupyter notebook +[I 17:22:18.081 NotebookApp] Writing notebook server cookie secret to /run/user/1000/jupyter/notebook_cookie_secret +[I 17:22:18.921 NotebookApp] Serving notebooks from local directory: /home/fabaff/home-assistant +[I 17:22:18.921 NotebookApp] 0 active kernels +[I 17:22:18.921 NotebookApp] The Jupyter Notebook is running at: http://localhost:8888/ +[I 17:22:18.922 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation). +``` + +Open [http://localhost:8888/](http://localhost:8888/) in your browser. Press "New" -> "Python3" to open a new notebook. + +

+ +

+ +You will get an emtpy notebook with one cell. Cells can contain code or text. To get the output of a cell you need to execute them with "Cell" -> "Run Cells" from the menu or by pressing the icon. + +

+ +

+ +The downloadable version of this notebook is available in the [Home Assistant notebooks repository](https://github.com/home-assistant/home-assistant-notebooks/blob/master/first-notebook.ipynb). + + +As you can see is the workflow very similar to working directly with a Python shell. One advantage is that you can go back and forth as you please and save your work. + + diff --git a/source/_cookbook/tor_configuration.markdown b/source/_cookbook/tor_configuration.markdown index 5b8072e5f48..83a76091353 100644 --- a/source/_cookbook/tor_configuration.markdown +++ b/source/_cookbook/tor_configuration.markdown @@ -8,6 +8,8 @@ comments: false sharing: true footer: true ha_category: Infrastructure +author: Nathan Freitas +author_twitter: n8fr8 --- This is an example about how you can configure Tor to provide secure remote access to your Home Assistant instance as an Onion site, through Tor's Hidden Service feature. With this enabled, you do not need to open your firewall ports or setup HTTPS to enable secure remote access. diff --git a/source/_includes/site/head.html b/source/_includes/site/head.html index 5d0d660be86..0c2a76007fc 100644 --- a/source/_includes/site/head.html +++ b/source/_includes/site/head.html @@ -11,7 +11,7 @@ {% if page.title %}{{ page.title }} - {% endif %}{{ site.title }} - + {% if page.keywords %}{% endif %} diff --git a/source/_posts/2016-07-16-sqlalchemy-knx-join-simplisafe.markdown b/source/_posts/2016-07-16-sqlalchemy-knx-join-simplisafe.markdown index 8cc80cbbde5..eb4e0aac409 100644 --- a/source/_posts/2016-07-16-sqlalchemy-knx-join-simplisafe.markdown +++ b/source/_posts/2016-07-16-sqlalchemy-knx-join-simplisafe.markdown @@ -37,7 +37,7 @@ You can omit the `--config` option if you use the default configuration director - [StatsD] can now also export attributes ([@bah2830]) - Support for [KNX] added ([@usul27]) - Switch: [TPLink] HS100/HS110 now supported ([@GadgetReactor]) -- Stability fixes for [RFXTRX] ([@Danielhiversen]) +- Stability fixes for [RFXtrx] ([@Danielhiversen]) - Tweaks to [Z-Wave] ([@turbokongen]) - Light: [Brightness] now clamped to 0-255 ([@keatontaylor]) - Thermostat: [Radiotherm] HVAC mode now supported ([@danieljkemp]) @@ -47,26 +47,16 @@ You can omit the `--config` option if you use the default configuration director - Frontend: Fix stream not reconnecting after standby ([@balloob]) - Frontend: Wait up to two seconds for new state before resetting toggle after toggling state ([@balloob]) -<<<<<<< HEAD -======= ### {% linkable_title Hotfix 0.24.1 - July 21 %} Quick hot fix after we found a bug in the migrator where it wouldn't work with a database in a non-standard location. Thanks to [@n8henrie] and [@AlucardZero]. ->>>>>>> master ### {% linkable_title Breaking changes %} - Migrating existing databases (see above). - The [APCUPSd Sensor][apcupsd-sensor] was updated. This will need that you modify your `configuration.yaml` file. - Entity IDs of Verisure locks will change. This is a one time change but should improve readability. -<<<<<<< HEAD -### {% linkable_title FAQ %} - -- Frequently asked questions about this release will show up here... - -======= ->>>>>>> master [@bah2830]: https://github.com/bah2830/ [@balloob]: https://github.com/balloob/ [@dale3h]: https://github.com/dale3h/ @@ -84,7 +74,11 @@ Quick hot fix after we found a bug in the migrator where it wouldn't work with a ======= [@n8henrie]: https://github.com/n8henrie/ [@AlucardZero]: https://github.com/AlucardZero/ +<<<<<<< HEAD >>>>>>> master +======= +[@Danielhiversen]: https://github.com/danielhiversen +>>>>>>> origin/master [apcupsd-sensor]: /components/sensor.apcupsd/ [Brightness]: /components/light/ @@ -101,10 +95,10 @@ Quick hot fix after we found a bug in the migrator where it wouldn't work with a [secrets]: /topics/secrets/ [simplisafe]: /components/alarm_control_panel.simplisafe/ [SQLAlchemy]: http://www.sqlalchemy.org/ -[StatD]: /components/statsd/ +[StatsD]: /components/statsd/ [Telegram]: /components/notify.telegram/ [TPLink]: /components/switch.tplink/ [Verisure]: /components/lock.verisure/ [yahoo-weather]: /components/sensor.yweather/ [Z-Wave]: /components/zwave/ - +[RFXtrx]: //components/rfxtrx/ diff --git a/source/_posts/2016-07-23-internet-of-things-data-exploration-with-jupyter-notebooks.markdown b/source/_posts/2016-07-23-internet-of-things-data-exploration-with-jupyter-notebooks.markdown new file mode 100644 index 00000000000..d9d17ba37be --- /dev/null +++ b/source/_posts/2016-07-23-internet-of-things-data-exploration-with-jupyter-notebooks.markdown @@ -0,0 +1,80 @@ +--- +layout: post +title: "IoT Data Exploration with Jupyter Notebooks" +description: "Tutorial how to get started exploring your data using Jupyter Notebooks, Pandas and Matplotlib." +date: 2016-07-23 18:00:00 +0000 +date_formatted: "July 23, 2016" +author: Anton Kireyeu +comments: true +categories: How-To IoT-Data +og_image: /images/blog/2016-07-data-exploration/graph.png +--- + +_This is the first blog post by Anton Kireyeu. A new contributor to Home Assistant who will focus on exploring and visualizing Home Assistant data._ + +As we learned in the recent [blog post by Fabian], all operational data of your Home Assistant application is stored locally and is available for exploration. Our first steps were querying data with the [DB Browser for SQLite], exporting the data extract as a CSV file and graphing in LibreOffice. But what else can be done with this data and what tools are there available? + +This post will help you get set up using a few popular data scientist tools to allow you to locally process your data: + + -  [Pandas]: an open source tool for data analysis for Python + -  [matplotlib]: a Python plotting library + -  [Jupyter notebook]: application for creation and sharing of documents containing live code, visualizations and explanatory text + +

+ +One of the graphs created with this tutorial. +

+ +_TL; DR: Use [this Jupyter Notebook][nb-prev] to visualize of your data_ + +[blog post by Fabian]: https://home-assistant.io/blog/2016/07/19/visualizing-your-iot-data/ +[DB Browser for SQLite]: http://sqlitebrowser.org/ +[Pandas]: http://pandas.pydata.org/ +[matplotlib]: http://matplotlib.org/ +[Jupyter notebook]: https://jupyter.org/ +[nb-prev]: http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/DataExploration-1/DataExploration-1.ipynb + + + +### {% linkable_title Dependencies %} + +In order to run the provided Jupyter notebook, please make sure you have the following applications/libraries installed on your computer: + +- Pandas +- NumPy +- Matplotlib +- SQLAlchemy +- Jupyter + +As a Windows user myself, I find the easiest, quickest and most hassle-free way of installing all of these dependencies is to use [WinPython]. This free open-source portable distribution includes all of the dependencies required for this notebook, as well as a few other essential Python libraries you may require for data exploration in the future. + +[WinPython]: https://winpython.github.io/ + +#### {% linkable_title Why Jupyter? %} + +While all Home Assistant implementations can have varying setup, components and scripts, the underlying data structure is standardized and well-defined. This allows us to write Python code that is environmentally agnostic. Wrapping it in a Jupyter notebook ensures the code, visualizations and directions/explanations are kept digestible and neatly-packaged. One of the amazing features of Jupyter is the ability to change code as you go along, customizing all outputs and visualizations on the fly! + +#### {% linkable_title Where do I start? %} + +This tutorial is based around a heavily commented Jupyter Notebook that we created. So to get started, you will have to open that: + + - [download the tutorial Jupyter Notebook][nb-prev] (leads to preview page, from there click download top-right) + - launch the Jupyter Notebook App + - Click the 'upload' button to add the downloaded notebook to Jupyter + - Adjust the `DB_URL` at the beginning of the notebook to point at your Home Assistant database + - Select in top menu: Cell -> Run All + +That’s it! The included code will walk you through importing the required libraries, show running raw SQL against your local database, plotting basic data from the states table, and in the end output a few plots of changes for every entity in your system as well as the mean daily value for the past 20 days. + +After just those few steps, you will be greeted with beautiful formatted data like this: + +

+ +One of the graphs created with this tutorial. +

+ +#### {% linkable_title What’s next? %} + +Thanks to the magic of Jupyter, all of the code is customizable: want to selectively display your data, only covering a specific entity? Sure thing! Want to change the properties of the plots? No problem! + +While you learn and explore your IoT data, we will be working on providing more ready-to-use Jupyter Notebooks. Feel free to ask questions or provide suggestions. Would you like to see a specific visualization? Is there a particular facet of data you’re interested in? Let’s talk about it, let’s dive into the world of data together! diff --git a/source/_posts/2016-07-28-esp8266-and-micropython-part1.markdown b/source/_posts/2016-07-28-esp8266-and-micropython-part1.markdown new file mode 100644 index 00000000000..ef91fc3e7b6 --- /dev/null +++ b/source/_posts/2016-07-28-esp8266-and-micropython-part1.markdown @@ -0,0 +1,163 @@ +--- +layout: post +title: "ESP8266 and MicroPython - Part 1" +description: "Using MicroPython on ESP8266 based devices and Home Assistant." +date: 2016-07-28 06:00:00 +0200 +date_formatted: "July 28, 2016" +author: Fabian Affolter +comments: true +categories: How-To +og_image: /images/blog/2016-07-micropython/social.png +--- + + +The first release of Micropython for ESP8266 was delivered a couple of weeks ago. The [documentation](http://docs.micropython.org/en/latest/esp8266/esp8266_contents.html) covers a lot of ground. This post is providing only a little summary which should get you started. + +Until a couple of weeks ago, the pre-built MicroPython binary for the ESP8266 was only available to backers. This has changed now and it is available to the public for [download](https://micropython.org/download/#esp8266). + + + +The easiest way is to use [esptool.py](https://github.com/themadinventor/esptool) for firmware handling tasks. First erase the flash: + +```bash +$ sudo python esptool.py --port /dev/ttyUSB0 erase_flash +esptool.py v1.0.2-dev +Connecting... +Erasing flash (this may take a while)... +``` + +and then load the firmware. You may adjust the file name of the firmware binary. + +```bash +$ sudo python esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=8m 0 esp8266-2016-07-10-v1.8.2.bin +esptool.py v1.2-dev +Connecting... +Running Cesanta flasher stub... +Flash params set to 0x0020 +Writing 540672 @ 0x0... 540672 (100 %) +Wrote 540672 bytes at 0x0 in 13.1 seconds (330.8 kbit/s)... +Leaving... +``` + +Now reset the device. You should then be able to use the [REPL (Read Evaluate Print Loop)](http://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/repl.html#getting-a-micropython-repl-prompt). On Linux there is `minicom` or `picocom`, on a Mac you can use `screen` (eg. `screen /dev/tty.SLAB_USBtoUART 115200`), and on Windows there is Putty to open a serial connection and get the REPL prompt. + +The [WebREPL](http://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/repl.html#webrepl-a-prompt-over-wifi) work over a wireless connection and allows easy access to a prompt in your browser. An instance of the WebREPL client is hosted at [http://micropython.org/webrepl](http://micropython.org/webrepl). Alternatively, you can create a local clone of their [GitHub repository](https://github.com/micropython/webrepl). This is neccessary if your want to use the command-line tool `webrepl_cli.py` which is mentionend later in this post. + +```bash +$ sudo minicom -D /dev/ttyUSB0 +#4 ets_task(4020e374, 29, 3fff70e8, 10) +WebREPL daemon started on ws://192.168.4.1:8266 +Started webrepl in setup mode +could not open file 'main.py' for reading + +#5 ets_task(4010035c, 3, 3fff6360, 4) +MicroPython v1.8.2-9-g805c2b9 on 2016-07-10; ESP module with ESP8266 +Type "help()" for more information. +>>> +``` + +

+The public build of the firmware may be different than the firmware distributed to the backers of the campaign. Especially in regard of the [available modules](http://docs.micropython.org/en/latest/esp8266/py-modindex.html), turned on debug messages, and alike. Also, the WebREPL may not be started by default. +

+ +Connect a LED to pin 5 (or another pin of your choosing) to check if the ESP8266 is working as expected. + +```python +>>> import machine +>>> pin = machine.Pin(5, machine.Pin.OUT) +>>> pin.high() +``` + +You can toogle the LED by changing its state with `pin.high()` and `pin.low()`. + +Various ESP8266 development board are shipped with an onboard photocell or a light dependent resistors (LDR) connected to the analog pin of your ESP8266 check if you are able to obtain a value. + +```python +>>> import machine +>>> brightness = machine.ADC(0) +>>> brightness.read() +``` + +Make sure that you are familiar with REPL and WebREPL because this will be needed soon. Keep in mind the password for the WebREPL access. + +Read the [instructions](http://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/network_basics.html) about how to setup your wireless connection. Basically you need to upload a `boot.py` file to the microcontroller and this file is taking care of the connection setup. Below you find a sample which is more or less the same as shown in the [documentation](http://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/network_basics.html#configuration-of-the-wifi). + +```python +def do_connect(): + import network + + SSID = 'SSID' + PASSWORD = 'PASSWORD' + + sta_if = network.WLAN(network.STA_IF) + ap_if = network.WLAN(network.AP_IF) + if ap_if.active(): + ap_if.active(False) + if not sta_if.isconnected(): + print('connecting to network...') + sta_if.active(True) + sta_if.connect(SSID, PASSWORD) + while not sta_if.isconnected(): + pass + print('Network configuration:', sta_if.ifconfig()) +``` + +Upload this file with `webrepl_cli.py` or the WebREPL: + +```bash +$ python webrepl_cli.py boot.py 192.168.4.1:/boot.py +``` + +If you reboot, you should see your current IP address in the terminal. + +```bash +>>> Network configuration: ('192.168.0.10', '255.255.255.0', '192.168.0.1', '192.168.0.1') +``` + +First let's create a little consumer for Home Assistant sensor's state. The code to place in `main.py` is a mixture of code from above and the [RESTful API](/developers/rest_api/) of Home Assistant. If the temperature in the kitchen is higher than 20 °C then the LED connected to pin 5 is switched on. + +

+If a module is missing then you need to download is it from [MicroPython Library overview](https://github.com/micropython/micropython-lib) and upload it to the ESP8266 with `webrepl_cli.py` manually. +

+ +```python +# Sample code to request the state of a Home Assistant entity. + +API_PASSWORD = 'YOUR_PASSWORD' +URL = 'http://192.168.0.5:8123/api/states/' +ENTITY = 'sensor.kitchen_temperature' +TIMEOUT = 30 +PIN = 5 + +def get_data(): + import urequests + url = '{}{}'.format(URL, ENTITY) + headers = {'x-ha-access': API_PASSWORD, + 'content-type': 'application/json'} + resp = urequests.get(URL, headers=headers) + return resp.json()['state'] + +def main(): + import machine + import time + + pin = machine.Pin(PIN, machine.Pin.OUT) + while True: + try: + if int(get_data()) >= 20: + pin.high() + else: + pin.low() + except TypeError: + pass + time.sleep(TIMEOUT) + +if __name__ == '__main__': + print('Get the state of {}'.format(ENTITY)) + main() +``` + +Upload `main.py` the same way as `boot.py`. After a reboot (`>>> import machine` and `>>> machine.reboot()`) or power-cycling your physical notifier is ready. + +If you run into trouble, press "Ctrl+c" in the REPL to stop the execution of the code, enter `>>> import webrepl` and `>>> webrepl.start()`, and upload your fixed file. + diff --git a/source/_topics/splitting_configuration.markdown b/source/_topics/splitting_configuration.markdown index 91cb7b823bc..40d3ccd5b93 100644 --- a/source/_topics/splitting_configuration.markdown +++ b/source/_topics/splitting_configuration.markdown @@ -179,7 +179,7 @@ That about wraps it up. If you have issues checkout `home-assistant.log` in the configuration directory as well as your indentations. If all else fails, head over to the [Gitter Chatroom](https://gitter.im/balloob/home-assistant) and ask away. -### {% linkable_title Advanced usage %} +### {% linkable_title Advanced Usage %} We offer four advanced options to include whole directories at once. @@ -190,3 +190,258 @@ We offer four advanced options to include whole directories at once. `!include_dir_merge_list` will return content of a directory as a list by merging all files (which should contain a list) into 1 big list. `!include_dir_merge_named` will return content of a directory as a dictionary by loading each file and merging it into 1 big dictionary. + +#### {% linkable_title Example: `!include_dir_list` %} + +`configuration.yaml` + +```yaml +automation: + - alias: Automation 1 + trigger: + platform: state + entity_id: device_tracker.iphone + to: 'home' + action: + service: light.turn_on + entity_id: light.entryway + - alias: Automation 2 + trigger: + platform: state + entity_id: device_tracker.iphone + from: 'home' + action: + service: light.turn_off + entity_id: light.entryway +``` + +can be turned into: + +`configuration.yaml` + +```yaml +automation: !include_dir_list automation/presence/ +``` + +`automation/presence/automation1.yaml` + +```yaml +alias: Automation 1 +trigger: + platform: state + entity_id: device_tracker.iphone + to: 'home' +action: + service: light.turn_on + entity_id: light.entryway +``` + +`automation/presence/automation2.yaml` + +```yaml +alias: Automation 2 +trigger: + platform: state + entity_id: device_tracker.iphone + from: 'home' +action: + service: light.turn_off + entity_id: light.entryway +``` + +It is important to note that each file must contain only **one** entry when using `!include_dir_list`. + +#### {% linkable_title Example: `!include_dir_named` %} + +`configuration.yaml` + +```yaml +{% raw %} +alexa: + intents: + LocateIntent: + action: + service: notify.pushover + data: + message: Your location has been queried via Alexa. + speech: + type: plaintext + text: > + {%- for state in states.device_tracker -%} + {%- if state.name.lower() == User.lower() -%} + {{ state.name }} is at {{ state.state }} + {%- endif -%} + {%- else -%} + I am sorry. Pootie! I do not know where {{User}} is. + {%- endfor -%} + WhereAreWeIntent: + speech: + type: plaintext + text: > + {%- if is_state('device_tracker.iphone', 'home') -%} + iPhone is home. + {%- else -%} + iPhone is not home. + {% endif %}{% endraw %} +``` + +can be turned into: + +`configuration.yaml` + +```yaml +alexa: + intents: !include_dir_named alexa/ +``` + +`alexa/LocateIntent.yaml` + +```yaml +{% raw %} +action: + service: notify.pushover + data: + message: Your location has been queried via Alexa. +speech: + type: plaintext + text: > + {%- for state in states.device_tracker -%} + {%- if state.name.lower() == User.lower() -%} + {{ state.name }} is at {{ state.state }} + {%- endif -%} + {%- else -%} + I am sorry. Pootie! I do not know where {{User}} is. + {%- endfor -%}{% endraw %} +``` + +`alexa/WhereAreWeIntent.yaml` + +```yaml +{% raw %} +speech: + type: plaintext + text: > + {%- if is_state('device_tracker.iphone', 'home') -%} + iPhone is home. + {%- else -%} + iPhone is not home. + {% endif %}{% endraw %} +``` + +#### {% linkable_title Example: `!include_dir_merge_list` %} + +`configuration.yaml` + +```yaml +automation: + - alias: Automation 1 + trigger: + platform: state + entity_id: device_tracker.iphone + to: 'home' + action: + service: light.turn_on + entity_id: light.entryway + - alias: Automation 2 + trigger: + platform: state + entity_id: device_tracker.iphone + from: 'home' + action: + service: light.turn_off + entity_id: light.entryway +``` + +can be turned into: + +`configuration.yaml` + +```yaml +automation: !include_dir_merge_list automation/ +``` + +`automation/presence.yaml` + +```yaml +- alias: Automation 1 + trigger: + platform: state + entity_id: device_tracker.iphone + to: 'home' + action: + service: light.turn_on + entity_id: light.entryway + +- alias: Automation 2 + trigger: + platform: state + entity_id: device_tracker.iphone + from: 'home' + action: + service: light.turn_off + entity_id: light.entryway +``` + +It is important to note that when using `!include_dir_merge_list`, you must include a list in each file (each list item is denoted with a hyphen [-]). Each file may contain one or more entries. + +#### {% linkable_title Example: `!include_dir_merge_named` %} + +`configuration.yaml` + +```yaml +group: + bedroom: + name: Bedroom + entities: + - light.bedroom_lamp + - light.bedroom_overhead + hallway: + name: Hallway + entities: + - light.hallway + - thermostat.home + front_yard: + name: Front Yard + entities: + - light.front_porch + - light.security + - light.pathway + - sensor.mailbox + - camera.front_porch +``` + +can be turned into: + +`configuration.yaml` + +```yaml +group: !include_dir_merge_named group/ +``` + +`group/interior.yaml` + +```yaml +bedroom: + name: Bedroom + entities: + - light.bedroom_lamp + - light.bedroom_overhead +hallway: + name: Hallway + entities: + - light.hallway + - thermostat.home +``` + +`group/exterior.yaml` + +```yaml +front_yard: + name: Front Yard + entities: + - light.front_porch + - light.security + - light.pathway + - sensor.mailbox + - camera.front_porch +``` diff --git a/source/developers/platform_example_light.markdown b/source/developers/platform_example_light.markdown index c50e2ca6e4a..759e9a379c2 100644 --- a/source/developers/platform_example_light.markdown +++ b/source/developers/platform_example_light.markdown @@ -39,7 +39,7 @@ _LOGGER = logging.getLogger(__name__) def setup_platform(hass, config, add_devices, discovery_info=None): - """Initialize Awesome Light platform.""" + """Setup the Awesome Light platform.""" import awesomelights # Validate passed in config @@ -63,8 +63,9 @@ def setup_platform(hass, config, add_devices, discovery_info=None): # Add devices add_devices(AwesomeLight(light) for light in hub.lights()) + class AwesomeLight(Light): - """Represents an AwesomeLight in Home Assistant.""" + """Representation of an Awesome Light.""" def __init__(self, light): """Initialize an AwesomeLight.""" @@ -72,7 +73,7 @@ class AwesomeLight(Light): @property def name(self): - """Return the display name of this light""" + """Return the display name of this light.""" return self._light.name @property @@ -86,7 +87,7 @@ class AwesomeLight(Light): @property def is_on(self): - """If light is on.""" + """Return true if light is on.""" return self._light.is_on() def turn_on(self, **kwargs): @@ -105,7 +106,7 @@ class AwesomeLight(Light): def update(self): """Fetch new state data for this light. - This is the only method that should fetch new data for Home Assitant. + This is the only method that should fetch new data for Home Assistant. """ self._light.update() ``` diff --git a/source/developers/platform_example_sensor.markdown b/source/developers/platform_example_sensor.markdown index 124475f9661..8902faead2d 100644 --- a/source/developers/platform_example_sensor.markdown +++ b/source/developers/platform_example_sensor.markdown @@ -31,19 +31,25 @@ from homeassistant.helpers.entity import Entity def setup_platform(hass, config, add_devices, discovery_info=None): + """Setup the sensor platform.""" add_devices([ExampleSensor()]) class ExampleSensor(Entity): + """Representation of a Sensor.""" + @property def name(self): + """Return the name of the sensor.""" return 'Example Temperature' @property def state(self): + """Return the state of the sensor."" return 23 @property def unit_of_measurement(self): + """Return the unit of measurement.""" return TEMP_CELSIUS ``` diff --git a/source/developers/python_api.markdown b/source/developers/python_api.markdown index 1e0e5a1f600..fba1fa78ad9 100644 --- a/source/developers/python_api.markdown +++ b/source/developers/python_api.markdown @@ -52,19 +52,19 @@ Similar to the output in the "Developer Tools" of the frontend. ```python import homeassistant.remote as remote -api = remote.API('127.1.0.1', 'password') +api = remote.API('127.1.0.1', 'YOUR_PASSWORD') print('-- Available services:') services = remote.get_services(api) for service in services: print(service['services']) -print('\n-- Available event') +print('\n-- Available events:') events = remote.get_event_listeners(api) for event in events: print(event) -print('\n-- Available entities') +print('\n-- Available entities:') entities = remote.get_states(api) for entity in entities: print(entity) @@ -77,7 +77,7 @@ To get the details of a single entity the `get_state` method is used. ```python import homeassistant.remote as remote -api = remote.API('127.1.0.1', 'password') +api = remote.API('127.1.0.1', 'YOUR_PASSWORD') office_temperature = remote.get_state(api, 'sensor.office_temperature') print('{} is {} {}.'.format(office_temperature.attributes['friendly_name'], office_temperature.state, @@ -97,7 +97,7 @@ The exact same thing is working for a switch. The difference is that both entiti ```python import homeassistant.remote as remote -api = remote.API('127.1.0.1', 'password') +api = remote.API('127.1.0.1', 'YOUR_PASSWORD') switch_livingroom = remote.get_state(api, 'switch.livingroom_pin_2') print('{} is {}.'.format(switch_livingroom.attributes['friendly_name'], switch_livingroom.state @@ -113,7 +113,7 @@ Of course, it's possible to set the state. import homeassistant.remote as remote from homeassistant.const import STATE_ON -api = remote.API('127.1.0.1', 'password') +api = remote.API('127.1.0.1', 'YOUR_PASSWORD') remote.set_state(api, 'sensor.office_temperature', new_state=123) remote.set_state(api, 'switch.livingroom_pin_2', new_state=STATE_ON) ``` @@ -122,14 +122,14 @@ The state will be set to those value until the next update occurs. ### {% linkable_title Blinking all entites of a domain %} -If you want to turn on all entities of a domain, just a service which was retrieved by `get_services`. +If you want to turn on all entities of a domain, just use a service which was retrieved by `get_services`. ```python import time import homeassistant.remote as remote -api = remote.API('127.1.0.1', 'password') +api = remote.API('127.1.0.1', 'YOUR_PASSWORD') domain = 'switch' remote.call_service(api, domain, 'turn_on') @@ -145,7 +145,7 @@ To turn on or off a single switch. The ID of the entity is needed as attribute. import time import homeassistant.remote as remote -api = remote.API('127.1.0.1', 'password') +api = remote.API('127.1.0.1', 'YOUR_PASSWORD') domain = 'switch' switch_name = 'switch.livingroom_pin_2' @@ -185,7 +185,7 @@ The example uses the jabber notification platform to send a single message to th ```python import homeassistant.remote as remote -api = remote.API('127.1.0.1', 'password') +api = remote.API('127.1.0.1', 'YOUR_PASSWORD') domain = 'notify' data = {"title":"Test", "message":"A simple test message from HA."} diff --git a/source/developers/rest_api.markdown b/source/developers/rest_api.markdown index 4f4020fa032..f8fd4f5429b 100644 --- a/source/developers/rest_api.markdown +++ b/source/developers/rest_api.markdown @@ -39,7 +39,7 @@ print(response.text) ```

-You can append ?api_password=YOUR_PASSWORD to any url to log in automatically. +You can append `?password=YOUR_PASSWORD` to any url to log in automatically.

Successful calls will return status code 200 or 201. Other status codes that can return are: diff --git a/source/developers/server_sent_events.markdown b/source/developers/server_sent_events.markdown index 86dc50952aa..6961d7e0d2a 100644 --- a/source/developers/server_sent_events.markdown +++ b/source/developers/server_sent_events.markdown @@ -18,7 +18,7 @@ A requirement on the client-side is existing support for the [EventSource](https There are various ways to access the stream. One is `curl`: ```bash -$ curl -X GET -H "x-ha-access: 12345" \ +$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ -H "Content-Type: application/json" http://localhost:8123/api/stream ``` @@ -31,7 +31,7 @@ For more comfort put the HTML snippet below in a file `sse.html` in your `www` f

Getting Home Assistant server events