Skip to content

Commit

Permalink
Merge branch 'master' into development
Browse files Browse the repository at this point in the history
  • Loading branch information
blakadder authored Sep 7, 2020
2 parents bfff9db + 1db8b85 commit 31ae36b
Show file tree
Hide file tree
Showing 49 changed files with 719 additions and 453 deletions.
4 changes: 1 addition & 3 deletions docs/APDS-9960.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,6 @@ and in MQTT topic (according to TelePeriod):

### Example Rules

***In gesture sensing mode `Tele-APDS9960` is the trigger (APDS9960 will not work)***

Device will be in RGBC mode until something is close to it, then it switches into gesture mode for 60 seconds.
```console
Rule on APDS9960#Proximity=250 do backlog Sensor27 1; RuleTimer1 60 endon on Rules#Timer=1 do Sensor27 0 endon
Expand All @@ -74,7 +72,7 @@ Rule on APDS9960#Ambient<100 do POWER ON endon

Control ON/OFF, brightness and color temperature with gestures
```console
Rule on Tele-APDS9960#Long do power toggle endon on Tele-APDS9960#Up do dimmer + endon on Tele-APDS9960#Down do dimmer - endon on Tele-APDS9960#Left do ct + endon on Tele-APDS9960#Right do ct - endon
Rule on APDS9960#Long=1 do power toggle endon on APDS9960#Up=1 do dimmer + endon on APDS9960#Down=1 do dimmer - endon on APDS9960#Left=1 do ct + endon on APDS9960#Right=1 do ct - endon
```

## Known Issues
Expand Down
2 changes: 1 addition & 1 deletion docs/About.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

![Tasmota logo](_media/logo-blue.png)

Tasmota is an open source firmware for [ESP8266](https://en.wikipedia.org/wiki/ESP8266) based devices created and maintained by [Theo Arendst](https://github.com/arendst).
Tasmota is an open source firmware for [ESP8266](https://en.wikipedia.org/wiki/ESP8266) based devices created and maintained by [Theo Arends](https://github.com/arendst).

Everything began as [Sonoff-MQTT-OTA](https://github.com/arendst/Sonoff-MQTT-OTA) with a [commit](https://github.com/arendst/Sonoff-MQTT-OTA/commit/9d4c0c60dc7ca8c24cf562a932f263d76f664473) on 25th January 2016. by Theo Arendst. Its goal was to provide ESP8266 based [ITEAD Sonoff](https://www.itead.cc/sonoff-wifi-wireless-switch.html) devices with MQTT and 'Over the Air' or OTA firmware.

Expand Down
2 changes: 1 addition & 1 deletion docs/Builds.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ There are many available features programmed into Tasmota. Not all devices need

Many times one just needs to download a pre-compiled binary and perform the necessary run-time configuration. It is not necessary to compile your own binary if these pre-compiled builds meet your needs. These available files provide a simpler approach to get up and going with Tasmota quickly.

The binary files available on [GitHub](https://github.com/arendst/Tasmota/releases) are for the current master release version only. These master release binaries are also available from the [OTA server](http://thehackbox.org/tasmota/release/). However, the latest development branch code binaries are only available from the [development OTA server](http://thehackbox.org/tasmota/).
The binary files available on [GitHub](https://github.com/arendst/Tasmota/releases) are for the current master release version only. These master release binaries are also available from the [OTA server](http://ota.tasmota.com/tasmota/release/). However, the latest development branch code binaries are only available from the [development OTA server](http://ota.tasmota.com/tasmota/).

Features that are not available in any official release build have to be enabled in source code and compiled yourself. Read more about [compiling your own build](Compile-your-build).

Expand Down
39 changes: 33 additions & 6 deletions docs/Buttons-and-Switches.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
!!! info "Buttons and switches: why the difference and how to configure them"
!!! info "Buttons and switches: why the difference and how to configure them"

A typical device usually has at least one button (exception being bulbs and some lights) to control the power state(s). Additional buttons and switches can be [wired](Expanding-Tasmota#connect-switch) to a free GPIO and configured in Module or Template settings.

Expand Down Expand Up @@ -126,17 +126,34 @@ Same as `SwitchMode 2` but when the state of the circuit changes within 0.5s twi
When you change switch states fast (within 0.5s) some extra actions can be triggered using rules. ON/OFFpower state is only changed when there is no second switch change within 0.5s.

**`SwitchMode 11`**
Set switch to pushbutton with dimmer mode
Set switch to pushbutton with dimmer mode incl. double press feature
!!! note
Setoption32 must be smaller than 64, when you use switchmode 11 and 12 !!

Tasmota will send a `TOGGLE` command **(use Switch<x>#state=2 in rules)** when the button is pressed for a short time and then is released.

When pressing the button (closing the circuit) for a long time (set in `SetOption32`), Tasmota will send repeated `INC_DEC` (increment or decrement the dimmer) commands **(use Switch<x>#state=4 in rules)** for as long as the button is pressed.

Two different `CLEAR` commands are available. An immediate `CLEAR` command is send **(use Switch<x>#state=7 in rules)** upon button release (no delay).

Releasing the button also starts an internal timer (time is set in `SetOption32`). When released for the time set in `SetOption32`, Tasmota will send a 'delayed' `CLEAR` command **(use Switch<x>#state=6 in rules)**.

If the button is pressed again before the timeout, Tasmota will send an `INV` command **(use Switch<x>#state=5 in rules)**. The `INV` command is for the controlling software (Home Assistant) to switch between incrementing and decrementing the dimmer.

Tasmota will send a `TOGGLE` command (use Switch<x>#state=2 in rules) when the button is pressed for a short time and is then released. When pressing the button (closing the circuit) for a long time (set in `SetOption32`) Tasmota sends repeated `INC_DEC` (increment or decrement the dimmer) commands (use Switch<x>#state=4 in rules) as long as the button is pressed. Releasing the button starts a internal timer, the time is set in `SetOption32`. When released for the time set in `SetOption32` Tasmota sends a `CLEAR` command (use Switch<x>#state=6 in rules). If the button is pressed again before the timeout Tasmota sends a `INV` command (use Switch<x>#state=5 in rules). The `INV` command is for the controlling software (home assistant) to switch between incrementing and decrementing the dimmer.
If button is pressed twice (within time set in `SetOption32`), Tasmota will send a `DOUBLE` command **(use Switch<x>#state=8 in rules)**. Note that this **doesn't** change behaviour of other switch states. So along with the `DOUBLE` command, `TOGGLE` command will also be fired twice upon a double press.

!!! tip
The dimmer mode can be used in [conjunction with rules](Rules#control-a-dimmer-with-one-switch) to create additional features or to control another Tasmota device.
The dimmer mode can be used to turn a media player on and off and to control the volume of a media player with one switch.
The dimmer mode has several use cases:
- In [conjunction with rules](Rules#control-a-dimmer-with-one-switch) to create additional features or to control another Tasmota device.
- In [conjunction with ControllerX (HA Appdeamon app)](https://xaviml.github.io/controllerx/examples/tasmota-switchmode11) to implement easy toggle and dimming of smart lights, with an 'in wall' hw Tasmota switch.
- Turn a media player on and off and to control the volume of a media player with one switch.


**`SwitchMode 12`**
Set switch to inverted pushbutton with dimmer mode. The same as `Switchmode 11` but with inverted behaviour.
Set switch to inverted pushbutton with dimmer mode incl. double press feature.
Same as `Switchmode 11` but with inverted behaviour.
!!! note
Setoption32 must be smaller than 64, when you use switchmode 11 and 12 !!

**`SwitchMode 13`**
Set switch to "push to on" mode (`1 = ON`, `0 = nothing`)
Expand Down Expand Up @@ -325,6 +342,16 @@ SetOption11 1
```
All of the above is easier accomplished using [Rules](Rules#button-single-press-double-press-and-hold)!

## AC Frequency Detection Switch
Some devices, such as [BlitzWolf BW-SS5](https://templates.blakadder.com/blitzwolf_BW-SS5.html) or [Moes MS-104B](https://templates.blakadder.com/moes-MS-104B.html), use mains frequency detection on their switch inputs. Whenever the connected switch or button is pressed there are 50/60 Hz pulses on the switch input. Inside the switch there's a frequency detection circuit which is connected to a GPIO of the ESP8266 chip which counts those pulses. Prior to Tasmota 8.4 this kind of switching was handled using Counter sensors and scripting which is now simplified.

You can imagine this algorithm as a leaking bucket. Every pulse adds water to the bucket (little more than leaking out in a cycle), but the water is dripping countinously. If the bucket is full, we will treat the switch on. If there's no pulses, the bucket will be empty, and the we will turn off the switch. The size of the bucket is the debouncing time which controls the sensitivity of the algorithm. If the mains frequency is 50 Hz, a whole AC wave is 20 msec long (for 60 Hz it's about 17 msec; 1000 / frequeny if we want the result in milliseconds). The exact frequency is not really important, because we add more water for every pulse.

After you have assigned a Switch<x\> to the GPIO connected to the AC frequency detection circuit use the ['SwitchDebounce'](Commands.md#switchdebounce) command to set the number of pulses required for the switch to be recognized as on or off. For example: `SwitchDebounce 69` will turn the switch on after three pulses and turn it off after three missing ones (3 * 20 msec is 60 and the last digit must be 9 to activate the AC detection). You will probably have to experiment with the values depending on your AC frequency and the devices frequency detection implementation.

Once the feature is enabled you can use this switch as any regular switch!

---

For a practical application of everything mentioned in this article read about this excellent [LEGO nightstand switch project](https://jeff.noxon.cc/2018/11/21/lego-nightstand-light-switch/).

158 changes: 151 additions & 7 deletions docs/CC2530.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,157 @@
# CC2530 Zigbee module
# CC253x Zigbee module

!!! info "The CC2530 is a system-on-chip (SoC) for Zigbee communication"
!!! info "The CC2530 or CC2531 is a system-on-chip (SoC) for Zigbee communication"

Complete setup of a CC2530 module is covered in the [Zigbee article](Zigbee)
Any Texas Instruments CC2530 or CC2531 chip based module can serve as a coordinator if it has [Z-Stack firmware flashed](https://zigbee.blakadder.com/flashing_ccloader.html). See [list of supported modules](https://zigbee.blakadder.com/zigbee2tasmota.html) with their pinouts and flashing instructions since they are different for each device.

## Breakout Boards
List of fully compatible CC2530 boards is [maintained here](https://zigbee.blakadder.com/zigbee2tasmota.html)
!!! info
You cannot use a CC2531 in USB mode! Flash it with CC2530 firmware and it will work in serial mode. You will have to wire it for serial communication using TX and RX pins, USB port cannot be used for communicating with the CC2531 chip.


!!! info
You can potentially use a CC2531 with Tasmota but **not in USB mode!** Flash it with CC2530 firmware and it will work in serial mode. You will have to wire it for serial communication using TX and RX pins, USB port cannot be used for communicating with the CC2531 chip.
## Wi-Fi Adapter
Using an ESP82xx device such as a Wemos D1 Mini or a NodeMCU to [flash the CC2530](https://zigbee.blakadder.com/flashing_ccloader.html) is a lower cost alternative than using a single purpose [CC_DEBUGGER](https://www.aliexpress.com/item/32869263224.html).

In normal operation two free GPIOs are needed for the serial communication with the CC2530.

### Custom PCBs
These PCBs make all the connections required to flash the CC2530 and to run Z2T:

#### SuperHouse.tv
Jon Oxer created a [custom PCB](https://github.com/SuperHouse/Z2T) to connect a Wemos D1 Mini and a CC2530 board (with or without CC2591).

**Complete module**
<img src="https://user-images.githubusercontent.com/49731213/72688606-3c432800-3b09-11ea-9e56-ed24a7c07017.jpg" height="120"> <img src="https://user-images.githubusercontent.com/49731213/72688611-4533f980-3b09-11ea-9c10-9202d1f60f4d.jpg" height="120">

#### H4NC
User _**h4nc**_ created a [custom PCB](https://github.com/h4nc/Zigbee2Tasmota_PCB) to connect a NodeMCU and a CC2530 board.

You can also get a complete Z2T module with case, pre-flashed and ready to configure and deploy.
<img src="https://raw.githubusercontent.com/h4nc/Zigbee2Tasmota_PCB/master/images/Z2T_2.jpeg" height="250"> <img src="https://user-images.githubusercontent.com/34340210/65651832-a7f30980-dfdd-11e9-845d-81c2b99babb9.jpg" height="140">

<!-- <table style="text-align:center; width: 80%;">
<col style="width:30%">
<col style="width:30%">
<col style="width:30%">
<tr>
<th><a href="https://www.aliexpress.com/item/32904763478.html"> CC2530 with PCB antenna, DL-20</a></th>
<th><a href="https://www.aliexpress.com/item/33007098493.html">CC2530 with external antenna</a></th>
<th><a href="https://www.aliexpress.com/item/4000118023903.html">CC2530 with external antenna and CC2591 RF front end</a></th>
</tr>
<tr>
<td>
<img src="https://user-images.githubusercontent.com/34340210/67676080-29301a00-f957-11e9-8799-c819241e0b4c.png" style="width:10em"></img>
</td>
<td>
<img src="https://raw.githubusercontent.com/tasmota/docs/master_media/CC2530%20External%20Antenna.png" style="width:10em"></img>
</td>
<td>
<img src="https://user-images.githubusercontent.com/49731213/64906209-c0ad1680-d6e3-11e9-8703-71ea36c5be72.jpg" style="width:10em"></img>
</td>
</tr>
</table> -->

## Configuration
### Flash Zigbee Adapter
Zigbee2Tasmota requires a TI CC2530 based module flashed with [Z-Stack CC2530 firmware file](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/Z-Stack_Home_1.2/bin/default) from [Koen Kanters](https://github.com/Koenkk).

Due to memory constraints of the CC2530, you can only pair 16 devices to a coordinator ([See details](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator)).

!!! note
There is an alternative firmware allowing for Zigbee routers to create a mesh network and go beyond 16 devices. This is currently not tested nor supported by Zigbee2Tasmota. It may be added later.

Flashing options:

- Flashing with [CCLoader](https://zigbee.blakadder.com/flashing_ccloader.html) and ESP8266 ==(recommended)==
- Flashing with [CCLib](Zigbee-CCLib-Flashing.md) and ESP8266
- Flash with a dedicated [CC Debugger](https://ptvo.info/how-to-select-and-flash-cc2530-144/) and PC

### Flash Tasmota
Once the flashing process completes, you can re-use the ESP82xx and flash Tasmota with Zigbee2Tasmota enabled firmware. Otherwise, you can use any ESP82xx device.

!!! failure "Zigbee feature is not included in precompiled binaries"

To use it you must [compile your build](Compile-your-build). Add the following to `user_config_override.h`:
```arduino
#define USE_ZIGBEE
```
#### Optional
Run the ESP at 160MHz instead of 80MHz which ensures higher reliability in serial communication with CC2530.

In `platformio_override.ini` uncomment line 51:

`board_build.f_cpu = 160000000L`

If you find that your Zigbee2Tasmota operation is unstable, you may have an ESP82xx device that cannot operate reliably at the higher frequency. If you are using hardware serial (see below) and you still have unreliability, try compiling for 80MHz (reverse the options above) and flash the ESP82xx device again to see if operating at a lower frequency improves stability. Running at 80MHz will impact software serial communications so hardware serial is highly recommended if running the ESP82xx at 80MHz.

Flash the newly compiled binary usig the [normal flashing process](Getting-Started.md#flashing).

### Connect CC2530 to Tasmota
If you are using your ESP82xx device to flash the Zigbee adapter as described in tutorials you may want to leave these connections in place in case you ever need to update Zigbee firmware. If not, any of the free GPIOs can be used.

!!! note "It is recommended that hardware serial pins be used (GPIO1/GPIO3 or GPIO13\[Rx]/GPIO15\[Tx])"
Due to ESP82xx GPIO pin constraints, GPIO15 can only be used as serial Tx.

The interface between the ESP82xx Wi-Fi device and the Zigbee module uses high speed serial.

!!! tip
Tasmota also provides serial communications emulation through software (i.e., software serial). This allows any GPIO to be used. TasmotaSerial version 2.4.x (PR [#6377](https://github.com/arendst/Tasmota/pull/6377)) has improved the reliability of software serial making it feasible for use in this application. However, if you have an option to use hardware serial, choose that.

!!! bug "Z2T uses software serial by default to allow for serial logging on GPIO1/GPIO3"
Use `SerialLog 0` to enable **hardware serial on GPIO13\[Rx]/GPIO15\[Tx]**.

Recommended wiring:

ESP<BR>Device|Tasmota|<BR>Zigbee Module
:--:|:--:|:--:
GPIO13|Zigbee RX (166)|CC_TXD<BR>(A.K.A. P0_3)
GPIO15|Zigbee TX (165)|CC_RXD<BR>(A.K.A. P0_2)
3V3 | VCC
GND | GND

### Tasmota Settings
In the **Configuration -> Configure Module** page assign:

- GPIO13 to `Zigbee RX (166)`
- GPIO15 to `Zigbee TX (165)`

<img src="https://user-images.githubusercontent.com/49731213/64920989-ec043400-d7bd-11e9-8f5c-74ece5c4e26c.jpg" width="240">

You can quickly configure Tasmota using a custom template instead.

Use this one for the recommended wiring scheme:

```json
{"NAME":"Zigbee","GPIO":[0,0,0,0,0,0,0,0,0,166,0,165,0],"FLAG":0,"BASE":18}
```


### First Run

When the Tasmota device boots, Zigbee2Tasmota will wait for 15 seconds before initializing the CC2530. This time allows for Wi-Fi and MQTT to connect (hopefully).

First boot:
```
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":1,"Message":"CC2530 booted","RestartReason":"Watchdog","MajorRel":2,"MinorRel":6}}
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":50,"MajorRel":2,"MinorRel":6,"MaintRel":3,"Revision":20190608}}
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":2,"Message":"Reseting configuration"}}
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":3,"Message":"Configured, starting coordinator"}}
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":51,"IEEEAddr":"0x00124B00199DF06F","ShortAddr":"0x0000","DeviceType":7,"DeviceState":9,"NumAssocDevices":0}}
MQT: tele/tasmota/Zigbee_home/RESULT = {"ZbState":{"Status":0,"Message":"Started"}}
ZIG: Zigbee started
ZIG: No zigbee devices data in Flash
```

Zigbee will automatically boot the CC2530 device, configure the device and wait for Zigbee messages.

Normal boot looks like:
```
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":1,"Message":"CC2530 booted","RestartReason":"Watchdog","MajorRel":2,"MinorRel":6}}
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":50,"MajorRel":2,"MinorRel":6,"MaintRel":3,"Revision":20190608}}
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":3,"Message":"Configured, starting coordinator"}}
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":51,"IEEEAddr":"0x00124B00199DF06F","ShortAddr":"0x0000","DeviceType":7,"DeviceState":9,"NumAssocDevices":0}}
MQT: tele/%topic%/RESULT = {"ZbState":{"Status":0,"Message":"Started"}}
ZIG: Zigbee started
ZIG: Zigbee devices data in Flash (516 bytes)
```

!!! info "You can force a factory reset of your CC2530 with `ZigbeeReset 1` and reboot"
Loading

0 comments on commit 31ae36b

Please sign in to comment.