search

mmakaay / esphome-xiaomi_bslamp2

ESPHome integration for the Xiaomi Mijia Bedside Lamp v2.
Other
218 stars 51 forks source link

[FEATURE] Chinese Translation #88

Open Thisisnotgoingpublished opened 2 years ago

Thisisnotgoingpublished commented 2 years ago

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 commented 2 years ago

README.zh.md

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

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

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

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

功能

快速开始指导

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

升级

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

内容一览表

mmakaay commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

doc\flashing.zh.md

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

刷机指导

目录:

警告

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

所需工具

拆灯, 露出印刷线路板

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

移除照明灯具底部的胶垫, 可以看到照明灯具底部的连接灯具主体的 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适配器连接到您的电脑上了。要特别注意 收发(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.

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:

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 commented 2 years ago

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:

afbeelding

"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:

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 commented 2 years ago

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.