给 ESP32 示例加自动构建和测试：让后续教程跟得上版本

idf.py -B build-debug -D SDKCONFIG=build-debug/sdkconfig -D SDKCONFIG_DEFAULTS=sdkconfig.defaults build
idf.py -B build-release -D SDKCONFIG=build-release/sdkconfig -D 'SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.release.defaults' build
bash ci/run_host.sh

python "$IDF_PATH/tools/idf_tools.py" install qemu-xtensa
# 在该IDF的新终端重新export，保证qemu-system-xtensa进PATH
python ci/run_qemu.py --build build-debug --log qemu-debug.log --timeout 90

// ---- main/command.h ----
/* SPDX-License-Identifier: MIT */
#pragma once
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
/* No NUL requirement, exact canonical SET:0..1000, maximum8 bytes. */
static inline bool command_parse(const uint8_t *data,size_t size,uint16_t *out){
 if(!data||!out||size<5||size>8||memcmp(data,"SET:",4))return false;
 if(size>5&&data[4]=='0')return false;
 unsigned value=0;
 for(size_t i=4;i<size;++i){if(data[i]<'0'||data[i]>'9')return false;value=value*10+(data[i]-'0');if(value>1000)return false;}
 *out=(uint16_t)value;return true;
}


// ---- main/test_main.c ----
/* SPDX-License-Identifier: MIT */
#include "unity.h"
#include "command.h"
#ifndef E10_HOST
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"
#endif
void setUp(void){}
void tearDown(void){}
static void parse_zero_and_limit(void){uint16_t v=99;TEST_ASSERT_TRUE(command_parse((const uint8_t*)"SET:0",5,&v));TEST_ASSERT_EQUAL_UINT16(0,v);TEST_ASSERT_TRUE(command_parse((const uint8_t*)"SET:1000",8,&v));TEST_ASSERT_EQUAL_UINT16(1000,v);}
static void parse_real_buffer_without_nul(void){const uint8_t b[]={'S','E','T',':','4','2'};uint16_t v=0;TEST_ASSERT_TRUE(command_parse(b,sizeof(b),&v));TEST_ASSERT_EQUAL_UINT16(42,v);}
static void reject_invalid_tokens(void){const char *bad[]={"SET:-1","SET:+1","SET:01","SET:1001","SET:1\n","set:1","SET:"};uint16_t v=77;for(size_t i=0;i<sizeof(bad)/sizeof(bad[0]);++i){TEST_ASSERT_FALSE(command_parse((const uint8_t*)bad[i],strlen(bad[i]),&v));TEST_ASSERT_EQUAL_UINT16(77,v);}}
static void reject_null_and_oversize(void){uint16_t v=0;TEST_ASSERT_FALSE(command_parse(NULL,5,&v));TEST_ASSERT_FALSE(command_parse((const uint8_t*)"SET:1",5,NULL));TEST_ASSERT_FALSE(command_parse((const uint8_t*)"SET:12345",9,&v));}
static void reject_embedded_nul(void){const uint8_t b[]={'S','E','T',':','1',0};uint16_t v=0;TEST_ASSERT_FALSE(command_parse(b,sizeof(b),&v));}
#ifdef E10_INJECT_FAILURE
static void intentional_red_gate(void){TEST_FAIL_MESSAGE("SYNTHETIC_EXPECTED_FAILURE: test runner must return nonzero");}
#endif
#ifndef E10_HOST
static void actual_freertos_fifo_and_full(void){
 QueueHandle_t q=xQueueCreate(2,sizeof(uint16_t));TEST_ASSERT_NOT_NULL(q);uint16_t a=1,b=2,c=3,out=0;
 TEST_ASSERT_EQUAL(pdTRUE,xQueueSend(q,&a,0));TEST_ASSERT_EQUAL(pdTRUE,xQueueSend(q,&b,0));TEST_ASSERT_EQUAL(errQUEUE_FULL,xQueueSend(q,&c,0));
 TEST_ASSERT_EQUAL(pdTRUE,xQueueReceive(q,&out,0));TEST_ASSERT_EQUAL_UINT16(1,out);TEST_ASSERT_EQUAL(pdTRUE,xQueueReceive(q,&out,0));TEST_ASSERT_EQUAL_UINT16(2,out);TEST_ASSERT_EQUAL(pdFALSE,xQueueReceive(q,&out,0));vQueueDelete(q);
}
static void actual_freertos_latest_mailbox(void){
 QueueHandle_t q=xQueueCreate(1,sizeof(uint16_t));TEST_ASSERT_NOT_NULL(q);uint16_t a=1,b=9,out=0;
 TEST_ASSERT_EQUAL(pdPASS,xQueueOverwrite(q,&a));TEST_ASSERT_EQUAL(pdPASS,xQueueOverwrite(q,&b));TEST_ASSERT_EQUAL(pdTRUE,xQueueReceive(q,&out,0));TEST_ASSERT_EQUAL_UINT16(9,out);vQueueDelete(q);
}
#endif
static int run_tests(void){
 UNITY_BEGIN();RUN_TEST(parse_zero_and_limit);RUN_TEST(parse_real_buffer_without_nul);RUN_TEST(reject_invalid_tokens);RUN_TEST(reject_null_and_oversize);RUN_TEST(reject_embedded_nul);
#ifdef E10_INJECT_FAILURE
 RUN_TEST(intentional_red_gate);
#endif
#ifndef E10_HOST
 RUN_TEST(actual_freertos_fifo_and_full);RUN_TEST(actual_freertos_latest_mailbox);
#endif
 return UNITY_END();
}
#ifdef E10_HOST
int main(void){return run_tests();}
#else
void app_main(void){int failures=run_tests();printf("E10_UNITY_COMPLETE failures=%d\n",failures);fflush(stdout);for(;;)vTaskDelay(pdMS_TO_TICKS(1000));}
#endif

# ---- ci/run_host.sh ----
#!/usr/bin/env bash
set -euo pipefail
: "${IDF_PATH:?Activate the exact IDF environment first}"
project_dir="$(cd "$(dirname "$0")/.." && pwd)"
output_dir="${E10_HOST_OUTPUT:-$project_dir/build-host}"
mkdir -p "$output_dir"
unity_dir="$IDF_PATH/components/unity/unity/src"
# SDK Unity itself, with only original application parser shared with firmware.
cc -std=c11 -Wall -Wextra -Werror -DE10_HOST -I"$unity_dir" -I"$project_dir/main" "$unity_dir/unity.c" "$project_dir/main/test_main.c" -o "$output_dir/tests"
"$output_dir/tests"
cc -std=c11 -Wall -Wextra -Werror -DE10_HOST -DE10_INJECT_FAILURE -I"$unity_dir" -I"$project_dir/main" "$unity_dir/unity.c" "$project_dir/main/test_main.c" -o "$output_dir/expected-red"
set +e
"$output_dir/expected-red" > "$output_dir/expected-red.log" 2>&1
red_exit=$?
set -e
if [[ $red_exit -eq 0 ]]; then echo 'ERROR: intentional failing Unity case was accepted'; exit 1; fi
if ! grep -q 'SYNTHETIC_EXPECTED_FAILURE' "$output_dir/expected-red.log"; then cat "$output_dir/expected-red.log"; exit 1; fi
printf 'Expected-red Unity process rejected with exit %s; not hardware evidence.\n' "$red_exit"


# ---- ci/run_qemu.py ----
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Run built S3 firmware through official idf.py qemu; fail closed, retain log.
No claim of Wi-Fi, I2C/OLED, USB/JTAG electrical, power or target timing coverage.
"""
import argparse,os,pathlib,re,signal,subprocess,sys,time,threading,queue
p=argparse.ArgumentParser();p.add_argument('--build',required=True);p.add_argument('--log',required=True);p.add_argument('--timeout',type=float,default=90);a=p.parse_args()
if not 0<a.timeout<=300:p.error('timeout must be in(0,300]')
project=pathlib.Path(__file__).resolve().parents[1];build=pathlib.Path(a.build).resolve();log=pathlib.Path(a.log).resolve();log.parent.mkdir(parents=True,exist_ok=True)
cmd=[sys.executable,str(pathlib.Path(os.environ['IDF_PATH'])/'tools/idf.py'),'-C',str(project),'-B',str(build),'qemu']
process=subprocess.Popen(cmd,stdout=subprocess.PIPE,stderr=subprocess.STDOUT,start_new_session=True);lines=queue.Queue()
def read():
 for raw in iter(process.stdout.readline,b''):lines.put(raw)
 lines.put(None)
threading.Thread(target=read,daemon=True).start();deadline=time.monotonic()+a.timeout;complete=False;tests=False;failure='timeout/no completion marker';received=[]
try:
 with log.open('wb') as f:
  while time.monotonic()<deadline:
   try:line=lines.get(timeout=min(.25,max(.01,deadline-time.monotonic())))
   except queue.Empty:
    if process.poll() is not None:failure='QEMU exited before completion';break
    continue
   if line is None:failure='QEMU stream ended before completion';break
   f.write(line);f.flush();text=line.decode('utf-8',errors='replace');received.append(text)
   if re.search(r'7 Tests 0 Failures 0 Ignored',text):tests=True
   if 'E10_UNITY_COMPLETE' in text:
    complete=tests and bool(re.search(r'E10_UNITY_COMPLETE failures=0(?:\s|$)',text));failure='incomplete or failing Unity summary';break
finally:
 if process.poll() is None:
  os.killpg(process.pid,signal.SIGTERM)
  try:process.wait(timeout=5)
  except subprocess.TimeoutExpired:os.killpg(process.pid,signal.SIGKILL);process.wait(timeout=5)
if not complete:print('FAIL',failure,'raw log:',log);sys.exit(1)
print('PASS actual S3 QEMU:5 parser +2 real FreeRTOS queue cases; not physical board or peripheral evidence. Raw log:',log)

# ---- ci/esp32-example-ci.yml ----
name: ESP32 E10 clean build and Unity
on:
  workflow_dispatch:
  push:
    paths:
      - 'examples/esp32/esp32-example-ci-qemu/**'
      - '.github/workflows/esp32-example-ci.yml'
  pull_request:
    paths:
      - 'examples/esp32/esp32-example-ci-qemu/**'
      - '.github/workflows/esp32-example-ci.yml'
permissions:
  contents: read
concurrency:
  group: e10-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
jobs:
  clean-build-unity:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        include:
          - idf: v5.5.5
            optimization: debug
            image: docker.io/espressif/idf@sha256:6e2800a69f1c6521a5651da524f811e237d13e34cad369687916d0ad0bc4ef89
          - idf: v5.5.5
            optimization: release
            image: docker.io/espressif/idf@sha256:6e2800a69f1c6521a5651da524f811e237d13e34cad369687916d0ad0bc4ef89
          - idf: v5.5.4
            optimization: debug
            image: docker.io/espressif/idf@sha256:116f0526dfc87e764785370e59b88822e02cf4f9e1edd953cad5ed2d02672023
          - idf: v5.5.4
            optimization: release
            image: docker.io/espressif/idf@sha256:116f0526dfc87e764785370e59b88822e02cf4f9e1edd953cad5ed2d02672023
    name: ${{ matrix.idf }} / S3 / ${{ matrix.optimization }}
    container:
      image: ${{ matrix.image }}
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
        with:
          persist-credentials: false
      - name: Fresh environment and QEMU dependencies
        run: |
          set -euo pipefail
          apt-get update -qq
          apt-get install -y --no-install-recommends libgcrypt20 libglib2.0-0 libpixman-1-0 libsdl2-2.0-0 libslirp0
          source "$IDF_PATH/export.sh"
          idf.py --version | tee "$RUNNER_TEMP/e10-idf-version.log"
          idf.py --version | grep -F '${{ matrix.idf }}'
          python "$IDF_PATH/tools/idf_tools.py" install qemu-xtensa
      - name: Host Unity and intentional red gate
        id: host_tests
        run: |
          set -euo pipefail
          source "$IDF_PATH/export.sh"
          export E10_HOST_OUTPUT="$RUNNER_TEMP/e10-host"
          bash examples/esp32/esp32-example-ci-qemu/ci/run_host.sh | tee "$RUNNER_TEMP/e10-host.log"
      - name: Clean S3 build and real QEMU Unity
        id: unity_build
        run: |
          set -euo pipefail
          source "$IDF_PATH/export.sh"
          project="$GITHUB_WORKSPACE/examples/esp32/esp32-example-ci-qemu"
          build="$RUNNER_TEMP/e10-build"
          test ! -e "$build"
          defaults='sdkconfig.defaults'
          if [[ '${{ matrix.optimization }}' == release ]]; then defaults='sdkconfig.defaults;sdkconfig.release.defaults'; fi
          idf.py -C "$project" -B "$build" -D SDKCONFIG="$build/sdkconfig" -D SDKCONFIG_DEFAULTS="$defaults" build | tee "$RUNNER_TEMP/e10-build.log"
          python "$project/ci/run_qemu.py" --build "$build" --log "$RUNNER_TEMP/e10-qemu.log" --timeout 90
          python "$project/ci/record_ci.py" --build "$build" --idf '${{ matrix.idf }}' --optimization '${{ matrix.optimization }}' --image '${{ matrix.image }}' --output "$RUNNER_TEMP/e10-ci-record.json"
      - name: Collect exact container artifacts and fail closed
        if: always()
        run: |
          set -euo pipefail
          args=()
          if [[ '${{ steps.unity_build.outcome }}' == success ]]; then args+=(--require-complete); fi
          python3 examples/esp32/esp32-example-ci-qemu/ci/collect_ci.py "${args[@]}"
      - name: Preserve artifacts and raw logs
        if: always()
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
        with:
          name: e10-${{ matrix.idf }}-${{ matrix.optimization }}-${{ github.run_attempt }}
          retention-days: 14
          if-no-files-found: error
          path: e10-ci-artifacts/


# ---- ci/record_ci.py ----
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
import argparse,pathlib,json,hashlib,os,subprocess
p=argparse.ArgumentParser();p.add_argument('--build',required=True);p.add_argument('--idf',required=True);p.add_argument('--optimization',required=True);p.add_argument('--image',required=True);p.add_argument('--output',required=True);a=p.parse_args()
root=pathlib.Path(__file__).resolve().parents[1];build=pathlib.Path(a.build).resolve();h=lambda p:hashlib.sha256(p.read_bytes()).hexdigest()
config=json.loads((build/'config/sdkconfig.json').read_text())
expected='COMPILER_OPTIMIZATION_DEBUG' if a.optimization=='debug' else 'COMPILER_OPTIMIZATION_SIZE'
if config.get('IDF_TARGET')!='esp32s3' or config.get(expected) is not True:raise SystemExit('matrix target/optimization differs from actual generated config')
sources=[{'path':str(p.relative_to(root)),'sha256':h(p)} for p in sorted(root.rglob('*')) if p.is_file() and not any(x.startswith('build') or x=='managed_components' or x=='__pycache__' for x in p.relative_to(root).parts)]
artifacts=[{'path':str(p.relative_to(build)),'sha256':h(p),'bytes':p.stat().st_size} for p in sorted(build.rglob('*')) if p.is_file() and (p.suffix in ['.bin','.elf','.map'] or p.name in ['sdkconfig','sdkconfig.h','sdkconfig.cmake','sdkconfig.json','flasher_args.json'])]
result={'githubSHA':os.getenv('GITHUB_SHA'),'runId':os.getenv('GITHUB_RUN_ID'),'runAttempt':os.getenv('GITHUB_RUN_ATTEMPT'),'runnerEnvironment':os.getenv('RUNNER_ENVIRONMENT'),'requestedIDF':a.idf,'actualIDF':subprocess.check_output(['python',str(pathlib.Path(os.environ['IDF_PATH'])/'tools/idf.py'),'--version'],text=True).strip(),'target':'esp32s3','optimization':a.optimization,'immutableImage':a.image,'sources':sources,'artifacts':artifacts,'scope':'clean firmware build; host parser Unity; S3 QEMU parser and actual FreeRTOS queue tests; no physical Wi-Fi/I2C/display/power/JTAG result'}
pathlib.Path(a.output).write_text(json.dumps(result,indent=2))


# ---- ci/collect_ci.py ----
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Collect from real container paths; always keep useful failed-run evidence.
Successful build requires complete hashed products. Never use runner.temp context.
"""
import argparse,datetime,hashlib,json,os,pathlib,shutil,sys
p=argparse.ArgumentParser();p.add_argument('--build');p.add_argument('--output');p.add_argument('--require-complete',action='store_true');a=p.parse_args()
workspace=pathlib.Path(os.environ['GITHUB_WORKSPACE']).resolve();temp=pathlib.Path(os.environ['RUNNER_TEMP']).resolve();project=pathlib.Path(__file__).resolve().parents[1]
build=pathlib.Path(a.build).resolve() if a.build else temp/'e10-build';output=pathlib.Path(a.output).resolve() if a.output else workspace/'e10-ci-artifacts';output.mkdir(parents=True,exist_ok=True)
errors=[];entries=[];seen=set();h=lambda p:hashlib.sha256(p.read_bytes()).hexdigest()
def copy(source,relative,required=False,expected=None):
 source=pathlib.Path(source);relative=str(relative)
 if not source.is_file():
  if required:errors.append('missing '+str(source))
  return
 if relative in seen:return
 seen.add(relative);dest=output/relative;dest.parent.mkdir(parents=True,exist_ok=True);shutil.copyfile(source,dest)
 digest=h(dest)
 if expected and digest!=expected:errors.append('record SHA mismatch '+str(source))
 entries.append({'path':relative,'source':str(source),'bytes':dest.stat().st_size,'sha256':digest})
for name in ['e10-idf-version.log','e10-host.log','e10-build.log','e10-qemu.log']:copy(temp/name,'logs/'+name,True)
copy(temp/'e10-host/expected-red.log','logs/expected-red.log',True)
record_path=temp/'e10-ci-record.json';copy(record_path,'e10-ci-record.json',True);record=None
if record_path.is_file():
 try:record=json.loads(record_path.read_text())
 except (ValueError,OSError) as e:errors.append('invalid CI record: '+str(e))
if record:
 for f in record.get('artifacts',[]):
  rel=pathlib.Path(f['path']);source=(build/rel).resolve()
  if not source.is_relative_to(build):errors.append('artifact escaped build '+str(rel));continue
  copy(source,'build/'+str(rel),True,f['sha256'])
 for f in record.get('sources',[]):
  source=(project/f['path']).resolve()
  if not source.is_relative_to(project) or not source.is_file() or h(source)!=f['sha256']:errors.append('source record mismatch '+f['path'])
else:errors.append('no readable CI record')
# Configuration and compiler provenance accompany final products even if record
# was not written because an earlier build step failed.
for name in ['sdkconfig','config/sdkconfig.h','config/sdkconfig.json','config/sdkconfig.cmake','flasher_args.json','flash_args','project_description.json','compile_commands.json','partition_table/partition-table.bin','bootloader/bootloader.bin']:
 copy(build/name,'build/'+name,True)
copy(project/'dependencies.lock','dependencies.lock',True)
try:
 desc=json.loads((build/'project_description.json').read_text())
 for key in ['app_bin','app_elf']:copy(build/desc[key],'build/'+desc[key],True)
 copy(build/(pathlib.Path(desc['app_elf']).stem+'.map'),'build/'+pathlib.Path(desc['app_elf']).stem+'.map',True)
except (ValueError,KeyError,OSError) as e:errors.append('application products unavailable: '+str(e))
# Success also requires genuine test summaries, not just a nonempty file.
required_text={'e10-host.log':['5 Tests 0 Failures 0 Ignored','Expected-red Unity process rejected with exit 1'],'e10-qemu.log':['7 Tests 0 Failures 0 Ignored','E10_UNITY_COMPLETE failures=0']}
for name,markers in required_text.items():
 text=(temp/name).read_text(errors='replace') if (temp/name).is_file() else ''
 for marker in markers:
  if marker not in text:errors.append('missing test marker '+name+': '+marker)
red=temp/'e10-host/expected-red.log';text=red.read_text(errors='replace') if red.is_file() else ''
if 'SYNTHETIC_EXPECTED_FAILURE' not in text or '6 Tests 1 Failures 0 Ignored' not in text:errors.append('expected-red evidence incomplete')
manifest={'collectedAt':datetime.datetime.now(datetime.timezone.utc).isoformat(),'githubSHA':os.getenv('GITHUB_SHA'),'runId':os.getenv('GITHUB_RUN_ID'),'runAttempt':os.getenv('GITHUB_RUN_ATTEMPT'),'runnerEnvironment':os.getenv('RUNNER_ENVIRONMENT','local-author-fixture'),'actualRUNNER_TEMP':str(temp),'actualGITHUB_WORKSPACE':str(workspace),'requireComplete':a.require_complete,'complete':not errors,'errors':errors,'files':sorted(entries,key=lambda x:x['path']),'scope':'artifact collection only; local fixtures are not hosted CI or physical results'}
(output/'collection-manifest.json').write_text(json.dumps(manifest,indent=2))
print('COLLECT',len(entries),'files; complete=',not errors,'requireComplete=',a.require_complete,'manifest=',output/'collection-manifest.json')
if errors:
 print('\n'.join(errors))
 if a.require_complete:sys.exit(1)