README.md · landaquan/Coffee

# ZClub Coffee
一个基于ESP32使用ESP-IDF架构开发的摩尔斯电码练习器，使用LVGL制作图形界面。可以实现摩尔斯电码的本地练习以及通过网络与其他使用此项目的HAM进行模拟通联。

**目前项目正处于开发测试阶段，不保证所有的功能都能正常使用，仅供有兴趣的朋友抢先体验。**

# 项目计划及进度
- [X] 基础功能
  - [X] 电码录入  
  - [X] 电码解译

- [X] ~~配网~~
  - [X] ~~微信配网~~
  - [X] ~~ESP-TOUCH配网~~

- [ ] 模拟通联
  - [X] WebSocket方式模拟通联  
  - [ ] MQTT方式模拟通联

- [X] 设置
  - [X] 在练习器上进行设置
  - [X] 在Web页面上进行设置

- [ ] 训练
  - [ ] 键入训练
  - [ ] 解码训练
  - [ ] 训练排行榜

- [ ] 网络对讲

- [ ] SDR
  - [ ] 本地SDR
  - [ ] 网络SDR

# 物料清单
**鉴于目前为测试阶段，此物料清单不作为最终版本使用。所列内容可能随时有改变。**
  
|名称|数量|说明|
|:---|:---:|:---|
|ESP32开发板|1||
|杜邦线|若干||
|扬声器|1||
|旋转编码器|1||
|彩色显示屏|1|显示控制芯片ILI9341<br>分辨率240×320<br>触摸控制芯片XPT2046|
|3.5毫米音频母座|1|用于连接电键|
|3.5毫米音频线|1|公对公，用于连接电键。|
|电键|1|手动或自动均可，或者也可以使用开关代替|
|功放||目前项目中并没有使用功放，后续会添加|

# 使用方法

## 接线
```
DISP:	显示屏  
TOUCH:	触摸控制引脚（可以不接，使用旋转编码器可进行所有操作）
KEY:	电键  
ROT:	旋转编码器  
SPK:	扬声器
```

所有模块的GND均接入开发板的GND引脚，下表中不再重复说明。

|设备|ESP32|说明|
|:---|:---:|:---|
|DISP - MOSI|GPIO13|或标为SDI|
|DISP - CLK|GPIO14|或标为SCK|
|DISP - CS|GPIO15||
|DISP - DC|GPIO2||
|DISP - RESET|GPIO4||
|DISP - VCC|VIN||
|DISP - LED|3V3||
|TOUCH - IRQ|GPIO27||
|TOUCH - CS|GPIO5||
|TOUCH - CLK|GPIO18|或标为SCK|
|TOUCH - MOSI|GPIO23|或标为DIN|
|TOUCH - MISO|GPIO19|或标为DO|
|ROT - CLK|GPIO33||
|ROT - DT|GPIO32||
|ROT - SW|GPIO12||
|KEY - A|GPIO34|默认手动键使用该引脚|
|KEY - B|GPIO35||
|SPK|GPIO25|暂时没有使用功放，后续接线方法可能会发生改变|

如需更改引脚，可在在coffee_lib目录下的config.h文件中进行配置。

## 固件上传
固件上传可以使用以下三种方式
- 使用乐鑫的Flash download tool工具上传。（仅限Windows操作系统）
- 使用IDF工具上传。（Windows、Linux及MacOS）
- 使用VSCode插件编译上传。（Windows、Linux及MacOS）

以下分别介绍这三种方式的操作方法。

### 固件下载的方式安装

**此方式目前仅支持Windows操作系统**
  
1. 在[乐鑫工具下载页面](https://www.espressif.com/zh-hans/support/download/other-tools)下载Flash下载工具。
	![](images/WX20220907-193850%402x.png)

2. 根据自己手上的开发板下载对应的USB驱动。目前市面上的ESP32开发板所使用的串口转USB芯片多为CH340或CP2102，确认好自己的开发板的芯片信号下载对应驱动即可。
3. 确定开发板已经被电脑正确识别后，启动乐鑫的Flash下载工具。
	![](images/WX20220907-200227@2x.png)

4. 启动后将`ChipType`选择为`ESP32`，其他内容不变。如下图：

5. 将bin目录中的4个文件分别添加到工具中。记得要将工具中文件名称前面的复选框勾选，并将每个文件对应的地址偏移写到文件名后方。具体填写内容如下表：

|文件名|地址|
	 |:---|:---:|
	 |bootloader.bin|0x1000|
	 |partition-table.bin|0x8000|
	 |ota_data_initial.bin|0xd000|
	 |coffee.bin|0x10000|

6. 选择好正确的端口，点击`START`后等待下载完成即可。完整的设置如下图：

**再次提醒：一定要将文件名称前面的复选框勾选上**

### 使用IDF工具上传
todo

### 使用VSCode插件编译上传

> 使用VSCode中编译使用的是乐鑫的[vscode-esp-idf-extension](https://github.com/espressif/vscode-esp-idf-extension)扩展插件。为什么不用[PlatformIO](https://github.com/platformio)呢？因为PlatformIO所使用依赖库大部分都是放在境外的服务器上，由于不便详细阐述的原因，很多小伙伴没有办法正常安装和使用。但是习惯使用PlatformIO的小伙伴也不用担心，项目源码在PlatfromIO上也可以正常跑通，IDF版本使用4.4.x和5都可以，但是由于IDF 5的特性，使用的时候需要手动添加一些库，例如esp_websocket_client。具体详情请参考乐鑫官方文档关于[从 ESP-IDF 中移出或弃用的组件](https://docs.espressif.com/projects/esp-idf/zh_CN/v5.0-beta1/esp32/migration-guides/release-5.x/removed-components.html)中的内容。

1. 在[Python官网的下载页面](https://www.python.org/downloads/)下载并安装python3。
	
	<img src="images/WX20220908-221826@2x.png" width="300"/>

安装时记得把底部的两个复选框都勾选上

<img src="images/WX20220908-222624@2x.png" width="300">
	
2. 下载保存源码文件，git或下载zip文件的方式均可。
3. 在[官网](https://code.visualstudio.com/)下载VSCode。
	
	<img src="images/1662638698095.jpg" width=300/>
  
4. 在VSCode中的扩展标签里搜索并安装”ESP-IDF“扩展插件。
	
	<img src="images/WX20220908-202024@2x.png" width=300/>

5. 插件下载完成后，点击工具栏的”ESP-IDF“图标，等待一会，初始化完成后会出现ESP-IDF安装配置页面。

6. 出现安装配置页面后选择”ADVANCED“选项。
	
	<img src="images/WX20220908-202536@2x.png" width = "300"/>

7. 进入配置页面后，在”Select download server“中尽量选择乐鑫服务器（Espressif）而不是Github。至于原因...这里不便展开说明，会被屏蔽。

IDF的版本选择4.4.X。如果选项中没有，可以勾选”Show all ESP-IDF tags“，之后就可以列出全部可下载版本。

一切就绪后点击”Install“。

8. 接下来就是耐心等待下载完成
  
	 <img src="images/WX20220908-203938@2x.png" width="300"/>

**温馨提示：如果不出意外的话，这一步骤需要极大的耐心**

9.  接下来是下载"ESP-IDF Tools"， 同样需要耐心等待。
	
	 <img src="images/WX20220908-205808@2x.png" width="300"/>

不过好在以上两个步骤的这个过程只需要一次即可。

1. 打开下载的项目文件夹，连接好ESP32开发板，选择正确的端口，编译并上传。

# 功能介绍

## 进入设置页面
在主页面按下编码器按钮即可进入设置页面。

## Web页面设置
在主页长按编码器按钮即可弹出一个二维码，当练习器与手机连接在同一个WiFi下时，扫描二维码即可进入设置页面。

<!-- ## 网络连接
在任何界面下，长按旋转编码器即可弹出一个二维码，根据提示连接到对应的SSID。默认情况下练习器的SSID为"ZClubCoffeeSettings"，如果使用联网功能，则手机与练习器连接到同一个WIFI即可。

在设置页面中填写要连接的SSID和密码，保存后自动尝试连接到WIFI。

在设置页面中也有其他很多设置选项。 -->

<!-- 前的配网方式使用的是微信配网，后续会调整。下面介绍的是以当前版本所使用的配网方法。
1. 练习器开机，等待到自检到WIFI步骤。
2. 将手机连接到当前WIFI下的2.4G信号，因为ESP32仅能连接2.4G信号，所以连接5G信号会导致无法连接WIFI。
3. 微信关注公众号`安信可科技`。
  
	<img src=images/WechatIMG65.jpeg width=200 />

4. 进入公众号后点击`应用开发` -> `微信配网`。

5. 在下一个页面中点击”开始配网“。

6. 进入下一个页面后输入正确的WIFI密码，等待配网完成即可。

## 传输内容格式约定
目前网络通信部分使用WebSocket方式，后续会添加MQTT方式可供选择。两种方式所传输的数据均使用同一种格式约定。具体约定内容如下：

```发送时间|呼号|发送内容```

其中，`发送时间`的格式为 小时:分钟:秒钟，每个时间使用2位数字表示，例如：`22:45:32`。  
每一部分内容之间使用”|“分割。完整示例如下：

```22:45:32|BG7YXY|-.-. --.-```

传输内容中不可包含电码翻译内容，电码翻译工作在练习器中实现。
如下内容为错误传输内容

```22:45:32|BG7YXY|-.-.C --.-Q```

尽管以上的传输内容可以正常工作，但是不建议这样使用。原因如下：

- 电码是否需要翻译在练习器中设定。练习器不过滤传输内容，会将所接收到的内容原样输出，所以如果将翻译后的电码一同传输会导致设置不翻译电码的用户显示出翻译后的内容。

-  后续功能中还将通过网络传输其他内容，将翻译后的电码一同传输将影响此功能。

## 自建服务器

用户可以自行搭建服务器使用，只需要实现如下功能即可。

1. 电码内容通过文本格式传输，练习器发送的内容不包含发送时间信息，需要由服务器添加。练习器发送的内容示例如下：```BG7YXY|-.-. --.-``` 。服务器需要将接收到的内容前插入时间信息，时间格式符合上一节”传输内容格式约定“中的要求。
1.  将整理好的数据发送到在线的其他用户客户端中。最好能够带有群组功能。后续我会将我的实现源码共享出来供大家参考。

# 特别鸣谢
感谢 **执水无为** 提供关于练习器通联训练的促进机制的创意，稍后会在基础功能稳定后添加进去。

**感谢在此项目中使用到的开源代码的所有贡献者们！世界因为有你们所以如此美好！**

# 更新日志
2023-01-01
* 完成练习器设置页面部分
  
2022-09-20
* 优化设置部分
* 取消微信配网，改为使用ESP的HTTP服务进行设置
* 增加通知对话框

2022-09-06
* 优化按键检查机制
* 优化分区表
* 调整 - 在播放接收到的电码时不可键入电码

2022-09-05
* 考虑到上网条件，将开发环境从PlatformIO更换到了乐鑫的IDF环境，以便下载相关内容的时候避免使用到境外服务器。
* ESP-IDF版本因为更换开发环境的原因，从5.1.1调整到4.4.3

2022-09-04
* 完成电码翻译功能

landaquan/Coffee

简介

发行版

贡献者

近期动态

landaquan/Coffee .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

landaquan/Coffee