กลับไปหน้ารวมไฟล์
plug-any-usb-device-on-an-esp8266-83c1be-en.md

I was having fun with Mozzi, an audio synthesis library (https://sensorium.github.io/Mozzi/), when I realized I will have to build a controller to really use it at his full potential.

What if I could just plug a keyboard or a Midi controller? That would be so much easier... What?! I didn't know that it was possible!

We will see how to do this kind of thing in another tutorial!

Project Overview

This project is a masterclass in Bus Interfacing Forensics. While the ESP8266 is primarily a wireless node, we transform it into a powerful USB Host capable of interfacing with industrial MIDI controllers, HID peripherals, and gaming hardware. The challenge lies in harmonizing the MAX3421E transceiver's logic with the ESP8266's restrictive boot-strap pins, requiring surgical hardware modifications and library-level driver patching to ensure system stability.

Choose Your USB Host

Thanks to Circuit@Home device we can do that. EDIT: Circuitathome website as been replaced so here is the original link from internet archive. https://web.archive.org/web/20190120133645/https://www.circuitsathome.com/usb-host-shield-hardware-manual/

In this tutorial we will use an USB Host Mini (clone version), the chip on it (MAX3421E) will only works at 3.3V.

If you want to use a 5V microcontroller (like the Arduino Uno / Nano) use the USB Host Shield instead.

Before we plug our USB host to our microcontroller, we will have to fix some issues or it won't work.

Technical Deep-Dive: Fix Powering Issues

If you buy a clone of the USB Host Mini, there is no jumper for VBUS. This means your USB devices will be** powered with 3.3v**, which didn't works with any of my devices who all require** 5V.**

You can find more details here: https://ht-deko.com/arduino/shield_usbhost_mini.html (in japanese)

You will have to cut this trace, to fix this. I used a small screw driver to do this, but you probably should use a small cutter instead.

I hate to do this, but I didn't find a better solution, except buying the official one :-)

VBUS Power Forensics (The 5V Transition):

  • The 3.3V Bottleneck: Most "Mini" USB Host clones incorrectly wire the VBUS (USB power line) to the 3.3V rail. Since standard USB peripherals (Keyboards, MIDI) operate on a 5V logic/power envelope, they fail to enumerate or brown out.
  • Surgical Trace Isolation: The implementation requires a precision cut on the VBUS trace to isolate it from the 3.3V LDO. By bridging VBUS to the RAW 5V input, the shield can deliver the required current for high-power peripherals without compromising the MAX3421E's 3.3V logic signaling.

Plug Your USB Host

OK, I hope you didn't break your board! Now it is time to plug it!

I used a Wemos Mini D1 with my USB Host Mini device, here is how to plug it.

I didn't plug the INT pin as it seems to work fine without it.

  • D3 -- SS
  • D7 -- MISO
  • D6 -- MOSI
  • D5 -- SCK
  • RST -- RST

SPI Bus & Boot-Strap Conflict Analysis:

  • The GPIO15 (D8) Conflict: On the Wemos D1 Mini, GPIO15 (D8) acts as the standard SPI SS (Slave Select). However, GPIO15 is also a Boot-Strap Pin that must be pulled LOW during power-up. Connect the USB Host's SS to D8 often causes the ESP8266 to enter an invalid boot state or firmware flashing mode.
  • GPIO0 (D3) Redirection: This project bypasses the conflict by remapping the SS signal to GPIO0 (D3). This forensic shift ensures the ESP8266 boots correctly into the SPI application while maintaining full control over the USB transceiver's chip-select timing.

Fix USB Host Library

You may have notice SS (Chip Select/CS) is plugged on D3 instead of D8.

I run into an issue where the USB Host set my Wemos Mini in** firmware flashing** mode, which stop the sketch from running.https://github.com/felis/USB_Host_Shield_2.0/issues/457

In order to change the SS pin, we need to change a line in the library.

Download USB Host Shield Library 2.0

Open UsbCore.h in libraries/USB_Host_Shield_Library_2.0 and change this line

#elif defined(ESP8266)typedef MAX3421e<P15, P5> MAX3421E; // ESP8266 boards

With this line

#elif defined(ESP8266)typedef MAX3421e<P0, P5> MAX3421E; // ESP8266 boards

Notice we used P0 instead of D3, it is because GPIO0 is D3 on the Wemos Mini.https://escapequotes.net/esp8266-wemos-d1-mini-pins-and-diagram/

Library-Level Driver Patching:

  • UsbCore.h Forensics: To support the non-standard pin mapping, the USB_Host_Shield_Library_2.0 core must be patched. By modifying the MAX3421e typedef from P15 to P0, the driver is re-targeted to handle the new SS routing at the hardware register level.

Downgrade ESP8266

OK, we are almost done, if you try to compile an example from the library, it will not works.

Note : This was recently fix, so this step is only required if your version of USB Host Shield Library 2.0 is 1.3.2 or lower.

It is because the library is not compatible with Arduino ESP8266 2.5, you need to downgrade it to 2.4.2https://github.com/felis/USB_Host_Shield_2.0/issues/449

Go to Tools / Boards / Boards Manager and change your version to 2.4.2.

Engineering & Implementation: ESP8266 Core Versioning

  • The 2.4.2 Downgrade: Certain versions of the ESP8266 Arduino core introduced breaking changes in the SPI implementation. This project identifies version 2.4.2 as the stable baseline for guaranteed MAX3421E initialization and descriptor enumeration.

Test Your USB Host

There is a lot of examples in USB Host Shield Library 2.0In order to test that everything is working correctly, you should first try USB_desc.

  • Upload USB_desc
  • Open Serial Monitor (115200)
  • Plug an USB device
  • Reset your board (ESP8266)

Note: You can't hot-plug your USB device (at least in the examples), you need to reset the board each times you unplug, plug your device.

You should see a message like this:

01
--
Device descriptor:
Descriptor Length:	12
Descriptor type:	01
USB version:		0200
Device class:		FF
Device Subclass:	FF
Device Protocol:	FF
Max.packet size:	08
Vendor  ID:		045E
Product ID:		028E
Revision ID:		0114
Mfg.string index:	01
Prod.string index:	02
Serial number index:	03
Number of conf.:	01
Configuration descriptor:
Total length:		0099
Num.intf:		04
Conf.value:		01
Conf.string:		00
Attr.:			A0
Max.pwr:		FA
Interface descriptor:
Intf.number:		00
Alt.:			00
Endpoints:		02
Intf. Class:		FF
Intf. Subclass:		5D
Intf. Protocol:		01
Intf.string:		00
Unknown descriptor:
Length:		11
Type:		21
Contents:	0001012581140000000013010800000705
Endpoint descriptor:
Endpoint address:	81
Attr.:			03
Max.pkt size:		0020
Polling interval:	04
Endpoint descriptor:
Endpoint address:	01
Attr.:			03
Max.pkt size:		0020
Polling interval:	08
Interface descriptor:
Intf.number:		01
Alt.:			00
Endpoints:		04
Intf. Class:		FF
Intf. Subclass:		5D
Intf. Protocol:		03
Intf.string:		00
Unknown descriptor:
Length:		1B
Type:		21
Contents:	000101018240010220168300000000000016030000000000000705
Endpoint descriptor:
Endpoint address:	82
Attr.:			03
Max.pkt size:		0020
Polling interval:	02
Endpoint descriptor:
Endpoint address:	02
Attr.:			03
Max.pkt size:		0020
Polling interval:	04
Endpoint descriptor:
Endpoint address:	83
Attr.:			03
Max.pkt size:		0020
Polling interval:	40
Endpoint descriptor:
Endpoint address:	03
Attr.:			03
Max.pkt size:		0020
Polling interval:	10
Interface descriptor:
Intf.number:		02
Alt.:			00
Endpoints:		01
Intf. Class:		FF
Intf. Subclass:		5D
Intf. Protocol:		02
Intf.string:		00
Unknown descriptor:
Length:		09
Type:		21
Contents:	000101228407000705
Endpoint descriptor:
Endpoint address:	84
Attr.:			03
Max.pkt size:		0020
Polling interval:	10
Interface descriptor:
Intf.number:		03
Alt.:			00
Endpoints:		00
Intf. Class:		FF
Intf. Subclass:		FD
Intf. Protocol:		13
Intf.string:		04
Unknown descriptor:
Length:		06
Type:		41
Contents:	000101034A20
Addr:1(0.0.1)

Engineering & Implementation: Multi-Class Peripheral Drivers

  • HID/Boot Protocol: Demonstrates the capture of Raw Scan Codes from keyboards and mouse delta-movement packets.
  • MIDI Buffer Parsing: Extracts Note ON (0x90) and Note OFF (0x80) events directly from the USB bulk transfer buffer, enabling the ESP8266 to act as a wireless MIDI synthesizer node.
  • XBOX 360 Forensics: Leverages the specialized XBOXUSB driver to read Hat-Switch values (-32768 to 32768) and trigger vibration feedback over the USB bus.
  • Interrupt-Free Operation: While the MAX3421E features an INT (Interrupt) pin, this project utilizes a high-speed Polling Architecture. By calling Usb.Task() in a tight loop, the ESP8266 handles sub-millisecond USB packet processing without the complexity of ISR-driven SPI transactions.

XBOX 360 Controller Example

If you have an XBOX360 for PC, use the example XBOX/XBOXUSB

  • L2/R2 vibrates when you press it.
  • L2/R2 : 0/255
  • Stick (Hat) X/Y : -32768 / 32768
  • Led can also be control ! (use the pad / back / start / xbox buttons to try it)

Keyboard Example

Open HID/USBHIDBootKbd example

This example detect key down/up and modifier (SHIFT/CTRL etc...)

DN      >07<
ASCII: d
UP      >07<

Mouse Example

I didn't manage to make my mouse works. The example is in HID/USBHIDBootMouse

Midi Controller Example

Open USBH_MIDI/USBH_MIDI_dump example

Most Midi devices, will only use a small part of the buffer (bufMidi)

00001679: 64: 09 90 2F 13 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

0000174A: 64: 08 80 2F 7F 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  • bufMidi[0] : Note ON (9) / Note OFF (8)
  • bufMidi[2] : Note
  • bufMidi[3] : Velocity

Summary

Using USB devices open up a lot of possibilities for our microcontroller, we only touch the surface of all the thing we can do with this USB Host device.

  • You can use a USB Hub to use multiple USB devices.
  • There are a lot of pins on the USB Host, it is because there are GPIO on it! You can plug buttons / leds even an LCD screen on it!
  • You can also use USB drive.

Conclusion

USB-Host bridges the gap between Embedded Microcontrollers and the Desktop Peripheral Ecosystem. By mastering VBUS Power Modification and Boot-Strap Conflict Forensics, developers can harness the power of any USB device to create sophisticated music synthesizers, custom game consoles, and IoT HMI systems.

Peripheral Mastery: Conquering the USB bus through hardware forensics.

ข้อมูล Frontmatter ดั้งเดิม 

apps:
  - "Arduino IDE (with ESP8266 Core 2.4.2)"
  - "USB Host Shield Library 2.0"
author: "usini"
category: "Communication"
components:
  - "1x Wemos D1 Mini (ESP8266 Host Node)"
  - "1x USB Host Mini Shield (MAX3421E Transceiver)"
  - "1x USB Peripheral (MIDI/Keyboard/XBOX Controller)"
  - "1x 5V External Power Supply (for VBUS stability)"
description: "A deep-dive into hardware-level USB interfacing, featuring VBUS power forensics, SPI pin remapping to bypass ESP8266 boot-strapping conflicts, and multi-class (HID/MIDI/XBOX) descriptor analysis."
difficulty: "Intermediate"
documentationLinks: []
downloadableFiles:
  - "https://projects.arduinocontent.cc/8bb67552-44b8-407c-b5bd-307b9817f566.h"
  - "https://projects.arduinocontent.cc/8bb67552-44b8-407c-b5bd-307b9817f566.h"
encryptedPayload: "U2FsdGVkX1/LHln6Mz1lz3AMj3Hu1ijf5NPOzFNyJt5WxuxwmnFAP0q3/rtrK8LKVnMK+0y41sFhqQsBPueQWHMxfkCIxWy9wtFrfpidPuo="
heroImage: "https://cdn.jsdelivr.net/gh/bigboxthailand/arduino-assets@main/images/projects/plug-any-usb-device-on-an-esp8266-83c1be_cover.jpg"
lang: "en"
likes: 6
passwordHash: "6502db6d7085ea9cf9b14a3a172f6a266d8ba76317007c5616b7eaf470bb6969"
price: 699
seoDescription: "Connect any USB Device to ESP8266 or Arduino. Support for Keyboard, mouse, game controller, and Midi controller."
tags:
  - "usb-host-shield"
  - "esp8266-forensics"
  - "max3421e-controller"
  - "midi-over-usb"
  - "hid-protocol"
  - "hardware-hacking"
title: "USB-Host: ESP8266 Peripheral Bridge Forensics"
tools:
  - "Precision Cutter (for VBUS trace forensics)"
  - "Soldering Iron"
videoLinks:
  - "https://www.youtube.com/embed/CeLYOu-UGXA"
views: 108214