Merge branch 'current' into next

This commit is contained in:
Otto Winter 2019-03-11 11:59:39 +01:00
commit 429ddb228f
No known key found for this signature in database
GPG Key ID: DB66C0BE6013F97E
12 changed files with 455 additions and 7 deletions

View File

@ -41,7 +41,7 @@ netlify: netlify-dependencies netlify-api html copy-svg2png
python3 travis.py
webserver: html
cd "$(BUILDDIR)/html" && python3 -m http.server
cd "_build/html" && python3 -m http.server
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).

View File

@ -67,9 +67,9 @@ Configuration variables:
- ``ESP8266_DMA`` (default for ESP8266, only on pin GPIO3)
- ``ESP8266_UART0`` (only on pin GPIO1)
- ``ESP8266_UART1`` (only on pin GPIO3)
- ``ESP8266_UART1`` (only on pin GPIO2)
- ``ESP8266_ASYNC_UART0`` (only on pin GPIO1)
- ``ESP8266_ASYNC_UART1`` (only on pin GPIO3)
- ``ESP8266_ASYNC_UART1`` (only on pin GPIO2)
- ``ESP32_I2S_0``
- ``ESP32_I2S_1`` (default for ESP32)
- ``BIT_BANG`` (can flicker a bit)

View File

@ -45,7 +45,7 @@ Configuration variables:
- **dns2** (*Optional*, IPv4 address): The backup DNS server to use.
- **use_address** (*Optional*, string): Manually override what address to use to connect
to the ESP. Defaults to auto-generated value.
to the ESP. Defaults to auto-generated value. Example, if you have changed your static IP and want to flash OTA to the prior configured IP address.
- **ap** (*Optional*): Enable an access point mode on the node.
- **ssid** (*Required*, string): The name of the access point to create.

Binary file not shown.

After

Width:  |  Height:  |  Size: 41 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 63 KiB

View File

@ -0,0 +1,269 @@
Mirabella Genio Bulbs
=====================
The Mirabella Genio is a tuya based smart bulb sold by Kmart in Australia.
.. figure:: images/mirabella-genio-b22-rgbw.jpg
:align: center
:width: 50.0%
Originally intended to be used with their companion app once flashed using `tuya-convert <https://github.com/ct-Open-Source/tuya-convert>`__ ESPHome generated
firmware can be uploaded allowing you to control the bulbs via Home Assistant.
1. Create the ESPHome Firmware
------------------------------
#. Refer to either :doc:`/guides/getting_started_command_line` or :doc:`/guides/getting_started_hassio` before moving onto the next step.
#. Select a bulb configuration below based on the bulb/s you have and copy all of the text in the code block and paste into your
``name_of_esphome_configuration.yaml`` file.
#. Compile the firmware, again depending on your chosen setup refer to the guides in the first point.
2. Flashing
-----------
2.1 Prerequisites
*****************
#. Before you begin you'll need one of the following linux machines running the latest copy of `Raspbian Stretch Lite
<https://www.raspberrypi.org/downloads/raspbian/>`__
a. Raspberry Pi 2B/B+ with `USB WiFi Dongle <https://www.raspberrypi.org/products/raspberry-pi-usb-wifi-dongle/>`__.
b. Raspberry Pi 3B/B+.
.. note::
As per the `tuya-convert documentation <https://github.com/ct-Open-Source/tuya-convert/blob/master/README.md#requirements>`__:
Any Linux with a Wifi adapter which can act as an Access Point should also work. Please note that we have tested the Raspberry Pi with clean installations
only. If you use your Raspberry Pi for anything else, we recommend using another SD card with a clean installation.
#. A microSD card (minimum 2GB, 8GB+ recommended).
#. Any WiFi device which can connect to the SSID generated by the Raspberry Pi and eventually the flashed tuya device. **This cannot be an iOS / Apple device.
Android devices will work.**
2.2 Installing the OS
*********************
#. It's recommended to read the documentation provided by the Raspberry Pi Foundation on the best way to flash the OS to the microSD card depending on your
platform - `Installing operating system images <https://www.raspberrypi.org/documentation/installation/installing-images/>`__.
#. After you've flashed the microSD card browse to the "boot" partition and add a blank file called "ssh" **(without any extension)** which will enable the
SSH server upon first boot, extended information on this step can be found `here
<https://www.raspberrypi.org/documentation/remote-access/ssh/README.md#3-enable-ssh-on-a-headless-raspberry-pi-add-file-to-sd-card-on-another-machine>`__.
#. Plug the microSD card into the Raspberry Pi, connect network cable and power, the Raspberry Pi will start to boot.
2.3 Connecting to the Pi via SSH
********************************
#. Download and install `Putty <https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html>`__.
#. Open Putty.
#. Enter the IP of Raspberry Pi in the box that says "Host Name", leaving the port set to 22 (default for SSH). A list of recommended ways can be found `here
<https://www.raspberrypi.org/documentation/remote-access/ip-address.md>`__, but the easiest is to download and use `Fing <https://www.fing.com/>`__
(`Android <https://play.google.com/store/apps/details?id=com.overlook.android.fing&hl=en_GB>`__ / `iOS
<https://itunes.apple.com/us/app/fing-network-scanner/id430921107?mt=8>`__).
#. In the "Saved Sessions" input box, name the Raspberry Pi connection and then press "Save".
#. Select your new saved session from the list.
#. Press "Open".
2.4 Configuring the Pi
**********************
#. In the putty window login with the **pi** as the user and **raspberry** for the password.
#. Type ``sudo apt-get update && sudo apt-get dist-upgrade -y`` and wait for the upgrades to install.
#. Type ``sudo apt-get install git`` and wait for it to install.
2.5 Setup and Install tuya-convert
**********************************
#. In the putty window type ``git clone https://github.com/ct-Open-Source/tuya-convert`` press enter and wait while the repository is cloned.
#. Type ``cd tuya-convert`` and press enter.
#. Type ``./install_prereq.sh`` press enter and wait as the script gathers all the required components needed to function.
2.6 Upload ESPHome Firmware using SFTP
**************************************
#. Download `FileZilla <https://filezilla-project.org/download.php?type=client>`__ or `WinSCP <https://winscp.net/eng/index.php>`__ or use your preferred FTP
client.
#. Depending on the program you need to connect to the Pi using the IP address as the hostname and the username and password the same as you used to connect
via SSH and ensure your connection type is set to **SFTP**
#. Browse to ``/root/tuya-convert/files``.
#. Upload your compiled ``firmware.bin`` file to this directory. For command line based installs you can access the file under
``<CONFIG_DIR>/<NODE_NAME>/.pioenvs/<NODE_NAME>/firmware.bin`` alternatively Hass.io users can download the file directly from the web ui.
2.7 Use tuya-convert to install ESPHome Firmware
************************************************
#. Type ``./start_flash.sh``
#. Type ``yes`` to accept the warning.
#. Connect your alternative WiFi device (non iOS / Apple based) to the ``vtrust-flash`` SSID using ``flashmeifyoucan`` as the password. This is the network
being broadcast by the Pi from the tuya flash script.
#. If you haven't already install your bulb and flip the switch. It should automatically enter pairing mode represented by the bulb flashing on and off. If it
doesn't, switch your bulb, on-off-on-off-on as per the instructions `here
<https://img1.wsimg.com/blobby/go/67cdd3b9-3600-4104-b097-603c05201237/downloads/1cq3j1sq1_277630.pdf>`__.
#. Press enter on your putty window to start the flash process and wait. The bulb will stop flashing followed by a large amount of scrolling text, this is the
script backing up the factory shipped firmware.
#. Once the process is complete you can type ``curl http://10.42.42.42/flashURL?url=http://10.42.42.1/files/firmware.bin``
#. The bulb will restart and if everything is working correctly after a few seconds the light should be on.
3. Bulb Configurations
----------------------
Thanks to the `existing work <https://github.com/arendst/Sonoff-tasmota/wiki/Mirabella-Genio-Bulb>`__ by
`@so3n <https://github.com/arendst/Sonoff-tasmota/wiki/Mirabella-Genio-Bulb>`__ which these adaptions created by `@cryptelli
<https://community.home-assistant.io/u/cryptelli>`__ and `@bircoe <https://community.home-assistant.io/u/bircoe>`__ are based on.
3.1 Monochromatic Bulbs
***********************
So the brightness of the bulb can be controlled we use the ``esp8266_pwm`` output component connected to the light component using the id configuration
variable ``output_component1``.
.. code-block:: yaml
esphome:
name: mirabella_genio_cw_1
platform: ESP8266
board: esp01_1m
# Ensure the light turns on by default if the physical switch is actuated.
on_boot:
priority: 100 # Highest priority, ensures light turns on without delay.
then:
- light.turn_on: light
wifi:
ssid: 'WIFI'
password: 'WIFIPASS'
logger:
api:
ota:
light:
- platform: monochromatic
name: "Mirabella Genio Smart Bulb"
id: light
output: output_component1
output:
- platform: esp8266_pwm
id: output_component1
pin: GPIO13
3.2 Cold + Warm White Bulbs
***************************
.. code-block:: yaml
esphome:
name: mirabella_genio_cwww_1
platform: ESP8266
board: esp01_1m
# Ensure the light turns on by default if the physical switch is actuated.
on_boot:
priority: 100 # Highest priority, ensures light turns on without delay.
then:
- light.turn_on: light
wifi:
ssid: 'WIFI'
password: 'WIFIPASS'
logger:
api:
ota:
output:
- platform: esp8266_pwm
id: output_warm_white
pin: GPIO14
- platform: esp8266_pwm
id: output_daylight
pin: GPIO5
light:
- platform: cwww
name: "Mirabella Genio Smart Bulb"
id: light
cold_white: output_daylight
warm_white: output_warm_white
cold_white_color_temperature: 6500 K
warm_white_color_temperature: 2700 K
3.3 RGBW Color Bulbs
********************
.. code-block:: yaml
esphome:
name: rgbw_e27_01
platform: ESP8266
board: esp01_1m
# Ensure the light turns on by default if the physical switch is actuated.
on_boot:
priority: 100 # Highest priority, ensures light turns on without delay.
then:
- light.turn_on: light
wifi:
ssid: 'WIFI'
password: 'WIFIPASS'
logger:
api:
ota:
output:
- platform: esp8266_pwm
id: output_red
pin: GPIO4
- platform: esp8266_pwm
id: output_green
pin: GPIO12
- platform: esp8266_pwm
id: output_blue
pin: GPIO14
- platform: esp8266_pwm
id: output_white
pin: GPIO5
light:
- platform: rgbw
name: "rgbw_e27_01"
id: light
red: output_red
green: output_green
blue: output_blue
white: output_white
4. Adding to Home Assistant
---------------------------
You can now add your bulb to home assistant via the configurations page, look for 'ESPHome' under the Integrations option and click 'Configure'.
.. figure:: images/mirabella-genio-b22-rgbw-homeassistant.jpg
:align: center
:width: 50.0%
See Also
--------
- :doc:`/components/light/index`
- :doc:`/components/light/monochromatic`
- :doc:`/components/light/cwww`
- :doc:`/components/light/rgbw`
- :doc:`/components/output/index`
- :doc:`/components/output/esp8266_pwm`
- :doc:`/guides/automations`
- :ghedit:`Edit`
.. disqus::

View File

@ -327,6 +327,23 @@ Teckin
See :doc:`/components/sensor/hlw8012` for measuring power.
Example config: `teckin.yaml <https://github.com/esphome/esphome-docs/blob/current/devices/teckin.yaml>`__
Teckin SP20 (US)
----------------
.. pintable::
GPIO13, Button,
GPIO2, Blue LED (inverted),
GPIO0, Red LED (inverted),
GPIO4, Relay,
GPIO12, HLW8012 SEL Pin (inverted),
GPIO5, HLW8012 CF Pin,
GPIO14, HLW8012 CF1 Pin,
See :doc:`/components/sensor/hlw8012` for measuring power.
Example config: `teckin_sp20_us.yaml <https://github.com/esphome/esphome-docs/blob/current/devices/teckin_sp20_us.yaml>`__
See Also
--------

View File

@ -0,0 +1,93 @@
# Example ESPHome code to emulate stock firmware functionality while maintaining 100%
# local control through Home Assistant.
substitutions:
device_name: '<NODE_NAME>' # used internally.. e.g. teckin_sp20
friendly_name: '<Node Name>' # displayed in HA.. e.g. Teckin SP20
wifi_ssid: '<WIFI_SSID>'
wifi_password: '<WIFI_PASSWORD>'
esphome:
name: ${device_name}
platform: ESP8266
board: esp01_1m
wifi:
ssid: ${wifi_ssid}
password: ${wifi_password}
# Enable Logs from the device
logger:
# Enable Home Assistant API
api:
# Enable Over-The-Air updates
ota:
sensor:
# Power measuring sensor
- platform: hlw8012
sel_pin:
number: GPIO12
inverted: True
cf_pin: GPIO5
cf1_pin: GPIO14
current:
name: ${friendly_name} Current
power:
name: ${friendly_name} Power
id: power
filters:
# Some calibration
- multiply: 0.4545
voltage:
name: ${friendly_name} Voltage
current_resistor: 0.001 # default 0.001
voltage_divider: 910 # default 2351
change_mode_every: 3 # default 8
update_interval: 3s # default 60s
# Sum power readings over the day
- platform: total_daily_energy
name: ${friendly_name} Total Daily Energy
power_id: power
filters:
- multiply: 0.001 # convert Wh to kWh
unit_of_measurement: kWh
# Enable getting local time for total daily energy calculation
time:
- platform: homeassistant
id: homeassistant_time
status_led:
pin:
number: GPIO0 # Red LED
inverted: True
binary_sensor:
- platform: gpio
pin: GPIO13
id: button
name: ${friendly_name} Button
on_press:
- switch.toggle: relay
internal: True
switch:
- platform: gpio
id: blue_led
pin:
number: GPIO2
inverted: True
- platform: gpio
pin: GPIO4
id: relay
name: ${friendly_name}
# Tie Blue LED to relay
on_turn_on:
- switch.turn_on: blue_led
on_turn_off:
- switch.turn_off: blue_led

View File

@ -320,6 +320,63 @@ Finally, for documentation changes go to your esphome-docs folder, and install s
Or alternatively just submit a draft PR to the docs repo and wait for netlify to create
a build preview.
Setting Up Git Environment
--------------------------
ESPHome's code-base is hosted on GitHub, and contributing is done exclusively through
"Pull Requests" (PRs) in the GitHub interface. So you need to set up your git environment
first.
When you want to create a patch for ESPHome, first go to the repository you want to contribute to
(esphome, esphome-core, etc) and click fork in the top right corner. This will create
a fork of the repository that you can modify and create git branches on.
.. code-block:: bash
# Clone your fork
git clone https://github.com/<YOUR_GITHUB_USERNAME>/<REPO_NAME>.git
# For example: git clone https://github.com/OttoWinter/esphome-core.git
# Add "upstream" remote
git remote add upstream https://github.com/esphome/<REPO_NAME>.git
# For example: git clone https://github.com/esphome/esphome-core.git
# For each patch, create a new branch from latest dev
git checkout dev
git pull upstream dev
git checkout -b <MY_NEW_FEATURE>
# For example: git checkout -b gpio-switch-fix
# Make your modifications, then commit changes with message describing changes
git add .
git commit -m "<COMMIT_MESSAGE>"
# For example: git commit -m "Fix GPIO Switch Not Turning Off Interlocked Switches"
# Upload changes
git push -u origin <BRANCH_NAME>
# For example: git push -u origin gpio-switch-fix
Then go to your repository fork in GitHub and wait for a create pull request message to show
up in the top (alternatively go to branches and create it from there). Fill out the
Pull Request template outlining your changes; if your PR is not ready to merge yet please
mark it as a draft PR in the dropdown of the green "create PR" button.
**Review Process:** ESPHome's code base tries to have a high code standard. At the bottom
of the Pull Request you will be able to see the "Travis" continuous integration check which
will automatically go through your patch and try to spot errors. If the CI check fails,
please see the travis log and fix all errors that appear there. Only PRs that pass the automated
checks can be merged!
**Catching up with reality**: Sometimes other commits have been made to the same files
you edited. Then your changes need to be re-applied on top of the latest changes with
a "rebase". More info `here <https://developers.home-assistant.io/docs/en/development_catching_up.html>`__.
.. code-block:: bash
# Fetch the latest upstream changes and apply them
git fetch upstream dev
git rebase upstream/dev
Contributing to ESPHome-Core
----------------------------

View File

@ -159,8 +159,19 @@ To install the dev version of ESPHome:
- In Hass.io: In the ESPHome add-on repository there's also a second add-on called ``ESPHome Dev``.
Install that and stop the stable version (both can't run at the same time without port collisions).
- From ``pip``: Run ``pip install https://github.com/esphome/esphome/archive/dev.zip``
- From docker: Run ``docker pull esphome/esphome:dev`` and use ``esphome/esphome:dev`` in all
commands.
- From docker, you need to build the docker image yourself (automated dev builds are not possible
due to docker hubs limited build quota)
.. code-block:: bash
git clone https://github.com/esphome/esphome.git
cd esphome
docker build -t esphome-dev -f docker/Dockerfile .
docker run [...] -it esphome-dev livingroom.yaml compile
# Update image and rebuild
git pull
docker build -t esphome-dev -f docker/Dockerfile .
The latest dev docs are here: `next.esphome.io <https://next.esphome.io/>`__
@ -181,7 +192,7 @@ Sure! I'd be happy to help :) You can contact me here:
- ESPHome `issue <https://github.com/esphome/issues>`__ and
`feature request <https://github.com/esphome/feature-requests>`__ issue trackers. Preferably only for issues and
feature requests.
- Alternatively, also under contact (at) esphome.io
- Alternatively, also under contact (at) esphome.io (NO SUPPORT!)
.. _wifi-problems:

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

View File

@ -291,6 +291,7 @@ Cookbook
Sonoff Fishpond Pump, cookbook/sonoff-fishpond-pump, cookbook-sonoff-fishpond-pump.jpg
H801 LED Controller, cookbook/h801, h801.jpg
Time & Temperature on OLED Display, cookbook/display_time_temp_oled, display_time_temp_oled_2.jpg
Mirabella Genio Bulb, cookbook/mirabella-genio-bulb, cookbook-mirabella-genio-b22-rgbw.jpg
Do you have other awesome automations or cool setups? Please feel free to add them to the
documentation for others to copy. See :doc:`Contributing </guides/contributing>`.