esp32-dev/components/protocol-quick-ref.md

Protocol Quick Reference

类别：reference | 主题：通信协议快速参考 | 信源： 多平台汇总

Table of Contents

• I2C (Inter-Integrated Circuit)
  • Overview
  • Signal Lines
  • Speed Modes
  • Pull-up Requirements
  • Common I2C Addresses (Collision Detection)
  • Platform Notes
• SPI (Serial Peripheral Interface)
  • Overview
  • Signal Lines
  • Speed
  • Clock Modes
  • Pull-up Requirements
  • Platform Notes
• UART (Universal Asynchronous Receiver/Transmitter)
  • Overview
  • Signal Lines
  • Common Baud Rates
  • Frame Format
  • Voltage Levels
  • Level Shifting
  • Platform Notes
• PWM (Pulse Width Modulation)
  • Overview
  • Key Parameters
  • Frequency by Application
  • Servo Control Specifics
  • Platform Notes
• 1-Wire
  • Overview
  • Signal Line
  • Pull-up Requirement
  • Common 1-Wire Devices
  • Platform Notes
• CAN (Controller Area Network)
  • Overview
  • Signal Lines
  • Common Transceivers
  • Speed and Termination
  • Platform Notes
• ADC (Analog-to-Digital Converter)
  • Overview
  • Key Parameters
  • Platform Comparison
  • ESP32 ADC Attenuation
  • External ADC Options
  • Input Protection
  • Platform Notes

---

I2C (Inter-Integrated Circuit)

Overview

• Two-wire synchronous serial bus
• Multi-device: multiple slaves on same bus
• Addressable: 7-bit (128) or 10-bit (1024) addresses
• Open-drain: requires external pull-up resistors
• Half-duplex: bidirectional on single data line

Signal Lines

• SDA：Direction=Bidirectional, Type=Open-drain, Description=Serial data
• SCL：Direction=Master→Slave, Type=Open-drain, Description=Serial clock

Speed Modes

• Standard：Speed=100 kHz, Notes=Universal compatibility
• Fast：Speed=400 kHz, Notes=Most common for sensors
• Fast Plus：Speed=1 MHz, Notes=Requires stronger pull-ups
• High Speed：Speed=3.4 MHz, Notes=Rarely used in hobby projects

Pull-up Requirements

REQUIRED on both SDA and SCL lines.

• Standard/Fast：Recommended Value=4.7kΩ, Notes=Most common choice
• Fast Plus：Recommended Value=2.2kΩ, Notes=Stronger pull needed
• High Speed / Long wires：Recommended Value=1kΩ, Notes=Compensates for capacitance

Calculation Formula:

R = (VCC - VOL) / IOL
R = (3.3V - 0.4V) / 3mA = 967Ω minimum

Consequences of Wrong Value:

• Too high (>10kΩ): Slow rise times, communication errors, fails at higher speeds
• Too low (<1kΩ): Excessive current draw, devices cannot pull line LOW, bus contention

Common I2C Addresses (Collision Detection)

• 0x20-0x27：Device(s)=MCP23017 GPIO expander, PCF8574
• 0x27, 0x3F：Device(s)=PCF8574 LCD backpack
• 0x29：Device(s)=VL53L0X ToF distance sensor
• 0x39：Device(s)=APDS9960 gesture/color sensor
• 0x3C, 0x3D：Device(s)=SSD1306 OLED display
• 0x40：Device(s)=INA219 current sensor, PCA9685 PWM
• 0x48-0x4B：Device(s)=ADS1115/ADS1015 ADC
• 0x50-0x57：Device(s)=AT24C EEPROM
• 0x5A：Device(s)=MLX90614 IR thermometer
• 0x60：Device(s)=Si5351 clock generator
• 0x68：Device(s)=DS3231 RTC, MPU6050 IMU
• 0x76, 0x77：Device(s)=BME280/BMP280 sensor

Note: Many devices have address pins (A0, A1, A2) to resolve conflicts.

Platform Notes

Raspberry Pi:

• I2C1 (GPIO2/3) is the primary user-accessible bus
• I2C0 (GPIO0/1) is reserved for HAT EEPROM detection — do not use
• Enable with dtparam=i2c_arm=on in config.txt
• Pi 4/5 have additional I2C buses via dtoverlay

ESP32:

• Any GPIO pair works via GPIO matrix — no fixed pins
• Convention: GPIO21 (SDA), GPIO22 (SCL)
• Do NOT use input-only pins (GPIO34-39) — they cannot drive SDA

---

SPI (Serial Peripheral Interface)

Overview

• Four-wire synchronous serial bus
• Full-duplex: simultaneous send and receive
• One chip select (CS) per slave device
• No addressing: CS line selects device
• Push-pull drivers: no pull-ups required on data/clock

Signal Lines

• MOSI：Direction=Master→Slave, Description=Master Out, Slave In
• MISO：Direction=Slave→Master, Description=Master In, Slave Out
• SCLK：Direction=Master→Slave, Description=Serial clock
• CS/SS：Direction=Master→Slave, Description=Chip Select (active LOW)

Speed

• Typical: 1-40 MHz (device dependent)
• Check slave device datasheet for maximum
• Longer wires = lower reliable speed

Clock Modes

• 0：CPOL=0, CPHA=0, Clock Idle=LOW, Data Sampled On=Rising edge
• 1：CPOL=0, CPHA=1, Clock Idle=LOW, Data Sampled On=Falling edge
• 2：CPOL=1, CPHA=0, Clock Idle=HIGH, Data Sampled On=Falling edge
• 3：CPOL=1, CPHA=1, Clock Idle=HIGH, Data Sampled On=Rising edge

Note: Mode 0 is most common. Check device datasheet.

Pull-up Requirements

• MOSI, MISO, SCLK: Generally NOT required (push-pull drivers)
• CS lines: 10kΩ pull-up recommended to prevent floating during boot/reset

Platform Notes

Raspberry Pi:

• SPI0 (GPIO7-11) is primary bus — CE0 (GPIO8), CE1 (GPIO7)
• SPI1 (GPIO16-21) available but conflicts with PCM/I2S audio
• Enable with dtparam=spi=on in config.txt

ESP32:

• VSPI (SPI3): GPIO23 (MOSI), GPIO19 (MISO), GPIO18 (SCLK), GPIO5 (CS) — recommended
• HSPI (SPI2): GPIO13 (MOSI), GPIO12 (MISO), GPIO14 (SCLK), GPIO15 (CS)
• WARNING: HSPI pins overlap strapping pins! GPIO12 can brick the module if HIGH at boot.
• Any GPIO can be used via GPIO matrix (except input-only pins for outputs)

---

UART (Universal Asynchronous Receiver/Transmitter)

Overview

• Two-wire asynchronous serial communication
• Point-to-point: one transmitter, one receiver per pair
• No clock line: baud rate must match on both ends
• Simple: widely supported, easy to debug

Signal Lines

• TX：Direction=Output, Description=Transmit data (connect to peer's RX)
• RX：Direction=Input, Description=Receive data (connect to peer's TX)
• RTS：Direction=Output, Description=Request to Send (optional flow control)
• CTS：Direction=Input, Description=Clear to Send (optional flow control)

Critical: TX connects to RX, RX connects to TX (crossover).

Common Baud Rates

• 9600：Use Case=Legacy devices, GPS modules
• 19200：Use Case=Some sensors
• 38400：Use Case=Bluetooth modules
• 57600：Use Case=Faster sensors
• 115200：Use Case=Most common default
• 230400：Use Case=High-speed peripherals
• 460800：Use Case=ESP32 flash programming
• 921600：Use Case=Fast data transfer

Frame Format

Standard: 8N1 (8 data bits, No parity, 1 stop bit)

Other formats exist (7E1, 8E1, etc.) but 8N1 covers 95%+ of use cases.

Voltage Levels

• TTL 3.3V：Voltage=0V / 3.3V, Common Devices=RPi, ESP32, modern MCUs
• TTL 5V：Voltage=0V / 5V, Common Devices=Arduino, many modules
• RS-232：Voltage=±12V, Common Devices=PC serial ports

CRITICAL: RS-232 levels (±12V) will DESTROY 3.3V GPIO instantly. Use MAX232 or similar transceiver.

Level Shifting

• 5V TX → 3.3V RX: Use voltage divider (1kΩ + 2kΩ) or level shifter
• 3.3V TX → 5V RX: Often works directly (check VIH threshold)
• Always use bidirectional level shifter for RTS/CTS

Platform Notes

Raspberry Pi:

• UART0 (GPIO14/15) is primary serial port
• Conflicts with Bluetooth on Pi 3/4/Zero2W — use dtoverlay=disable-bt or dtoverlay=miniuart-bt
• Pi 4/5 have additional UARTs via dtoverlay

ESP32:

• UART0 (GPIO1/3) is USB serial debug — avoid for peripherals
• UART1 and UART2 are freely available
• Any GPIO can be assigned via GPIO matrix

---

PWM (Pulse Width Modulation)

Overview

• Digital approximation of analog voltage
• Square wave at fixed frequency
• Duty cycle controls average voltage
• Used for: LED dimming, motor speed, servo position, audio

Key Parameters

• Frequency：Description=Pulses per second, Typical Range=50 Hz - 100 kHz
• Duty Cycle：Description=HIGH time percentage, Typical Range=0-100%
• Resolution：Description=Steps of duty control, Typical Range=8-bit (256) to 16-bit (65536)

Average Voltage: Vavg = VCC × (Duty Cycle / 100)

Frequency by Application

• LED dimming：Frequency=500-5000 Hz, Reason=>500Hz avoids visible flicker
• Servo control：Frequency=50 Hz, Reason=Standard RC servo protocol (20ms period)
• Motor control：Frequency=1-20 kHz, Reason=Higher = less audible whine
• Audio generation：Frequency=20-100 kHz, Reason=Above audible range
• Switching PSU：Frequency=50-500 kHz, Reason=Efficiency vs. noise tradeoff

Servo Control Specifics

• Period: 20ms (50 Hz)
• Pulse width: 1ms (0°) to 2ms (180°)
• Neutral: 1.5ms (90°)
• Duty cycle: 5% (1ms) to 10% (2ms) at 50Hz

Platform Notes

Raspberry Pi:

• 2 hardware PWM channels only
• PWM0: GPIO12 (preferred) or GPIO18 (conflicts with audio)
• PWM1: GPIO13 (preferred) or GPIO19 (conflicts with audio)
• Software PWM available on any pin but less precise (jitter)
• Enable with dtoverlay=pwm or dtoverlay=pwm-2chan

ESP32:

• LEDC peripheral: 16 channels of hardware PWM
• Can output on any output-capable GPIO
• Cannot use input-only pins (GPIO34-39)
• Configurable resolution (1-16 bit) and frequency
• Motor Control PWM (MCPWM) for advanced motor control

---

1-Wire

Overview

• Single-wire bidirectional bus
• Parasitic power option (power over data line)
• Each device has unique 64-bit ROM ID
• Multiple devices on same bus (addressed by ROM)
• Open-drain: requires pull-up resistor

Signal Line

• DQ：Type=Bidirectional, Open-drain, Description=Data and (optionally) power

Pull-up Requirement

REQUIRED: 4.7kΩ to VCC (3.3V or 5V depending on devices)

• Stronger pull-up (2.2kΩ-1kΩ) for long cables or many devices
• Parasitic power mode may need stronger pull-up during temperature conversion

Common 1-Wire Devices

• DS18B20：Function=Temperature sensor, Notes=Most popular 1-Wire device
• DS18S20：Function=Temperature sensor, Notes=Older, 9-bit only
• DS2401：Function=Serial number, Notes=Silicon serial number
• DS2413：Function=GPIO, Notes=2-channel I/O
• iButton：Function=Various, Notes=Key fobs, access control

Platform Notes

Raspberry Pi:

• Default pin: GPIO4
• Enable with dtoverlay=w1-gpio
• Change pin with dtoverlay=w1-gpio,gpiopin=N
• Kernel driver handles protocol automatically

ESP32:

• Any GPIO can be used via OneWire library
• GPIO4 is common convention
• Requires software library (no hardware peripheral)

---

CAN (Controller Area Network)

Overview

• Differential two-wire bus (noise immune)
• Multi-master: any node can initiate
• Message-based: no addresses, messages have IDs
• Priority: lower message ID = higher priority
• Error detection: CRC, ACK, bit stuffing
• Common in: automotive, industrial, robotics

Signal Lines

• CAN_H：Description=CAN High (dominant = 3.5V)
• CAN_L：Description=CAN Low (dominant = 1.5V)

Note: Requires transceiver chip (GPIO cannot drive CAN directly)

Common Transceivers

• MCP2551：Voltage=5V, Notes=Classic, widely available
• SN65HVD230：Voltage=3.3V, Notes=Good for ESP32/RPi
• TJA1050：Voltage=5V, Notes=Automotive grade

Speed and Termination

• 125 kbps：Max Bus Length=500m, Use Case=Long distance
• 250 kbps：Max Bus Length=250m, Use Case=General purpose
• 500 kbps：Max Bus Length=100m, Use Case=Automotive
• 1 Mbps：Max Bus Length=40m, Use Case=High speed

Termination: 120Ω resistor at each end of bus (two total). Many transceiver modules have onboard termination jumper.

Platform Notes

Raspberry Pi:

• No built-in CAN controller
• Requires external MCP2515 (SPI-to-CAN) + transceiver
• Enable with dtoverlay=mcp2515-can0,oscillator=8000000,interrupt=25
• Uses SocketCAN interface

ESP32:

• Built-in TWAI controller (CAN 2.0B compatible)
• Only needs external transceiver (e.g., SN65HVD230)
• Common pins: GPIO4 (TX), GPIO5 (RX) — but any GPIO works
• ESP-IDF and Arduino libraries available

---

ADC (Analog-to-Digital Converter)

Overview

• Converts continuous analog voltage to discrete digital value
• Key parameters: resolution, reference voltage, sample rate
• Input must not exceed reference voltage

Key Parameters

• Resolution：Description=Bits of precision (10-bit = 1024 steps, 12-bit = 4096)
• Reference：Description=Full-scale input voltage (typically VCC or internal ref)
• Sample Rate：Description=Conversions per second (SPS)
• Input Range：Description=Allowable input voltage (0 to Vref typically)

Platform Comparison

• Built-in ADC：Raspberry Pi=No, ESP32=Yes (2 ADCs)
• Resolution：Raspberry Pi=N/A, ESP32=12-bit (4096 levels)
• Channels：Raspberry Pi=N/A, ESP32=ADC1: 8ch, ADC2: 10ch
• Reference：Raspberry Pi=N/A, ESP32=0-3.3V (with attenuation)
• Sample Rate：Raspberry Pi=N/A, ESP32=Up to 2 MSPS
• WiFi Conflict：Raspberry Pi=N/A, ESP32=ADC2 unusable with WiFi

ESP32 ADC Attenuation

• 0 dB：Input Range=0-1.1V, Notes=Highest accuracy
• 2.5 dB：Input Range=0-1.5V
• 6 dB：Input Range=0-2.2V
• 11 dB：Input Range=0-3.3V, Notes=Full range, lower accuracy

External ADC Options

• ADS1115：Interface=I2C, Resolution=16-bit, Channels=4, Notes=Programmable gain, slow (860 SPS)
• ADS1015：Interface=I2C, Resolution=12-bit, Channels=4, Notes=Faster than ADS1115 (3300 SPS)
• MCP3008：Interface=SPI, Resolution=10-bit, Channels=8, Notes=Simple, cheap, fast
• MCP3208：Interface=SPI, Resolution=12-bit, Channels=8, Notes=Higher resolution MCP3008
• ADS7828：Interface=I2C, Resolution=12-bit, Channels=8, Notes=8-channel I2C option

Input Protection

• Never exceed reference voltage — will damage ADC or give invalid readings
• Use voltage divider for higher voltages
• Add clamp diodes (Schottky to VCC and GND) for unknown inputs
• Add RC filter (100Ω + 100nF) to reduce noise

Platform Notes

Raspberry Pi:

• No built-in ADC — external ADC required for any analog input
• MCP3008 (SPI) or ADS1115 (I2C) are most common choices
• Many HATs include ADC chips

ESP32:

• ADC1 (GPIO32-39): Always available, even with WiFi active
• ADC2 (GPIO0-27 subset): Unusable when WiFi or Bluetooth active
• Design rule: Use ADC1 pins for analog if project uses WiFi
• Non-linear at extremes — calibration improves accuracy

---