From 98692c867348d82fcfbac11036101eae76383263 Mon Sep 17 00:00:00 2001
From: David Ross Smith <5095074+DragRedSim@users.noreply.github.com>
Date: Wed, 13 Mar 2024 17:17:37 +1100
Subject: [PATCH 1/2] Revised HDMI-CEC documentation - Added mapping between
ESP GPIOs and WemosD1 pin numbers - Spelling and grammar corrections - Added
info on requirement for I2C feature - Expanded documentation of command usage
---
docs/HDMI_CEC.md | 41 +++++++++++++++++++++++++----------------
1 file changed, 25 insertions(+), 16 deletions(-)
diff --git a/docs/HDMI_CEC.md b/docs/HDMI_CEC.md
index 6c61685b45..ec9d52293c 100644
--- a/docs/HDMI_CEC.md
+++ b/docs/HDMI_CEC.md
@@ -9,27 +9,36 @@
#define USE_HDMI_CEC
```
+??? tip "This feature relies on I2C support, and may not compile if this is not enabled."
+
+ If you encounter this issue, add the following flag to the build environment or `user_config_override.h`:
+ ```arduino
+ #ifndef USE_I2C
+ #define USE_I2C
+ #endif
+ ```
+
## What is HDMI CEC?
HDMI CEC is a feature of HDMI designed to control HDMI connected devices by using only one remote controller; so, individual CEC enabled devices can command and control each other without user intervention, for up to 15 devices.
-This features enables a simple Tasmota device plugged to any HDMI port of your home equipment, to control the TV and other equipments, with a protocol more standard and robust than Infra-Red.
+This feature enables a simple Tasmota device plugged to any HDMI port of your home equipment, to control the TV and other equipments, with a protocol more standard and robust than Infra-Red.
## Hardware needed
HDMI CEC needs only 3 GPIOs to be connected to an HDMI port. You can use a simple ESP8266 Wemos D1 Mini plugged with Dupont cables to an HDMI pass-through like [these devices from Alix](https://www.aliexpress.com/item/1005004343592426.html)
-The GPIOs from ESP devices are electrically compatible with HDMI specifications, so you can simply connect GPIOs with no additional harware components:
+The GPIOs from ESP devices are electrically compatible with HDMI specifications (running at 3.3V logic levels, and the ESP is able to emulate an open-drain communication line by switching its pin input state), so you can simply connect GPIOs with no additional hardware components:
-Wemos D1 Mini|Configuration|HDMI
+ESP8266|Wemos D1 Mini|Configuration|HDMI
:---|:---|:---
-GPIO 2|HDMI CEC|HDMI Pin 13
GPIO 2 on Wemos D1 Mini is connected to a blue Led which is a visual indicator of CEC traffic
-GPIO 4|I2C SDA|HDMI Pin 16
-GPIO 5|I2C SCL|HDMI Pin 15
-Ground||HDMI Pin 17
-+5V||HDMI Pin 18
If another device is present on the same HDMI port, it provides +5V with enough power for ESP8266. In such case you don't need an external power (tested with AppleTV).
+GPIO 2|D4|HDMI CEC|HDMI Pin 13
On the Wemos D1 Mini (and possibly other dev boards), GPIO2 is connected to a blue LED which can act as a visual indicator of CEC traffic.
+GPIO 4|D2|I2C SDA|HDMI Pin 16
+GPIO 5|D1|I2C SCL|HDMI Pin 15
+Ground|||HDMI Pin 17
++5V|||HDMI Pin 18
If another device is present on the same HDMI port by using a passthrough adapter such as the one linked above, the other device provides +5V with enough power for ESP8266. In such cases, you don't need an external power (tested with AppleTV). However, if you are using the Tasmota device in a standalone capacity (without a further device connected), you may need to supply 5V from the ESP's power source to cause the TV to detect the port as active, and listen to and broadcast commands.
Below is the template:
@@ -75,15 +84,15 @@ In the above example, the first part probes I2C to get EDID data and compute the
Command|Parameters
:---|:---
-HdmiType|: set the CEC device type (0..15 as per CEC specs)
The default value is `4` (Playback Device). Changes require a restart to renegociate a new HDMI logical address.
Possible values are:
`0`: TV
`1`: Recording Device
`2`: Reserved
`3`: Tuner
`4`: Playback Device
`5`: Audio System
-HdmiSend|Send a payload to the TV or to any device
`HdmiSend `: sends the `` payload to the TV
`HdmiSend { ["To": , ] "Data":""}` gives more control about the target.
`` is the logical address of the targer, default is `0` which is the TV
`` is the payload
Examples:
`HdmiSend 8F` or `HdmiSend {"Data":"8F"}` - ask the power status of the TV
`HdmiSend {"To":4,"Data":"8C}` - ask its vendor id to logical address `4`
+HdmiType|: set the CEC device type (0..15 as per CEC specs)
The default value is `4` (Playback Device). Changes require a restart to renegotiate a new HDMI logical address.
Possible values are:
`0`: TV
`1`: Recording Device
`2`: Reserved
`3`: Tuner
`4`: Playback Device
`5`: Audio System
+HdmiSend|Send a payload to the TV or to any device
`HdmiSend `: sends the `` payload to the TV
`HdmiSend { ["To": , ] "Data":""}` gives more control about the target.
`` is the logical address of the target, default is `0` which is the TV.
`` is the payload, being an encoded CEC command. Note that the byte which describes the requesting and target device does not need to be added; it will be calculated from the logical address which Tasmota has claimed.
Examples:
`HdmiSend 8F` or `HdmiSend {"Data":"8F"}` - ask the power status of the TV
`HdmiSend {"To":4,"Data":"8C"}` - ask its vendor id to logical address `4`
## Receiving and parsing payloads
-Currently payloads are passed as HEX data without any encoding/decoding.
+Currently, payloads are passed as HEX data without any encoding/decoding.
-Whenever a message is received on the CEC bus, a payload using the following syntax is triggered and can be matched with a Rule. Only messages addressed to Tasmota are published as payloads in MQTT, all messages not adressed to Tasmota are masked to avoid generating too much traffic. Note: the total traffic can be monitored with loglevel 3.
+Whenever a message is received on the CEC bus, a payload using the following syntax is triggered and can be matched with a Rule. Only messages addressed to Tasmota are published as payloads in MQTT; all messages not adressed to Tasmota are masked to avoid generating too much traffic. Note: the total traffic can be monitored with loglevel 3.
Received payloads generate an Rule event as follows:
```
@@ -96,7 +105,7 @@ Example: command `HdmiSend 8F`
20:07:59.454 RSL: RESULT = {"HdmiSend":"Done"}
20:07:59.632 RSL: SENSOR = {"HdmiReceived":{"From":0,"To":8,"Data":"9001"}}
```
-In the above, Tasmota sends command `8F` (Give Device Power Status) to query the power status of the TV. The response `9001` (Report Power Status) indicates that the TV is in Standby mode.
+In the above, Tasmota sends command `8F` (Give Device Power Status) to query the power status of the TV. The response `9001` (command `90`: Report Power Status) indicates that the TV is in Standby mode (the value of `01`).
### Turning the TV on
@@ -114,7 +123,7 @@ The following commands are for advanced users or specific use-cases:
Command|Parameters
:---|:---
-HdmiSendRaw|``: send a raw payload to the HDMI CEC bus
This gives full control over messages and allows to impersonate another device
`HdmiSendRaw 408F` pretend that device at logical address `4` asks TV for its power status.
-HdmiAddr|: set the default HDMI Physical Address in case it cannot be discovered.
The default value is `0x1000` which is HDMI Port 1 on the TV
This value is only used if the I2C port is not connected or if the discovery failes.
If no argumant, this command returns the current physical adress.
+HdmiSendRaw|``: send a raw payload to the HDMI CEC bus.
This gives full control over messages and allows to impersonate another device. Note that if using this command, unlike `HdmiSend`, the address byte must be included.
`HdmiSendRaw 408F` will issue a command that asks the TV for its power status, and report it to the device at logical address `4` (which may not be the Tasmota device that actually issued the command).
+HdmiAddr|: set the default HDMI Physical Address in case it cannot be discovered.
The default value is `0x1000` which is HDMI Port 1 on the TV
This value is only used if the I2C port is not connected or if the discovery failes.
If no argument is provided, this command returns the current physical adress.
-The [CEC-O-MATIC](https://www.cec-o-matic.com/) tool is handy to decode and encode payloads.
+The [CEC-O-MATIC](https://www.cec-o-matic.com/) tool is handy to decode and encode payloads. Note that it does take into account the addressing byte; you may need to remove it if you are sending commands.
From c371e399050a972ac661b3a99ab016bc0a01019d Mon Sep 17 00:00:00 2001
From: David Ross Smith <5095074+DragRedSim@users.noreply.github.com>
Date: Wed, 13 Mar 2024 17:21:15 +1100
Subject: [PATCH 2/2] Fixed pin mapping table
---
docs/HDMI_CEC.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/HDMI_CEC.md b/docs/HDMI_CEC.md
index ec9d52293c..1d65be3517 100644
--- a/docs/HDMI_CEC.md
+++ b/docs/HDMI_CEC.md
@@ -33,7 +33,7 @@ The GPIOs from ESP devices are electrically compatible with HDMI specifications
ESP8266|Wemos D1 Mini|Configuration|HDMI
-:---|:---|:---
+:---|:---|:---|:---
GPIO 2|D4|HDMI CEC|HDMI Pin 13
On the Wemos D1 Mini (and possibly other dev boards), GPIO2 is connected to a blue LED which can act as a visual indicator of CEC traffic.
GPIO 4|D2|I2C SDA|HDMI Pin 16
GPIO 5|D1|I2C SCL|HDMI Pin 15