Common Fixes

USB and permissions

Permission denied on /dev/ttyACM0

• Run setup script:

sudo ./scripts/setup-linux-usb.sh

• Log out/in (or reboot), then reconnect board
• Confirm dialout group membership:

groups | grep dialout

Board powers on but no serial device

• Use a data-capable USB cable
• Try direct port, avoid unstable hubs
• Re-check enumeration:

lsusb
ls /dev/ttyACM*

Upload failures

Failed to connect / No serial data received

• Enter download mode with BOOT + RST/EN sequence
• Ensure monitor is closed during upload
• Verify env is esp32-s3-n16r8 for S3 hardware

Invalid head of packet (0x1B)

• Close any active serial monitor/tool using the same port
• Re-enter bootloader mode and retry upload

Serial runtime checks

Blank monitor after upload

• Press RST/EN once while monitor is open
• Or use upload-and-monitor one-liner:

pio run -d firmware -e esp32-s3-n16r8 -t upload && pio device monitor -d firmware -b 115200

Wi-Fi or MQTT MQTT
Message Queuing Telemetry Transport — lightweight publish/subscribe protocol used between ESP32 and AWS IoT Core. never connects

• Re-check WIFI_SSID and WIFI_PASSWORD
• Regenerate headers:

./scripts/generate-headers.sh

• Re-provision device certs if needed — see Device Provisioning:

./aws/provision.sh
./scripts/generate-headers.sh

Cloud verification

Serial publishes but CloudWatch CloudWatch
Amazon CloudWatch Logs — stores IoT rule output for Phase 1 verification (`/aws/iot/esp32-demo/telemetry` and `/events`). is empty

• Confirm correct region variable:

echo "$AWS_REGION"

• Tail error log group:

aws logs tail /aws/iot/esp32-demo/errors --since 1h

• Confirm both IoT rules IoT rules
  AWS IoT Rules — route incoming MQTT messages to Lambda and CloudWatch Logs for ingest and verification. are enabled:

aws iot get-topic-rule --rule-name esp32_demo_telemetry_rule --query 'rule.ruleDisabled'
aws iot get-topic-rule --rule-name esp32_demo_events_rule --query 'rule.ruleDisabled'

• If rules or log groups are missing, re-run CloudFormation Bootstrap

Telemetry publish but no blue LED

• Validate onboard RGB routing (GPIO48 default, some boards require PIN_NEOPIXEL=38)
• Check RGB solder bridge on board variants

FIRMWARE FIRMWARE
PlatformIO-based ESP32 application in `firmware/` — connects to Wi-Fi, syncs time, and publishes MQTT telemetry and events. issues

Wi-Fi reconnect loops in serial logs

• Confirm AP is 2.4 GHz and credentials are correct
• Re-run header generation after env changes:

./scripts/generate-headers.sh

• Reflash firmware and monitor from clean boot

MQTT disconnect after NTP failure

• Confirm outbound NTP and TLS paths are not blocked on the network
• Reboot device and check for successful time sync before MQTT connect
• If repeated, capture serial logs and verify ts fallback behavior is expected

Watchdog reset triggers under unstable connectivity

• Verify power stability and USB cable quality first
• Reduce concurrent host serial tooling to a single monitor
• Check repeated reconnect storms in logs, then reboot and retest in stable network conditions