{"id":13815664,"url":"https://github.com/ohdarling/AirCube","last_synced_at":"2025-05-15T09:33:02.935Z","repository":{"id":64942873,"uuid":"542604748","full_name":"ohdarling/AirCube","owner":"ohdarling","description":"An DIY all in one air quality monitor and environment detector powered by ESPHome, includes metrics such as PM2.5, PM10, CO2, Luminance, Temperature, Humidity and Barometric Pressure.","archived":false,"fork":false,"pushed_at":"2024-12-18T13:53:57.000Z","size":7328,"stargazers_count":90,"open_issues_count":0,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-11T02:12:54.762Z","etag":null,"topics":["airquality","co2","domoticz","eink","esp32","esphome","home-assistant","humidity","pm25","sensor","temperature"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ohdarling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-28T13:28:49.000Z","updated_at":"2025-03-23T12:58:53.000Z","dependencies_parsed_at":"2024-01-18T02:37:19.037Z","dependency_job_id":"24b28b71-b34a-46e8-8935-de461a80bc22","html_url":"https://github.com/ohdarling/AirCube","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdarling%2FAirCube","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdarling%2FAirCube/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdarling%2FAirCube/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdarling%2FAirCube/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ohdarling","download_url":"https://codeload.github.com/ohdarling/AirCube/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254314012,"owners_count":22050153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["airquality","co2","domoticz","eink","esp32","esphome","home-assistant","humidity","pm25","sensor","temperature"],"created_at":"2024-08-04T04:03:50.659Z","updated_at":"2025-05-15T09:33:02.267Z","avatar_url":"https://github.com/ohdarling.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# AirCube 空气检测站\n\n[English Version](README_EN.md)\n\nAirCube 是一个开源的环境状态监测设备，可以监测各种环境状态，例如温度、湿度、二氧化碳浓度、PM 2.5 浓度等，还可以与 Domoticz、Home Assistant 等智能家居系统集成，建立家庭环境数据监测系统。\n\n\u003cimg src=\"AirCube.png?raw=true\" style=\"zoom:50%;\" /\u003e\n\n## 功能列表\n\n* 概览页面，可以直观查看各种环境数据的当前数值，例如当前温度、湿度、PM 2.5 以及二氧化碳浓度\n* 左右键切换传感器详情界面，可以查看具体细分项数值，例如 PM 1，PM 10 等\n* 各项数据的历史趋势数据，通过记录过去 12 小时的数据并通过图表展示环境数据的变化趋势\n* 特定传感器的详情数据，例如攀藤 PMS5003 可以同时检测 PM 1.0、PM 2.5、PM 10 浓度，在概览页面无法展示完全，就可以在详情页面展示出来\n* 设备信息界面，可以展示当前设备的名称、Wi-Fi 连接情况、运行时间等基础信息\n* 数据上报能力，可以通过 MQTT 将数据上报到 Domoticz 或 Home Assistant\n* 批量部署能力，通过脚本批量部署设备固件\n\n## 更新日志\n\n* 2023.03.31\n  * 禁用 MQTT 无法连接时自动重启，防止未配置 MQTT Broker 时 AirCube 定时重启\n  \n* 2023.02.24\n  * 与小米温湿度传感器对比后，BME280 温度校正 -2，湿度 +10\n  * 添加重启功能，长按右键 5 秒以上，会重启 AirCube\n  * 添加 CO2 传感器校准功能，长按左键 5 秒以上，开启 MH-Z19 或 SenseAir S8 校准功能，校准前请将 AirCube 在室外放置运行 20 分钟以上\n  * 使用自定义组件读取 BME280 数据，避免 ESPHome 初始化失败的问题\n\n## 目录结构\n\n* 3D_Model - 设备外壳 3D 模型文件，可以通过 FDM 类型 3D 打印机打印\n  * AirCube_Back.stl - 后盖\n  * AirCube_Eink.stl - 使用 E-ink 屏幕时的外壳模型\n  * AirCube_Eink_Stand.stl - 使用 E-ink 屏幕时的屏幕支架\n  * AirCube_LCD.stl - 使用 LCD 屏幕时的外壳模型\n  * AirCube_LCD_Stand.stl - 使用 LCD 屏幕时的屏幕支架\n\n* Firmware - 基于 ESPHome 的设备固件，因传感器造型可变化，未编译成二进行，可以自行编译\n* Hardware - 包含用于制造 PCB 的 Gerber 文件和原理图\n\n## PCB\n\nPCB 尺寸为 6cm x 6cm，四角安装孔直径为 2mm。\n\n* PCB 正面为屏幕及触摸按钮安装位置。\n\n* PCB 底面为传感器及 NodeMCU 安装位置，目前版本预留了 IR、433MHz 以及电源接头，但并未使用。\n\n\u003cimg src=\"Images/aircube-pcb-top.png?raw=true\" alt=\"aircube-pcb-top\" style=\"width:300px;\" /\u003e\u003cimg src=\"Images/aircube-pcb-bottom.png?raw=true\" alt=\"aircube-pcb-bottom\" style=\"width:300px;\" /\u003e\n\n## 元件选型\n\n| 图片                                                         | 类型         | 型号            | 价格（元） | 说明                                                         |\n| ------------------------------------------------------------ | ------------ | --------------- | ---------- | ------------------------------------------------------------ |\n| \u003cimg src=\"Images/aircube-part-bme280.png?raw=true\" alt=\"BME280\" style=\"width:200px;\" /\u003e | 温湿度       | BME280 或 SHT31 | 22         | 其中 BME280 还额外支持压强检测，同时支持这两种传感器主要是因为它们的引脚顺序相同，可以替换使用。 |\n| \u003cimg src=\"Images/aircube-part-pms5003.png?raw=true\" alt=\"PMS5003\" style=\"width:200px\" /\u003e | 颗粒物浓度   | 攀藤 PMS5003    | 70         | 支持 PM 1.0、PM 2.5、PM 10 三种颗粒物浓度检测，以及 PMS5003ST，额外增加了甲醛浓度检测。另外 PMS7003 虽然同样可以使用，但是因为需要额外转接板，不能直接使用 1.25mm 8P 连接线，因此并不推荐。 |\n| \u003cimg src=\"Images/aircube-part-mhz19.png?raw=true\" alt=\"MH-Z19B\" style=\"width:200px\" /\u003e | 二氧化碳浓度 | MH-Z19B         | 120        | 可以检测 400-5000 ppm 范围的二氧化碳浓度，当然也可以采用 SenseAir S8 传感器，它们的引脚位置和定义都完全一致。 |\n| \u003cimg src=\"Images/aircube-part-bh1750.png?raw=true\" alt=\"BH1750\" style=\"width:200px\" /\u003e | 光照强度     | BH1750          | 4          | 如果使用光敏电阻还需要额外换算，还是直接采用传感器更简单直接。 |\n| \u003cimg src=\"Images/aircube-part-touch-sensor.png?raw=true\" alt=\"TTP223\" style=\"width:200px;\" /\u003e | 触摸按钮     | TTP223          | 0.3        | 这个模块触摸感应距离大，可以隔着外壳完成触摸操作，用来切换信息页。 |\n| \u003cimg src=\"Images/aircube-part-nodemcu32s.png?raw=true\" alt=\"NodeMCU-32S\" style=\"width:200px;;\" /\u003e | 单片机       | NodeMCU-32S     | 22         | 直接选用常见的 NodeMCU-32S 开发板，价格便宜，还可以直接给传感器提供 3.3V 供电。 |\n| \u003cimg src=\"Images/aircube-part-lcd.png?raw=true\" alt=\"1.54 LCD\" style=\"width:200px\" /\u003e | 屏幕         | 1.54 LCD        | 20         | 1.54 寸 SPI 接口 IPS 屏幕：分辨率 240x240，主控 ST7789V。    |\n| \u003cimg src=\"Images/aircube-part-eink.png?raw=true\" alt=\"1.54 E-ink\" style=\"width:200px;\" /\u003e | 屏幕         | 1.54 E-ink      | 30         | 1.54 寸 SPI 接口 E-ink 屏幕：单色屏，只支持黑白，分辨率 200x200。 |\n\n**注：表格中的价格为淘宝上大致价格，随卖家不同价格也会不太相同。**\n\n## 其他配件\n\n| 配件                                                         | 型号                | 数量 | 用途                    |\n| ------------------------------------------------------------ | ------------------- | ---- | ----------------------- |\n| \u003cimg src=\"Images/aircube-5p-header-90.png?raw=true\" alt=\"aircube-5p-header-90\" style=\"width:100px\" /\u003e | 弯针 5P 2.54mm 母座 | 2    | 安装 BME280 以及 BH1750 |\n| \u003cimg src=\"Images/aircube-3p-header.png?raw=true\" alt=\"aircube-3p-header\" style=\"width:100px\" /\u003e | 3P 2.54mm 母座      | 2    | 安装 TTP223 触摸传感器  |\n| \u003cimg src=\"Images/aircube-15p-header.png?raw=true\" alt=\"aircube-15p-header\" style=\"width:100px\" /\u003e | 15P 2.54mm 母座     | 2    | 安装 NodeMCU-32S        |\n| \u003cimg src=\"Images/aircube-5p-header.png?raw=true\" alt=\"aircube-5p-header\" style=\"width:100px\" /\u003e | 5P 2.54mm 母座      | 1    | 安装 MH-Z19B            |\n| \u003cimg src=\"Images/aircube-4p-header.png?raw=true\" alt=\"aircube-4p-header\" style=\"width:100px\" /\u003e | 4P 2.54mm 母座      | 1    | 安装 MH-Z19B            |\n| \u003cimg src=\"Images/aircube-8p-header.png?raw=true\" alt=\"aircube-8p-header\" style=\"width:100px\" /\u003e | 8P 2.54mm 母座      | 1    | 安装 1.54 寸 LCD        |\n| \u003cimg src=\"Images/aircube-8p-1.25mm.png?raw=true\" alt=\"aircube-8p-1.25mm\" style=\"width:100px;\" /\u003e | 8P 1.25mm 直针座    | 1    | 安装 PMS5003            |\n| \u003cimg src=\"Images/aircube-m2x5-screw.png?raw=true\" alt=\"aircube-m2x5-screw\" style=\"width:100px\" /\u003e | M2*5 沉头自攻螺丝   | 8    | 固定 PCB 以及后盖       |\n\n## 焊接\n\n**建议母座焊接顺序**\n\n1. 5P 弯针 2.54mm 排母\n2. 8P 1.25mm 直针座\n3. 8P 2.54mm 母座\n4. 3Px2 2.54mm 母座\n5. 15P 2.54mm 母座\n6. 5P 及 4P 2.54mm 母座\n\n其中 BME280 预留位置为 6P，使用弯 5P 母座时，请使用下侧 5P，保留最上针脚留空。\n\n建议参考 [立创开源平台 AirCube](https://oshwhub.com/wandaeda/aircube) 项目中的 PCB 来进行焊接。\n\n## 组装\n\n3D 模型中，外壳和后盖均已预置 M2 螺丝孔，组装时使用 M2*5 自攻螺丝将 PCB 固定在外壳上，再将后盖固定在外壳上即可。\n\n**组装顺序**\n\n1. 将 3D 打印的屏幕支架安装在 PCB 上\n2. 将屏幕安装到排母上，并且 M2 螺丝固定在屏幕支架上\n3. 将 2 个触摸传感器安装在排母上\n4. 将 PMS5003 传感器的连接线连接到 1.25mm 针座上\n5. 将 NodeMCU-32S 安装在排母上\n6. 将 MH-Z19B 安装在排母上\n7. 将 BH1750 安装在排母上\n8. 将 PCB 放进外壳中（可以倾斜着放进去），使用 M2 螺丝固定\n9. 将 PMS5003 固定在后盖上，有必要可以使用双面胶固定\n10. 将后盖使用 M2 螺丝固定在外壳上\n11. 将 BME280 在侧面安装在排母上\n\n注意，BME280 预设安装位置为外壳外部，因此需要将其他部件安装完成，装入外壳固定好后，再从侧面将 BME280 插入 5P 母座。\n\n另外，BH1750 的开孔是朝上的，如果需要避免积灰，可以使用透明胶带盖住。\n\n## 编译和烧录固件\n\nFirmware 目录中已经提供了 `build.sh` 脚本用于快速编译及烧录固件，需要本地安装乐鑫 `esptool.py`，另外 `build.sh` 还接受以下参数用于定制可替换部分元件型号或上报数据参数：\n\n* DP - 屏幕类型，st7789v 或 eink，默认 st7789v\n* CO2 - 二氧化碳传感器型号，mhz19 或 s8，默认 mhz19\n* TEMP - 温湿度传感器型号，bme280 或 sht31，默认 bme280\n* DOMOTICZ - 是否启用 Domoticz 支持，enable 或 disable，默认 disable\n* ROOM - 当前节点所处房间名称，需要英文字符，例如 livingroom\n* IP - 当前节点 IP，建议使用固定 IP，便于后续 OTA 更新固件\n* IDX_BH1750，IDX_PM25，IDX_CO2，IDX_TEMP，IDX_PRESSURE，IDX_HOCO - Domoticz 中对应传感器的设备 ID\n\n另外，如果设置了 `IDX_HOCO`，将会将 PM 2.5 传感器类型设置为 PMS5003ST。\n\n另外，`build.sh` 还提供了 `upload` 参数，可以在编译完成后马上烧录固件。\n\n如果所有传感器类型与默认一致，可以直接使用以下命令编译及烧录固件，注意，需要提前将 NodeMCU-32S 连接到电脑上：\n\n`./build.sh upload`\n\n如果需要定制传感器型号，例如将温湿度传感器替换为 sht31，可以使用以下命令：\n\n`TEMP=sht31 ./build.sh upload`\n\n## 为什么会有这个项目\n\n可以参考这篇文章 [超简单 DIY - AirCube 空气检测站](https://xujiwei.com/blog/2022/12/aircube-diy-environment-monitor-station/)。\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohdarling%2FAirCube","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fohdarling%2FAirCube","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohdarling%2FAirCube/lists"}