From b0d0c23bac65fb85844e192cca1edde92236a276 Mon Sep 17 00:00:00 2001
From: mondraker <691806052@qq.com>
Date: Thu, 6 Jul 2023 13:40:49 +0800
Subject: [PATCH] update md
---
README.md | 139 +
hardware/AXP202在电路中的接线.drawio | 1 +
hardware/AXP202邮票孔模块_ibom.html | 4613 -----------------------
hardware/AXP202邮票孔模块底板_ibom.html | 4613 -----------------------
hardware/BOM_邮票孔模块2023-07-04.xlsx | Bin 0 -> 10746 bytes
5 files changed, 140 insertions(+), 9226 deletions(-)
create mode 100644 hardware/AXP202在电路中的接线.drawio
delete mode 100644 hardware/AXP202邮票孔模块_ibom.html
delete mode 100644 hardware/AXP202邮票孔模块底板_ibom.html
create mode 100644 hardware/BOM_邮票孔模块2023-07-04.xlsx
diff --git a/README.md b/README.md
index 2584245..c51bc11 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,141 @@
# AXP202-PMIC
AXP202 Power management IC(AXP202电源管理芯片)
+
+##### 有问题直接进Q群轰炸我:735791683
+* ###### 为什么不用最新版AXP2101呢?首先AXP2101功能太多,目前DIY的小型设备根本用不了那么多。其次由于是主推产品价格相对较贵,是AXP202的10倍(不过要是有朋友需要后期也可以搞一个出来)
+* ###### 该项目已经过长期验证,提供封装,3D文件等等,**资料充足(包含ESP-IDF例程以及Arduino例程,中英文手册)**,并且这个邮票孔自己打也**不需要额外收费**,不选半孔工艺自己磨一下就行了🤣
+* ###### 一块芯片1.98元,其它都是阻容和电感,一片“自己整”**三块钱以内**
+* ###### 相关资料、[BOM表单](https://easyeda.online/ibom/d5313712.html)以及元器件相关链接都在文末附件里
+* ###### 过段时间自己会整一批沉金+半孔工艺的模块出来,和雪花灯一起放在TB小店里:[奥特曼的电子星球](https://m.tb.cn/h.50LlvTB )
+
+# 前言(闲聊)
+* ###### Hello,大家好久不见,大半年没发新东西了,小伙伴都以为我隐退了。其实这段时间一直在闭关修炼,忙毕业设计,顺便学习一下ESP-IDF和LVGL。
+* ###### 文章可能相对较长,但是这个模块确实非常好用,资料非常齐全,真心希望每一个感兴趣的朋友都可以将他掌握。
+* ###### 当然了,后面整理一下资料会把自己这段时间的收获分享给大家。由于过两天要开源的开发板也用到了这个电源模块,因此先开源这个模块。(如下图)
+
+###### [开源视频预告,直接点我](https://b23.tv/cWTMeIv)
+开发板
+
+模块
+
+测试底板
+
+# 正文(AXP202电源管理芯片)
+## 注意事项
+### 由于芯片功能非常多,因此我分为以下几部分进行大致介绍
+1. **功能部分**:这部分主要介绍设计目的,设计思路,芯片功能,芯片参数以及应用场景
+
+2. **硬件部分**:这部分主要介绍了芯片外围电路(详述各个特殊器件功能以及选型),模块外围电路(这部分涉及到默认电源电压设置以及开机方式设置),电源模块测试底板讲解,PCB参数与注意事项(厚度等等),电源模块在电路中的接线(由于电源模块的特殊性导致容易无法通讯)
+
+3. **软件部分**:这部分主要介绍软件实现的功能,例程的使用,注意事项等等
+
+4. **视频与相关链接部分**:这部分主要有AXP173工程的地址,AXP202工程的Github地址,在线bom和焊接点位工具(朋友开发的一种非常厉害的东西)的使用方法以及AXP202模块的视频展示与讲解(反响强烈就推出一手,现在暂时鸽一下下)
+
+## 功能部分
+### 设计目的
+**1. 在硬件设计时,电源部分一直是万事开头、重中之重。我发现在大家平时的制作里经常讨论的核心问题就是:**
+* 电源怎么设计
+* 求一个体积小的LDO
+* 求一个效率高的DCDC
+* 求一个电池充电芯片
+* 哪里有便宜的电源芯片
+
+**2. 还有很多玩家经常遇到的问题:**
+* 外部输入电源和电池怎么实现高效可靠的电源通路管理
+* 怎么实现长按开关机
+* 怎么精确的检测电池电量
+* 怎么获取电源实时状态
+* 低功耗怎么办怎么办怎么办怎么办怎么办怎么办
+
+**那么好,我现在告诉你,有一个芯片,他可以实现上述的所有功能,并且体积小、效率高、功耗低、价格香你心动吗???**
+
+
+### 芯片功能
+**1. 上功能。(官方文档如下)**
+* 
+
+**2. 上概述。(官方文档如下)**
+* 
+
+### 芯片参数
+**这里主要举例电源输出能力参数,其它电源参数去数据手册里看。(官方文档如下)**
+* 
+
+**如果你还需要5V输出,那么使用模块IPSOUT脚+DCDC5V的buck电路即可轻松实现,输出能力取决于外部供电的输入能力,且芯片专门有一个EXTEN脚控制外部DCDC芯片的EN脚,节省NCU的功能引脚,太香了。(官方文档如下)**
+* 
+
+### 设计思路
+**做成邮票孔模块类型方便大家直接使用,因为这种芯片外围的阻容参数都比较奇怪。**
+* 为方便PCB电路板的设计与焊接,增加成功率,本设计采用模块化思想,将AXP202外围电路封装为一个邮票孔模块焊接在主板上,将可用户自定义的管脚全部引出,这样就可以方便的在主板上使用相应阻值的电阻来配置这些引脚。
+
+* 为统一封装,本次设计使用了标准2.54mm间距LCC邮票孔,便于焊接,使用了4层PCB设计用以缩小封装体积,引出全部必要的功能。
+### 应用场景
+**所有包含单片机的设备。(官方文档如下)**
+* 
+
+## 硬件部分
+### 芯片外围电路
+**原理图里写的很详细,这里简单概括一下**
+
+* 首先是电源输入部分,**如图左上方区域**。VBAT为电池正极接入端,并联一个0603封装10uF耐压16V的电容用以滤波。ACIN为外部DC电源供电脚,可以容纳5V/2A电源进入,VBUS为外部USB电源输入,可以容纳5V/1A的电源进入,因此分别并联了一个0603封装4.7uF的电容用以电源滤波,故意串联两个2.2ohm的电阻用以防止震荡,降低电容充电速度,更好地吸收电源的噪声。该部分在电源处还可以并联齐纳二极管减少高电压击穿危险,由于模块体积限制以及功能上并不敏感,因此没有添加。BACKUP为外部备用电池正极,接常规RTC/BIOS电池。
+
+* 其次是DCDC降压部分,**如图右上方区域**。这一部分电路为独立区域,需要外部接入系统输入电源IPSOUT,其可以让内部电压IPSOUT降压到电源芯片调压范围之内,如果应用中不需要用到某个 DC-DC只需要将对应的 LX 管脚悬空即可。输出电压2.5V以下时推荐4.7uH电感,输出电压2.5V以上时推荐2.2uH电感,电感饱和电流需大于最大需求电流50%,这里由于4.7uH有0806封装所以全用4.7uH,同样是为了减少体积。R17务必为30mΩ/1%/1206电阻,PCB布线注意芯片42/43脚务必接R17电阻PAD,以确保直接从电阻PAD检测到信号,因为R17为电池充电电流,放电电流与与充电电压的检测电阻,不仅精度要高还需要在布局时严格考虑干扰。
+
+* 之后便是信号与功能引脚的引出,以及芯片内部参考电压外围的电路部分,**如图左下方区域**。以下两个GPIO除了具有常规输入输出能力以外还具有其他功能:GPIO0:ADC/LDO5(输出驱动能力为50mA),GPIO1:ADC。PWRON为电源芯片开机脚,低电平有效,R24上拉至LDO1防止误触发。N_OE可以用来通过外部电源接入直接开机设备。N_VBUSEN用以选择是否使能VBUS供电。IRQ中断信号引脚,可选上拉至LDO1或MCU_3V3。I2C使用2.2k电阻上拉至MCU_3V3。
+
+* 最后是LDO(低压差线性稳压器)输出部分,**如图右下方区域**。该部分在功能框图中同样为独立区域,需要外部接入系统供电ISPOUT。PWROK为MCU使能引脚,RESET按键接在MCU的EN管脚上可以实现MCU的重启,上拉至MCU供电脚。DC3SET为DCDC3电压设置管脚,接APS或LDO1为3.3V/2.5V,接地为1.8V,悬空为1.2V/1.5V。
+
+* 
+
+### 模块外围电路
+**下图中写的很详细,不在赘述**
+
+* 
+
+### 电源模块测试底板讲解
+**如上图引出了所有的功能,芯片外部可设置的一些引脚可以使用跳帽设置,并且加入了一个5V的DCDC升压,用以基本测试,地线引出较少,可以自己酌情添加。或者根据要使用的主控芯片自己绘制一个测试板,我这个测试底板只是用以筛选哪家芯片合适以及基本的功能测试,因为自己直接画了ESP32的测试板所以没有再继续优化这个底板(后续可能会有面包板模块吧)。**
+
+### 电源模块在电路中的接线
+**相较于普通的I2C模块,电源管理模块还要给主控芯片提供电源,除此之外,AXP202必须在开机状态下,一定要共地,否则两者之间是无法正常通信的。**
+
+
+### PCB参数与邮票孔处理注意事项
+**下单打1mm(下面图是1.6mm的非常厚,仅用以演示),四层。不需要半孔工艺,回来之后是卷边的,需要先用镊子把半孔里多余的铜抠出来,然后用800目左右砂纸磨掉就行了。(以下是简单的步骤演示)**
+
+* 处理前(银色代表OK,黄色代表不OK)
+* 
+* 处理中(镊子挑出来)
+* 
+* 处理中(挑出来之后)
+* 
+* 
+* 处理中(打磨打磨)
+* 没图了,别太用力就行,磨一磨看一看,别把板边的铜磨出来了。
+* 处理后(自己可以用更高目砂纸精细打磨一下)
+* 
+
+### PS
+**模块上面那个洞是为了方便拆装的**
+* 
+
+## 软件部分
+### **[GitHub链接](https://github.com/HwzLoveDz/AXP202-PMIC)**
+### 声明:
+* axp20x库以及Arduino相关例程,均来自于Lewis He大佬,感谢大佬的开源(开源协议:MIT)
+* 原GitHub链接: github:https://github.com/lewisxhe/AXP202X_Libraries
+* 后续自己的例程都将围绕该库编写,自己添加了其它一些常用的寄存器与功能,比如LED指示灯的充电控制等等,以后的修改将同步更新至GitHub
+
+### 说明:
+* 该库同时兼容AXP173/192/202等
+* 基本实现了芯片所有的功能
+* 代码中有相关功能注释,可以配合官方寄存器文档进行学习与编写
+* 代码中使用独立的I2C接口进行编写,移植至其他平台只需要写一个接口库即可,非常方便
+* **代码中有疑惑可以参照这一篇开源的[AXP173](https://oshwhub.com/mondraker/axp173)进行学习,或者进群轰炸我**
+
+## 视频以及相关链接部分
+* **[GitHub个人主页](https://github.com/HwzLoveDz)**
+* **[b站个人主页](https://space.bilibili.com/240319986)** **(这里有这次的AXP202(QFN)芯片焊接教程哦)**
+* **[在线BOM地址](https://easyeda.online/ibom/d5313712.html)** **(朋友开发,和ibom一样,但是是在线的,并且手机也可以浏览,后期会出一期文章重点介绍他)**
+* **QQ交流群号:735791683**
+* **器件购买链接在附件BOM中**
+* **更全的软件资料都打包在GitHub,登不上GitHub的可以加群下载,因为资料需要实时更新,不在这里给审核添麻烦了**
\ No newline at end of file
diff --git a/hardware/AXP202在电路中的接线.drawio b/hardware/AXP202在电路中的接线.drawio
new file mode 100644
index 0000000..9ae0767
--- /dev/null
+++ b/hardware/AXP202在电路中的接线.drawio
@@ -0,0 +1 @@
+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
\ No newline at end of file
diff --git a/hardware/AXP202邮票孔模块_ibom.html b/hardware/AXP202邮票孔模块_ibom.html
deleted file mode 100644
index 5f26448..0000000
--- a/hardware/AXP202邮票孔模块_ibom.html
+++ /dev/null
@@ -1,4613 +0,0 @@
-
-
-
-
-
-
- Interactive BOM for KiCAD
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- |
- Title
- |
-
- Revision
- |
-
-
- |
- Company
- |
-
- Date
- |
-
-
-
-
-
-
-
-
-
-
-
diff --git a/hardware/AXP202邮票孔模块底板_ibom.html b/hardware/AXP202邮票孔模块底板_ibom.html
deleted file mode 100644
index 4f23f94..0000000
--- a/hardware/AXP202邮票孔模块底板_ibom.html
+++ /dev/null
@@ -1,4613 +0,0 @@
-
-
-
-
-
-
- Interactive BOM for KiCAD
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- |
- Title
- |
-
- Revision
- |
-
-
- |
- Company
- |
-
- Date
- |
-
-
-
-
-
-
-
-
-
-
-
diff --git a/hardware/BOM_邮票孔模块2023-07-04.xlsx b/hardware/BOM_邮票孔模块2023-07-04.xlsx
new file mode 100644
index 0000000000000000000000000000000000000000..6f46ea75b99e3069ef8a0b7369009f541b03b513
GIT binary patch
literal 10746
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