ESP32 Wireless: add BLE + Bluetooth lessons, restructure module into Fundamentals/Wireless#133
Merged
Conversation
Add a comprehensive ESP32 Bluetooth Low Energy lesson (esp32/ble.md). The new document explains BLE concepts (peripheral/central, GATT, UUIDs), the ESP32 BLE Arduino API, and includes multiple full example sketches (Hello World, sensor notifications, NeoPixel control, Nordic UART Service) plus a Web Bluetooth demo page and exercises. The page also lists materials, troubleshooting notes (MTU/notifications), and TODOs for diagrams and media. Also add a bluetooth-serial.md file entry (new Bluetooth Classic reference).
Update esp32/ble.md and esp32/bluetooth-serial.md with expanded, cross-platform guidance and working examples. Added Python client examples (bleak) for BLE discovery, notifications, and NeoPixel control in ble.md, plus notes clarifying iOS/Android compatibility. Revised bluetooth-serial.md to focus on computer-based Bluetooth Classic workflows: pairing instructions for macOS/Windows, pySerial Python demos, Web Serial / p5.js usage with serial.js, and clearer explanations about ESP32 vs ESP32-S3 and SPP limitations. Also cleaned up wording, added troubleshooting notes, TODOs for screenshots/videos, and minor formatting fixes.
Replace in-file examples and old p5js serial library links with canonical references to the Makeability Lab JS repo and CDN. Removed large inline Python demos in favor of existing serial_demo/serial_bar_graph/serial_draw_circle scripts, simplified instructions to changing only the serial port, and clarified SPP behavior and usage notes. Updated p5.js example script src to the new makelab.serial.iife.min.js CDN path and adjusted README links in the resources list. File changed: esp32/bluetooth-serial.md.
Revise the Bluetooth Serial tutorial to improve clarity, accuracy, and accessibility. Key changes: - Add explanation of BluetoothSerial library and API parity with Arduino Serial; include compile-time guards and links to example sketches in the Arduino repo. - Update Python example baud parameter to 115200 and note that most OSes ignore baud for Bluetooth virtual COM ports. - Expand technical context: SPP internals, practical throughput and latency (10–30ms), ESP32 vs ESP32-S3 hardware limitations, and connection-drop behavior. - Improve accessibility and deliverables: require captions/transcripts for videos and descriptive alt text for screenshots; update TODOs accordingly. - Update image alt text and Fritzing TODOs, normalize serial.js links to the repo path, and add notes about analogWrite/LEDC. - Minor wording, formatting, and example path updates throughout to make the lesson more actionable and developer-friendly.
Replace the HTML <details> block with a {.note} blockquote for the "In this lesson, you will learn" section to standardize styling. Add a brief intro to the Exercises section, remove emoji status markers from individual exercises, and rename the "## Summary" heading to "## Lesson Summary". No substantive content changes—just formatting and copy cleanup.
Add a concise Markdown table to esp32/bluetooth-serial.md comparing Arduino Serial and BluetoothSerial APIs (initialization, read/write, connection checks, and callbacks). Clarify that Serial.begin() uses a baud rate while SerialBT.begin() takes a device name and note Bluetooth-specific connection semantics (connected(), register_callback()). Reword the surrounding paragraph to reference the new table and emphasize the initialization difference.
Expand the note in esp32/bluetooth-serial.md to better explain why analogWrite() is used: it was added in ESP32 Arduino core v3.x as a convenience wrapper around the LEDC API. Added a link to the core implementation, renamed the lesson reference, and recommend using the LEDC API when you need control over PWM frequency or resolution.
Revise esp32/ble.md to improve clarity, accessibility, and developer guidance. Changes include: add descriptive alt text for images and TODOs to include captions/transcripts for videos/screencasts; clarify iOS and ESP32-S3 support and adjust BLE throughput wording; replace some callout classes (note→important/caution/highlight) for emphasis; add TODOs and links to push Arduino and Python example sketches to the makeabilitylab GitHub repo and a future ble.js reference; add inline note to verify Bluedroid vs NimBLE defaults; expand NeoPixel/Arduino sections and supply repository links for example sketches; add improved nRF Connect and Web Bluetooth guidance and UI screenshots TODOs; add a comparison table for WiFi / Bluetooth Classic / BLE and a BLE security note; enhance Exercises (new challenges and accessibility suggestion for color indicators); assorted wording, formatting, and structural tweaks to make the lesson more actionable for developers and more accessible to learners.
Enhance the ESP32 BLE lesson with clearer guidance and supplemental references. Added a new comparison table for WiFi, Bluetooth Classic, and BLE (including ESP32/ESP32-S3 support notes) and removed a duplicated table elsewhere in the file. Linked to the Arduino-ESP32 BLE library source and API docs, and added a header table describing common BLE headers. Clarified the server/callback workflow (including onDisconnect advertising restart), expanded explanations for discovery/debugging with bleak, notifications (BLE2902/PROPERTY_NOTIFY and MTU guidance), writable characteristics and callback model, and Web Bluetooth usage. Minor copy edits (note vs caution) and other wording improvements for discoverability and tooling.
I split up ble.md into two lessons as ble.md was getting too long
Rewrite and clarify the ESP32 Bluetooth Classic (SPP) lesson: refine wording and emphasis, add a new section on the continued relevance of Bluetooth Classic, and reorganize the notes about ESP32 vs ESP32-S3 and iPhone limitations. Update instructions and examples for the HelloBluetooth Arduino sketch (improved startup messages, greeting counter, switch to non-blocking read/write loops) and expand the Python usage guide with serial port listing and concrete examples.
Rework the Bluetooth Serial lesson to verify connectivity using built-in OS tools before introducing Python. The HelloBluetooth sketch now sends periodic greetings so users can confirm the sketch is running immediately. Replace the Python-first pairing flow with terminal-based verification (cat/screen on macOS/Linux and a PowerShell serial_reader for Windows), expand pairing/COM-port guidance, and add a comprehensive troubleshooting section. Also renumbered subsequent parts (Parts 3–6 → 2–6 shift) and cleaned up comments/formatting around the serial forwarding logic.
Restructure the ESP32 lesson hierarchy: assign Bluetooth-related lessons to a new 'Wireless' parent (add grand_parent: ESP32) and move analog input under 'Fundamentals'. Renumber lessons and update nav_order (Bluetooth Serial → L2, BLE Intro → L4, Bidirectional BLE → L5). Add new pages (bluetooth-web-serial.md, fundamentals.md, wireless.md), update internal cross-links and lesson references to the new numbering, and adjust content (examples, prerequisites, exercises, and notes) accordingly to reflect the reorganization and split/trimmed Bluetooth Serial content. This addresses: #97
Update esp32/bluetooth-serial.md to improve wording and usability: replace "greeting" language with "message", add p5.js mention, clarify compile-time warning formatting, and add notes about the CHG (orange) LED. Add LED visual feedback (LED_PIN, flashLED, flash timing constants) and refactor periodic message logic to check SerialBT.connected(), only flash LED on send/receive bursts, and tweak serial-forwarding comments. Improve terminal instructions (screen usage and PowerShell link) and add a note linking to a NeoPixel example. Update esp32/wireless.md to include a new, expanded "Lessons" index: list Lesson 1–5 with brief descriptions (including Bluetooth Classic requirements and Web Serial/BLE notes), and a "What's next?" section. Remove duplicate/old lesson block and reorganize content for clearer onboarding and navigation.
Refine ESP32 documentation and Bluetooth examples: tidy copy, fix tables and image paths, and clarify links/TODOs across bluetooth-serial.md and bluetooth-web-serial.md. Rename and simplify the potentiometer sketch (BluetoothPot), push updated Arduino code that adds constants, ADC normalization, LED brightness control, Bluetooth connection state reporting, and optional USB mirroring. Remove a large inline p5 example in favor of guidance to reuse existing serial.js/p5 sketches and add workbench/demo TODOs. Expand fundamentals.md with a clear lessons list and improve wording/clarity in index.md and wireless.md.
Revise esp32/bluetooth-web-serial.md to expand and modernize the lesson: add a bidirectional NeoPixel color-mixer example (BluetoothColorMixer), introduce hosted browser tools (SerialTest and SerialHueBrightnessTest), and include a serial.js API reference and usage notes (baud ignored for SPP). Update materials to recommend Feather V2 (onboard NeoPixel) and provide wiring options for external WS2812 sticks. Clarify prerequisites and ADC1 requirement, add code-level details (smoothing, throttled brightness sends, asymmetric wire protocol), restructure parts/benchmarks, improve workbench/video TODOs, and refresh exercises and resources. Also tidy wording and examples throughout.
# Conflicts: # esp32/analog-input.md # esp32/capacitive-touch.md # esp32/esp32.md # esp32/index.md # esp32/iot.md # esp32/led-blink.md # esp32/led-fade.md # esp32/tone.md
The six pages added on this branch (fundamentals, wireless, and the four BLE/Bluetooth lessons) lacked `description:`, which fails the SEO content-lint gate. Add concise descriptions sourced from each page's content. Heroes/OG images remain deferred (blocked on workbench media) and are tracked per-lesson in #129-#132. Draft-visibility (nav_exclude/search_exclude) for the unfinished BLE drafts left as an open #122 policy decision. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- code-blocks (MD040): add language tokens to 16 bare fences — `text` for
ASCII diagrams and program/serial output, `bash` for shell commands.
- link-check (html-proofer): fix broken refs introduced by the new pages —
- ble-intro: 10kΩ pot image path (Potentiometer_100h.png was nonexistent) →
PanelMountPotentiometer_NoCap_150h.jpg
- bluetooth-web-serial: WS2812 stick image → advancedio/assets path;
../led/addressable-leds.md → ../advancedio/addressable-leds.md (x3)
- fundamentals: capacitive-touch-sensing.md → capacitive-touch.md
- ble-bidirectional: stale cross-ref to L3 "Part 3" bidirectional →
Part 5 (#part-5-bidirectional-control--wireless-color-mixer) (x2)
- bluetooth-serial: serial-intro anchor (#only-one-program-can-open-a-
serial-port-at-a-time)
Verified locally: markdownlint code-blocks gate clean, jekyll build clean,
all link/image/anchor targets resolve in _site.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Adds the ESP32 Wireless lesson series and restructures the ESP32 module into two sub-series — Fundamentals and Wireless — re-parenting every existing ESP32 lesson accordingly. This effectively closes #97 (ESP32 sub-modules).
New pages
esp32/fundamentals.md— Fundamentals sub-module landingesp32/wireless.md— Wireless sub-module landingesp32/bluetooth-serial.md(L2) — Bluetooth Classic SPP / virtual COM portesp32/bluetooth-web-serial.md(L3) — Bluetooth + Web Serial visualizationesp32/ble-intro.md(L4) — Intro to BLE (GATT, services, characteristics, notifications)esp32/ble-bidirectional.md(L5) — bidirectional BLE (phone/browser → hardware, Nordic UART)esp32/index.mdreworked into the two-sub-series structure;iot.mdmoves under Wireless as L1.Standards / CI
maininto the branch and resolved all 8esp32/conflicts (each combines main's recent body edits — gif→mp4, code fences,videos/paths, OGimage:/description:— with this branch'sFundamentals/Wirelessre-parenting).description:front matter to the six new pages.check_seo_frontmatter.pyandcheck_a11y.py --ci(176 pages, 0 issues);bundle exec jekyll buildclean (~15s, all pages render, new nav live).Deferred (intentional)
nav_exclude), consistent with howiot.mdalready ships. Tracked under Finalize draft lessons (add missing circuit diagrams, workbench videos, media) #122.Closes #97. Part of #122.
Draft media tracked in #129, #130, #131, #132.
🤖 Generated with Claude Code