# 安装 poetry
curl -sSL https://install.python-poetry.org | python3 -

# 遇到错误如下，这里省略绝大部分内容，突出错误
...
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:992)
...

解决 poetry 安装问题

之前在执行某些脚本时也遇到过这个原因，比较暴力的解决方式就是不验证，因为我此时的目标是安装 poetry，我简单看了下安装脚本内容，定位到是下载 https://pypi.org/pypi/poetry/json 这个 json 文件时使用了 urllib 库出现的 SSL 问题，比较暴力的方式就是将 ssl 全局关闭验证，改造命令如下：

# 1. 下载脚本
# 2. 脚本内容最前面加上设置验证的 python 代码
# 3. 执行脚本安装 poetry
curl -sSL https://install.python-poetry.org | sed '1s;^;import ssl\nssl._create_default_https_context = ssl._create_unverified_context\n;' | python3 -

🔖 思考

暴力的解决思路就是关闭验证，这里是 python，其它语言或者工具相应的思路关闭 SSL 验证即可！

分析原因

看脚本内容是试图创建一个安全的 HTTPS 连接，但在验证服务器 SSL 证书时失败了。这可能是由多种原因导致的，包括:

1. 服务器的 SSL 证书过期：如果服务器的 SSL 证书已过期，就无法完成验证，会导致这个错误。
2. 证书颁发机构不被信任：如果 SSL 证书是由一个不在你的操作系统信任的证书颁发机构发出的，那么在尝试创建安全连接时就会出现这个错误。
3. 连接的服务器不是证书中列出的服务器：如果你试图连接到的服务器与 SSL 证书中列出的服务器不匹配（例如，证书是为 “www.example.com” 发出的，但你正在尝试连接到 “www.somethingelse.com”），那么就会出现这个错误。
4. 系统时间或日期错误：如果你的系统日期或时间设置错误，可能会导致 SSL 证书验证失败。
5. 中间人攻击：虽然不太可能，但理论上这个错误也可能由网络攻击或劫持引发（如中间人攻击）。

一项项分析。

证书过期

理论上讲，https://pypi.org的证书不太可能过期，但还是看一下吧，🤣

echo | openssl s_client -servername pypi.org -connect pypi.org:443 2>/dev/null | openssl x509 -noout -dates

结果是

notBefore=Apr 29 19:53:38 2023 GMT
notAfter=May 30 19:53:37 2024 GMT

看时间是今年 4 月～明年 5 月，所以不是这个原因。

证书机构不被信任

先查看证书机构：

echo | openssl s_client -servername pypi.org -connect pypi.org:443 2>/dev/null | openssl x509 -noout -issuer

得到结果是：

issuer=C = BE, O = GlobalSign nv-sa, CN = GlobalSign Atlas R3 DV TLS CA 2023 Q2

我使用的是 macOS，所以去钥匙串访问 app 中查找，发现找不到同名的证书：

服务器不一致

使用下面命令查看证书和服务器是否一致：

echo | openssl s_client -servername pypi.org -connect pypi.org:443 2>/dev/null | openssl x509 -noout -subject

得到结果：

subject=CN = pypi.org

这个也没问题。

🐛 补充

我一开始以为是代理的问题，但是开关代理结果都一样不是代理导致的 SSL 验证异常。

写在最后

SSL 验证失败，非必须验证的情况下，可以使用本文提到的关闭验证的方式（比如能保证链接是公开公正的官方网站），毕竟我们的目标是其它的而不是从根本上解决验证问题（目标感很重要），希望本文对您有所帮助！

Pake 介绍

🤱🏻Pake 是一款利用 Rust 轻松构建轻量级多端桌面应用的工具。使用 Pake CLI 工具可以快速构建指定网址 URL 的工具，Github 介绍页面中也展示了多个用 Pake 打包的示例应用，可以说作者相当贴心了！比如：

当然不止如图 4 个，自己去 https://github.com/tw93/Pake 查看吧！

Pake 安装

我这里以 macOS 为例，其它系统自己尝试即可，安装过程也不难，参考Document！

首先保证你已经安装了 node 和 npm 包管理工具，这里推荐使用 nvm 安装 node。node 安装成功后通常 npm 就可以使用，执行以下命令安装 pake-cli：

npm install -g pake-cli

之后启动新的 shell 就能使用 pake 了，可以通过 pake --help 查看帮助信息。

Icon 准备

我按照 macOS 的 App Icon 的设计规范设计了 Claude 图标，如下:

当然 macOS 下需要 icns 格式的图标，推荐使用 Image2Icon 将 PNG 转换导出 icns，将上面 👆 的 png 图片拖入工具，点击导出选择 icns 即可，我导出的 icns 图标如下：

claude.icns.zip

如果是在 macOS 下打包的话，使用我制作的 claude icns 图标即可！

使用 Pake 打包

pake https://claude.ai/chat/ --name claude --transparent --icon claude.icns

我这里没有指定自定义的窗口宽高，只是指定了名称、启用沉浸式标题和指定图标，当然也可以指定其他的参数，参考Pake Document - CLI Usage

打包过程需要下载 Rust 的相关包，网络需要魔法 🪄

打包后的应用如下：

claude.app.zip

应用运行后如下图所示：

总结

🤱🏻Pake 为各类 web 应用的打包提供了极大便利，值得使用和推荐 🚀！如果有什么问题欢迎留言讨论。

We respect your privacy rights and are committed to protecting your privacy. Please read the following carefully to understand our privacy policy.

1. No Data Collection

TimeGo does not collect any personal information, device information, or other identifiable information about you. The app operates independently on your device and does not send your data to us or any third parties.

2. User-Generated Content and Data

Data and content generated by you while using TimeGo are stored only on your device. We do not access, collect, store, or otherwise process your data. Any app-related settings and data remain within your device unless you voluntarily sync or share with other services.

3. Sharing with Third Parties

As we do not collect any of your data, we do not share your data with any third parties.

4. Legal Requirements

We comply with applicable laws and regulations. If a legal requirement requires us to disclose your information, we will do so in accordance with the legal requirement.

5. Contact Us

If you have any questions, comments, or suggestions about this Privacy Policy, please contact us through the following means:

Email: 5km@smslit.cn or okooo5km@gmail.com

6. Changes to the Privacy Policy

We may update this Privacy Policy from time to time to reflect your feedback and changes to our services. When we change this policy, we will update the policy effective date on this page. If the changes have a significant impact on your rights, we will notify you in a more prominent way (e.g., through a prominent notice or email notification). Therefore, please check this policy regularly to learn how we handle your information.

隐私政策（中文版）

本隐私政策旨在帮助您了解我们如何处理与您相关的信息，当您使用我们的应用 时光(TimeGo) 时。

我们充分尊重您的隐私权益，并对您的隐私承担义务。请仔细阅读以下内容以了解我们的隐私政策。

1. 未收集数据

时光(TimeGo) 并未收集您的任何个人信息、设备信息或其他可识别您身份的信息。应用在您的设备上独立运行，不会向我们或任何第三方发送您的数据。

2. 用户生成的内容和数据

您在使用 时光(TimeGo) 时生成的数据和内容仅存储在您的设备上。我们不会访问、收集、存储或以其他方式处理您的数据。任何与应用相关的设置和数据都将保持在您的设备内，除非您主动与其他服务同步或共享。

3. 与第三方分享

由于我们不收集您的任何数据，我们也不会与任何第三方共享您的数据。

4. 法定规定

我们会遵守适用的法律、法规，如果法定规定需要我们披露您的信息，我们将按照法定要求进行披露。

5. 联系我们

如果您对本隐私政策有任何疑问、意见或建议，请通过以下方式联系我们：

电子邮箱：5km@smslit.cn 或 okooo5km@gmail.com

6. 隐私政策修改

我们可能会不时更新此隐私政策以反映您的反馈以及我们的服务的变化。在我们更改此政策时，我们会更新此页面上的政策生效日期。如果更改对您的权利产生重大影响，我们将用更明显的方式（例如通过突出提示或发送电子邮件通知）告知您。因此，请定期查看本政策以了解我们如何处理您的信息。

ChatGPT是一个人工智能聊天机器人（非常强大的工具），由OpenAI开发并于2022年11月发布。它基于OpenAI的GPT-3系列大型语言模型，并使用监督学习和强化学习技术进行了微调。它可以与用户进行自然的文本对话，回答后续问题，承认错误，挑战错误的前提，拒绝不恰当的请求，可回答的问题几乎涉及全知识领域。可以通过合理的 Prompt 限定他的角色从而将它转变为特定领域的工具。

chatGPT是什么

可以观看下面的视频详细了解一下这个比较颠覆性的工具：

【渐构】万字科普GPT-4为什么会颠覆人类社会

使用哔哔终结者 BibiGPT (这个工具就是基于 chatGPT)生成上面视频的大纲：

本视频科普了ChatGPT-4技术的原理、制造过程、能力及未来影响，并探讨了如何维持未来竞争力。

• 🤖 ChatGPT-4是一种生成语言模型，通过单字接龙回答问题。
• 🧠 它具有自回归生成的能力，只需提供上文就能生成下一个字。
• 📚 训练ChatGPT-4的方法是让它遵照所给的学习材料，调整其通用模型。
• 💡 ChatGPT-4的目的不是记忆，而是学习提问和回答的通用规律（泛化）。
• 🚀 ChatGPT-4的生成模型可以创造不存在的文本，在自然语言处理领域有巨大潜力。

使用 chatGPT

方式一：使用官方原版

OpenAI 并没有开放给中国国内账户，要使用官方版本的 chatGPT 需要魔法，注册账号也比较繁琐，目前 OpenAI 只接受 Gmail 用户的注册，而且在注册的最后一步需要国外的电话进行验证码验证，具体步骤参考下面两个链接（需要科学的上网🤦）

• 2023如何成功解决国内邮箱注册ChatGPT显示注册不可用请重试的问题
• https://share.weiyun.com/5VAf4rF0

使用原版账号的好处就是:

1. 注册账号后可以使用 API，而且默认会有 5 美元的免费额度，目前基于 chatGPT API 的应用如雨后春笋般疯狂增多，后面后列举一些。
2. 可以申请试用 GPT-4 的 API 试用，chatGPT 的 Plus 用户可以直接使用 GPT4 模型版本的，但一定问答次数限制。

方式二：国内可使用的镜像

1. 「⭐⭐⭐」BAI Chatopen in new window：站长投入很多资金来运营，超级稳
2. 「⭐⭐」yqcloudopen in new window：速度还可以，稳定
3. 「⭐⭐」tdchatopen in new window：反应快，但输出长度受限
4. 「⭐⭐」forchangeopen in new window：官方皮肤，目前无限制。
5. 「⭐⭐」GeekChatopen in new window：支持语音和文字进行交互
6. 「⭐⭐」jingranopen in new window：稍微有些慢
7. 「⭐⭐」GeekChatopen in new window：支持语音和文字进行交互
8. 「⭐⭐」trychatgpopen in new window：目前无限制，速度还可以
9. 「⭐⭐」fastgptopen in new window：用的是 ChatGPT 网站的皮肤，反应很迅速【每天5次】
10. 「⭐⭐」Chat Chat：每天有一定额度。

方式三：应用

AI0x0

https://github.com/mushan0x0/AI0x0.com

超强 AI 聚合工具。

使用微软的 New Bing

这个工具也只对美国开放，而且需要申请试用，目前有最新的方式如下视频：

New Bing无需魔法最新办法

视频总结-哔哔终结者 BibiGPT

https://b.jimmylv.cn/?ref=opengpt

OpenGPT

https://open-gpt.app/

可以为 chatGPT 创建不同的应用，其实就是通过一定指令限定 chatGPT 的角色，每天有一定的限制次数。

Notion AI

https://www.notion.so/product/ai

[点击我看介绍视频](https://pichome-1254392422.cos.ap-chengdu.myqcloud.com/uPic/Notion AI - - 2023-03-17 15-33-01-20230317-153337.mp4)

AI Translator

https://github.com/yetone/openai-translator

需要有自己的账号并且生成 API-KEY，软件会调用 OpenAI 的 API（收费），需要魔法上网

Poe

https://poe.com/

需要魔法上网

OpenCat

支持 Apple 全平台：iOS、macOS、iPadOS，自行在商店搜索安装。

需要有自己的账号并且生成 API-KEY，软件会调用 OpenAI 的 API（收费），需要魔法上网

chatchat

https://chat.okis.dev/?mode=chat

使用 AI 解锁下一代对话体验，支持上传 PDF 解读分析问答、支持代码提问转换，也支持对话式聊天。每日都会有免 API 使用的额度，可以直接使用。后续会一直维护和开发新功能。而且永远不会收费。

warp

https://www.warp.dev/

号称 21 世纪的终端工具，Warp是一款由Cloudflare开发的终端工具，它可以改善你的网络连接速度并保护你的隐私。这一工具通过在本地端和云端建立加密通信隧道来提高联网速度和加密用户的连接。它的主要特点有：

• 高速： Warp可以通过 Cloudflare 的网络优化算法消除网络瓶颈，从而加速网络连接速度。此外，他们还提供了全球服务器设置，以提供更快的分布式网络。
• 加密隐私： Warp使用了现代密码学技术来加密用户的网络连接，从而在可能的情况下防止拦截和监视。此外，它不会存储数据，这也保障了用户的隐私。
• 易于使用：Warp的设置非常简单，只需下载安装程序并创建一个账户即可使用。它还提供了简单、安全的链接管理，使用户可以轻松地控制其网络特性。
• 强大的扩展性：通过 Cloudflare 的网络和代理技术，Warp可以随着您的需求和使用需求的增长而不断扩展。

总之，Warp是一款提供快速、可靠、加密的网络专用工具，适用范围广泛。

cursor

https://www.cursor.so/

一款可以使用 GPT-4 编写代码的代码编辑器。

Cubox

https://cubox.pro/

在信息碎片中重获专注，一站式信息收集、阅读、管理和回顾，善用网络碎片构建个人知识库。

阅读Cubox AI 阅读助手了解更多内容。

AI Color

https://aicolors.co/

设计师会用到的一块 AI 色卡工具。

深度导航

https://www.deepdh.com/ai

有人整理的各类 AI 工具，供参考！

类似的工具有很多，这里就不一一列举了。

注：不知道上图是谁整理的，感谢他的分享。

要用好工具，Prompt 很关键，可以从ChatGPT 提示语 找灵感！

方式四：调用第三方 API

1. steamship

https://www.steamship.com/

GPT-4免费用，无需官方账号，SteamShip 已开放 GPT-4 的模型接口，只需要注册SteamShip 账号，无需付费几行代码直接就能调用 GPT-4。

最新动态

GitHub Copilot X

微软最近的动作除了 AI 就是 AI，这不 2023年03月21日晚，guthub 推出的 Copilot 智能代码助手直接融合 chatGPT 发布了个 GitHub Copilot X，可惜我没用过 Copilot，据说很厉害！

Nvidia GTC 2023

Nvidia GTC 2023，就在 2023年03月21日晚11点老黄正式开启 GTC 大会，在 keynote 中发布了 Nemo、Picasso和Bionemo，以及一众硬件，其中 DGX AI 超级计算机交付给了 OpenAI 可以为 chatGPT 进行超强加速。

1. NeMo

   NeMo是一个用于对话式人工智能的工具包，由NVIDIA开发1。它主要为从事自动语音识别（ASR）、文本到语音合成（TTS）、大型语言模型（LLMs）和自然语言处理（NLP）的研究人员而设计1。NeMo的主要目标是帮助研究人员重用之前的工作（代码和预训练模型），并快速构建新的应用。NeMo最新的版本是1.13.0，于2022年12月16日发布。NeMo还有一个文本处理模块，用于ASR和TTS的数据预处理和后处理。

2. Picasso

   Picasso是NVIDIA在GTC 2023发布的一个新的基于云的平台，用于在创意应用中从文本生成 AI 支持的视觉内容，用于构建和部署生成AI工具。

3. Bionemo

   BioNeMo 是一款基于 NVIDIA NeMo Megatron 构建的 AI 赋能药物研发云服务和框架，用于在超级计算规模下训练和部署大型生物分子 Transformer AI 模型。服务包括预训练 LLM、对蛋白质、DNA、RNA 和化学的通用文件格式的原生支持，还提供可供 SMILES（用于分子结构）和 FASTA（用于氨基酸和核苷酸序列）使用的数据加载器。BioNeMo 框架也可供下载，以便您可以在自己的基础架构上运行。

Microsoft Image Creator

https://www.bing.com/create

微软杀疯了，2023年3月21日又发布了生成图片的预览版应用 Image Creator！

谷歌 Bard

https://bard.google.com/

2023年03月21日，今天 google Bard 开放申请。一起排个队吧！

Microsoft 365 Copilot

点我看发布会

[点我看宣传片](【Microsoft 365 Copilot 简介——一种全新的工作方式】https://www.bilibili.com/video/BV1aM411W7Yb?vd_source=fbe8ecd1547e7e909fd660f4a2b27cef)

3月17日凌晨，微软发布集成 GPT4 的 Microsoft 365 Copilot，将无缝集成在用户每天使用的应用当中，帮助保持工作的流畅性，从繁琐事务作中解放出来，从而专注于手头工作。

• Copilot in Word能够在人们工作时与他们一起撰写、编辑、总结和创作。
• Copilot in PowerPoint能够在创作过程中，通过自然语言命令将想法转化为设计好的演示文稿。
• Copilot in Excel 能够帮助用户释放洞察、识别趋势，或在短时间内创建专业型式的数据可视化。
• Copilot in Outlook能够帮助用户整合并管理收件箱，从而节约出更多时间用于实际沟通。
• Copilot in Teams能够直接从对话上下文中提供实时摘要和待办事项，提高会议效率。
• Copilot in Power Platform通过在Power Apps和Power Virtual Agents中引入两项新功能，能够让各种技能水平的开发人员利用低代码工具加速和简化开发。
• Business Chat汇集了来自文档、演示文稿、电子邮件、日历、笔记和联系人的数据，能够帮助用户总结聊天内容、撰写电子邮件、查找关键日期，甚至根据其他项目文件制定计划。

百度文心一言

3月16日下午两点发布，未公开试用，只是小范围试用。

文心一言发布会

• 文学创作
• 数理逻辑
• 中文理解
• 商业文案创作
• 多模态生成

看评测对比 chatGPT(GPT-3.5)/GPT4 ，也没有想象中拉胯，也有做的更好的点，但还是跟 GPT 有差距。

文心一言已经开放接口试用申请：文心一言云服务邀您测试

GPT4 横空出世

3月15日凌晨，OpenAI 发布 GPT4 模型，正式买入多模态阶段，可以理解图片，同时综合能力吊打 GPT3.5（chatGPT 使用的模型）

发布会视频

GPT-4 简短版总结

• GPT-4是一个大型多模态模型（Large Multimodal Model），能够接受图像和文本输入，并输出文本。
• 实验表明，GPT-4 在各种专业和学术考试中表现出了与人类水平相当的性能（human-level performance）。例如，它通过了模拟律师考试，且分数在应试者的前 10% 左右；相比之下，GPT-3.5 的得分在倒数 10% 左右。
• GPT-4的训练稳定性是史无前例的，这得益于对抗性测试计划和来自于ChatGPT的经验教训，对 GPT-4 进行迭代调整，从而在真实性、可控性等方面取得了有史以来最好的结果。
• 在过去的两年里，OpenAI重建了整个深度学习堆栈，并与Azure共同设计了一台超级计算机以便于应付他们的工作负载。 将继续专注于可靠的扩展，进一步完善方法，以帮助其实现更强大的提前预测性能和规划未来的能力，这对安全至关重要。
• OpenAI首先发布了GPT-4的文本输入功能，图像输入功能敬请期待。
• OpenAI还开源了OpenAI Evals，这是他们的自动化评估AI模型性能的框架，任何人都可以提交他们模型的缺陷以帮助改进。
• OpenAI 正在通过 ChatGPT 和 API（有候补名单）发布 GPT-4 的文本输入功能。图像输入功能方面，为了获得更广泛的可用性，OpenAI 正在与其他公司展开合作。
• OpenAI 还在为机器学习模型设计的传统基准上评估了 GPT-4。GPT-4 大大优于现有的大型语言模型，以及大多数 SOTA 模型

商汤书生v2.5

2023年3月14日，商汤科技发布多模态多任务通用大模型“书生（INTERN）2.5”。

https://mp.weixin.qq.com/s/3pu6uwRmSx1sleUBmreTmQ

大模型

1. 百度文心

https://wenxin.baidu.com/

2. 商汤 OPENGVLab

https://opengvlab.shlab.org.cn/home

3. 清华 ChatGLM

单卡可部署。

https://github.com/THUDM/ChatGLM-6B

4. OpenChatKit

https://github.com/togethercomputer/OpenChatKit

5. Stanford Alpaca

https://github.com/tatsu-lab/stanford_alpaca

6. Alpaca-Lora (羊驼-Lora)

https://github.com/tloen/alpaca-lora

轻量级 ChatGPT 的开源实现, 它使用 Lora (Low-rank Adaptation) 技术在 Meta 的 LLaMA 7B 模型上微调，只需要训练很小一部分参数就可以获得媲美 Standford Alpaca 模型的效果。

7. Belle

https://github.com/LianjiaTech/BELLE

弥补斯坦福70亿参数「羊驼」短板，精通中文的大模型。

8. GPT4ALL

GPT4ALL

Demo, data and code to train an assistant-style large language model with ~800k GPT-3.5-Turbo Generations based on LLaMa。

持续更新中…

主要会用到：

• Rosetta
• Homebrew

前言

你能找到这篇文章，想必你是了解现在 macOS 平台下应用（比如 APP）的分类：

• Universal（通用）
• Apple Silicon（Apple 芯片）
• Intel

以 App 为例，我们可以找到一个 app，看一下它的信息就能知道这个 app 是哪种分类：

Safari 就是通用的，钉钉是Apple 芯片的，图压是Intel的，其实 Intel 就是 x86_64 架构的。

尽管我们在 Apple Silicon 的平台（比如我使用的是 M1 Pro 的 MBP）使用默认方式安装的 homebrew 是无法正常安装 x86_64 架构的应用，但我们又想通过 homebrew 的方式安装，下面就开始搞起！

安装 Rosetta 2

一行命令搞定：

/usr/sbin/softwareupdate --install-rosetta

为 universal 或者 Apple Silicon 应用安装 Homebrew

按照官方的方式安装即可，比如：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

通常使用这个会安装到 /opt/homebrew/bin/brew。

使用 homebrew：

brew install xxx
brew list

为 Intel 应用安装 homebrew

这是本文重点，通常在 Intel 的 macOS 下，brew 会安装到 /usr/local/homebrew 下，我们手动安装一下：

# 下载 homebrew
cd ~/Downloads
mkdir homebrew
curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew

# 移动到目标位置
sudo mv ~/Downloads/homebrew /usr/local/homebrew

修改 shell 配置文件，bash 就修改 ~/.bashrc，zsh 的话就修改 ~/.zshrc，在最后添加以下内容：

# 修改 PATH 变量
# for intel x86_64 brew
export PATH=$HOME/bin:/usr/local/bin:$PATH
# 建立别名
alias xbrew='arch -x86_64 /usr/local/homebrew/bin/brew'

重新开启新的终端，就可以使用 xbrew 安装 x86_64 的软件或库了。

使用 homebrew：

xbrew install xxx
xbrew list

环境

• 硬件：14寸 M1 Pro 版 Macbook Pro 2021 款；
• 系统：macOS 12.3.1
• 终端工具：iterm2
• 包管理工具：brew

准备工具

1. 使用 brew 安装 neovim

   brew install neovim
   

2. 使用 brew 安装 ripgrep

   brew install ripgrep
   

安装 Nvchar

执行以下命令安装：

git clone https://github.com/NvChad/NvChad ~/.config/nvim --depth 1
nvim +'hi NormalFloat guibg=#1e222a' +PackerSync

配置 Nvchad

后续配置文件操作均以 ~/.config/nvim作为基础目录，即执行终端命令的 PWD 均为此目录。

创建自定义文件

# 创建自定义文件目录
mkdir lua/custom
# 复制示例初始化文件
cp examples/init.lua lua/custom/init.lua
# 复制示例配置文件
cp examples/chadrc.lua lua/custom/chadrc.lua

安装代码高亮支持

Nvchad 套件安装了 TreeSitter 插件以支持更丰富的代码高亮特性，所以我们可以根据自己的需求安装所需语言的高亮支持，支持语言列表可以去插件网址查，打开 neovim，执行命令

:TSInstall css html http javascript vue vim json latex llvm make markdown python toml yaml c cpp swift lua dockerfile go gomod bash cmake 

设置主题

最近用的比较多的颜色主题是 Gruvbox，Nvchad也支持，打开 neovim 使用快捷键调出颜色主题选择框，快捷键为<leader>+th，选择 gruvbox 敲回车键，按下Esc推出主题设置窗口，颜色主题立即生效。

Tips：这里需要注意的是，设置主题的前提是已创建自定义的文件！

配置快捷键

在 lua/init.lua 中配置快捷键，替换文件内容为如下：

-- example file i.e lua/custom/init.lua

-- MAPPINGS
local map = require("core.utils").map

map("n", "<leader>cc", ":Telescope <CR>")

map("n", "<leader>q", ":q <CR>")
map("i", "<leader>q", "<ESC> :q <CR>")
map("n", "<leader>w", ":w <CR>")
map("i", "<leader>w", "<ESC> :w <CR>")
map("n", "<leader>qq", ":x <CR>")
map("i", "<leader>qq", "<ESC> :x <CR>")

-- require("my autocmds file") or just declare them here

这里添加了我常用的快捷键用于保存文件和退出文件。

开启 Dashboard

新增目录lua/custom/plugins，并添加文件lua/custom/plugins/init.lua：

mkdir lua/custom/plugins
touch lua/custom/plugins/init.lua

文件内容添加如下：

return {
	["goolord/alpha-nvim"] = {
    disable = false,
  }
}

lua/custom/chadrc.lua内容添加如下：

local userPlugins = require "custom.plugins"

M.plugins = {
   user = userPlugins
}

配置开启 Dashboard，保存后，nvim中执行命令:PackerSync，会同步插件安装goolord/alpha-nvim，重新打开 nvim 就会显示 dashboard。

配置 LSP

LSP（Language Server Protocl）用于提供代码编写的很多智能特性，需要配置一下。

安装 williamboman/nvim-lsp-installer

编辑文件 lua/custom/plugins/init.lua 添加内容后整体如下：

return {
  ["goolord/alpha-nvim"] = {
     disable = false,
  },
  ["williamboman/nvim-lsp-installer"] = {
  }
}

nvim 中执行命令 :PackerSync，会自动安装插件 williamboman/nvim-lsp-installer。

添加配置文件 lspconfig.lua

在 lua/custom/plugins 中添加文件 lua/custom/plugins/lspconfig.lua，文件内容如下：

-- custom.plugins.lspconfig 

local M = {}

M.setup_lsp = function(attach, capabilities)
   local lsp_installer = require "nvim-lsp-installer"

   lsp_installer.settings {
      ui = {
         icons = {
            server_installed = "﫟" ,
            server_pending = "",
            server_uninstalled = "✗",
         },
      },
   }

   lsp_installer.on_server_ready(function(server)
      local opts = {
         on_attach = attach,
         capabilities = capabilities,
         settings = {},
      }

      server:setup(opts)
      vim.cmd [[ do User LspAttachBuffers ]]
   end)
end

return M

在 lua/custom/chadrc.lua 中指定 lspconfig 的配置文件为上述文件：

M.plugins = {
  user = userPlugins,
  options = {
    lspconfig = {
      setup_lspconf = "custom.plugins.lspconfig"
    }
  }
}

安装各种语言 LS

打开 nvim，执行命令:LspInstallInfo，就会打开一个安装配置窗口，按上下方向键选择对应语言的 LS，选择后按 i键即可添加支持。

常规配置

需要将 vim 中常规配置使用 lua 配置到 neovim。

lua/custom/chadrc.lua中添加以下内容：

M.options = {
   user = function ()
      vim.opt.number = true
      vim.opt.relativenumber = true
      vim.opt.encoding = "utf-8"
      vim.opt.fileencodings = "utf-8,ucs-bom,gb18030,gbk,gb2312,cp936"
      vim.opt.autoindent = true
      vim.opt.shiftwidth = 4
      vim.opt.tabstop = 4
      vim.opt.softtabstop = 4
      vim.opt.cursorline = true
      vim.opt.mouse = "a"

      -- File extension specific tabbing
      vim.cmd [[ autocmd Filetype sql,yaml,yml,toml,javascript,html,jinja.html,css,markdown,md,xml,vue,vue.html.javascript.css setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2 ]]
      vim.cmd [[ autocmd Filetype lua setlocal expandtab tabstop=3 shiftwidth=3 softtabstop=3 ]]
   end
}

保存重启 neovim 即刻生效。

配置格式化和语法提示

安装插件 null-ls

lua/custom/plugins/init.lua中添加null-ls相关内容，如下：

 ["jose-elias-alvarez/null-ls.nvim"] = {
      after = "nvim-lspconfig",
      config = function()
         require("custom.plugins.null-ls").setup()
      end,
 }

-- load it after nvim-lspconfig cuz we lazy loaded lspconfig

添加文件lua/custom/plugins/null-ls.lua，内容如下：

local null_ls = require "null-ls"
local b = null_ls.builtins

local sources = {

   b.formatting.prettierd.with { filetypes = { "html", "markdown", "css" } },
   b.formatting.deno_fmt,

   -- Lua
   b.formatting.stylua,
   b.diagnostics.luacheck.with { extra_args = { "--global vim" } },

   -- Shell
   b.formatting.shfmt,
   b.diagnostics.shellcheck.with { diagnostics_format = "#{m} [#{c}]" },
}

local M = {}

M.setup = function()
   null_ls.setup {
      debug = true,
      sources = sources,

      -- format on save
      on_attach = function(client)
         if client.resolved_capabilities.document_formatting then
            vim.cmd "autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_sync()"
         end
      end,
   }
end

return M

保存两个文件后，执行 :PackerSync，会安装 null-ls，重新打开后就可以格式化代码了，保存的时候会自动进行格式化。

至此，Neovim 的 Nvchad 基本可用，目前还存在一个小问题就是 lua 的语法分析的配置项需要完善，还需要屏蔽掉配置文件中显示 vim 未定义的问题，等后面有时间会补充上。

我和水木都完成了第一次 30 天挑战，但我中途给水木发过 30 元红包了，不过最终还好，终究还是完成了，期间因为机缘巧合慢慢变成了使用 figma 绘制插画，最终 30 天的成果如下：

从完成到今天中间发生了很多事情，耽搁了博客中发文记录，很好，成为“鸽王”真是指日可待！年底了，还是挺忙的，不过这周好了很多，能有自己的时间了。那么问题来了，第二个 30 天挑战什么时候开始呢？我还没想好，目前来看精力不够，最近两天得多睡觉好好休息，不然亚健康要亚到底了。。。

因为之前一直有看油管上有一位韩国的机械键盘 DIY 大神——:3ildcat——的视频，在他视频中经常出现 XDA 球帽，非常 NICE，所以这次我决定就入手 XDA 键帽，挑来挑去选中了一款叫微光的复古键帽。

上面图中展示的是一整套的键帽，再看看换键帽前的 F60S，有点脏，可以看到键帽侧面站上了粉尘颗粒，上表面也出现打油现象，油性皮肤真难伺候，实在不是我的风格，哈哈：

先把键帽拆下来，清理下键帽下面隐藏的XXX，清理之后未穿衣服的 F60S：

赶快给他穿上衣服：

我拿着安装好键帽的键盘去问水木，键盘怎么样，结果来了句“键盘的廉价感”，我说这是“复古风”，她竟表示理解。。。这什么逻辑，这个混色还是挺好看的，啊哈哈，球帽用起来的好处可能就是对于新手用键盘误触会减小，总体来说，这一套键帽还是很喜欢的，清爽复古风～

当然网上还有一大堆说法，什么21天成长计划、30天养成一个习惯、60天xxx，这些宣传套话背后应该是有一定道理的，包括21天入门xxx，然后我就萌生了 30天挑战 计划，这个计划有以下原则：

1. 每天坚持做一件小事情，它不能占用超过 1 个小时的时间，否则视为挑战失败，最好 30 分钟左右就能完成；
2. 最好早上做，如果不能，晚上睡得多晚都得做完，30 天内有 1 次补做机会，之后不做直接视为挑战失败；
3. 补做一次向共同挑战者发送 30 元 🧧，即刻发！
4. 挑战失败给共同挑战者发送 30 * 30 元 🧧！
5. 每天完成成果要让共同挑战者检验或者发到博客或者其他社交平台！

备注：

• 如果完成一个 30 天挑战后，继续下一个;

• 每个挑战内容最好不一样！

然后我把这个想法告诉了水木，她作为我的第一个共同挑战者，当然自己决定要做什么事情。水木不怎么玩社交平台分享，那只能由我亲自检查她每天的完成情况了，我最起码会分享到博客 Daily 中， 30天挑战 分别为：

会持续更新，那么问题来了，30 天挑战这个事能长期坚持吗。。。

共同监督，共同期待，共勉！

本文描述的是使用 Nvidia GPU 的操作步骤。

1. 环境搭建

• 为了考虑 python 的兼容性，使用最新版本的 python 3.7，即 python 3.7.9。
• 使用更轻量级的 conda 工具包 Miniconda 来管理虚拟环境。

如果已经有了 python 的虚拟环境工具，比如 anaconda，这里推荐 anaconda 或 miniconda，可以直接跳过 1.1 小节！

后续无特殊说明，均在有 Nvidia GPU 的服务器上操作，当然也可以在本地有显卡的 linux 环境下操作。

1.1 python 环境

2. 远程连接服务器 remote-server，这里 remote-server 为远程服务器：

   ssh remote-server
   

3. 打开 Miniconda 页面，找到最新的 64 位的 linux 下的安装包复制链接，写本文时的 64位 linux 版本为：https://repo.anaconda.com/miniconda/Miniconda3-py39_4.9.2-Linux-x86_64.sh:

   wget https://repo.anaconda.com/miniconda/Miniconda3-py39_4.9.2-Linux-x86_64.sh
   

4. 为下载的 miniconda 包添加运行权限：chmod +x Miniconda3-py39_4.9.2-Linux-x86_64.sh

5. 运行安装包启动安装流程：./Miniconda3-py39_4.9.2-Linux-x86_64.sh，随后按 Enter键，后打开一个协议文件

   • 按 Ctrl+d 组合键进行翻页，一直翻页，会有提示问是否接受协议内容 - Do you accept the license terms?[yes|no]，输入 yes按回车键 Enter 即可

   • 之后后询问你安装位置，默认是在自己 HOME 目录下的 miniconda3 中，这里我一般是加个 . 隐藏目录，所以我一般使用用户目录下的 .miniconda3即 /home/tianye/.miniconda3，根据自己的情况改成自己的 HOME 即可，然后继续 Enter，等待安装即可 ⌛️

   • 一段时间后会继续有提示问题 - Do you wish the installer to initialize Miniconda3 ny running conda init? [yes|no] 这里输入 yes 直接回车

   • Ctrl + d断开 SSH 连接，重新连接远程机器 ssh remote-server，此时就能使用 conda 了，which conda 应该就能看打印出 conda 的安装路径；

   • 为了加速 conda 安装包的速度，可以配置使用国内的清华源：

     conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
     conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/
     conda config --set show_channel_urls yes
     

1.2 paddle 环境

1.2.1 创建虚拟环境

重新连接远程机器后，默认会激活 conda 的 base 环境，默认是 python 3.9 的环境，我们要使用 python 3.7.9 ，所以需要新建一个虚拟环境，执行命令 conda create -n paddle python=3.7.9

• -n paddle指定虚拟环境名称为 paddle，这个名称随意，最好是自己能记住，用于区分不同的环境
• python=3.7.9环境中使用 3.7.9 版本的 python

稍等 ⌛️ 一段时间后会有提示，回车直接默认 yes 即可，再 ⌛️ 一段时间即可完成虚拟环境的安装，会有提示如何激活和退出虚拟环境：

# To activate this environment, use
#
#     $ conda activate paddle
#
# To deactivate an active environment, use
#
#     $ conda deactivate

加速 pip 包安装速度

1. 更新 pip：pip install --upgrade pip
2. 配置使用国内安装源，这里使用 aliyun 的源：pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

下面的步骤主要是安装 PaddleDetection 2.1 版本的环境，可以参考对应版本的环境安装说明，这里 2.1 的是 docs/tutorials/INSTALL_cn.md，如果是其它版本可以对应选择分支，找到 docs/tutorials/INSTALL_cn.md。

1.2.2 安装 paddlepaddle

激活虚拟环境：conda activate paddle，使用 which 命令查看 python 安装目录：

首先确实使用 cpu 还是 GPU，这里我们使用 Nvidia 的 GPU ，cuda 10.1 版本，根据 docs/tutorials/INSTALL_cn.md 确定安装 paddlepaddle 的命令如下：

# CUDA10.1
python -m pip install paddlepaddle-gpu==2.1.0.post101 -f https://paddlepaddle.org.cn/whl/mkl/stable.html

如果 CUDA 是其它版本，可以去 PaddlePaddle官网找对应计算平台的安装命令。

1.2.3 验证安装

安装完成后您可以使用 python 进入 python 解释器，输入import paddle ，再输入 paddle.utils.run_check()

如果出现PaddlePaddle is installed successfully!，说明您已成功安装。

2. 目标检测模型训练

这里以 ppyolo 算法的模型训练为例，使用的数据集为 VOC 数据格式，使用 COCO 格式的数据集训练方式后面如果有涉及也会记录相关操作。

2.1 下载 PaddleDetection

使用最新的 PaddleDetection 代码进行目标检测，使用 git clone 到服务器适当目录即可，比如用户目录下 paddle 目录下：

# 如果没有 paddle 目录可以新建
mkdir ~/paddle
# 进入 paddle 目录
cd paddle
# 克隆 PaddleDetection 仓库
git clone https://github.com/PaddlePaddle/PaddleDetection.git
# 可以查看下 PaddleDetection 的 1 层级目录结构
tree -L 1 PaddleDetection

此文撰写时使用的仓库的默认分支，即 release/2.1

• configs：训练的配置文件，包含各种常用的算法，我们可以复制创建自己的配置文件，进行新的训练任务
• dataset：存放标注数据，一般不要将自己的数据添加到实际的 git 跟踪中
• demo：存放一些 demo 图像，可以将我们的测试样本放到这个目录中
• output：这里一般用来存放训练导出的模型以及 demo 图像的推理结果图像
• ppdet：基于 paddlepaddle 框架的目标检测的基本库
• slim：裁剪蒸馏文件的存放位置
• tools：存放基本的模型训练、评估、推理、裁剪、生成锚框、转换数据集格式等工具脚本
• vdl_dir：可视化深度学习服务所需的文件，用于可视化训练过程

为了更好的管理自己的配置文件，建议使用好 git，这里我们可以建立自己的分支，比如我这里建立 5km 分支！

# 进入 PaddleDetection 目录
cd PaddleDetection
# 创建并切换到 5km 分支
git checkout -b 5km

2.2 数据集处理

可以使用 vocgo 切分数据集，VOC 数据集中一般会有两个目录，以数据组帮忙标注的银行大厅人员的数据为例，简单讲解下 vocgo 使用。

这里数据放在了我的用户下的 data/bank 中，首先进入这个目录：

# 进入数据目录
cd ~/data/bank
# 激活虚拟环境
conda activate paddle

2.2.1 安装 vocgo

python3 -m pip install vocgo

2.2.2 查看标注类别

一般情况下， VOC 数据的目录结构如下：

使用命令 vocgo list .即可查看当前目录下数据中标注的类别都有哪些：

• 包含了 5 种类别的目标，也分别统计了每种类别的目标个数
• 同时也统计了有、没有检测目标的图像个数

命令中**.**指的是当前目录

2.2.3 切分数据

可以使用命令 vocgo split --ratio 0.9 . 对当前目录中的标注数据进行切分，其中训练集图像与验证集图像按照 比例 0.9 进行划分，执行命令后会提示输入切分数据文件的导出目录，这里我们指定为 all:

会在指定导出目录中生成相应的标注文件。

如果我们只想筛选其中的 customer、security、teller三个类别训练模型，可以通过命令vocgo split --labels=customer,security,teller --ratio 0.9 .进行数据筛选和切分，执行命令后指定导出目录为 human ：

# 查看导出数据的类别
➜ cat human/label_list.txt
customer
security
teller

同样我们可以使用 vocgo list human 查看新导出切分数据集的类别信息：

为了不占用多余的数据空间，这里建议将我们的数据目录建立软链接到 PaddleDetection 的 dataset 目录下！

# 将 bank 目录链接到 ~/paddle/PaddleDetection/dataset/bank
ln -s ~/data/bank ~/paddle/PaddleDetection/dataset/bank
# 建议将新增的 bank 软链接添加到 PaddleDetection 仓库的 .gitignore 中
echo "dataset/bank" >> ~/paddle/PaddleDetection/.gitignore

最好是把自己添加的数据集目录都追加到 PaddleDetection 的忽略文件中！就像上面的第二条命令。

2.3 建立配置文件

我们这里使用百度 paddlepaddle 团队自研算法训练模型。

仓库中自带的 ppyolo 配置文件在 configs/ppyolo中，当然我们可以直接修改已经有的配置文件，但是为了不影响原有的参考文件，我们最好是复制一份，重命名一下，比如这里我们使用的是 configs/ppyolo/ppyolo_voc.yml ，我们要用 [2.2.3 小节](#2.2.3 切分数据) 中的切分出的 human 数据进行训练，我们暂且重命名为ppyolo_bank_human_voc.yml吧：

# 复制新的配置文件
cp configs/ppyolo/ppyolo_voc.yml configs/ppyolo/ppyolo_bank_human_voc.yml

下面开始修改配置文件，这里只简单说几项关键的参数。首先我们明确一下要使用几个 GPU，比如我们使用 4 个卡去训练模型（GPU_num=4）。

2.3.1 修改 batch_size

这个指的是一次显卡加载的图像样本数量，这受到显存的限制，默认使用的是 12，默认值对应的是 32GB 显存的卡 Tesla V100，我们的卡显存是 12GB 的 2080Ti，所以需要调小一点，比如使用 4，有一定的线性关系，当看着还有显存的时候，可以慢慢上调，比如 6，这里我们就使用 4。这个在 TrainReader的batch_size设置。

2.3.2 修改 max_iters

ppyolo 中不使用 epoch_size 表示迭代，而是使用 max_iters表示，这里我们默认 epoch_size=120，可以使用以下关系式去设置参数值：

$$ iters_{max}=\frac{Num_{image} \times Size_{epoch}}{Num_{GPU} \times Size_{batch}} $$

在 [2.2.3 小节](#2.2.3 切分数据) 切分数据的时候，可以看到 human 数据集中图像数量（image_num）是 4926， [2.3.1 小节](#2.3.1 修改 batch_size) 中调整 batch_size 为 4，GPU_num 为 4，最后计算如下：

$$ iters_{max}=\frac{4926 \times 120}{4 \times 4}=36945 $$

这里我们就取个整 36000 吧！

# image_num * epoch_size / GPU_num / batch_size
# 4926 * 120 / 4 / 4 => 36000
max_iters: 36000

2.3.3 调整日志打印间隔

为了更细的看到迭代过程中的结果，将 log_smooth_window和log_iter由原来的 20 改为 5。

log_smooth_window: 5
log_iter: 5

2.3.4 设置快照间隔 snapshot_iter

此参数表示每多少次保存一版模型，这里设置 3000，最终算下来能保存 12 个。

snapshot_iter: 3000

2.3.5 设置模型目录

此参数为设置模型权重文件的最终名称，其实是变相的设置输出目录，一般是设置在 output 下，即：

save_dir: output

训练过程中，会在指定的 save_dir 下生成与配置文件同名目录 - ppyolo_bank_human_voc，中间过程即 [2.3.4 小节](#2.3.4 设置快照间隔 snapshot_iter) 中设置保存的每一版模型都会存储到该目录中。

这里要特别说一下 weights 参数，这个参数一般用于模型转换和模型推理，用于指定转换的输入模型，模型训练完成后最终的模型名称就是 model_final，我们可以指定为下面的配置：

weights: output/ppyolo_bank_human_voc/model_final

2.3.6 设置类别个数

yolo 系的算法在数据集的配置中都会设置 with_background 为 false 也就是不包含背景，那么依照 [2.2.3 小节](#2.2.3 切分数据) 最后查看 human 切分数据的时候的类别个数为准，也就是 3 个：

num_classes: 3

2.3.7 设置学习率参数

1. 按照百度传达的经验，调整学习率应该依据于使用 GPU 的个数 GPU_num 和设置的 batch_size，原始的 base_lr=0.01为使用 8 卡，同时 batch_size 设置为 12 时设置的值，因为我们使用卡数量为 4，batch_size 为 4，所以最终设置 base_lr为 0.0025即可。
2. 设置学习率调整的 schedulers 参数，其中PiecewiseDecay 的 milestones 设置依赖于 [2.3.2 小节](#2.3.2 设置 max_iters)中的 max_iters 值，两个值一般分别按比例 0.8 和 0.88（大约，周边取整即可)，所以对应 36000 的话，应该是 28800 和 32000。
3. 同样需要按比例调整 LinearWarmup的 steps，也是依据 [2.3.2 小节](#2.3.2 设置 maxiters) 中的 max_iters 值，一般比例是 17.5 左右，计算取整即可，这里 $\frac{iters{max}}{17.5}=\frac{36000}{17.5}\approx2100$，所以最终配置。

LearningRate:
  base_lr: 0.0025
  schedulers:
    - !PiecewiseDecay
      gamma: 0.1
      milestones:
        - 28800
        - 32000
    - !LinearWarmup
      start_factor: 0.
      steps: 2100

2.3.8 设置 Reader

1. 设置 _Reader_，默认值是相对于配置文件下的 ppyolo_reader.yml文件，以后有可能我们还会修改里面的内容，所我们也复制这个文件，新文件命名为 ppyolo_bank_human_reader.yml，同时更新 _Reader_ 的值为 ppyolo_bank_human_reader.yml。

   # 复制 reader 文件
   cp configs/ppyolo/ppyolo_reader.yml configs/ppyolo/ppyolo_bank_human_reader.yml
   

2. 设置数据集目录，需要对训练集、评估集的 dataset_dir 、anno_path

   • dataset_dir 数据集的目录路径，相对于 PaddleDetection 的目录设置，训练集和评估集都是 dataset/bank/human
   • anno_path 对应的切分数据文件，训练集的为 train.txt，评估集的为 valid.txt

3. 设置使用我们自己生成的 label_list 文件，所以需要把 TrainReader、EvalReader、TestReader 的 dataset 下的 use_default_label 设置为 false 。

4. 对应 [2.3.1 小节](# 设置 batch_size) 中的 batch_size 就是在 TrainReader 中设置，值为 4。

_READER_: "ppyolo_bank_human_reader.yml"
TrainReader:
  dataset: !VOCDataSet
    dataset_dir: dataset/bank/human
    anno_path: train.txt
    use_default_label: false
    with_background: false
  mixup_epoch: 350
  batch_size: 4

EvalReader:
  inputs_def:
    fields: ["image", "im_size", "im_id", "gt_bbox", "gt_class", "is_difficult"]
    num_max_boxes: 50
  dataset: !VOCDataSet
    dataset_dir: dataset/bank/human
    anno_path: valid.txt
    use_default_label: false
    with_background: false

TestReader:
  dataset: !ImageFolder
    use_default_label: false
    with_background: false

2.3.9 设置 Anchor

1. 这里需要使用 PaddleDetection 提供的工具脚本 tools/anchor_cluster.py聚类生成对应 human 数据的 Anchor 数据：

   python tools/anchor_cluster.py -c configs/ppyolo/ppyolo_bank_human_voc.yml -n 9 -s 608 -m v2 -i 1000
   

   • -c 指定使用的配置文件，这里我们的就是刚刚修改好的配置文件 configs/ppyolo/ppyolo_bank_human_voc.yml
   • -n 9 生成 9 组尺寸
   • -s 608 指定图像训练尺寸
   • -m v2 使用默认的 v2 版本方法
   • -i 1000 迭代次数

   其实这里的 -c 之后的很多选项我也不知道具体明确的意思，后面有时间在探究然后补充到这里，先按照默认的选项生成！

   执行上边脚本后会打印 9 组尺寸，用于替换配置文件中原有配置即可，比如我这里打印的是：

   

2. 需要替换配置文件 configs/ppyolo/ppyolo_bank_human_voc.yml中 YOLOv3Head的 anchors 为上面打印的 9 个尺寸列表。

   YOLOv3Head:
     anchor_masks: [[6, 7, 8], [3, 4, 5], [0, 1, 2]]
     anchors:
       [
         [20, 44],
         [28, 108],
         [38, 158],
         [78, 123],
         [55, 221],
         [108, 152],
         [79, 268],
         [118, 326],
         [156, 352],
       ]
   

3. 因为配置项 YOLOv3Loss 的 use_fine_grained_loss 配置为了 true 所以还需要设置 configs/ppyolo/ppyolo_bank_human_reader.yml 中的 anchor 配置，具体找到 TrainReader -batch_transforms-!Gt2YoloTarget 修改 anchors 即可：

   # Gt2YoloTarget is only used when use_fine_grained_loss set as true,
   # this operator will be deleted automatically if use_fine_grained_loss
   # is set as false
   - !Gt2YoloTarget
     anchor_masks: [[6, 7, 8], [3, 4, 5], [0, 1, 2]]
     # anchors: [[22, 47], [29, 112], [41, 170],
     #           [75, 123], [62, 243], [106, 148],
     #           [101, 278], [121, 384], [155, 328]]
     anchors:
       [
         [20, 44],
         [28, 108],
         [38, 158],
         [78, 123],
         [55, 221],
         [108, 152],
         [79, 268],
         [118, 326],
         [156, 352],
       ]
   

到这里完成了基本的配置文件的修改，下一步就可以进行模型训练了！

本小节简单介绍了基本的常规需要调整的参数，后面如果有收获会继续丰富这个小节关于参数的调整内容。

2.4 模型训练

得益于强大的 PaddleDetection 我们只需要简单的一条命令就可以开启模型训练。

2.4.1 准备工作

训练过程一般是很长时间，然而我们 ssh 链接一旦断开就会把运行的训练程序停掉，为了防止这种情况的发生，我们一般远程 SSH 链接机器后，还会使用 tmux 创建会话，在新的会话中执行我们的命令，只要不是 tmux 挂掉或者我们自己 kill 程序，一般情况下我们的程序就会由 tmux 进行托管执行，即使我们断开了 SSH ，重新连接机器后，连接上 tmux 的会话也能看到自己也还在执行的程序，下面简单说一下我的操作过程：

1. 创建会话，会话名称为 paddle

   tmux new -s paddle
   

   这样就会打开一个会话并激活一个窗口 shell。

2. 我一般会把窗口重命名，还会创建一个专门监控显卡和其他硬件资源的窗口，使用当前的窗口创建即可：

   • 重命名窗口为 monitor：按下快捷键 ctrl+b，然后按 , 键就会在最低边可以编辑修改名称，改为 monitor 回车即可

   • 这样回到 shell 之，执行命令 watch -n 0.5 nvidia-smi，这样就会每 0.5 秒刷新一次显卡状态

   • 快捷键 ctrl+b，然后按 % 键，会在右侧竖分出一个新的窗格，我们可以打开一个 top 命令随时查看 CPU、memery 和 proc 情况，我这里使用的是 gotop 命令，更好看一些，直接运行命令 gotop，你可以运行 top 或者 htop，这样我们的监控窗口就做好了，晒一下我的监控窗口：

     

   • 快捷键 ctrl+b，然后按 c 键，此时会创建新的窗口，按下快捷键 ctrl+b，然后按 , 键就会在最低边可以编辑修改名称，改为 train 回车，这样我们的窗口都准备好了，窗口切换的快捷键是：快捷键 ctrl+b，然后按 p 或 n

     • 其中 p 代表 previous 表示切换到前一个窗口
     • 其中 n 代表 next 表示切换到前一个窗口

3. 然后进入工作目录，并激活虚拟环境

   # 进入 PaddleDetection 目录
   cd paddle/PaddleDetection
   # 激活虚拟环境
   conda activate paddle
   

2.4.2 开始训练

假设我们使用 0、1、2、3 号卡训练模型，那么执行命令

CUDA_VISIBLE_DEVICES=0,1,2,3 python tools/train.py -c configs/ppyolo/ppyolo_bank_human_voc.yml --eval -o use_gpu=true --use_vdl=True --vdl_log_dir=vdl_dir/scalar

• CUDA_VISIBLE_DEVICES=0,1,2,3 指定环境变量，告诉 ppdect 使用 0、1、2、3 号卡进行多卡训练
• tools/train.py 训练工具脚本
• -c configs/ppyolo/ppyolo_bank_human_voc.yml 使用我们刚做好的配置文件
• --eval 每次快照保存模型的时候进行一次评估
• -o use_gpu=true 覆盖配置文件中的指定配置项的值，这里是指定要使用 gpu
• --use_vdl=True 配置开启深度学习可视化，可以看一些 loss 曲线，可视化训练过程中关键指标的变化
• --vdl_log_dir=vdl_dir/scalar 指定可视化日志输出位置

正常的情况下，经过 ⌛️ 一段时间我们就能看到迭代过程中的日志打印了，类似于：

[INFO 2021-04-14 14:29:09,065 train.py:286] iter: 765, lr: 0.000607, 'loss_xy': '1.455415', 'loss_wh': '1.337777', 'loss_obj': '11.151718', 'loss_cls': '2.540418', 'loss_iou': '4.378272', 'loss_iou_aware': '0.087677', 'loss': '20.988634', eta: 6:41:24, batch_cost: 0.68355 sec, ips: 5.85182 images/sec

可以查看日志打印观察 loss 是否是收敛的。

训练起来之后可以按快捷键 快捷键 ctrl+b，然后按 p 返回到 monitor 窗口，查看硬件资源使用情况，比如显卡，可以看一下显存占用，可以作为依据调整配置文件中 batch_size。

2.4.3 可视化曲线

为了更直观的观看训练情况，我们可以开启 VDL 的服务查看动态的曲线变化。这里有个小技巧，如果直接在 ssh 连接机器的 shell 中执行启动可视化服务的命令，因为服务器的端口并未开放，我们在自己本地是无法访问的，最简单的坚决方式是使用 vscode，vscode 能自动转发连接服务器上自己启动的端口服务，这里就不讲如何使用 vscode 远程连接服务器了，自行百度。

使用 vscode 远程连接上面训练任务开启的机器，打开 paddle/PaddleDetectioj 文件夹，打开一个终端窗口，如果没有激活我们创建的 paddle 虚拟环境的话，我们自己激活即可 conda activate paddle ，然后执行以下命令启动服务，指定 vdl 的日志目录与训练命令中对应起来：

visualdl --logdir vdl_dir/scalar/

执行命令后，vscode 就会检测到新的端口服务并提示完成转发：

点击**「在浏览器中打开」**按钮即可在浏览器打开我们的可视化服务的页面，便可以查看各种曲线了：

2.4.4 后台运行

我们可以把 tmux 会话推到后台，使用快捷键 ctrl+b，然后按下 d 即可退出 tmux。

如果想要重新连接我们训练的会话，执行命令：

tmux a -t paddle

• paddle 就是我们的会话名称
• a 是 attach 的缩写

2.4.5 等待完成

训练需要很长时间，具体大约的时间，在打印的日志中有体现，比如：

[INFO 2021-04-14 14:29:09,065 train.py:286] iter: 765, lr: 0.000607, 'loss_xy': '1.455415', 'loss_wh': '1.337777', 'loss_obj': '11.151718', 'loss_cls': '2.540418', 'loss_iou': '4.378272', 'loss_iou_aware': '0.087677', 'loss': '20.988634', eta: 6:41:24, batch_cost: 0.68355 sec, ips: 5.85182 images/sec

其中 eta 就是评估的可能耗时。

去干点其它的事情就行了，可以偶尔连接机器连接 tmux 会话查看训练情况，有可能会出问题的！

2.5 模型推理

2.5.1 一张图像推理

推理很简单，使用以下命令即可测试一张图像的推理：

CUDA_VISIBLE_DEVICES=0 python tools/infer.py -c configs/ppyolo/ppyolo_bank_human_voc.yml -o use_gpu=true --infer_img=demo/demo.jpg

• CUDA_VISIBLE_DEVICES=0 声明要使用的显卡编号，比如这里指定使用 0 号卡
• -c configs/ppyolo/ppyolo_bank_human_voc.yml 使用我们刚做好的配置文件
• -o use_gpu=true 覆盖配置文件中的指定配置项的值，这里是指定要使用 gpu
• --infer_img 指定要测试的图像

这里注意的是，根据训练配置，推理会默认加载使用配置项 weights 指定的模型，这里就是 output/ppyolo_bank_human_voc/model_final，详见[2.3.5 设置模型目录](#2.3.5 设置模型目录) 。

2.5.2 多张图像推理

如果要推理一批图像，可以将图像放置在一个目录中，比如是 ./demo/bank，使用 infer.py 时指定图像目录即可：

CUDA_VISIBLE_DEVICES=0 python tools/infer.py -c configs/ppyolo/ppyolo_bank_human_voc.yml -o use_gpu=true --infer_dir=demo/bank

• --infer_dir 指定要测试的图像目录

2.5.3 其它选项

可以查看 tools/infer.py 最后的代码，自行查看。

2.6 模型部署

步骤比较清晰，要看是预测部署还是服务部署方式。

2.6.1 预测部署

2.6.1.1 导出模型

使用以下命令导出模型文件：

python tools/export_model.py -c configs/ppyolo/ppyolo_bank_human_voc.yml -o use_gpu=true --output_dir=./inference_model

• tools/export_model.py 导出模型的工具脚本；
• -c configs/ppyolo/ppyolo_bank_human_voc.yml 指定配置文件
• --output_dir=./inference_model 指定导出目录，会在此指定目录下生成与配置文件同名的目录存放导出模型文件

导出模型结构：

➜ tree inference_model/ppyolo_bank_human_voc
inference_model/ppyolo_bank_human_voc
├── infer_cfg.yml
├── __model__
└── __params__

0 directories, 3 files

可以看到只有三个文件：

• infer_cfg.yml 中能看到模型的关键配置信息和类别信息
• __model__ 描述网络结构
• __params__ 存储网络结构中的权重参数数据

2.6.1.2 预测

使用 deploy/python/infer.py 这个工具脚本推理即可，deploy/python 目录下三个 python 脚本，只需要这三个文件和上面导出的模型文件即可独立于 PaddleDetection 完成推理预测，支持分析指定图像以及视频文件。

• 分析图像

  python deploy/python/infer.py \
           --model_dir inference_model/ppyolo_bank_human_voc \
           --image_file demo/xxx.jpg \
           --output_dir output/bank_human/ppyolo_bank_human_voc \
           --use_gpu True \
           --threshold 0.5
  

• 分析视频

  python deploy/python/infer.py \
           --model_dir inference_model/ppyolo_bank_human_voc \
           --video_file demo/bank_human/chlorine_bottle/demo_chlorine_bottle_ch24.mp4 \
           --output_dir output/bank_human/ppyolo_bank_human_voc \
           --use_gpu True \
           --threshold 0.5
  

2.6.1 服务部署

如果我还喘气，可能还会更新。。。

一、准备环境及仓库

1. 创建开发环境

   # 创建新的 conda 环境
   conda create -n open-mmlab python=3.7 -y
   # 激活 conda 环境
   conda activate open-mmlab
   

2. 安装 pytorch

   conda install pytorch==1.6.0 torchvision==0.7.0 cudatoolkit=10.1 -c pytorch -y
   

3. 安装 mmcv-full

   pip install https://download.openmmlab.com/mmcv/dist/latest/torch1.6.0/cu101/mmcv_full-latest%2Btorch1.6.0%2Bcu101-cp37-cp37m-manylinux1_x86_64.whl
   

4. clone 仓库

   git clone https://github.com/open-mmlab/mmdetection.git
   cd mmdetection
   

5. 安装仓库中开发需要的依赖

   pip install -r requirements/build.txt
   pip install -v -e .  # or "python setup.py develop"
   

二、准备数据集

下载 coco 格式的数据集，或者自己标注制作 coco 格式的数据集，比如我们的数据集的目录是 /path/to/your/dataset（绝对路径），需要在 mmdetection 中建立 data 目录，在其下面建立数据集目录的软链接：

# 此时在 mmdetection 目录下，建立 data 目录，如果已经存在可以省略此步
mkdir data
# 建立数据集软链接
ln -s /path/to/your/dataset data/mydetaset

建立软链接时使用的目录路径必须是绝对路径

看一下目录结构，这里是 coco 格式，都差不多，以我手头的一个数据集为例，目录结构如下：

$ tree -L 2 data/mydetaset                          
data/mydetaset
├── annotations
│   ├── test_image_info.json
│   ├── train1.json
│   ├── train2.json
│   ├── val1.json
│   └── val2.json
└── images
    ├── test
    ├── train1
    ├── train2
    ├── val1
    └── val2

7 directories, 5 files

三、修改配置文件

这里以 configs/faster_rcnn/faster_rcnn_x101_64x4d_fpn_2x_coco.py 为例，直接修改配置适配训练任务。

打开这个配置文件发现是引用其它的配置文件，一步步的找到相应的配置文件进行修改：

1. configs/base/models/faster_rcnn_r50_fpn.py

   这里主要修改检测目标类型个数，比如我修改为 2 个，修改 46 行的 num_classes 的值为 2 即可。

2. configs/base/schedules/schedule_2x.py

   这里我要使用一张显卡进行训练，所以这里需要调整学习率为原来的 $\frac{1}{8}$ ，修改第 2 行的 lr 即可，修改为 $0.025$。

   原来的值一般是针对 8 卡训练的，因为这里使用一张卡，所以这里调整为原来的 $\frac{1}{8}$

3. configs/base/datasets/coco_detection.py

   需要修改数据集相关的配置，主要是路径及取样数

   • data_root：这里要修改为上面我们创建的数据集的软链接，为 data/mydetaset/

     这里的目录最后要带着 /

   • samples_per_gpu：如果显卡显存有限，这里就调成 1 吧

   • train：需要对应数据集修改 img_prefix 和 ann_file，以上边准备的数据集为例，修改标注文件和图像目录，同样需要注意最后带上 /:

     train=dict(
       type=dataset_type,
       ann_file=data_root + 'annotations/train1.json',
       img_prefix=data_root + 'images/train1/',
       pipeline=train_pipeline),
     

   • val：需要对应数据集修改 img_prefix 和 ann_file，以上边准备的数据集为例，修改标注文件和图像目录，同样需要注意最后带上 /:

     val=dict(
       type=dataset_type,
       ann_file=data_root + 'annotations/val1.json',
       img_prefix=data_root + 'images/val1/',
       pipeline=test_pipeline),
     

   • train：需要对应数据集修改 img_prefix 和 ann_file，以上边准备的数据集为例，修改标注文件和图像目录，同样需要注意最后带上 /:

     val=dict(
       type=dataset_type,
       ann_file=data_root + 'annotations/val1.json',
       img_prefix=data_root + 'images/val1/',
       pipeline=test_pipeline),
     

四、修改代码中的问题

加载数据集的时候，可以修改数据集加载器类中的代码，实现自动加载正确的类别信息及所有的数据，否则会无法成加载数据倒是训练失败。

修改文件 mmdet/datasets/coco.py 中初始化数据中 categories 的加载实现，很简单，只需要去掉 self.coco.get_cat_ids() 方法中的传参，第 58 行代码修改为：

self.cat_ids = self.coco.get_cat_ids()

另外，保证一致性，还是修改一下 self.CLASSES吧，按照正确顺序写上所有类型即可，这里就不展示了。

五、训练

使用工具脚本 tools/train.py 即可开启一个简单的训练任务，记得指定 gpu：

python tools/train.py configs/faster_rcnn/faster_rcnn_x101_64x4d_fpn_2x_coco.py --gpu-ids 1 --work-dir output

• configs/faster_rcnn/faster_rcnn_x101_64x4d_fpn_2x_coco.py：指定使用的配置，就是上面决定使用的那个
• –gpu-ids：指定使用 1 号卡
• –work-dir：指定模型训练日志及中间 epoch 文件或其它文件的存储目录为 output

TensorRT dynamic library (libnvinfer.so) that Paddle depends on is not configured correctly. (error code is libnvinfer.so: cannot open shared object file: No such file or directory) Suggestions:

1. Check if TensorRT is installed correctly and its version is matched with paddlepaddle you installed.
2. Configure TensorRT dynamic library environment variables as follows:

• Linux: set LD_LIBRARY_PATH by export LD_LIBRARY_PATH=...
• Windows: set PATH by `set PATH=XXX;———– Running Arguments ———–

其实这个问题并没有影响我们模型的推理结果，强迫症不允许有任何警告，还是解决下吧！临时解决可以采用离线安装方式。

源安装方式

参考：Install TensorRT - 4.1. Debian Installation

后面有时间会稍微整理一下！

离线包安装方式

这个方法比较适用于无法添加 nvidia 相关开发包仓库源的场景：

• 不是唯一的方式，也不是最好的方式
• 而且不是很灵活，具有版本针对性，针对服务器已安装 Cuda 10.0 的版本

安装相关依赖包

上面已经说了具有版本针对性是因为 Cuda 版本是10.0，下载的依赖包都是针对这个版本的，点我可下载，文件列表如下：

ls -l /data/nvidia-debs/TensorRT-debs 
总用量 255M
-rw-rw-r-- 1 tianye tianye  29M Sep 19  2018 cuda-cublas-10-0_10.0.130-1_amd64.deb
-rw-rw-r-- 1 tianye tianye 107K Sep 19  2018 cuda-cudart-10-0_10.0.130-1_amd64.deb
-rw-rw-r-- 1 tianye tianye  18K Sep 19  2018 cuda-license-10-0_10.0.130-1_amd64.deb
-rw-rw-r-- 1 tianye tianye 157M Oct 28  2019 libcudnn7_7.6.5.32-1+cuda10.0_amd64.deb
-rw-r--r-- 1 tianye tianye  66M Dec  3 12:33 libnvinfer7_7.0.0-1+cuda10.0_amd64.deb
-rw-r--r-- 1 tianye tianye 2.1M Dec  3 12:33 libnvinfer-plugin7_7.0.0-1+cuda10.0_amd64.deb
-rw-r--r-- 1 tianye tianye 588K Dec  3 12:33 libnvonnxparsers7_7.0.0-1+cuda10.0_amd64.deb
-rw-r--r-- 1 tianye tianye 761K Dec  3 12:33 libnvparsers7_7.0.0-1+cuda10.0_amd64.deb

我这里上面 deb 包下载后都是放在 /data/nvidia-debs/TensorRT-debs 下的，您可以放在其它地方，安装即可：

sudo dpkg -i /data/nvidia-debs/TensorRT-debs/*.deb

上面的相关依赖包是在 nvidia 源仓库下载的，可以在官网页面中找到相应版本的依赖包，这里需要安装的只是:

• libnvinfer7
• libnvinfer-plugin7
• libnvonnxparsers7
• libnvparsers7

安装过程中发现它们依赖于其它包，所以你看到目录下的其它包都是依赖，都得安装！

deb 包仓库地址(进入页面按系统进入即可)：

1. cuda：https://developer.download.nvidia.com/compute/cuda/repos
2. machine-learning：https://developer.download.nvidia.com/compute/machine-learning/repos

添加动态链接库软链接

上面安装后的动态链接库都在/usr/lib/x86_64-linux-gnu 下，虽然这个目录已经在 LD_LIBRARY_PATH 中了，但运行推理还是找不到的，因为名字不对，找不到，所以需要创建相应的软链接，这一步很简单，因为目录下已经有相应的带版本的软链接文件了，所以复制改名即可：

sudo cp /usr/lib/x86_64-linux-gnu/libcudnn.so.7 /usr/lib/x86_64-linux-gnu/libcudnn.so
sudo cp /usr/lib/x86_64-linux-gnu/libnvinfer.so.7 /usr/lib/x86_64-linux-gnu/libnvinfer.so
sudo cp /usr/lib/x86_64-linux-gnu/libnvinfer_plugin.so.7 /usr/lib/x86_64-linux-gnu/libnvinfer_plugin.so
sudo cp /usr/lib/x86_64-linux-gnu/libnvparsers.so.7 /usr/lib/x86_64-linux-gnu/libnvparsers.so
sudo cp /usr/lib/x86_64-linux-gnu/libnvcaffe_parser.so.7 /usr/lib/x86_64-linux-gnu/libnvcaffe_parser.so

再次推理发现就没有警告了。

本文将以一个简单的 web 应用例子以清晰地讲述部署方式。

准备工作

安装 nginx

网上有很多资料参考，搜索相应系统的安装方式进行安装即可。

ubuntu 可以借用包管理工具 apt 或 apt-get 进行安装，当然也可以使用 docker 进行启动，这里不做过多延伸。

前后端开发环境

以笔者使用的机器为例，描述的版本号为机器使用的各工具版本。

1. 前端开发环境：
   • node：12.16.3
   • yarn: 1.22.10
2. 后端开发环境：
   • python: 3.6.10
   • flask: 1.1.2

Demo

以一个简单的 demo 讲述部署，功能很简单，前端输入两个数，发给后端，后端计算后返回前端，前端页面显示结果，即一款简单的整数加法器。

前端工程

vue-flask-deploy-demo-frontend

后端工程

vue-flask-deploy-demo-backend

第一次部署

部署后端服务

后端服务启动到 10086 端口，使用 gunicorn启动：

gunciorn -b 127.0.0.1:10086 main:app

不暴露后端服务，只能 localhost 进行访问！

可以使用 systemctl 管理后端服务，需要撰写 service 文件，放置到 /etc/systemd/system 下，比如这里最终的文件是 /etc/systemd/system/demo.service，内容如下：

[Unit]
Description = vue-flask-deploy-demo
After = network.target

[Service]
User = xxx
Group = xxx

WorkingDirectory = /data/home/xxx/vue-flask-deploy-demo/vue-flask-deploy-demo-backend
ExecStart = /data/home/xxx/.local/share/virtualenvs/vue-flask-deploy-demo-backend--ctYQkX6/bin/gunicorn -b 127.0.0.1:10086 main:app
Type = simple

[Install]
WantedBy = multi-user.target

• User: 改为自己的用户名；
• Group: 改为自己的用户组名称；
• WorkingDirectory：后端项目目录，使用绝对路径
• ExecStart：后端服务启动在本地 10086 的命令，其中 gunicorn 要使用绝对路径

重载一下服务文件：

sudo systemctl daemon-reload 

如果需要服务器重启后自启动服务，需要：

sudo systemctl enable demo.service

启动服务：

sudo systemctl start demo

构建前端项目

1. 构建前端项目

   yarn build
   

2. 将构建后的文件全部拷到 /data/www/demo 下：

   # 创建目录
   mkdir -p /data/www/demo
   # 拷贝构建生成的文件到目录
   cp -r dist/* /data/www/demo/
   

其中, /data/www/demo 为要放置前端静态文件的目录，根据自身情况而定！

nginx 配置文件

自定义的 nginx 配置文件可以放在路径 /etc/nginx/conf.d 下，所以我们第一步需要先在其下添加一个配置文件，比如 demo.conf，内容如下：

upstream backend {
  	# 定义后端服务，这里为 10086
    server 127.0.0.1:10086;
}

server {
    listen  20804;

    # 前端项目build dist 文件部署
		location / {
        # 1. 前端项目构建出的文件放置位置
        root /data/www/demo;
        # 2. 解决 vue 采用 history 模式时前端路由页面刷新 404 的错误
        try_files $uri $uri/ /index.html last;
    }

    # 3. 后端 api/static文件代理，没有后端可忽略这个
    location ~/(api|static)/ {
        proxy_pass http://backend;
        # 4. 增大数据体大小限制，防止 413 错误；
        client_max_body_size 1024m;
    }

	# 5. IP 白名单
    # - 允许局域网段 192.168.xxx.xxx 机器访问
    # allow 192.168.0.0/16;
    # deny all;
}

这里解释一下配置：

1. 其中 root 后的内容指定前端项目的构建文件存放目录，比如这里为 /data/www/demo
2. 解决前端页面在某一个路由下人为进行页面刷新导致 404 错误的问题
3. 后端 API 转发代理
4. nginx 数据体大小限制默认为 2MB，这里我们修改为 1GB，根据情况修改
5. 配置 IP 白名单可以进行访问限制

这里这样配置的目标有两个：

• 对外只暴露一个端口即 20804
• 前后端项目的分离部署，包括静态文件目录

nginx 重新加载配置

sudo nginx -s reload

此时，我们的项目就可以访问了！

项目升级部署

后续的开发中，会经常进行升级，就非常简单了。

前端项目

只需在本机进行构建，然后把文件覆盖到服务器的前端文件目录即可

# 构建项目
yarn build
# 上传文件
scp -r -P 20800 dist/* xxx@xxx.xxx.xxx.xxx:/data/www/demo/

• scp 命令将构建的前端文件拷贝到服务器的部署目录下。
• 前端项目更新升级，不再需要后端重启服务

后端项目

服务器拉取部署分支（develop 或 master）最新代码，然后重启服务即可。

# 拉取最新代码
git pull
# 重启后端服务
sudo systemctl restart demo

日常开发中经常会在同域名或 IP 下在不同端口部署不同的 web 应用服务，但如果恰好每个服务都有用户登录功能，且采用 session 的安全认证方式，就会出现两个应用登录信息互顶的问题，具体表现为：已经登录了 A 应用，结果再去登录 B 应用，回头去 A 应用的页面发现登录信息失效了，本文就看一下这个问题。

说明

web 项目使用基于 python 的 web 框架 flask 实现。

探索

复现问题

我以自己的项目为例：

• 应用 A：localhost:20702
• 应用 B：localhost:20709

首先打开项目 A 的网页并登录，然后打开浏览器的网页检查器看一下，cookie 信息中 session id 叫 session:

session:"eyJ1c2VybmFtZSI6InRpYW55ZTEifQ.X5OddA.Tt8ayJhPp8KHcBdzRzU72I6U-SI"

同样，再打开项目 B 的网页并登录，然后同样打开浏览器网页检查器看一下 cookie 信息，也有一个 session id 为 session 的信息：

session:"eyJ1c2VybmFtZSI6InRpYW55ZSJ9.X5OaxQ.IltnUYo4-bO9JcrNxBJYPc1hxWs"

回过头去看项目 A 的网页发现，原来的 cookie 信息变了，还是有 session 的信息，但是值变了：

session:"eyJ1c2VybmFtZSI6InRpYW55ZSJ9.X5OexQ.OC7TtbfCLfuUtwsS0D9nbK6mh5w"

导致项目 A 的页面登录失效了。

排查原因

上面在检查器中可以明确看到 session 信息，cookie 中仅仅出现的是域名 localhost 下的一个 session 信息，id 为 session，怎么回事？两个项目共用了一个 session 信息。

经过了解知道：

对于浏览器来说，cookie 不区分端口，因此对于同一个域名，它的所有端口都是共享 cookie

解决

所以解决方法很简单，修改后端默认的 session id 名称为各自项目的，只要不相同就可以了。可以在 Flask 应用的配置中修改配置项 SESSION_COOKIE_NAME，其默认为 session，因为两个项目的均没有配置这个，都使用 session 作为了 session id，造成了冲突，我们添加这个配置项改为相关的应用名称即可，比如我的 Flask 项目中可以通过以下多种方式修改此配置：

# app 为 Flask 实例
app.config["SESSION_COOKIE_NAME"] = "session-demo1"

或者

# 单独定义配置对象
class ProductionConfig():
    SESSION_COOKIE_NAME = "session-demo1"

# 从对象读入配置内容，app 为 Flask 实例
app.config.from_object(ProductionConfig)

两个项目各自修改 SESSION_COOKIE_NAME 为不同值之后，即可解决 session 冲突问题了！Nice！

如果使用其它语言或 web 框架，一定可以找到这个 session cookie name 的配置项！

希望能帮到您！

本文主要讲一下制作这个基础镜像的过程，灰常简单。

需求

先理一下我们的需求：

• ubuntu16.04(xenial)，apt-get 使用国内源，安装基本的工具
• 最新的 python3.6，目前最新的为 python3.6
• 最新的 pip3，而且要更改配置为国内的 pypi 源

准备工作

我们使用 Dockerfile 制作镜像，这里需要准备一些文件，所以先创建个目录，在此目录下进行操作，比如目录是 docker_ubuntu_python3.6

mkdir docker_ubuntu_python3.6
# 进入目录
cd docker_ubuntu_python3.6

此目录下后面我们需要创建三个文件，最好是不要包含其它文件：

• sources.list
• pip.conf
• Dockerfile

注：

这个目录不要再有其它文件，否则还要将多余的文件加到 .dockerignore

sources.list

为更改镜像中的 apt-get 源为国内源而准备。

新建文件 sources.list，内容如下：

deb-src http://archive.ubuntu.com/ubuntu xenial main restricted #Added by software-properties
deb http://mirrors.aliyun.com/ubuntu/ xenial main restricted
deb-src http://mirrors.aliyun.com/ubuntu/ xenial main restricted multiverse universe #Added by software-properties
deb http://mirrors.aliyun.com/ubuntu/ xenial-updates main restricted
deb-src http://mirrors.aliyun.com/ubuntu/ xenial-updates main restricted multiverse universe #Added by software-properties
deb http://mirrors.aliyun.com/ubuntu/ xenial universe
deb http://mirrors.aliyun.com/ubuntu/ xenial-updates universe
deb http://mirrors.aliyun.com/ubuntu/ xenial multiverse
deb http://mirrors.aliyun.com/ubuntu/ xenial-updates multiverse
deb http://mirrors.aliyun.com/ubuntu/ xenial-backports main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ xenial-backports main restricted universe multiverse #Added by software-properties
deb http://archive.canonical.com/ubuntu xenial partner
deb-src http://archive.canonical.com/ubuntu xenial partner
deb http://mirrors.aliyun.com/ubuntu/ xenial-security main restricted
deb-src http://mirrors.aliyun.com/ubuntu/ xenial-security main restricted multiverse universe #Added by software-properties
deb http://mirrors.aliyun.com/ubuntu/ xenial-security universe
deb http://mirrors.aliyun.com/ubuntu/ xenial-security multiverse

这里使用的是阿里云 ubuntu16.04 的源，可选择其它源。

pip.conf

为加速 pip 安装第三方依赖的速度而准备。

创建文件 pip.conf，内容如下：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host=pypi.tuna.tsinghua.edu.cn
disable-pip-version-check = true
timeout = 6000

这里使用的清华的 pypi 源，可选择使用其它源！

Dockerfile

最后是制作 Docker 镜像的 Dokerfile，新建文件，名为 Dockerfile，内容如下：

FROM ubuntu:xenial AS ubuntu16_04-with-python3_6
LABEL author="5km"
# 用ubuntu国内源替换默认源
RUN rm /etc/apt/sources.list
COPY sources.list /etc/apt/sources.list
# 安装python3.6必要的包。源镜像太精简了，ip ifconfig之类的都没有。后续安装python pip也需要一些。但是build_essential似乎不必须，先去了。如果后面安装numpy之类需要gcc了，再加上
RUN apt-get update \
    && apt-get install -y libapt-pkg5.0 apt-transport-https iproute2 net-tools ca-certificates curl wget software-properties-common \
    && apt-get clean
# 安装python3.6 来自第三方
RUN add-apt-repository ppa:deadsnakes/ppa \
    && apt-get update \
    && apt-get install -y python3.6 python3.6-dev python3-pip \
    && apt-get clean
# 和自带的3.5共存
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.5 1 \
    && update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.6 2 \
    && update-alternatives --config python3
# 更改 pip 源为清华源，加速
RUN mkdir /root/.pip
COPY pip.conf /root/.pip/pip.conf
# 更新 pip3
RUN pip3 install --upgrade pip \
    && rm -rf /root/.cache/pip
#print()时在控制台正常显示中文
ENV PYTHONIOENCODING=utf-8

内容中有注释，所以很容易明白过程！！！

准备工作大功告成，看一下当前目录下的文件结构：

irecog@irecog [01:59:36 PM] [~/docker_ubuntu_python3.6]
-> % tree .
.
├── Dockerfile
├── pip.conf
└── sources.list

0 directories, 3 files

制作镜像

一条命令，完成制作：

docker build -t ubuntu16_04-with-python3_6 .

理论上不到一杯咖啡过后，就能看到制作完成的镜像：

irecog@irecog [02:00:40 PM] [~/docker_ubuntu_python3.6]
-> % docker images
REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
ubuntu16_04-with-python3_6   latest              7883d49a0394        47 minutes ago      623MB

过程回顾

下面是整个操作过程的 asciinema 录制，可参考录制进行操作：

如果上面过程录制加载很慢，可自行安装 asciinema ，使用 asciinema 播放 docker-ubuntu1604-python36.json

asciinema play docker-ubuntu1604-python36.json

这玩意儿能记录在终端的命令操作过程，最终记录文件并不是视频文件，而是一个 json 文件。

工具除了录制还能播放此文件，就是解析这个 json 文件中的内容，里面记录了每个关键时刻的 stdin 和 stdout，所以在播放的时候其实就是输入输出的过程，当然没这么简单，里面还记录了终端的一些信息，比如终端的行数和列数、颜色等信息。

所以，播放记录的时候还可以复制粘贴里面的内容。这东西太适合做命令行操作分享的时候使用了，所以又深入研究了下。

官方提供了播放记录文件的 WEB 支持，只需一个 js 文件和 css 文件，使用标签 asciinema-player 就能在 HTML 中展示记录文件了，而且还能换主题。花了几分钟，在自己的博客中简单添加了 asciinema 的支持！

BUT！BUT！BUT！ @yyrcd 提醒下，发现js 文件竟然与评论系统 valine 的 js 不兼容，如果加载了 asciinema-player.js 评论就不能正常加载显示了，本来想着可以自己本地管理要分享的录制，那还是使用 asciinema 官网管理吧，官方提供了 script 嵌入方式的分享途径，也能达到自己想要的效果，且不会造成不兼容的现象，就是加载的会慢一点，就先这样吧！

以后分享命令行操作就用这玩意儿了，舒服～

比如我要在本页展示官方的 demo ，就可以页面中加入：

<script id="asciicast-326538" loop="loop" src="https://asciinema.org/a/326538.js" async data-speed="3"></script>

效果如下：

本文适用于 macOS 下的 python 开发。

pyenv

pyenv 可以用来管理不同版本的 python

安装

brew install pyenv

配置

在使用的 shell 配置文件中加 pyenv 相关内容

• 使用 bash 的话，就编辑 .bashrc 文件
• 使用 zsh 的话，编辑 .zshrc 文件

配置内容：

export PYENV_ROOT=~/.pyenv
export PATH=$PYENV_ROOT/shims:$PATH
eval "$(pyenv init -)"

安装

查看 python 可用版本

pyenv install --list

安装某个版本

比如安装 3.6.8

pyenv install 3.6.8

会发现极慢，此时可以自己到 python 官网下载相应版本的 tar.xz 包，比如这里就下载 Python-3.6.8.tar.xz，然后放到用户目录下的 .pyenv/cache 下，如果目录不存在就自己创建，pyenv 安装就会先下载源码包到这个目录。

卸载

pyenv uninstall 3.6.8

查看已安装的版本

pyenv versions

这个命令同时也会查看当前使用的版本。

切换 python 版本

全局

作用域在全局

pyenv global 3.6.8

局部

作用域在一个工作目录

pyenv local 3.6.8

进入某个目录，执行上面的命令后，每当进入这个目录就会自动切换 python 为指定的版本。

which python 可以查看 python 的目录是：~/.pyenv/shims/

pipenv

可以参考博文 一起使用 pipenv

虚拟环境

某个工程使用 3.6.8 的 python：

1. 进入工程目录 cd project1
2. 切换 python 版本 pyenv local 3.6.8
3. 创建虚拟环境 pipenv --python /Users/5km/.pyenv/shims/python
4. 安装依赖 pipenv install --skip-lock

创建工程

# 安装 Vue
# npm install -g @vue/cli
$ vue creat antd-demo

排除 vscode 配置忽略

vscode 打开上面创建的工程，修改 .gitignore 文件内容为：

.DS_Store
node_modules
/dist

# local env files
.env.local
.env.*.local

# Log files
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Editor directories and files
.idea
- .vscode
+ .vscode/*
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

+ !.vscode/settings.json

修改 vscode 工程配置

修改文件 .vscode/settings.json ，内容如下：

{
  // vscode默认启用了根据文件类型自动设置tabsize的选项
  "editor.detectIndentation": false,
  // 重新设定tabsize
  "editor.tabSize": 2,
  // #每次保存的时候自动格式化
  "editor.formatOnSave": true,
  // #每次保存的时候将代码按eslint格式进行修复
  "eslint.autoFixOnSave": true,
  // 添加 vue 支持
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    {
      "language": "vue",
      "autoFix": true
    }
  ],
  // #让prettier使用eslint的代码格式进行校验
  "prettier.eslintIntegration": true,
  // #去掉代码结尾的分号
  "prettier.semi": false,
  // #使用带引号替代双引号
  "prettier.singleQuote": true,
  // #让函数(名)和后面的括号之间加个空格
  "javascript.format.insertSpaceBeforeFunctionParenthesis": true,
  // #这个按用户自身习惯选择
  "vetur.format.defaultFormatter.html": "js-beautify-html",
  // #让vue中的js按编辑器自带的ts格式进行格式化
  "vetur.format.defaultFormatter.js": "vscode-typescript",
  "vetur.format.defaultFormatterOptions": {
    "js-beautify-html": {
      "wrap_attributes": "force-aligned"
      // #vue组件中html代码格式化样式
    }
  },
}

安装 Ant Design Vue

从 yarn 或 npm 安装并引入 ant-design-vue。

$ yarn add ant-design-vue

安装 antd 导入插件

babel-plugin-import 是一个用于按需加载组件代码和样式的 babel 插件（原理）。

$ yarn add babel-plugin-import --dev

修改babel.config.js文件，配置 babel-plugin-import

 module.exports = {
  presets: ["@vue/app"],
+  plugins: [
+    [
+      "import",
+      { libraryName: "ant-design-vue", libraryDirectory: "es", style: true }
+    ]
+  ]
};

简单测试

修改 main.js 文件如下：

  import Vue from 'vue'
+ import { Button } from 'ant-design-vue';
  import App from './App'

+ Vue.component(Button.name, Button)

  Vue.config.productionTip = false

  new Vue({
    render: h => h(App)
  }).$mount("#app");

修改 src/App.vue的 template 内容。

<template>
  <div id="app">
    <img src="./assets/logo.png">
-    <HelloWorld msg="Welcome to Your Vue.js App"/>
+    <a-button type="primary">Button></a-button>
  </div>
</template>
<script>
  
- import HelloWorld from './components/HelloWorld.vue'

export default {
  name: 'app',
  components: {
-     HelloWorld
  }
}
</script>
...

此时运行 yarn serve 会出现错误。

core-js 错误

出现如下错误提示：

yarn serve                                         
yarn run v1.19.1
$ vue-cli-service serve
 INFO  Starting development server...
98% after emitting CopyPlugin

 ERROR  Failed to compile with 1 errors                                                                                                              10:34:18 AM

This dependency was not found:

* core-js/modules/es.function.name in ./src/main.js

To install it, you can run: npm install --save core-js/modules/es.function.name

解决：

$ yarn add core-js

less-loader 错误

再次运行仍然有错误：

yarn serve
yarn run v1.19.1
$ vue-cli-service serve
 INFO  Starting development server...
98% after emitting CopyPlugin

 ERROR  Failed to compile with 2 errors                                                                                                              10:36:34 AM

Failed to resolve loader: less-loader
You may need to install it.
Failed to resolve loader: less-loader
You may need to install it.

解决

安装 less 和 less-loader

$ npm i less less-loader --save-dev

添加配置文件 vue.config.js ，内容如下：

module.exports = {
  css: {
    loaderOptions: {
      less: {
        javascriptEnabled: true
      }
    }
  }
}

此时运行，正常的话就可以查看页面了。

工程

我们继续使用上一篇文章最后完成的工程：

MenuToolDemo

探索

为了展示左键和右键点击处理的区别，指定不同的行为：

• 左键单击：显示一个提示窗口
• 右键单击：弹出之前的菜单

我们第一反应就是，为按钮设置点击事件直接分开处理就可以了，我们试一下。

1. 打开文件 AppDelegate.swift，修改之前工程中指定 button 图标的代码如下：

   if let button = statusItem.button {
       button.image = NSImage(named: "StatusIcon")
       button.action = #selector(mouseClickHandler)
       button.sendAction(on: [.leftMouseUp, .rightMouseUp])
   }
   

2. 在方法 applicationDidFinishLaunching(_ aNotification:) 后面添加鼠标点击处理方法 mouseClickHandler：

   @objc func mouseClickHandler() {
       if let event = NSApp.currentEvent {
           switch event.type {
           case .leftMouseUp:
               print("左键")
           default:
               print("右键")
           }
       }
   }
   

运行程序，是不是发现，左键和右键单击还都是显示菜单，而没有打印出 左键 和 右键，这是为什么呢？

我们尝试把下面的代码注释掉：

statusItem.menu = menu

再次运行程序，Amazing！是不是左键单击就打印 左键 右键单击就打印出 右键！所以我们能想到的原因就是当指定 menu 后，系统会忽略按钮的事件设置，都只是弹出菜单。

思路

有了上面的探索，是不是就有思路了！目标中右键还是要显示菜单的，所以我们可以在右键单击的时候指定 menu，菜单关闭的时候将 statusItem 的 menu 设置为 nil，这样就保证常态下，menu 是不指定的，就可以响应我们设置的左右键单击的处理了。

实现

1. 删除 applicationDidFinishLaunching 中的 statusItem.menu = menu

2. 修改 mouseClickHandler 的处理如下：

   @objc func mouseClickHandler() {
       if let event = NSApp.currentEvent {
           switch event.type {
           case .leftMouseUp:
               // 使用警告窗口示意左键单击
               let alert = NSAlert()
               alert.messageText = "鼠标事件"
               alert.informativeText = "左键单击"
               alert.addButton(withTitle: "关闭")
               alert.window.titlebarAppearsTransparent = true
               alert.runModal()
           default:
               statusItem.menu = menu
               statusItem.button?.performClick(nil)
           }
       }
   }
   

3. 保证菜单关闭的时候，将 statusItem 的 menu 设置为 nil，扩展一下 AppDelegate，遵循 NSMenuDelegate 在方法 Menu 关闭后指定 nil：

   extension AppDelegate: NSMenuDelegate {
       // 为了保证按钮的单击事件设置有效，menu要去除
       func menuDidClose(_ menu: NSMenu) {
           self.statusItem.menu = nil
       }
   }
   

   需要指定 menu 的代理为 AppDelegate，在 applicationDidFinishLaunching 方法中添加下面的代码:

   menu.delegate = self
   

此时运行程序，鼠标左键单击菜单栏按钮，便会弹出警告窗口，右键单击就能显示菜单了。

平台

• macOS 10.15
• Xcode 11.1
• Swift 5.1

本文使用上述平台实现验证，版本不同可能有些差异，但基本思路一致。

工程新建及配置

• 打开xcode新建工程， macOS -> App -> Next:

  

• 输入工程名称：MenuToolDemo，language 选择Swift，User Interface 选择 SwiftUI(本文不会用到 SwiftUI)点击 Next：

  

• 选择合适的目录，点击 create 即可打开创建的新工程；

• 点击运行按钮，可以看到程序运行，出现一个显示 hello world 的窗口，同时dock上出现了应用图标，这不是我们想要的，设置一下不显示它们：

  • 工程导航栏选中工程MenuToolDemo，打开Info标签页;

  • 可以看到Custom macOS application Target Properties组，添加新的配置Application is agent(UI Element)，布尔属性，值为 YES:

    

• 重新运行程序，可以看到已经不显示Dock图标；

• 删除 ContentView.swift 文件；

• 打开文件AppDelegate.swift，删掉两个地方代码：

  var window: NSWindow!
  

  // Create the SwiftUI view that provides the window contents.
  let contentView = ContentView()
  
  // Create the window and set the content view.
  window = NSWindow(
      contentRect: NSRect(x: 0, y: 0, width: 480, height: 300),
      styleMask: [.titled, .closable, .miniaturizable, .resizable, .fullSizeContentView],
      backing: .buffered, defer: false)
  window.center()
  window.setFrameAutosaveName("Main Window")
  window.contentView = NSHostingView(rootView: contentView)
  window.makeKeyAndOrderFront(nil)
  

• 再次运行程序，主窗口也不显示了，连菜单栏也木有了，不要着急，咱继续。

添加状态栏按钮

打开文件AppDelegate.swift，在类中添加属性，这一步是创建一个状态栏按钮，设置宽度属性NSStatusItem.squareLength，代码如下：

let statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)

状态栏按钮总该需要一个图标吧！打开Assets.xcassets，右击显示AppIcon下方的空白区，选择New Image Set，重命名为statusIcon，当然这个名字随便定，选中这个图集，会看到右侧有配置区，配置图集按照Template Image渲染。

看到有三个虚线框空白区，这就是图片区，状态栏按钮的图片基本大小为 $18px\times18px$ ，还需2倍和3倍的适用于视网膜屏幕的mac，像素分别是 $36px\times36px$ 和 $54px\times54px$ ，可以使用以下我提供的图标：

分别将图拖到对应位置：

找到applicationDidFinishLaunching 在其中添加以下代码，为状态栏按钮配置图标和行为：

if let button = statusItem.button {
    button.image = NSImage(named: "StatusIcon")
}

此时运行程序会看到状态栏中出现了我们定义的按钮，当然此时鼠标单击没有任何动作发生。

前面设置图片集渲染方式为Template Image，是为了适配不同的状态栏主题，因为macOS还有个暗黑主题不是？

两种主题下的效果如下：

添加菜单

打开 Main.storyboard 文件，使用以下两种方式中的任意一种，打开控件库窗口：

• 按下快捷键 Command + Shift + L

• 点击 Xcode 窗口右上角的 ➕ 按钮

在搜索框中输入 Menu，就会检索到 NSMenu 控件：

鼠标左键在控件单击不松拖放到文件 Main.storyboard 的左边栏 First Responder 下面：

按下快捷键 Ctrl + Option + Command + Enter(⌃⌥⌘⏎) 打开 Assitant 编辑器：

按住 Ctrl 键，鼠标左键按住 Menu 控件不松拖动至辅助编辑器的文件 AppDelegate.swift 中，在弹出的属性添加弹窗中输入属性名 menu，点击 Connect 就会看到 AppDelegate.swift 中出现 menu 属性：

statusItem.menu = menu

@IBAction func quitApp(_ sender: Any) {
    NSApplication.shared.terminate(self)
}

购买新脸

去过 Apple 实体店，换屏幕需要四千多大洋，我去，有点猛烈，为了节流，十里决定亲自帮 MBP 换脸，木有办法，需要现便宜买张合适的脸，从某宝网上花了不到两千大洋买了一个屏幕总成，整个上盖包含屏幕，A1707 深空灰版本：

拆屏幕

不得不说，小心翼翼，生怕把后盖弄变形，单单后盖拆了很久，不过掌握了诀窍。MBP 做工极佳，看到内部的设计也会明白为什么卖这么贵了！为了拆屏幕，可是动了不少螺丝和结构，还好的是，不需要拆主板！

安装屏幕

屏幕取下的时候挺费劲的，往上卡屏幕也得小心，再按照倒序还原螺丝和结构的位置就 OK 了：

最后开机，完美点亮屏幕

总结

• 拆机过程中发现电池有鼓包现象，这有点恐怖呀，算了先不理会！我好像拆完后盖，没有先把电池电源断开，好险，没有发生什么问题！😅
• 换完脸之后，第一次开机极慢，据说这是正常现象，我重复重启几次之后就正常了
• 可以开心地拿着 MBP 出去浪了

测试平台

• PlatformIO IDE (VSCode)
• stm32f103c8t6 最小系统板，板载 LED 连接在 PC13 管脚，低电平点亮
• stlink v2 仿真调试器

测试目标：创建 stm32cube 框架的工程项目，实现 LED 周期闪烁的代码

创建工程项目

这一步很简单，注意选择框架 stm32cube^[stm32cube 对应的就是 cubemx 库，详见STM32Cube]，开发板选择 STM32F103C8(20k RAM. 64k Flash)(Generic)，名称随便，最后点击创建即可：

添加例程代码

按照 STM32Cube HAL and Nucleo-F401RE: debugging and unit testing - Adding Code to the Generated Project ^[STM32Cube HAL and Nucleo-F401RE: debugging and unit testing] 描述的过程添加适合自己开发板的代码（修改对应的 LED 管脚即可）。

右键 src 文件夹，新建两个文件，一个是 main.h 另一个是 main.c：

向 mian.h 中添加以下代码，如果您的板载 LED 连接到其它管脚，请相应修改关于 LED 的三个宏定义：

#ifndef MAIN_H
#define MAIN_H

#include "stm32f1xx_hal.h"

#define LED_PIN GPIO_PIN_13
#define LED_GPIO_PORT GPIOC
#define LED_GPIO_CLK_ENABLE() __HAL_RCC_GPIOC_CLK_ENABLE()

#endif  // MAIN_H

向 mian.c 中添加以下代码：

#include "main.h"

void LED_Init(void);

int main(void) {
  HAL_Init();
  LED_Init();

  while (1) {
    // LED 翻转
    HAL_GPIO_TogglePin(LED_GPIO_PORT, LED_PIN);
    HAL_Delay(1000);
  }
}

void LED_Init(void) {
  // LED GPIO 初始化
  LED_GPIO_CLK_ENABLE();
  GPIO_InitTypeDef GPIO_InitStruct;
  GPIO_InitStruct.Pin = LED_PIN;
  GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
  GPIO_InitStruct.Pull = GPIO_PULLUP;
  GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_HIGH;
  HAL_GPIO_Init(LED_GPIO_PORT, &GPIO_InitStruct);
}

void SysTick_Handler(void) { HAL_IncTick(); }

确保把 stm32f103c8t6 的最小系统板通过 stlink 连接到电脑 usb，编译并上传程序：

what？ LED 竟然没有如期的闪动起来!

解决问题

代码都正确呀，为什么程序没有正常工作呢?首先怀疑对象是系统时钟，用示波器测试了一下芯片的高速晶振管脚，竟然没有起振，哎呀，我们确实没有添加系统时钟配置的代码，再次对照一下用 STMCubeMX^[STM32CubeMX is a graphical tool that allows a very easy configuration of STM32 microcontrollers and microprocessors, as well as the generation of the corresponding initialization C code for the Arm® Cortex®-M core or a partial Linux® Device Tree for Arm® Cortex®-A core), through a step-by-step process.——STM32CubeMX] 生成的普通项目的源码，确实我们的工程中缺少了对于时钟的配置。

为了解决这个问题，参考了 STMCubeMX 项目，笔者建议除了添加时钟的配置之外，还要加一些可能以后会用到的处理函数。这里我们添加两个新的文件 sys_basic.h 和 sys_basic.c。

文件 sys_basic.h 内容如下：

#ifndef SYS_BASIC_H
#define SYS_BASIC_H

void _Error_Handler(char*, int);
#define Error_Handler() _Error_Handler(__FILE__, __LINE__)

void SystemClock_Config(void);

#endif

文件 sys_basic.c 内容如下：

#include "sys_basic.h"
#include "stm32f1xx_hal.h"

/** System Clock Configuration
 */
void SystemClock_Config(void) {
  RCC_OscInitTypeDef RCC_OscInitStruct;
  RCC_ClkInitTypeDef RCC_ClkInitStruct;

  /**Initializes the CPU, AHB and APB busses clocks
   */
  RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE;
  RCC_OscInitStruct.HSEState = RCC_HSE_ON;
  RCC_OscInitStruct.HSEPredivValue = RCC_HSE_PREDIV_DIV1;
  RCC_OscInitStruct.HSIState = RCC_HSI_ON;
  RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON;
  RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE;
  RCC_OscInitStruct.PLL.PLLMUL = RCC_PLL_MUL9;
  if (HAL_RCC_OscConfig(&RCC_OscInitStruct) != HAL_OK) {
    _Error_Handler(__FILE__, __LINE__);
  }

  /**Initializes the CPU, AHB and APB busses clocks
   */
  RCC_ClkInitStruct.ClockType = RCC_CLOCKTYPE_HCLK | RCC_CLOCKTYPE_SYSCLK |
                                RCC_CLOCKTYPE_PCLK1 | RCC_CLOCKTYPE_PCLK2;
  RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK;
  RCC_ClkInitStruct.AHBCLKDivider = RCC_SYSCLK_DIV1;
  RCC_ClkInitStruct.APB1CLKDivider = RCC_HCLK_DIV2;
  RCC_ClkInitStruct.APB2CLKDivider = RCC_HCLK_DIV1;

  if (HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_2) != HAL_OK) {
    _Error_Handler(__FILE__, __LINE__);
  }

  /**Configure the Systick interrupt time
   */
  HAL_SYSTICK_Config(HAL_RCC_GetHCLKFreq() / 1000);

  /**Configure the Systick
   */
  HAL_SYSTICK_CLKSourceConfig(SYSTICK_CLKSOURCE_HCLK);

  /* SysTick_IRQn interrupt configuration */
  HAL_NVIC_SetPriority(SysTick_IRQn, 0, 0);
}

/**
 * @brief  This function is executed in case of error occurrence.
 * @param  None
 * @retval None
 */
void _Error_Handler(char* file, int line) {
  /* USER CODE BEGIN Error_Handler_Debug */
  /* User can add his own implementation to report the HAL error return state */
  while (1) {
  }
  /* USER CODE END Error_Handler_Debug */
}

void NMI_Handler(void) {}

void HardFault_Handler(void) {
  while (1) {
  }
}

void MemManage_Handler(void) {
  while (1) {
  }
}

void BusFault_Handler(void) {
  while (1) {
  }
}

void UsageFault_Handler(void) {
  while (1) {
  }
}

void SVC_Handler(void) {}

void DebugMon_Handler(void) {}

void PendSV_Handler(void) {}

时钟初始化在函数 SystemClock_Config 中实现，这里时钟源选择使用 8M 高速晶振、9倍频等等常用的时钟配置，在 main.c 中包含头文件 sys_basic.h 并在主函数 HAL_Init(); 后加入时钟初始化函数调用 SystemClock_Config();。

此时编译上传程序，可以看到 LED 如期灵动了起来！

调试程序

调试程序与使用 Arduino 框架时一致，需要在配置文件中指定调试工具，这里使用的是 stlink ，所以 paltformio.ini 的内容如下：

[env:genericSTM32F103C8]
platform = ststm32
board = genericSTM32F103C8
framework = stm32cube
debug_tool = stlink

点击 F5 按键便可以进行程序调试了！

总结

本文简单讲解了创建 stm32cube 框架的 PIO 工程的过程、遇到的问题及解决方法，希望对初次使用 PIO 开发 stm32cube 项目的同学有所帮助！

硬件连接

本文的实现驱动的硬件条件如下：

• STM32F103C8T6 最小系统板
• stlink v2 仿真调试器
• VS1838B 红外接收头
• 常规的红外遥控器

VS1838B 有三个管脚，VCC 、 GND 和 OUT，搭建的硬件电路很简单，不需要其他的配套电路，直接连接单片机管脚和电源就能正常使用，这里我将管脚连接到 PA0 管脚。

红外相关知识

要想编写红外驱动需要了解红外接收器输出得信号特点，根据 VS1838B 输出信号有的放矢的设计信号解析驱动。

笔者手头的红外遥控器采用 NEC 编码协议^[ NEC红外线编码协议]，其中红外发射芯片会自动扫描矩阵键盘电路，根据不同的键码，生成一串二进制数据，再按每位的二进制数据用相应的红外光信号发出。遥控器上的一个按键按下后的 bit 数据:

引导码用于标识一个键码数据的传输开始，将传输 32 位数据，共四个字节，按照先低位后高位传输。第一个字节为用户编码，用于标识遥控器的厂家，第二个字节为用户编吗的反码，用于校验用户编码。第三个字节是按键编码用于区别按下的键，第四个字节为按键编码的反码，用于校验按键编码, 从而确保红外线传输的数据的有效性。

引导码、位数据 0 和位数据 1 信号特征明显，可以参考如下：

上面就是红外要发射数据的格式了，真正发射光信号的时候，其实是将待发射的数据调制到一个 38KHz 的光信号中的，红外接收头比如 VS1838B，接收到这个信号后会对信号进行信号放大、带通滤波、解调、波形整形最终还原出原始的 NEC 协议按键编码，但是要注意的是从 VS1838B 输出的信号是与原始编码反相的^[35 红外接收头在linux内核里的驱动]，通俗讲就是高低电平是反着的。

驱动设计思路

为了找到解析 VS1838B 输出信号的方法，我们还是得先分析一下引导码、位数据 0 和 位数据 1 的特征，其实我们只要找到能区分这三个信号的方法即可。

观察上一小节信号特征图，可以发现三种信号最明显的区别就是低电平时间：

但是我们知道 VS1838B 输出信号是与图中高低信号相反的，所以针对 VS1838B 的输出信号，我们只需要判断每段高电平的时间就可以区分出引导码、位数据 0 和 位数据 1。

一组红外数据的信号是以引导码开始的，所以正常状态下一旦判断到是引导码，下面就应该通过区分位数据信号来保存位数据生成字节数据了，需要连续分辨 32 位数据是 0 或 1即可。

为了保证及时的判断管脚电平的变化，这里采用 IO 外部中断的方式，在中断子程序中实现解析逻辑，解析数据之前关键的一点还是得到高电平时间，将外部中断触发方式设置为电平变化触发，也就是无论电平下降沿还是上升沿都会触发中断。

中断处理逻辑中，加入状态机的处理形式，可分两种状态：

• 正常状态：等待引导码
• 接收数据状态：解析 0、1 数据

最终结果存储在一个 32 位整型数据中，那么整个中断的处理逻辑步骤可参考如下：

1. 判断进入中断时管脚电平
   • 如果是高电平，记录此刻时间，退出中断
   • 如果是低电平，用此刻时间减去记录的时间就得到了高电平脉冲宽度（单位 us），然后进行第 2 步
2. 判断此时状态：
   • 如果是正常状态，脉宽如果大于 4000us 说明是引导码，此时将状态切换为接收数据状态，结果置为 0，然后退出中断
   • 如果是接收数据状态，判断脉宽如果在 1120us 和 2240us 之间说明是 1 ，将结果的对应位置 1 ，然后判断是否接受完所有位：
     • 如果是，对结果进行校验（利用反码），如果正确进行数据处理
     • 如果没有，退出中断

驱动程序实现

根据上述思路设计了红外接收驱动程序，以库的形式对程序封装，声明对象只需指定管脚和处理回调函数即可，在 PlatformIO IDE 项目工程目录 lib 中新建 IrRemote 目录，目录下放置源代码 irRemote.h 和 irRemote.cpp。理论上只要是使用 Arduino 框架，并且管脚支持 IO 外部中断，均可以正常使用。

irRemote.h

#ifndef IRREMOTE_H_
#define IRREMOTE_H_

#include "Arduino.h"

typedef void (*IrRemoteCBPtr)(uint32_t);

enum IrRemoteState { WAITING, READING };

/**
 * @brief 红外接收结果联合体
 *
 * 定义红外接收联合体是为了可以从原生的 32 位数据，轻松获取字节数据
 */
union IrRemoteResult {
  uint32_t value;
  uint8_t bytes[4];
};

class IrRemote {
 public:
  /**
   * @brief 红外类的构造函数
   *
   * 指定红外的管脚和回调函数
   *
   * @param pin 连接红外数据输出的管脚
   * @param callback
   * 收到数据后要执行的回调函数，回调函数具有一个参数用于传递数据结果
   */
  IrRemote(uint8_t pin, IrRemoteCBPtr callback);

  /**
   * @brief 红外数据接收处理函数
   *
   * 分析红外输出电平及持续时间，解析得到数据
   */
  void handler(void);

  /**
   * @brief 启动红外接收
   *
   * 开启红外数据解析逻辑
   */
  void begin(void);

  /**
   * @brief 关闭红外接收
   *
   * 关闭红外数据解析逻辑
   */
  void end(void);

 private:
  uint8_t pin;             // 连接红外输出的管脚
  uint32_t time;           // 上一次 FALLING 的时刻，单位 us
  uint32_t width;          // 脉冲宽度，单位 us
  uint32_t count;          // 数据接收位数计数
  IrRemoteState state;     // 处理状态
  IrRemoteResult result;   // 收到的数据结果
  IrRemoteCBPtr callback;  // 收到数据的回调函数

  /**
   * @brief 红外接收结果校验
   *
   * 校验红外接收结果，最后两个字节互为反码即为正确结果
   *
   * @param result 解析得到的红外接收结果
   */
  bool check(IrRemoteResult result);
};

#endif

irRemote.cpp

#include "irRemote.h"

void nullCB(uint32_t _) {}

void irRxHandler(IrRemote *ir) { ir->handler(); }

IrRemote::IrRemote(uint8_t pin, IrRemoteCBPtr callback) {
  this->pin = pin;
  this->callback = callback;

  pinMode(this->pin, INPUT);
}

void IrRemote::handler() {
  if (digitalRead(this->pin) == HIGH) {
    this->time = micros();
  } else {
    this->width = micros() - this->time;
    switch (this->state) {
      case WAITING:
        if (this->width > 4000 && this->width < 10000) {
          this->state = READING;
          this->count = 0;
          this->result.value = 0;
        }
        break;
      case READING:
        if (this->width > 1120 && this->width < 2240) {
          this->result.value |= (0x00000001 << this->count);
        }
        this->count++;
        if (this->count >= 32) {
          this->count = 0;
          this->state = WAITING;
          if (check(this->result)) {
            detachInterrupt(this->pin);
            this->callback(this->result.value);
            attachInterrupt(this->pin, (voidArgumentFuncPtr)irRxHandler, this,
                            CHANGE);
          }
        }
        break;
      default:
        break;
    }
  }
}

void IrRemote::begin() {
  this->state = WAITING;
  attachInterrupt(this->pin, (voidArgumentFuncPtr)irRxHandler, this, CHANGE);
}

void IrRemote::end() { detachInterrupt(this->pin); }

bool IrRemote::check(IrRemoteResult result) {
  if ((result.bytes[3] + result.bytes[2] == 0xFF) &&
      (result.bytes[1] + result.bytes[0] == 0xFF)) {
    return true;
  }
  return false;
}

测试驱动

编写一个例程测试一下驱动，当收到数据的时候通过串口把数据打印出来，main.cpp 内容如下：

#include <Arduino.h>
#include "irRemote.h"

void test(uint32_t result) { Serial.println(result, HEX); }

IrRemote ir(PB0, test);

void setup() {
  // 启动红外接收
  ir.begin();
  Serial.begin(9600);
}

void loop() {}

将连接了 VS1838B 的 stm32f103c8t6 最小系统板通过 stlink 连接电脑同时将其 usb 直连到电脑，编译上传程序，待运行以后，打开串口调试助手，对着 VS1838B 按下红外遥控按钮，便可以看到对应的 32 位原数据(从高位到低位四个字节分别是按键编码反码、按键编码、用户编码反码、用户编码)：

总结

本文讲的红外驱动实现思路对于 NEC 协议的红外数据解析应该是通用的，笔者因为使用了 Arduino 框架，所以是以 Arduino 为基础设计的驱动程序，当然不使用 Arduino 框架也可以按照实现思路进行设计对应的驱动，思路可行就可以！希望本文介绍的思路能够帮到您！

前言

本文将使用 Arduino Leonardo 讲解，以文章 PlatformIO IDE(VSCode) 基本使用 - 新建项目 中新建的控制 LED 闪烁的工程（blink）为例。

这个工程中 LED 的控制是阻塞式的，因为使用了 delay 方法，就是死等延时这造成了运算资源的浪费，有没有更好的方法控制 LED 按周期闪烁，而不阻塞呢？笔者很自然地想到了用定时器控制 led 就行啦，所以这就有了我们的新的需求，有没有第三方库支持定时器操作呢！

PIO 提供了很好的方式帮助我们查找和管理第三方库，在下一小节跟笔者一起看一下如何找到我们需要的第三方库。

第三方库的管理

首先我们打开 blink 工程，然后打开 PIO Home 页面，点击左侧的 Libraries 标签打开库的标签页，我们会看到库的标签页中有四个标签页分别是：

• Registry：仓库，在这里我们可以查找我们需要的第三方库，也能看到按照下载量排序的关键词标签，也能看到最近库的下载排名
• Installed：在这里我们能看到曾经安装的库，并对它们进行管理
• Build-in：在这里我们能看到安装的平台和框架中内建的库
• Updates：在这里我们能看到需要更新的库

库的查找

按照上面提到的需求，我们在 Registry 标签页中查找库，我们在搜索框中搜索定时器对应的英文 Timer:

可以看到会列出搜索到的结果，搜索优先会按照框架进行关键词搜索，我们看一下具体的一个条目，比如第一个库 Ticker，每个条目包含的信息如下：

• 名称及功能描述
• 适用的框架
• 适用的平台
• 关键词标签
• 其它：下载量、例程数

根据第一个描述就符合我们的需求呀，我们点击一下进入库的页面：

可以看到有五个标签页，这里简单说明一下：

• Examples：展示库中包含的例程，有的包含多个，可以点击下拉列表选择不同的例程查看代码
• Installtion：展示如何在项目工程中使用库，在 platformio.ini 文件中如何配置
• Headers：库中包含的头文件
• Manifest：这个一般不用关心，展示的是这个库在 PIO 仓库中的配置信息
• Changelog：更新日志

库的安装

安装库一般是两种形式，一种是全局安装，其他项目工程也能够使用，另一种是只安装到指定项目工程中。

点击 Install 会默认全局安装，这样其它的工程项目也能使用而不用重复安装。

另外，也可以点击 Install 按钮右边的 ... 按钮完成指定位置的安装：

这里我们采用全局安装，点击 Install 按钮即可，库安装完成后会有弹窗提示。

库的卸载

有时有些库可能不再会使用，如果想卸载怎么操作？找到 Librairies 的 Installed 标签页，就会看到我们刚才安装的 Ticker 库，可以看到 Uninstall 按钮，点击它按照提示操作即可完成卸载，点击 Reveal 按钮会打开安装库的目录：

库的更新

PIO Home 启动后会检测库的更新，如果库有新的版本发布，就会在 Libraries - Updates 页面出现待更新的库，点击 Update 按钮即可实现更新！

库的使用

配置

使用第三方库的方式会在库的页面的 Installtion 标签页展示，比如 Ticker 库的：

需要在 paltformio.ini 文件中添加 lib_deps 项，指定库即可，主要有三种方式：

lib_deps =
# 使用库的名称
    Ticker

# ... 或者使用库的 ID
    1586

# ... 或者使用指定版本的库
    Ticker@3.1.5
    
# Semantic Versioning Rules
# http://docs.platformio.org/page/userguide/lib/cmd_install.html#description
# Ticker@^3.1.5
# Ticker@~3.1.5
# Ticker@>=3.1.5

我们这里采用第一种方式，最终 blink 项目的 platformio.ini 内容如下：

[env:leonardo]
platform = atmelavr
board = leonardo
framework = arduino
lib_deps =
  # Using a library name
  Ticker

这里要注意的是，一个项目工程极有可能会使用多个库，这是有两种语法配置：

; one line definition (comma + space)
[env:myenv]
lib_deps = LIBRARY_1, LIBRARY_2, LIBRARY_N

; multi-line definition
[env:myenv2]
lib_deps =
  LIBRARY_1
  LIBRARY_2
  LIBRARY_N

使用库

这样我们就可以在工程中源代码中包含库的头文件然后使用库了，因为毕竟是别人的写的库，所以应该先看一下例程的用法，然后根据自己的需求实现自己需要的功能。

比如还是实现 1s 切换一次 LED 状态实现等的闪烁，只需要编写相应的处理函数，定义新的 Ticker 指定处理函数和时间参数即可，代码如下：

#include <Arduino.h>
#include <Ticker.h>

void blink() {
  static uint32_t state = 0;
  state ^= 1;
  digitalWrite(LED_BUILTIN, state);
}

Ticker timer(blink, 1000, 0, MILLIS);

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
  timer.start();
}

void loop() {
  timer.update();
  //放置其它处理操作
}

编译上传程序，顺利的话同样实现了 LED 的秒闪烁。

结语

本文只是简单的说了库管理和使用的基本常用操作，可以满足基本使用需求了，如果需要了解更多内容，可以参考：Library Manager。

基本概念

在使用 PlatformIO 的过程中经常会遇到一些词，比如 Platform 、 Framworks 以及 Boards，在新建项目之前有必要先说明一下，这些具体都代表了什么！

Platform

直译的话就是 平台，具体就是指的芯片平台，再详细一点那就是各个公司具体的系列芯片的开发平台了。目前为止 PIO^[PIO 是 PlatformIO 的简称，后面系列文章会经常使用这个简称] 针对支持的平台都有以下功能支撑：

• 支持指定框架的基于脚本的编译构建系统
• 针对各公司常规开发板的预配置
• 提供多架构的构建工具及相关工具链的支持

PIO 目前支持的平台分为嵌入式和桌面两大类。

• 嵌入式平台

  • Aceinna IMU
  • Atmel AVR
  • Atmel SAM
  • Espressif 32
  • Espressif 8266
  • Freescale Kinetis
  • Infineon XMC
  • Intel ARC32
  • Intel MCS-51 (8051)
  • Kendryte K210
  • Lattice iCE40
  • Maxim 32
  • Microchip PIC32
  • Nordic nRF51
  • Nordic nRF52
  • NXP LPC
  • RISC-V GAP
  • Samsung ARTIK
  • SiFive
  • Silicon Labs EFM32
  • ST STM32
  • ST STM8
  • Teensy
  • TI MSP430
  • TI TIVA
  • WIZNet W7500

• 桌面平台

  • Native
  • Linux ARM
  • Linux i686
  • Linux x86_64
  • Windows x86

上面也有前面文章中使用到的 ST STM32，Atmel AVR 一般指的就是 Arduino 系列开发板使用的芯片，说到 Arduino ，它其实就是一个完整的生态，提供开源的硬件开发板的设计以及 Arduino 统一的软件开发包就是所谓的 Frameworks。

Frameworks

上面已经提到 Frameworks 其实就是类似于 SDK 的一个东西，全世界最有名的 Arduino 有自家的一套 SDK，那就是 Arduino，框架基本特征就是提供一整套一致的 API 的集合，本质是一个官方或第三方提供的软件库。

因为 Arduino 极具影响力，所以很多芯片平台也都有了自己的 Arduino 框架，现在 Arduino 框架平台支持的平台有很多：Atmel AVR、Atmel SAM、Espressif 32、Espressif 8266、Infineon XMC、Intel ARC32、Kendryte K210、Microchip PIC32、Nordic nRF51、Nordic nRF52、T STM32、ST STM8 、Teensy、TI MSP430 、TI TIVA ^[更多关于 Arduino 框架的信息参考：https://docs.platformio.org/en/latest/frameworks/arduino.html]。

反过来讲，一个平台有可能支持多个不同开发框架，比如 ST STM32 支持的开发框架有：Arduino、CMSIS、libOpenCM3、mbed、SPL、STM32Cube^[更多关于 stm32 单片机开发平台的信息参考：https://docs.platformio.org/en/latest/platforms/ststm32.html]。

PIO 支持的框架也是有很多，总有适合你的：

• Arduino
• ARTIK SDK
• CMSIS
• ESP8266 Non-OS SDK
• ESP8266 RTOS SDK
• ESP-IDF
• Freedom E SDK
• Kendryte FreeRTOS SDK
• Kendryte Standalone SDK
• libOpenCM3
• mbed
• PULP OS
• Pumbaa
• Simba
• SPL
• STM32Cube
• Tizen RT
• WiringPi

详见：https://docs.platformio.org/en/latest/frameworks/index.html

Boards

PIO 支持绝大部分流行的开发板，比如 Arduino 的全系开发板、STM32 的 Nucleo 和 Discovery 系列评估板。有太多太多了，这里就没必要一一罗列了，可以查看下面的链接了解更多关于开发板的支持列表：

https://docs.platformio.org/en/latest/boards/index.html

PIO 针对支持的开发板都提供完整的项目生成脚本，新建项目从未如此快捷和简单！

新建项目

这里我们以新建一个 Arduino Leonardo 的项目为例。

• 打开 PIO Home：打开新的 VSCode 的窗口，点击左下角状态栏的第三个小房子按钮，就能打开 PIO Home 页面了：

  

• 点击项目操作按钮的 + New Project，在弹窗中分别填入或选择 Name、Board、Framework 点击 Finish：

  

• 稍作等待，PIO 会自动根据选择的 Board 和 Framework 配置工程并且下载需要用到的编译工具，需要的编译依赖什么的 PIO 通通帮我们搞定，一段时间过后项目工程就新建完成了，打开 src 文件夹下的 main.cpp 如下：

  

项目文件结构

项目文件结构要了解一下，方便后期自己手动管理项目。

• .pio，存放工程编译产生的文件
• .vscode, 存放针对工程定制化的 vscode 配置文件
• include，存放统一管理的 h 头文件
• lib，存放自己编写的库文件
• src，存放工程项目的 C/C++ 源文件
• test，存放工程项目的测试文件，一般用不到
• .gitignore，git 仓库的忽略文件，方便 git 进行工程项目的版本控制
• travis.yml，持续集成的配置文件，一般用不到
• platformio.ini，项目的核心配置文件，这个会经常用到，所以得了解其中可用的配置项^[详见：“platformio.ini” (Project Configuration File)]

编译和上传

新建了项目工程之后，就是进行开发了，必然要用到编译代码，要将编译生成的二进制文件上传到开发板的芯片中。

为了看到效果，我们编写一段让板载 LED 闪动的实现：

#include <Arduino.h>

void setup() {
  // put your setup code here, to run once:
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  // put your main code here, to run repeatedly:
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
  digitalWrite(LED_BUILTIN, LOW);
  delay(1000);
}

在这之前有必要了解一下 PIO 的工具栏按钮：

Tip:

如果使用 Arduino 框架代码中，一定要包含头文件 Arduino.h。

编译项目工程

将上面的代码录入 src 目录下的 main.cpp 文件中，看文件名就知道使用的是 c++ 编程语言了。多种方式可以触发编译，比如笔者经常用的两种方式：

• 点击上面截图底部中工具栏的第二个对号图标
• 按下组合键 CTRL + ALT + B

还有两种方式可以触发编译任务：

• 按下组合键 CTRL + SHIFT + P (macOS 下是 COMMAND + SHIFT + P)，然后输入关键字 platformio，选择 Build
• 点击窗口左边栏的蚂蚁头的图标会打开 PlatformIO 的工具栏，点击其中的 Build

顺利的话，触发了编译，很快就会在终端窗口提示编译完成：

> Executing task: platformio run <

Processing leonardo (platform: atmelavr; board: leonardo; framework: arduino)
------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: https://docs.platformio.org/page/boards/atmelavr/leonardo.html
PLATFORM: Atmel AVR 1.15.0 > Arduino Leonardo
HARDWARE: ATMEGA32U4 16MHz, 2.50KB RAM, 28KB Flash
PACKAGES: toolchain-atmelavr 1.50400.190710 (5.4.0), framework-arduinoavr 4.1.1
LDF: Library Dependency Finder -> http://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 7 compatible libraries
Scanning dependencies...
No dependencies
Checking size .pio/build/leonardo/firmware.elf
Memory Usage -> http://bit.ly/pio-memory-usage
DATA:    [=         ]   5.8% (used 149 bytes from 2560 bytes)
PROGRAM: [=         ]  14.4% (used 4130 bytes from 28672 bytes)
============================ [SUCCESS] Took 0.66 seconds ============================

上传

先把手头的 Arduino Leonardo 开发板与电脑连接，直接触发上传任务即可，甚至不用自己去选择接口，PlatformIO 会自动查找与电脑连接的端口进行判断然后上传程序，笔者经常会用到的触发方式：

• 组合键 CTRL + ALT + U
• 点击窗口状态栏中 PIO 工具栏的第三个按钮→

第一次上传程序的时候，PIO 往往会先根据板子芯片对应的平台选择合适的上传工具包，所以第一次上传可能需要等一会儿，顺利的话也会在终端窗口看到 Sucess 的消息，同时会看到 Leonardo 板载 LED 开始闪烁：

总结

PIO 让新建芯片开发的项目工程变得异常简单，只需几小步就可以完成，另外本文也简单说了一下程序的编译和上传操作，同样简单方便！希望本文能够帮助想要体会 PlatformIO 魅力的朋友！

官方称其为 PIO Unified Debugger，很好理解，就是统一的调试器，意思是凡是 PIO 支持的可调式的 MCU 开发平台均可以使用统一功能的调试器，PIO 跨平台的特性仍然支持程序调试，也就是说在 windows、linux和 macOS 下均可以得到相同的开发体验。

You should have PIO Account to work with PIO Unified Debugger. A registration is FREE.

官方说明免费使用这个调试功能需要登录一个 PIO 账户，这个很简单嘛，注册一个然后在 VSCode 的 PIO IDE 中登录即可，这可能是唯一的限制了！

功能特性

官方文档中提到 VScode 搭建的 PIO 开发环境可以提供最强大的调试功能特性，包括以下：

• 局部、全局和静态变量的浏览器 (Local, Global, and Static Variable Explorer)
• 条件断点 (Conditional Breakpoints)
• 表达式监控 (Expressions and Watchpoints)
• 通用寄存器检阅 (Generic Registers)
• 外设寄存器检阅 (Peripheral Registers)
• 内存数据检阅器 (Memory Viewer)
• 汇编检阅 (Disassembly)
• 多线程支持 (Multi-thread support)
• 调试会话的热重启和激活 (A hot restart of an active debugging session)

以下为 genericSTM32F103C8 开发板使用 Arduino 开发框架时调试程序时的界面：

实践

下面我们就以 genericSTM32F103C8 开发板使用 Arduino 开发框架为例讲解一下，调试程序是多么的简单。

前提条件

开发环境

• 已经安装 vscode
• vscode 已经安装 PlatformIO IDE 插件

上述条件满足后，打开 vscode 新的窗口，会如下图中所示，左边栏多出 PlatformIO 的logo，以及最下边状态栏左边有个小房子的图标：

硬件

• 一个 stm32f103c8t6 的最小系统板
• stlink v2 调试器

PIO 账户

如果没有 PIO 账户那就先注册一个，打开 vscode 点击上图中提到的小房子的图标就会打开 PlatformIO 的管理页面，点击右上角的 PIO Account 图标

此时会跳转到 PIO 账户登录页面，登录按钮下面有一个链接 create a new one ，点击一下即可进入注册页面：

输入自己的邮箱，点击注册按钮即可完成注册， PlatformIO 会自动生成一个密码发到你的邮箱，返回到登录页面输入邮箱和密码登录即可。

新建项目

返回到 Home 页面，点击 New Project 按钮开始新建项目，这里项目名称定义为 c8t6Blink，一个控制 LED 闪烁的简单例子，Board 就选 STM32F103C8(20k RAM. 64k Flash)(Generic) ，然后使用 Arduino 框架，最后点击 Finish 即可创建项目：

初次创建可能需要时间会长一点，会下载编译需要的一些依赖工具包，以后再创建相同平台项目的时候就很快了。

编写程序

手头上这个最小系统板上的 LED 是 PB0 管脚控制的，硬件设计是低电平 LED 点亮，所以一个简单的闪灯程序如下：

#include <Arduino.h>

#define LED_PIN PB0

void setup() {
  // put your setup code here, to run once:
  pinMode(LED_PIN, OUTPUT);
}

void loop() {
  // put your main code here, to run repeatedly:
  digitalWrite(LED_PIN, LOW);
  delay(100);
  digitalWrite(LED_PIN, HIGH);
  delay(900);
}

点击底部状态栏左边的小对号图标就可以进行编译，编译完成后点击右边向右的箭头图标就可以烧写程序，初次上传烧写需要时间长一些，PIO 需要下载一些相关工具包，以后就是正常上传程序了，完成后就能看到程序正常运行，LED 闪了起来。

调试程序

按下 F5 按键即可触发程序调试，本以为会出现类似本篇文章第一张图的样子，结果会出现以下错误：

> Executing task: platformio debug <

Error: Please specify `debug_port` for environment
终端进程已终止，退出代码: 1

终端将被任务重用，按任意键关闭。

为什么会出现这个错误？原因很简单，PIO 不知道我们是用什么调试工具进行程序调试，所以需要在项目配置文件 platformio.ini 中指明一下我们使用 stlink 进行调试：

[env:genericSTM32F103C8]
platform = ststm32
board = genericSTM32F103C8
framework = arduino
debug_tool = stlink

此时点击 F5 就可以正常触发调试了，可以看到启动调试程序默认停到 main 中第一句。

• 顶部会看到调试工具栏，可以实现调试会话的重启、程序启停、执行等操作按钮
• 可以在代码编辑器行号前面单击添加或删除断点
• 左侧调试工具区点击 PERIPHERALS 栏，可以查看所有外设寄存器配置，方便验证寄存器配置正确与否
• MEMORY 栏可以添加内存地址来查看指定字节的数据，方便验证指针数据
• 监视 中可以添加监测变量，随时查看变量变化
• 变量 中展示了所有当前断点可检阅的全局、局部以及静态变量
• 调用堆栈 中展示了函数的调用层次
• 调试控制台的最下方可以输入 adb 命令，从而实现更强大的调试操作
• DISASSEMBLY 栏可以控制切换汇编窗口方便查看汇编代码

开发平台

• macOS 10.14.4
• Swift 5
• xcode 10.2

概述

所有 macOS 程序要呈现用户界面都是以 Windows 作为容器的，当然除了纯粹的命令行工具和菜单栏小工具。Windows 定义了 App 在屏幕中的活动区域，在这个区域内允许用户进行易于理解的多任务交互操作。macOS 应用最终可分为以下几种：

• 单窗口的工具，比如计算器

  

• 单窗口的 library-style 应用，比如照片应用(Photos.app)

  

• 基于文档的多窗口应用，比如文本编辑应用(TextEdit.app)

  

不管属于哪一类的应用，几乎每一个 macOS 应用都是使用 MVC (Model-View-Controller) 构建的，这是 macOS 开发中核心的开发模式。

Cocoa 应用中，一个窗口是 NSWindow 类的一个实例(window 就是 view 的容器)，其与控制器紧密配合工作，而控制器是 NSWIndowController 的一个实例。在一个设计良好的应用中会发现通常窗口和控制器是一一对应的，而 MVC 模式中的第三个组成部分——模型(model)的使用会根据应用的类型和设计而不同。

在本文中我们会创建一个有点像 TextEdit 的应用，是 document based 的，我管它叫 5kmEditor，这个名字随便，只要您喜欢啥都行！在我们开发过程中，将会涉及到以下内容：

• 窗口 和 窗口控制器
• document 架构
• NSTextView
• 模态窗口
• 菜单栏和菜单项

搞起

启动 Xcode，按快捷键 Shift + Command + n ，新建工程，选择 macOS -> Cocoa App，点击 Next：

新出现的窗口中，勾选 Create Document-Based Application，应用的名称随意取，比如 5kmEditor，然后 Document Extention 这一项指定文件的扩展名，其决定以后应用保存文件的扩展名，比如十里指定的是 5km，可以不勾选包含测试，点击 Next：

选择合适的目录，点击 Create 创建即可，创建成功后编译运行，你会看到类似下面的窗口：

此时，按快捷键 Command + n 或者菜单栏点击 File -> New，可以创建新的窗口如下：

Document-Based 应用如何工作

上面也看到了这类应用的样子，下面花几分钟一起看一下 Document-Based 应用如何工作的。

Document 的结构

一个 Document 其实就是 NSDocument 的一个实例对象，文档模型 NSDocument 作为模型保存了文档的数据，同时负责文档窗口控制器 NSWindowController 的创建管理，它管理文档数据，负责文档打开时数据读取的管理和文档对象管理的数据保存到文件的处理，而文件有可能是在硬盘也有可能在 iCloud，均支持。

创建关联的 NSWindowController 负责展示文档的内容，内容视图最终相应处理用户对文档操作的各种交互事件。

NSDocumentController 是一个单例对象，主要负责文档模型 NSDocument 的管理工作，维护系统中所有的文档模型 NSDocument 列表，控制多个文档窗口的激活切换，同时跟踪当前活动文档对象，最终结构图如下：

禁用 Document 的保存和打开

Document-Based 应用的 Documnent 架构支持文件的保存和打开，但是需要定义 Document 类中自己具体实现，本文暂不涉及这部分内容，所以先禁用 Document 的保存和打开。

打开文件 Document.swift，会发现有两个函数是空的：

• data(ofType:): 用于写文件
• read(from:ofType:): 用于读取文件

同时还有一个函数是 autosavesInPlace()->Bool，更改返回值为 false:

override class var autosavesInPlace: Bool {
    return false
}

这样我们首先禁用了自动保存功能，下面我们需要禁用菜单栏 File 中的保存和打开菜单项。在这之前，我们运行程序，点击 File -> Open ，竟然会弹出打开文件的窗口，很神奇，我们并没有实现打开呀，为什么会出现文件打开窗口呢？

其实是因为 Open 的菜单项绑定了具体的 Action，Action中实现了这些，所以我们只需要断开菜单项与 Action 的链接就可以禁用掉菜单项，视觉上的表现就是菜单栏相应菜单项会变灰色不可用。

打开 Main.storyboard ，找到 Application Scene，点击菜单栏中 File，选择其中的 Open，右击会看到所有的连接，点击 Sent Action 中连接右侧的 x 号，即可断开连接：

同样的操作，分别将 Save...、Save As... 和 Reverrt to Saved 与相应的 Action 断开连接。

然后删除 Open Recent 菜单项，最后我们重写一下 save(withDelegate:didSave:contexInfo:) 方法，后面我们会用到，主要是添加一个错误🙅‍提醒窗口，打开 Document.swift 文件，在 Document 类中添加重写方法如下：

override func save(withDelegate delegate: Any?, didSave didSaveSelector: Selector?, contextInfo: UnsafeMutableRawPointer?) {
    let userInfo = [NSLocalizedDescriptionKey: "Sorry, no saving implemented in this post. Click 'Do not save' to quit!"]
    let error = NSError(domain: NSOSStatusErrorDomain, code: unimpErr, userInfo: userInfo)
    let alert = NSAlert(error: error)
    alert.runModal()
}

运行程序，此时会看到菜单栏的相应菜单项已经禁用：

窗口显示

上面新建文件的时候，我们发现新建文档的窗口完全覆盖了之前的文档窗口，然而这不是我们想要的结果，本节就聊一下怎么合理布局窗口的位置。进行改造前，我们需要新建一个 NSWindowController 的子类，然后添加相应的代码实现我们预期的功能。

新建 NSWindowController 的子类

工程导航栏选择 5kmEditor，按下快捷键 Command + n，就会弹出新建文件的导航窗口，选择 macOS -> Source -> Cocoa Class，点击 Next

取名为 WindowController，选择继承自 NSWindowController，不要勾选 Also Create XIB file for user interface，语言选择 Swift ，点击 Next，之后默认然后点击 Create 即可创建。

下一步需要确保 storyboard 中的 window 的控制器是我们刚定义的 WindowController 的实例，打开 Main.storyboard 点击 Window Controller Scene 中的 Window Controller，按快捷键 Option + Command + 3 ，在右侧显示的 Identity Inspector 中配置 Custom Class 为 WindowController，也就是刚刚创建的类：

层叠窗口

现在我们可以使新建的窗口层叠显示而不是覆盖显示，打开新建的 WindowController.swift 文件，添加以下代码：

required init?(coder: NSCoder) {
    super.init(coder: coder)
    shouldCascadeWindows = true
}

只需要设置 shouldCascadeWindows 为 true 就可以实现层叠效果，运行程序测试一下：

以标签页显示

层叠效果很不错，但我们可以尝试一下其它的方式，比如从 macOS Sierra 开始新增加的 tabbed Windows，简单说就是新建的窗口以标签页显示。

打开 Main.storyboard，选中 Window Controller scene 下的 Window ，然后打开 Inspector 栏的 Attributes Inspector (可以按快捷键 Option + Command + 4)，找到 Tabbing Mode，更改它的值为 Preferred:

运行程序，然后按快捷键 Command + n 新建窗口，可以看到新的窗口以标签页的方式显示了：

当我们运行程序的时候，macOS 会根据当前屏幕大小和应用请求窗口的大来决定应用窗口的显示位置和实际的大小，下面我们将学习两种方式控制应用窗口的显示位置和实际大小。

使用 Interface Builder 设置窗口显示位置

首先我们需要先使用 Interface Builder 设置窗口的初始位置。

打开 Main.storyboard，选中 Window Controller scene 下的 Window ，然后打开 Inspector 栏的 Size Inspector (可以按快捷键 Option + Command + 5)，找到 Initial Position，运行程序后的窗口就是按照这个设置初始位置的：

其中 x 代表窗口到屏幕左边缘的距离，y 代表窗口到屏幕底边的距离，单位是 px，在 macOS 中应用的坐标原点在左下角，这与 iOS 中是不同的（iOS 使用的是 flipped 坐标系，其原点在左上角）。

我们可以点击上面 Size Inspector 中的窗口位置预览图中的红色 constrains，这会决定 macOS 显示应用窗口位置的设定，点击红色 Constrains 可以打开或关闭相关限制，同时会看到下面两个下拉框得值会改变，比如这里：

• 取消上边和右边的红色限制，此时会看到下面两个下拉框的值分别变成 Fixed From Left 和 Fixed From Bottom
• 设置初始的位置：x -> 200, y -> 200

此时重新编译运行应用，你会发现不管屏幕多大，只要尺寸允许范围内，应用的窗口会显示在离屏幕左边和底边均为 200 px 的位置。

⚠️: macOS 会记住 app 的窗口显示位置，所以需要先把应用完全退出，然后再编译运行就能看到修改的效果！

代码实现对窗口显示位置的设置

代码实现的话，需要在 window 加载之后进行设置，在 WindowsController 中重写的 windowDidLoad 方法中添加相关代码。

这次我们来点特别的，我们设置窗口显示在离屏幕顶边和左边均为 150px 的位置，打开 WindowController.swift 文件，在 WindowController 类中修改 windowDidLoad 方法内容如下：

override func windowDidLoad() {
    super.windowDidLoad()
    
    if let window = window, let screen = window.screen {
        let offsetFromLeftOfScreen = CGFloat(150)
        let offsetFromTopOFScreen = CGFloat(150)
        let screenFrame = screen.visibleFrame
        let offsetFromBottomOfScreen = screenFrame.maxY - window.frame.height - offsetFromTopOFScreen
        window.setFrameOrigin(CGPoint(x: offsetFromLeftOfScreen, y: offsetFromBottomOfScreen))
    }
}

上面代码主要完成以下工作：

• 获取需要用到的 NSWindow 和 NSScreen 的实例
• 得到 screen 的 visibleFrame
• 通过离顶边的距离计算得到离底边距离
• 设置 window 的远点坐标为 (offsetFromLeftOfScreen, offsetFromBottomOfScreen)

选中之前显示的应用窗口，Command + q 完全退出应用，然后回到 Xcode 编译运行应用，会看到应用的窗口如期显示在指定的位置：

变身超 mini 富文本处理工具

Cocoa 有很多可以添加到 window 中的牛🐂的功能性 UI 控件，在本节我们将会用到 NSTextView，在这之前，我们需要了解 NSWindow 的 content view。

content view

contentView 位于 window 中视图层次的根级，在这个视图中我们可以放置所有界面元素。另外，我们还能替换默认的 contentView 为我们自定义的视图，在这里我们就不做相关操作了，以后我们可能会用到！

添加 Text View

打开 Main.storyboard 文件，找到 View Contorller Scene 下的 View Controller，其下的 View 中有个控价 Your document contents here ，将其删除，然后我们添加 Text View:

• 按快捷键 Shift + Command + l 打开 Object Library

• 搜索 Text View

  

• 将 Rich Document Content Text View 拖入 Content View 中

• 调整 Rich Document Content Text View 的大小和位置，最终使其四边分别与 contentView 的边缘贴齐

• 选中刚添加的 Text View 控件，然后点击底边的 Resolve Auto Layout Issues 按钮，选中 Reset To Suggested Constrains

  

• 添加限制之后的样子如下：

  

编译运行，可以看到刚添加的 Text View 了：

在窗口的 Text View 中可以添加进行文本编辑了，也支持常用的快捷键，比如复制、粘贴、剪切、撤销、重做等。窗口中也出现了一组工具栏，支持字体设置、简单的段落设置等，同时菜单栏的 Format 的菜单项功能也是可用的，还支持查找替换。这一小节我们没有添加任何代码，就完成了一个简单的富文本编辑工具了，是不是炒🐔煎🍳！

撤销和重做

在窗口中添加部分文本，已经可以完成基本的富文本编辑功能了，但是此时还不支持撤销和重做，我们需要添加支持。

• 打开 Main.storyboard 文件，依次找到 View Controller -> View -> Scroll View - Text View -> Clip View -> Text View，选中 Text View
• 按下快捷键 Option + Command + 4 打开 Attribute Inspector，勾选 Undo 复选框

此时运行程序，就支持 Undo 和 Redo 了！

在文本框添加文本以后，我们点击窗口关闭按钮，此时会提醒要不要保存文档：

点击 save 按钮，会弹出一个警告窗口：

是不是对里面的内容很熟悉，这就是前面添加的 save 方法中的错误信息。

模态窗口(Modal Window)

模态窗口是一种特殊的窗口，一旦显示就会独占用户的所有操作事件，一直到它被关闭，其它窗口才能响应用户的操作。

显示模态窗口有三种方法：

• 以一个普通窗口的形式显示，使用 NSApplication.runModal(for:) 触发显示
• 以 Modal sheet 的形式显示， 调用 NSWindow.beginSheet(_:completionHandler:) 显示窗口
• 通过模态会话的形式，本文暂不涉及这种高级的方法

其实，文档的保存和打开窗口就是模态窗帘的好例子，就像上面关闭窗口时弹出的提示保存的窗口，它出现在窗口的顶部，这就是 Modal Sheet，在本文也不讲这种模态窗口，下面我们一起实现一个显示字数和段落统计的模态窗口，它是以一个正常窗口形式显示的。

添加一个新的窗口

打开 Main.storyboard 文件，按快捷键 Shift + Command + l 打开 Object Library，搜索 Window Controller，拖拽 Window Controller 进入画布，这会生成两个场景：Window Controller Scene 和 View Controller Scene。

选中刚添加的 WIndow Controller Scene 中的 Window，按快捷键 Option + Command + 5，打开 Size Inspector，调整其宽为 300，高为 150。

继续选中 Window，按快捷键 Option + Command + 4 打开 Atrribute Inspector，取消 Close、Resize 和 Minimise 控件复选框的勾选，设置标题为 Word Count。

窗口 Close 按钮会造成一个 bug：当点击这个按钮后虽然窗口已经关闭，但是应用因为没有调用 stopModal 方法而一直保留在模态状态，这就很尴尬了！

另外，不保留 Minimise 和 Resize 按钮是为了遵循 Apple 的 Human Interface Guidelines (HIG)。

选中新添加的 View Controller Scene 中的 View，按下快捷键 Option + Command + 5 打开 Size Inspector，设置宽为 300 高为 150。

配置 Word Count 窗口

Shift + Command + l 打开 Object Library 拖拽 4 个 label 到 View 中。

改变四个 label 的标题分别为：Word Count、Paragraph Count、0 和 0，同时设置它们都是右对齐，调整它们的宽为 120，这里我们不涉及自动布局，可能会出现几个警告，先不管它们。

从 Object Library 推拽一个 Push Button 到 View 中，更改其标题为 OK，手动调整所有控件布局到合适的位置。

创建 Word Count 的 View Controller 的类

Command + n 会打开一个文件新建的导航窗口，我们选择 macOS -> Source -> Cocoa Class，新出现的窗口中输入类的名称为 WordCountViewController，Subclass of 设置为 NSViewController，取消勾选 Also create XIB for user interface

点击 Next 创建新的文件。

打开 Main.storyboard，选中新添加的 View Controller，按快捷键 Option + Command + 3 打开 Identity Inspector，选择 class 为刚添加的 WordCountViewController 类。

绑定计数 label 与 View Controller

打开新建的 WordCountViewController.swift 文件，在 WordCountViewCOntroller 中添加属性如下：

@objc dynamic var wordCount: Int = 0
@objc dynamic var paragraphCount: Int = 0

⚠️：两个属性添加了 @objc dynamic 修饰符是为了有效实现 Cocoa Bindings^[Cocoa Bindings 是 UI 开发中一个强大的技术，主要用于数据与 UI 的绑定，可以阅读 Cocoa Bindings on macOS 了解更多相关内容，后面有时间十里会专门写一篇相关的文章与大家一起学习！]，否则绑定无效运行时会报错。

打开 Main.storyboard 选中与 Word Count 的 label 相对应的数字 label，按下快捷键 Option + Command + 7 打开 Bindings Inspector:

• 点击 Value 左边的小三角，展开 Value
• Bind to 的下拉框选择 Word Count View Controller
• 勾选 Bind to
• Model Key Path 输入 wordCount

同样的步骤，与 Paragraph Count 的 label 相对应的数字 label 绑定到 paragraphCount:

下一步设置 Window Controller 的 Storyboard ID。

选择 Word Count Window 的 Window Controller，然后按快捷键 Option + Command + 3 打开 Identity Inspector，更改 Storyboard ID 的值为 Word Count Window Controller。

显示和关闭模态窗口

前面的准备工作做足了，那本节讲讲如何召唤和轰走模态窗口。

出来吧，模态窗口

打开 ViewController.swift 文件，在类中添加以下属性：

@IBOutlet var text: NSTextView!

同时添加以下方法：

@IBAction func showWordCountWindow(_ sender: AnyObject) {
    // 1
    let storyboard = NSStoryboard(name: "Main", bundle: nil)
    let wordCountWindowController = storyboard.instantiateController(withIdentifier: "Word Count Window Controller") as! NSWindowController

    if let wordCountWindow = wordCountWindowController.window, let textStorage = text.textStorage {

        // 2
        let wordCountViewController = wordCountWindow.contentViewController as! WordCountViewController
        wordCountViewController.wordCount = textStorage.words.count
        wordCountViewController.paragraphCount = textStorage.paragraphs.count

        // 3
        NSApplication.shared.runModal(for: wordCountWindow)
        // 4
        wordCountWindow.close()
    }
}

打开 Main.storyboard 文件，选中添加 Text View 的 View Controller，按住 Ctrl 键，点击 View Controller 按钮，不松手拖动至 Text View 上松手，此时会弹出一个绑定选择框，里面就包含了我们刚添加的 text 属性，点击它，这就完成了 Text View 控件与 text 属性的绑定

上面添加的方法，这里一步一步的说明一下：

1. 使用之前配置的 Storyboard ID 实例化一个 Word Count Window Controller 对象
2. 从 text view 的 storage 对象中获取字数统计和段落统计，将值设置到 wordCountViewController 的两个属性 wordCount 和 paragraphCount
3. 模态方式显示 word count 窗口
4. 一旦模态状态结束就关闭模态窗口，这里需要注意，只要模态不结束这一句就不会执行

消失吧，模态窗口

这里我们需要添加结束模态的实现，打开文件 WordCountViewController.swift，添加以下方法：

@IBAction func dismissWordCountWindow(_ sender: NSButton) {
    NSApplication.shared.stopModal()
}

下面我们将此方法与上面添加的 OK 按钮进行绑定。

打开 Main.storyboard，选中 OK 按钮，点击它，同时按住 Ctrl 键，拖动鼠标至 Word Count View Controller 的按钮上，在弹出的绑定窗口上选择刚添加的方法 dismissWordCountWindow 即可完成绑定。

添加召唤模态的符咒

这里我们以菜单栏的菜单项的方式触发模态窗口。

打开 Main.storyboard 文件，找到 Main Menu，点击展开 Edit，然后进行以下操作：

1. Shift + Command + l 打开 Object Library，搜索 Menu Item，拖动到最下面的位置，添加一个新的菜单项，选中它
2. Option + Command + 4 打开它的 Attribute Inspector，更改标题为 Word Count，同时配置快捷键为 ⌘K

下面我们需要为其绑定上面定义的方法 showWordCountWindow，点击菜单项 Word Count，同时按住 Ctrl 键，拖动至 Application Scene 下的 First Responder 上松手，在弹出的列表中找到方法 showWordCountWindow，选择它，这就完成了触发模态的绑定：

召唤模态

编译运行程序，在窗口中输入一些内容，比如：

望岳

唐代：杜甫

岱宗夫如何？齐鲁青未了。

造化钟神秀，阴阳割昏晓。

荡胸生曾云，决眦入归鸟。

会当凌绝顶，一览众山小。

菜单栏 Edit -> Word Count (或者按快捷键 Command + k) 就能打开统计字数的模态窗口。

点击 OK 就可以“轰走”模态窗口了。

总结

点我可以下载本文中的工程。本文涉及到了以下内容：

• MVC 的设计模式
• 多窗口应用的实现
• Interface Builder 和 代码 两种方式控制窗口位置
• 控件与类属性的绑定，控件 Action 与类方法的绑定
• 窗口形式的 macOS 的常规开发姿势
• 如何代码控制显示模态窗口
• 富文本编辑的简单实现

希望对大家学习 macOS 开发有所帮助！感谢您的阅读！

参考

Windows and WindowController Tutorial for macOS

PlatformIO is an open source ecosystem for IoT development.

Cross-platform IDE and unified debugger.

Remote unit testing and firmware updates.

PlatformIO 是一个用于物联网开发的开源生态系统。它提供跨平台的开发环境和统一的调试器，还支持远程单元测试和固件更新…

PlatformIO 简介

PlatformIO 是独立于平台运行的，实际上它只依赖于 python，然而 python 在 macOS、linux 和 windows 都能完美适配. 也就是说 PlatformIO 的工程从一个电脑很容易迁移到另一个电脑，只需要拷贝再使用 PlatformIO 就能完美打开，不管团队中的成员使用什么操作系统 PlatformIO 可以让工程共享变得异常简单. 除此之外, PlatformIO 不仅可以在笔记本和台式机上运行，同样可以运行在没有显示桌面的服务器。PlatformIO 的核心(PlatformIO Core) 就是一个终端程序, 它能配合您喜欢的多款云 IDE、桌面 IDE 或者 通用代码编辑器构建 PlatformIO 的 IDE，比如 Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM, Visual Studio, VSCode, etc.

目前官方推荐的 IDE 使用方案就是 VSCode + PlatformIO IDE 插件，界面如右图：

• PIO 统一的调试器，可以零配置的对支持硬件调试的的嵌入式开发板进行调试工作，调试器支持很多的架构和开发平台
• 跨平台的代码构建系统对系统软件没有额外的依赖: 600+ 嵌入式开发板, 30+ 开发平台, 15+ 框架
• C/C++ 智能代码补全，语法检查，快速重构以及代码跳转满足快速专业的开发需求
• VSCode 提供多工程和文件管理的支持和统一而流畅的使用体验，并且支持多种色彩主题，总有您喜欢和适合您的
• 内建的终端支持 PlatformIO Core 命令行工具，并且支持强大的串口调试器

尽管 PlatformIO 可以运行在不同的操作系统中，但从开发的角度看更重要的是它支持多少开发板和单片机。概括来说: PlatformIO 支持大约 600+ 个开发板和市面上流行的支持跨平台的 30 个开发平台。

• 支持的嵌入式开发板列表: Boards
• 支持的单片机平台和桌面平台: Platforms

同时，PlatformIO 还提供大量的开发库，目前超过了 6000 个，为了方便新手入门开发，他们也同样提供代码例程。

PlatformIO 解决的问题

• 嵌入式开发的世界让很多人望而却步的主要原因是针对某一个单片机或开发板开发环境复杂的配置过程：交叉编译链工具下载、安装和配置，另外还得使用厂商独有的 IDE (有时还不是免费的) ，还有有时还不得不使用 IDE 只支持的 Windows
• 多个硬件平台 (单片机, 开发板) 需要不同交叉编译链工具和开发环境, 所有相应的开发人员需要花费大量精力在配置新的开发环境上
• 为了学习如何使用常规的传感器或执行器件等外设，需要花时间查找合适的库和例程
• 每个团队成员可能会使用不用的操作系统，这就为他们之间共享成果形成阻碍（当然国内现状是公司逼着员工使用统一的操作系统，哈哈🤣）

PlatformIO 如何工作

这里不深入说 PlatformIO 的实现细节, 使用 PlatformIO 时工程的工作流程如下：

• 用户在 “platformio.ini” (工程配置文件) 中指定开发平台（开发板）
• 根据配置文件中的开发板（一个工程可以配置多个开发板），PlatformIO 会自动下载并安装对应的交叉编译链工具以及调试工具.
• 用户编写代码，PlatformIO 来保证所有指定开发板的编译、调试和上传工作

PlatformIO 需要用户进行的选择

• 决定使用什么系统运行 PlatformIO 来进行单片机开发，需要进行相应系统的安装工作
• 选择使用什么编辑器进行代码编写，可以是极简通用的代码编辑器，也可以您喜欢的桌面 IDE
• 专注于代码开发，显著简化使用开发平台和单片机的过程

PlatformIO 的相关报道

通常情况下不同的单片机需要不同的开发工具，比如 Arduino 使用的是 Arduino IDE，有些高级用户为了更好的进行代码工程管理，也会配置基于 Eclipse 的图形界面的开发环境。有时同步支持不同的单片机比较困难，您可能觉得如果有一个统一的开发工具那该多好呀！ PlatformIO 就是这么一个开源的进行单片机嵌入式开发的生态工具。

PlatformIO 是一个跨平台的代码构建工具和库管理工具，并且支持像 Arduino 和 MBED 这样的平台。他们关心可以跨 macOS、windows 和 linux 三个平台工作的工具链、调试器和开发平台，它支持超过 200 个的开发板和超过 15 种的开发平台以及 10 中开发框架，所以绝大多数流行的开发板都是包含其中的。他们在收集整理开发库上倾注了大量精力，以至于您的工程可以使用上百种开发库。另外，也有很多代码例程提供方便您入门单片机开发。PlatformIO 最初以命令行的形态进行开发，现如今它可以完美配合其它的 IDE 进行使用，比如 Eclipse、Visual Studio，最近他们最新发布了基于 Atom 的 PlatformIO 开发环境。

PlatformIO 的荣誉

PlatformIO 曾提名 2015/16 IOT 年度最佳开发软件和工具奖。

• 什么是 Swift 的 Codable
• 怎么使用 Codable
• Codable 给我们带来什么便利

开发平台

• macOS 10.14.4
• Swift 5
• xcode 10.2

Swift 的 Codable

In a nutshell, Encoding is the process of transforming your own custom type, class or struct to external data representation type like JSON or plist or something else & Decoding is the process of transforming external data representation type like JSON or plist to your own custom type, class or struct.

可以使用的协议

Swift 的标准库中包含了用于自定义类型(结构体、类)与其它表示形式(JSON、Property List 或 二进制)的数据之间相互转换的协议：

• Encodable: 用于自定义类型向 JSON 或 Property List 的转换，协议包含一个方法

  encode(to:) 
  

• Decodable: 用于自 JSON 或 Property List 数据向自定义类型的转换，协议包含一个方法

  init(from:)
  

• Codable: 包含 Encodable 和 Decodable 两方面的转换，其定义如下：

  typealias Codable = Decodable & Encodable
  

使用 Codable 协议 的 Encodable 和 Decodable，可以让我们轻松实现自定义数据类型的序列化以及得到相应数据类型的实例对象。按照字面意思，我们后面将数据类型实例向 JSON 或 Property List 转换的过程称为编码，反之，称为解码！

遵循协议的类型

如果我们想要实现自定义类型或数据模型的编码和解码，必须遵循 Codable 协议！Swift 基本的内建类型已经是 Codable 的了，比如 String、Int、Double、Date 和 Data。另外像 Array、Dictionary 和 Optional 也都是遵循 Codable 协议的，可以进行编码和解码。

如下自定义的结构体 Person 和 Team，遵循 Codable 协议，同时结构体的所有属性要么是标准的 Codable 类型，要么包含 Codable 类型：

struct Person : Codable {
    var id: Int
    var name: String
    var age: Int
    var isMale: Bool
}

struct Team: Codable {
    var master: Person
    var memebers: [Person]
}

Codable 类型的编解码

对于 Codable 的类型，需要使用相应的编码器对我们的数据进行编码和解码，具体细节可以参考后面的小节，有两种编码器可用：

• JSON
  • JSONEncoder: 将 Codable 类型数据编码为 JSON 数据
  • JSONDecoder: 将 JSON 数据解码为指定的 Codable 类型数据
• Property List
  • PropertyListEncoder: 将 Codable 类型数据编码为 plist 数据
  • PropertyListDecoder: 将 plist 数据解码为指定的 Codable 类型数据

Codable 的使用

下面我们就一起研究一下 Codable 的使用，这里我们只尝试 Codable 类型数据与 JSON 数据的编码解码的实现。

编码和解码

使用 JSONEncoder 编码

非常简单，只需调用 JSONEncoder 的 encode(_:) 方法就能将 Codable 类型转换为 JSON 数据：

let jack = Person(id: 1, name: "Jack", age: 12, isMale: true)
if let jackData = try? JSONEncoder().encode(jack) {
    print(String(data: jackData, encoding: .utf8)!)
}

可以看到打印出转换得到的 JSON 字符串数据：

{"age":12,"id":1,"isMale":true,"name":"Jack"}

是不是很方便，解码同样如此简单！

使用 JSONDecoder 解码

只需要调用 JSONDecoder 实例的 decode(_:from:) 方法就能将 JSON 对象转换得到指定类型的实例。

let jsonString = """
{
    "id": 2,
    "name": "lucy",
    "age": 11,
    "isMale": false
}
"""
if let json = jsonString.data(using: .utf8) {
    let lucy = try? JSONDecoder().decode(Person.self, from: json)
    print(lucy!)
}

打印结果，如您所料，将 JSON 字符串成功的解码为了 Person 实例对象：

Person(id: 2, name: "lucy", age: 11, isMale: false)

Codable 使用的基本步骤

综上过程，我们可以总结一下，要使用 Swift 的特性其实很简单，分两步：

• 自定义类型遵循 Codable 协议
• 使用编码器实现自定义类型数据的编码和解码

使用 CodingKeys 来选择部分属性是 Codable 的

也许此时此刻您可能会想：

• 如果不想把自定义数据所有的属性编码到 JSON 该怎么办？
• 如果 JSON 数据中的键名与自定义类型中的属性名不一致怎么办？

请放心，您想到的，Apple 同样照顾到了！就是本节要讲的 CodingKeys

Codable types can declare a special nested enumeration named CodingKeys that conforms to the CodingKey protocol. When this enumeration is present, its cases serve as the authoritative list of properties that must be included when instances of a codable type are encoded or decoded. The names of the enumeration cases should match the names you’ve given to the corresponding properties in your type.

CodingKeys 是我们在自定义数据类型中定义的枚举，有以下两点要求：

• 枚举元素类型是 String，并且遵循 CodingKey 协议、
• 枚举元素的名称必须与自定义类型中的属性名称保持一致

那么我们回过头来看一下前面的两个问题怎么解决：

• CodingKeys 中的元素与自定义数据类型中的属性名称对应，只要删除对应属性的枚举元素就可以实现编码时对应属性的忽略，这样就解决了第一个问题，但是要注意，不编码的属性必须赋予默认值
• 为 CodingKeys 中枚举元素自定义 String 值与 JSON 数据中的键名对应起来，就能解决第二个问题。

假如想为 Person 结构体添加一个 description 的属性，同时不想让它参与编码和解码，另外 JSON 数据中的键名是中文的，我们可以重构 Person 类：

struct Person : Codable {
    var id: Int
    var name: String
    var age: Int
    var isMale: Bool
    var description: String = "person"
    
    enum CodingKeys: String, CodingKey {
        case id = "身份证号"
        case name = "姓名"
        case age = "年龄"
        case isMale
    }
}

我们看一下将自定义数据转换为 JSON 会是怎样的：

let tim = Person(id: 3, name: "tim", age: 10, isMale: true, description: "")
if let timData = try? JSONEncoder().encode(tim) {
    print(String(data: timData, encoding: .utf8)!)
}

编码得到的 JSON 数据如下：

{"姓名":"tim","isMale":true,"年龄":10,"身份证号":3}

自定义 encode 和 decode

我们定义一个 Size 结构体、Point 结构体和 Rect 结构体如下：

struct Size: Codable {
    var width: Double
    var height: Double
}

struct Point: Codable {
    var x: Double
    var y: Double
}

struct Rect: Codable {
    var position: Point
    var size: Size
}

我们利用一开始定义的 Rect 结构体声明一个 rect，坐标在原点，宽高都为 2.0，并将其转换为 JSON 数据：

let rect = Rect(position: Point(x: 0.0, y: 0.0), size: Size(width: 2.0, height: 2.0))
if let rectData = try? JSONEncoder().encode(rect) {
    print(String(data: rectData, encoding: .utf8)!)
}

team 对应的 JSON 字符串如下：

{"position":{"x":0,"y":0},"size":{"width":2,"height":2}}

但是呢，十里不想让 JSON 数据中 x 和 y 嵌套在 positon 中，也不想 width 和 height 嵌套在 size 中，而是像下面的样子：

{
    "x": 0,
    "y": 0,
    "width": 2.0,
    "height": 2.0
}

要实现这种需求，我们必须自定义 Encodable 协议的 encode(_:) 方法 和 Decodable 协议的 init(from:) 方法，实现自定义的编码解码逻辑，大体分下面几步：

• 定义 CodingKeys 枚举，元素与目标 JSON 数据的键名对应，定义 x 和 y 而不是 position，定义 width 和 height 而不是 size
• 删除 Rect 定义中的 Codable
• 扩展 Rect 遵循 Encodable 协议，并实现 encode(_:) 方法
• 扩展 Rect 遵循 Decodable 协议，并实现 init(from:) 方法

最终 Rect 定义如下：

struct Rect {
    var position: Point
    var size: Size
    
    enum CodingKeys: String, CodingKey {
        case x
        case y
        case width
        case height
    }
}

extension Rect: Encodable {
    func encode(to encoder: Encoder) throws {
        var container = encoder.container(keyedBy: CodingKeys.self)
        try container.encode(position.x, forKey: .x)
        try container.encode(position.y, forKey: .y)
        try container.encode(size.width, forKey: .width)
        try container.encode(size.height, forKey: .height)
    }
}

extension Rect: Decodable {
    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        let x = try container.decode(Double.self, forKey: .x)
        let y = try container.decode(Double.self, forKey: .y)
        position = Point(x: x, y: y)
        let width = try container.decode(Double.self, forKey: .width)
        let height = try container.decode(Double.self, forKey: .height)
        size = Size(width: width, height: height)
    }
}

测试一下编码实现：

let rect = Rect(position: Point(x: 0.0, y: 0.0), size: Size(width: 2.0, height: 2.0))
if let rectData = try? JSONEncoder().encode(rect) {
    print(String(data: rectData, encoding: .utf8)!)
}

得到的 JSON 数据的打印结果为：

{"y":0,"x":0,"width":2,"height":2}

测试一下解码的实现：

let rectString = """
{
    "x": 3,
    "y": 3,
    "width": 2.5,
    "height": 2.5
}
"""

if let json = rectString.data(using: .utf8) {
    let newRect = try? JSONDecoder().decode(Rect.self, from: json)
    print(newRect!)
}