CH392 Arduino Library

Arduino Ethernet-compatible library for the WCH CH392 SPI Ethernet controller (CH392F / CH392T).

Use it as a drop-in replacement for the official Arduino Ethernet library (W5500-style API).

Supported hardware

Chip	SPI sockets	Max SPI (datasheet)	Default chunk size
CH392F	4	10 MHz (use 1 MHz on ESP32)	512 bytes
CH392T	8	24 MHz	1536 bytes

Select chip in src/CH392_Config.h or with -DCH392_CHIP=CH392F.

Wiring (typical ESP32)

CH392	MCU
SCS	GPIO CS (e.g. 5)
SCK	SPI SCK
SDI	SPI MOSI
SDO	SPI MISO
INT	GPIO (e.g. 13), pull-up
RST	GPIO (e.g. 14), optional
VCC / GND	3.3 V

Connect the Ethernet magnetics and RJ45 per your module schematic.

Getting started

#include <CH392.h>   // ESP32: or #include <CH392Ethernet.h> for Ethernet.* names

#define PIN_CS   5
#define PIN_INT  13
#define PIN_RST  14

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };

void setup() {
  Serial.begin(115200);
  CH392.init(PIN_CS, PIN_INT, PIN_RST);

  if (CH392.begin(mac) == 0) {
    Serial.println(F("DHCP failed"));
    while (1) {}
  }
  Serial.println(CH392.localIP());
}

void loop() {
  CH392.maintain();   // DHCP lease renewal when using DHCP
}

Static IP

IPAddress ip(192, 168, 1, 100);
IPAddress dns(192, 168, 1, 1);
IPAddress gw(192, 168, 1, 1);
IPAddress mask(255, 255, 255, 0);
CH392.begin(mac, ip, dns, gw, mask);

Migrating from W5500

W5500 / Arduino Ethernet	CH392
#include <Ethernet.h>	#include <CH392.h> or <CH392Ethernet.h>
Ethernet.init(cs)	CH392.init(cs, intPin, rstPin)
Ethernet.begin(mac)	CH392.begin(mac)
EthernetClient	CH392Client (or EthernetClient with shim)
EthernetServer	CH392Server
EthernetUDP	CH392UDP
Ethernet.maintain()	CH392.maintain()

On AVR/STM32, CH392.h already defines Ethernet as an alias. On ESP32, use CH392Ethernet.h for Ethernet macros.

API reference (Ethernet parity)

CH392Class / Ethernet

• init(cs), init(cs, int, rst)
• begin(mac), begin(mac, timeout), begin(mac, ip, …)
• localIP(), subnetMask(), gatewayIP(), dnsServerIP()
• MACAddress() / macAddress()
• linkStatus() → LinkON, LinkOFF, Unknown
• maintain() → DHCP_CHECK_NONE (0), DHCP_CHECK_RENEW_FAIL (1), DHCP_CHECK_RENEW_OK (2), DHCP_CHECK_REBIND_FAIL (3), DHCP_CHECK_REBIND_OK (4) — same values as Arduino Ethernet Dhcp.h
• hostByName(host, ip)

CH392Client / EthernetClient

• connect(ip, port), connect(ip, port, localPort), connect(host, port)
• connected(), stop(), available(), read(), peek()
• write(), print(), println(), flush(), availableForWrite()
• remoteIP(), remotePort()
• setTimeout(ms) / setConnectionTimeout(ms) — default 1000 ms (Arduino Ethernet parity)

CH392Server / EthernetServer

• begin()
• available() — returns a client only when RX data is buffered
• accept() — hands out each established client once, even with no data yet
• write(), print(), println()

CH392UDP / EthernetUDP

• begin(port), beginPacket(), write(), endPacket()
• parsePacket(), available(), read(), remoteIP(), remotePort() — datagram boundaries preserved

Examples

Folder	Sketch
Basics/LinkStatus	Cable link up/down
Basics/HardwareTest	SPI + chip ID
TCP/WebServer	Minimal HTTP server
TCP/EchoServer	TCP echo
TCP/TCPClient	Outbound TCP client
UDP/UDPSendReceive	UDP echo
Network/DHCP	DHCP lease
Network/DHCP_Maintain	maintain() renew/rebind
Network/DNSLookup	hostByName()
Advanced/MAC_RAW	Raw Ethernet frames
Advanced/TCP_Server_Raw	WCH low-level TCP (debug)

Application demos: extras/Relay_Test, extras/MQTT_Test (requires PubSubClient).

Stress tests (extras/Stress/)

Sketch	Purpose
TCP_ConnectStress	Thousands of connect/send/stop cycles
HTTP_RequestStress	Repeated HTTP GET against a WebServer
UDP_EchoStress	Continuous UDP send/receive
MQTT_LongRun	Hours/days MQTT publish soak

Edit peer/broker IPs in each sketch. Leave running unattended and watch Serial counters.

Production notes (v1.0.1)

• TX is gated on SINT_STAT_SENBUF_FREE (not HW idle-queue — stuck at 0 on many CH392F parts).
• Socket IRQs are consumed once (clear-on-read); do not double-read.
• Software RX uses backpressure: HW FIFO is not drained when the SW ring is full.
• DNS allocates a temporary UDP socket (never steals socket 0).
• Link-down in maintain() tears down TCP sockets and restores the listen port on link-up.
• Disconnecting sockets with unread data are reclaimed after 30 s if the app never stop()s.
• Keep CH392_DEBUG and CH392_TX_DEBUG at 0 for field builds.
• CH392F: treat as one concurrent server client unless you add multi-listen yourself.
• Always call CH392.maintain() in loop() for DHCP + link recovery.

Troubleshooting

Wrong IP (0.168.x.x instead of 192.168.x.x)

SPI too fast or noisy wiring. Default 1 MHz on ESP32. Verify MISO/MOSI and short leads.

Web page blank but serial shows “sent”

Multi-kilobyte HTTP must use paced sends (sendChunk() with SENBUF wait). Do not blast the TX buffer faster than the chip can drain.

API / buttons hang after page load

Ensure client.stop() is called after each HTTP response and call CH392.maintain() in loop().

CH392Server: listen OK spam

Set CH392_DEBUG to 0 in CH392_Config.h.

MQTT connect hangs / TX chunk FAIL / rc=-2

Confirm library ≥ 1.0.3. rc=-2 after broker “New connection” then immediate client close was caused by status-based onDisconnect() killing new TCP sessions; disconnect is IRQ-only now. Also set ethClient.setConnectionTimeout(15000) for PubSubClient.

Continuous integration

Every example is compiled for ESP32 (esp32:esp32:esp32, core 3.3.0) on push and pull request via GitHub Actions.

Compile locally (same as CI)

Install arduino-cli, then:

Windows (PowerShell):

cd C:\Users\ABDO\Documents\Arduino\libraries\CH392
.\scripts\compile-examples.ps1

Linux / macOS:

cd path/to/CH392
chmod +x scripts/compile-examples.sh
./scripts/compile-examples.sh

Override board or core version:

FQBN=esp32:esp32:esp32s3 ESP32_VERSION=3.3.0 ./scripts/compile-examples.sh

Enable CI on your fork

1. git init in the library folder (if not already a repo).
2. Push to GitHub.
3. Replace YOUR_GITHUB_USER in the README badge with your username.
4. Actions run automatically — no secrets required.

License

MIT — see LICENSE. Based on WCH CH392 reference code.