[FEATURE] Chinese Translation

[Thisisnotgoingpublished]

Is your feature request related to a problem? Please describe.
I want to translate this project. I find Xiaomi and Yeelight is annoying me. It's been almost a year since i contacted to both Xiaomi and Yeelight. And about one month since i complained to 12315, yet no one want to solve this.

Describe the solution you'd like
Me by offering the translation.

Describe alternatives you've considered
Google Translate

[Thisisnotgoingpublished]

README.zh.md

对小米®米家床头灯 2 进行 ESPHome 兼容支持

[ 变更记录 | 许可协议 | 行为准则 ]

小米®米家床头灯2是一款智能型三色二温(EGBWW) 的 LED 照明灯具，由易来(Yeelight)公司替小米®米家品牌代工。这款灯具可以通过Wi-Fi网络以及该机器前侧的触摸面板来对其进行操控。触摸面板带有电源键、变色键还有一个控制灯光亮度的滑条。

本项目为用户提供客制化后的 ESPHome 组件，使得用户对本照明灯具进行全方位的完全控制，并把本照明灯具加入到您的家居助手(Home Assistant)里成为可能。

功能

• 本照明灯具 与家居助手(Home Assistant)集成十分容易 只需要采用ESPHome加入就可以做到。

• 本照明灯具不再会与米家云(Mijia Cloud)进行通信 采用本固件后，用户可以完全放心，网络传输仅限于使用者的本地网络。这一点也与家居助手(Home Assistant)的理念相吻合，那就是为使用者提供本地家居自动化平台，以个人隐私为重中之重。

• 不用本地局域网控制选项 就能把照明灯具加入到家居助手(Home Assistant)里。这点非常重要，是因为也不知道小米是犯了什么糊涂穷尽了全体成员的智慧拍脑门子决定要移除本机器的本地局域网控制功能，这样极大地破坏了现有的集成环境。

• 夜灯功能支持多重颜色 原固件只支持单一的暖白夜灯颜色。

• 平滑的灯光颜色切换 不像是当前易来(Yeelight)集成版本的那样。Homekit集成的确提供了挺不错的切换，可是在我个人的系统中，在家居助手(Home Assistant)用户界面里缺少色温白光模式。

• 由于本照明灯具的组件是被当做ESPHome组件存在的，用户不需要依照该灯具过去的运行功能来使用 你可以把本照明灯具依照你的偏好添加到你的家居自动化环境里。使用滑条控制您音响系统的音量你喜欢么？长按电源按键把整个屋子变成夜晚模式可以吗？使用滑条的显示面团发酵进度怎么样？好哇，说走就走！ (^U^)

• 所有照亮前面板的LED(电源键、变色键和滑条的10颗LED)可以一对一控制 这意味着你有12颗可以依照你的偏好使用的LED，而不需要依照该灯具过去的运行功能来使用。

• 通过硬件模改以扩展机器功能可能性 存在GPIO 针没有被使用。如果你的人送外号是“修改狂人”，你可以利用这些针来想出你自己的硬件妙用来扩展机器的功能。

快速开始指导

对刷ESPHome到机器中有经验的人可以来看看：

• 确保你使用的是ESPHome 2021.10.0或者更加新的版本。
• 复制example.yaml到<CONFIG_DIR>/<NODE_NAME>.yaml。
• 根据需求自行修改配置文件(详阅 配置指导)。
• 编译firmware.bin文件并下载到被你连接到串行转USB适配器的机器里。
• 拆灯 连接灯具的TX, RX, GND 和 GPIO0 调试接点到串行适配器。请看接点的位置图。
• 给本照明灯具通电，GPIO0要与GND连在一起以启用刷机模式。
• 把firmware.bin刷进机器，例如使用esphome-flasher。

升级

我总想让这个机器不用进行其他修改就可以升级固件。但有些时候，根本不可能完成。如果升级失败，升级的说明在这里。

• 升级到 2021.10.0

内容一览表

• 何苦要用自制固件？
• 安装指导
• 配置指导
• 刷机指导
• 技术详情
• 资助

[mmakaay]

Xiaomi and Yeelight annoying you is not good :-)
I'm not sure what the best way would be to get the translated documentation in the project.
Maybe a doc_cn folder would be an option?

Are you translating all of the project, or mainly the starting page?
The configuration guide might be the one least useful for translation, since that one will get some more changes over time. Both additionals and breaking changes. The rest of the pages might be quite static at this point.

[Thisisnotgoingpublished]

Xiaomi and Yeelight annoying you is not good :-) I'm not sure what the best way would be to get the translated documentation in the project. Maybe a doc_cn folder would be an option?

Are you translating all of the project, or mainly the starting page? The configuration guide might be the one least useful for translation, since that one will get some more changes over time. Both additionals and breaking changes. The rest of the pages might be quite static at this point.

I'll translate the whole project, but it will take time, which I am not have quiet amount of that precious. And I have to do some updates from time to time here and there. I promise that will not use machine to translate it. But I am also unexperienced. So please bear with me till I get it all done.

I will translate in a sequence that I think is proper.
For the time being, I am just gonna leave all my work right here. It's good for the editing mobility and preview.

The Format Being Like:

File path
Content

[Thisisnotgoingpublished]

doc\flashing.zh.md

< 配置指导 | 主页 | 技术详情 >

刷机指导

目录:

• 警告
• 所需材料
• 拆灯, 露出印刷线路板
• 把转接线焊到主板
• 把转接线连接到读者的串行转 USB 适配器 上
• 读者的 USB 适配器 只有一个 GND 针怎么办
• 对现有固件进行备份
• 如何恢复已备份的固件
• 刷入新的 ESPHome 固件
• 刷机故障排除

警告

这里的指导都是我们用心撰写的, 不过我们不能给予读者任何保证。也许在操作途中读者会弄坏读者自己的照明灯具和读者自己的电脑。

所需工具

• 六角扳手 (2mm, 5/64") 或是梅花形 (T8) 螺丝刀
• 焊接烙铁
• 串行转 USB适配器 (例如 FTDI) 可以提供 3.3V 的收发(RX/TX)信号
• 一些转接线
• 可选工具: 透明胶带、热胶枪、放大镜

拆灯, 露出印刷线路板

提示: 读者可以任意点击下方图片以查看完整尺寸图像。

移除照明灯具底部的胶垫, 可以看到照明灯具底部的连接灯具主体的 4 个螺丝孔。

注意并不需要把胶垫全部剥离。只要能看到螺丝孔, 一般就够了。

把胶垫隐藏起来的4个螺丝卸下来。

把照明灯具底部和灯具的其他部分拆开, 露出印刷线路板。可能得稍微用点力才行。一点一点的把底座拉下来, 一直到底部脱落为止。

把转接线焊到灯具主板

应该把转接线连接到调试接触点, 如下图所示。

许多串行转USB适配器有一些 引脚头(Header Pin), 让读者可以把转接线接到设备上(并不需要焊接操作)。于是乎, 使用 杜邦线(Dupont Wire) 可能更加实用一点。把转接线尾部掐折、拨线、上焊锡、把转接线接到灯具主板上。

注意: 到底是使用插入式还是被插式线头这点取决于读者想怎么接在串行适配器上。在本范例中, 作者我本人使用的是插入式转接线, 这样我直接能把转接线插入适配器板上。

焊接转接线到 RX、TX、GND 和 GPIO0 调试接点。要注意不要在 GPIO0 调试接点使用过多焊锡,
因为这么做会使得焊锡错连到旁边的调试接点上, 导致这个灯具永远都处于刷机模式。

注意: 经过测量本灯具的主板上有一个调试接点提供 3.3V 电压 。一定不要企图采用串行适配器的接头连接本调试接点, 妄想借此给主板供电。要时刻确保照明灯具的电是从灯具自己的电源供应来供电的。

一些提示:

• 根据读者眼睛的视力, 可以选用放大镜来进行焊接工作。把放大镜固定在支架上, 不然您很快就会恨不得自己怎么这辈子没当哪吒呢。
• 焊接前, 读者可以选用透明胶布来固定转接线。
• 如果读者想在刷机后保留转接线 (例如, 为了查看串行日志或者为了未来的固件升级), 建议读者最好用热熔胶固定转接线。这样可以防止因移动剧烈造成的转接线断裂。

连接转接线到读者的串行转 USB 适配器

确保读者要连接到照明灯具的适配器的 收发(RX/TX)针 采用的是 3.3V 电压。有些适配器或许会提供 3.3V 与 5V 切换的功能, 一般要么是有开关, 要么就是有跨接器。不要选用只能输出 5V 的适配器。原因是因为, ESP32芯片的工作电压是 3.3V, 我亲测该芯片也是可以接受5V电压的(也刷机成功了), 但是我并不确定该芯片可以忍受 5V 的电压。因此, 没有什么必要, 别做傻事！

转接线必须以以下方式进行连接:

焊接点	串行 USB 适配器名称
GND	GND
TX	RX
RX	TX (3.3V)
GPIO0	GND

为了刷灯, 开机的时候 GPIO0 必须接地。因此要在插入电源线 前 连接这些转接线。如果你在开机 后 才连接这俩转接线，刷机就 不会 成功。

读者的 USB 适配器只有一个 GND 针怎么办

要是读者的USB适配器没有多个 GND 针，那么您就得找其他方式把 GPIO0 连接地线上。有以下选项:

• 采用面包板, 这样你就可以连接 USB适配器的 GND 针 到面包板的一排上, 并且连接 GND 和 GPIO0 照明灯具主板的转接线连在同一排上. 本指导的接下来的部分会教你怎么才能做到。
  可以查看 @mmakaay.

• 在灯具的主板上焊上一个点动按钮 在按下的时候可以连通 GPIO0 和 GND。 然后读者就可以插入电源的时候按住这个按钮。 在开机后, 读者可以松开这个按钮 (串行的控制台也会提示现在已经激活刷机模式)。 这或许不会是绝大数人的最实用的解决方案 (因为只需要这么刷机一次, 今后只要用 OTA: 隔空传输(Over The Air) 升级就可以了), 不过这在作者我反向工程的初期和固件开发的时候提供了我很大的便利。 成功案例: 简易示范 @mmakaay, 示范 @edwinschoonhoven 还有 示范 @mmakaay, 谢谢 Erwin 带给我的灵感。

• 用手握着导线连通 GND 表面 (例如主板上左方的银色接点) 和 GPIO0 调试接点, 同时把电源插入。在开机后, 可以拿开导线。这算是非常难的办法了 (要是哪吒来做就没什么问题), 但是我相信你一定也能行。

• 临时在主板的 GND 和 GPIO0 上焊接一个导线, 使得 GPIO0 永久性接 GND。这没有其他选项来得更灵活, 不过要是读者只需要做初始化备份和固件刷灯, 那么做只这个步骤就足够了。在刷机后拿开导线, 不这么做的话灯具就无法以正常模式启动。详见示范 @erwinschoonhoven.

下列图片的内容, 是第一种的解决办法, 使用面包板的那个办法。

近景:

现在读者可以将串行转USB适配器连接到您的电脑上了。要特别注意 收发(TX/RX) 转接线的两端需要进行**交叉接线** 的常识要则 (主板上写 发送(TX) 的接触点 连接到 适配器写 接收(RX) 的接触点, 主板上写 接收(RX)的接触点 连接到 适配器写 发送(TX) 的接触点)。 打开
ESPhome刷机工具包(esphome-flasher tool) 选择所选用的COM端口以便进行操作。然后点击查看日志("View logs")。

好了, 可以插入灯具的电源供应开机了。

由于 GPIO0 连接到了 GND, 机器理应开机进入的是刷机模式。如果一帆风顺的话, ESPhome刷机(esphome-flasher) 的日志输出应该是这个模样的:

对现有固件进行备份

对现有固件进行备份, 在读者使用 ESPHome 固件的期间有问题的话就有办法刷回官方原版固件。备份可以通过ESP工具包("esptool")制作。安装流程可以在这边找到:

https://github.com/espressif/esptool/blob/master/README.md#installation--dependencies

以下是利用Linux系统备份原始固件的范例。首先, 拔掉灯具的电源供应, 然后开始 ESP工具包(esptool) 读取刷机(read_flash) 命令:

python esptool.py -p /dev/ttyUSB0 read_flash 0x0 0x400000 original-firmware.bin

/dev/ttyUSB0 是在 Linux 系统下的USB适配器的端口。is the port of the USB adaper on Linux. You can find what port is used by the adapter
by running dmesg after plugging in the USB device. On Windows this is often COM1, COM2 or
COM3.

Now plug back in the power supply. The output of esptool should now show that it connects to the
lamp and downloads the firmware from it.

Caution: You will find the WLAN SSID and Password of the last used WiFi network in this file.
Therefore, keep this backup in a safe place.

How to restore the backed up firmware

In case you need to rollback to the lamp's original firmware at some point, here's an example of how
to restore the original firmware from Windows, by fully flashing it back onto the lamp.

First, unplug your lamp's power supply, then start the esptool write_flash command:

python.exe .\esptool.py --chip esp32 --port COM3 --baud 115200 write_flash 0x00 original-firmware.bin

Make sure that GPIO0 is connected to GND and plug in the power supply. The output of esptool
should now show that it connects to the lamp and uploads the firmware to it.

Be patient after the upload reaches 100%. The output is silent while esptool tool is verifying that
the firmware was uploaded correctly.

After the firmware upload completes, unplug the power, disconnect GPIO0 from GND and reconnect the
power supply to boot into the restored firmware.

Flash new ESPHome firmware

Setup an ESPHome Project (see README.md), compile the firmware for the lamp and
download the firmware.bin file to the device to which the serial adapter is connected.

You can flash the lamp using esphome or esptool. I would strongly recommend using the
esphome-flasher tool. This is a very easy to use GUI
utility app for flashing ESPHome devices and for viewing serial console logging.

• In the app, select the COM port of your serial adapter.
• Then select the firmware.bin file to flash onto the lamp.
• Power up the lamp with GPIO0 connected to GND.
• Click the "Flash ESP" button to flash the firmware.

If all went well, the final log output in esphome-flasher looks somewhat like this:

If you want to flash with esptool, you can use the following command.

Note: unless you know exactly what you're doing with esptool here, I recommend to use the
esphome-flasher instead.

python esptool.py --chip esp32  -p /dev/ttyUSB0 --baud 115200 \
    write_flash -z --flash_mode dout --flash_freq 40m --flash_size detect \
    0x1000 bootloader_dout_40m.bin \
    0x8000 partitions.bin \
    0xe000 boot_app0.bin \
    0x10000 firmware.bin

The required .bin files can be found in the following locations:

• bootloader_dout_40m.bin: from arduino-esp32 package in tools/sdk/bin/
• partitions.bin: from <config dir>/<device name>/.pioenvs/<device name>/partitions.bin
• boot_app0.bin: from arduino-esp32 package in tools/partitions/
• firmware.bin: from <config dir>/<device name>/.pioenvs/<device name>/firmware.bin

After flashing, power down the lamp, disconnect GPIO0 from GND and reconnect the power to boot
into the new ESPHome firmware.

The lamp should now be operational using the new firmware.

From here on, it is possible to flash the lamp OTA (over the air, which means that the firmware is
uploaded over WiFi) from ESPHome. Therefore, it is now time to tuck away or remove those soldered
wires.

Because I want to keep them around for future use, I tuck them away, making sure that the connectors
don't touch each other or the board.

The bottom cover can now be put back on. The lamp is ready for use.

Troubleshooting flash

If you have A fatal error occurred: MD5 of file does not match data in flash!, then make sure
you are powering the board using the lamp's own power adapter. We've seen these errors when trying
to power the board using the 3.3V debug pad.

After seeing this error, user @tabacha was able to successfully flash his lamp using the regular
power adapter.

< Configuration guide | Index | Technical details >

[mmakaay]

I thinks it's easier to get it done through pull requests. Copying and pasting from here might end up in errors.
Pull requests might sound difficult, but GitHub has a great feature, especially for editing documentation. You can go to a documentation page and there you can click on:

"edit this file".

After editing, you can do "Propose changes" at the bottom, to send in a pull request, which I can then accept.

I added some files to the project tree, so you can work with those:

• README.chinese.md
• doc.chinese/*

I updated the internal links, so the README.chinese.md links point to the files inside the doc.chinese/ folder and the images are used from the English doc/images/ folder. I already copied over the translated text from README.md to README.chinese.md.

[Thisisnotgoingpublished]

Thanks~
Ok... So what about I can only just edit a partial of one doc for one time. Cannot just pulling requests every single time. That's gonna be like spams. (￣﹏￣；)
Also please check the newly added warning, the GPIO0 pad in the doc is not in the perfect marked status.
Also don't worries about pics, one can always refer the final file url on GitHub.

I just realized that you wont be online for a long time, and if you ever come back, you can just pick the latest pull.