如何从私有GitHub仓库为ESP32执行HTTPUpdate固件更新

前置说明 #

你已经完成公开仓库场景的HTTPUpdate固件更新调试，无需修改httpupdate.cpp底层源码即可完成私有仓库的身份认证，操作步骤如下： #

操作步骤 #

1. 生成GitHub个人访问令牌（PAT） #

• 登录GitHub，依次进入「设置」→「开发者设置」→「个人访问令牌」→「Tokens (classic)」
• 点击「Generate new token (classic)」，填写令牌有效期，仅勾选repo类权限即可，生成后保存好令牌字符串，该字符串仅会显示一次

2. 构造私有固件直链 #

私有固件必须使用raw格式的直链，格式为：
https://raw.githubusercontent.com/<GitHub用户名>/<仓库名>/<分支名>/<固件文件路径>.bin

注意不要使用GitHub网页端的文件预览页链接，该链接无法直接下载二进制文件

3. 调用HTTPUpdate时传入认证头 #

官方HTTPUpdate库已经预留了自定义请求头的传入方法，直接在更新请求前添加认证头即可，参考代码如下：

#include <WiFi.h>
#include <HTTPUpdate.h>
#include <WiFiClientSecure.h>

const char* WIFI_SSID = "你的WiFi名称";
const char* WIFI_PWD = "你的WiFi密码";
// 替换为你自己生成的PAT
const char* GITHUB_PAT = "ghp_xxxxxxxxxxxxxxxxxxxx";
// 替换为你自己的私有仓库固件raw直链
const char* FIRMWARE_URL = "https://raw.githubusercontent.com/你的用户名/你的仓库名/main/firmware.bin";

void setup() {
  Serial.begin(115200);
  // 连接WiFi
  WiFi.begin(WIFI_SSID, WIFI_PWD);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("WiFi连接成功");

  // 初始化安全客户端
  WiFiClientSecure client;
  // 测试阶段可关闭证书校验，生产环境建议配置GitHub根证书
  client.setInsecure();

  // 添加GitHub认证头
  httpUpdate.addHeader("Authorization", "token " + String(GITHUB_PAT));
  // 执行固件更新
  t_httpUpdate_return updateRet = httpUpdate.update(client, FIRMWARE_URL);

  switch (updateRet) {
    case HTTP_UPDATE_OK:
      Serial.println("固件更新成功，设备即将重启");
      break;
    case HTTP_UPDATE_FAILED:
      Serial.printf("固件更新失败，错误信息：%s\r\n", httpUpdate.getErrorString().c_str());
      break;
    case HTTP_UPDATE_NO_UPDATES:
      Serial.println("未检测到可用更新");
      break;
  }
}

void loop() {
}

常见问题排查 #

• 若返回401错误：检查PAT是否有权限访问对应仓库，认证头格式是否为token 你的PAT（token和PAT之间有空格）
• 若返回404错误：检查固件raw直链是否正确，仓库/分支/文件路径是否存在
• 若证书校验失败：测试阶段可先使用client.setInsecure()关闭证书校验，排查是否为证书配置问题

内容的提问来源于stack exchange，提问作者Erik Rust