Overzicht
LogiWheelHost is een MIT-gelicenseerde, 'header-only' bibliotheek die het mogelijk maakt om Logitech Driving Force racewielen (waaronder de G25, G27, G29, G920 en G923) aan te sluiten op een ESP32-S3 via USB host.
Belangrijkste kenmerken
- Genormaliseerde inputs: Ruwe data wordt omgezet naar bruikbare waarden: sturen loopt van -1 tot +1 en pedalen van 0 tot 1.
- Native-mode handling: De bibliotheek automatiseert de complexe HID-outputrapporten die nodig zijn om het wiel volledig te ontgrendelen, inclusief de PlayStation → PC switch van de G923.
- Hardware-ondersteuning: Specifiek ontworpen voor de ESP32-S3 vanwege de native USB-host functionaliteit. Het biedt daarnaast ondersteuning voor RPM LED-controle op de G923 en optionele H-schakelpook-decodering.
Installatie en Gebruik
De bibliotheek bouwt voort op EspUsbHost. Voor een correcte werking moet de ESP32-S3 in OTG-modus staan en is externe 5V voeding voor het stuurwiel noodzakelijk. Via build-flags kunnen gebruikers deadzones, inversie en as-offsets aanpassen zonder de broncode zelf te wijzigen.
LogiWheelHost
Met deze tool kun je een racewiel uit de Logitech Driving Force-serie (G29, G923, G920, G27, G25, DFGT) uitlezen via een ESP32-S3 over USB host. De resulterende inputs zijn genormaliseerd: sturen loopt van -1 tot +1, pedalen van 0 tot 1, aangevuld met knoppen, de D-pad en optioneel de H-schakelpook.
De bibliotheek is MIT-gelicenseerd, 'header-only' en is gebouwd op de EspUsbHost-bibliotheek.
Kenmerken
- Genormaliseerde inputs: Sturen tussen -1..+1 en pedalen tussen 0..1; geen gedoe met ruwe bytes.
- Native-mode switch afgehandeld: Inclusief de lastige PlayStation → PC schakeling van de G923.
- Brede ondersteuning: Werkt met de volledige Driving Force-familie (G29 / G923 / G920 / G27 / G25 / DFGT / DFP).
- RPM LED-controle: Bediening van de RPM LED-balk op de G923 met één aanroep.
- Lichtgewicht: Header-only, slechts ongeveer één afhankelijkheid (EspUsbHost), MIT-licentie.
De native-mode switch: waarom dit nodig is
Logitech-stuurwielen streamen hun assen niet direct zodra ze zijn aangesloten. Ze starten in een beperkte modus die alleen neutrale of gecombineerde asdata rapporteert, totdat de host een specifiek HID-outputrapport verzendt om de afzonderlijke pedalen, volledige 16-bit besturing, alle knoppen en de schakelpook te ontgrendelen.
De G923 is nog complexer: in de standaard PlayStation-modus streamt het stuur alleen neutrale rapporten (het wacht op een PlayStation-authenticatie die een generieke host niet kan bieden) totdat het wordt omgeschakeld naar de PC ("Classic") modus.
Het uitzoeken van deze commando's is het moeilijkste deel. Deze bibliotheek bevat deze commando's per wiel, waardoor een G29 of G923 direct werkt: sluit hem aan op een ESP32-S3 en lees simpelweg de stuur-, gas- en remwaarden uit.
Ondersteunde stuurwielen
Alle wielen in de Logitech Driving Force-familie (VID 0x046D) worden ondersteund:
- G29
- G920
- G923 (PS/Xbox/PC)
- G25
- G27
- Driving Force Pro
- Driving Force GT
Andere wielen uit deze familie zullen waarschijnlijk ook werken; schakel de debug-dump in om dit te controleren.
Hardwarevereisten
- ESP32-S3: De native USB van dit board kan als host fungeren (een gewone ESP32 of C3 kan dit niet).
- Bedrading: De USB D+/D- van het wiel moet verbonden zijn met de native-USB D+/D- van de S3.
- Voeding: 5V moet worden toegevoerd aan de VBUS van het wiel, aangezien de S3 een wiel niet zelf kan voeden.
- Ground: Een gemeenschappelijke ground (massa) tussen de S3 en de 5V-voeding van het wiel.
Raadpleeg WIRING.md voor volledige details.
Installatie
- Installeer de afhankelijkheid (via Arduino IDE Library Manager of CLI):
arduino-cli lib install "EspUsbHost" (getest met versie 2.7.2)
- Installeer deze bibliotheek:
- Via Sketch → Include Library → Add .ZIP Library…
- Of plaats de map in je Arduino
libraries/ map.
- Of via CLI:
arduino-cli lib install --git-url https://github.com/botsofcog/LogiWheelHost
- IDE Instellingen: Selecteer een ESP32-S3 board en laat de USB Mode op de standaard OTG mode staan, zodat de native USB als host kan fungeren.
Snelstart
#include <LogiWheelHost.h>
LogiWheelHost wheel;
void setup() {
Serial.begin(115200);
wheel.begin(); // of wheel.begin(onInput) voor een callback
}
void loop() {
wheel.tick(); // beheert de G923 modus-schakeling
if (wheel.connected()) {
LogiWheelInput in = wheel.latest();
// in.steer -1.0 .. +1.0
// in.throttle / in.brake / in.clutch 0.0 .. 1.0
myServo.write(90 + (int)(in.steer * 90));
myMotor.setDuty(in.throttle - in.brake);
}
}
Zie examples/SerialMonitor voor een compleet voorbeeld dat alle inputs print en het gaspedaal spiegelt naar de RPM LED-balk van de G923.
API Referentie
LogiWheelInput
| Veld | Type | Betekenis |
|---|
steer | float | -1.0 volledig links … +1.0 volledig rechts (deadzone + invert toegepast) |
throttle, brake, clutch | float | 0.0 losgelaten … 1.0 volledig ingetrapt |
steerRaw | uint16_t | Ruwe 16-bit besturing (midden $\approx$ 32768) |
throttleRaw, brakeRaw, clutchRaw | uint8_t | Ruwe pedalen (idle 255) |
buttons | uint32_t | Ruw knop-bitveld (report[0..3]) |
hat | uint8_t | D-pad: 0=N, 2=E, 4=S, 6=W, 8=midden |
gear | int8_t | H-shifter versnelling (indien LOGIWHEEL_SHIFTER=1), anders UNKNOWN |
stampMs | uint32_t | millis() moment waarop deze meting arriveerde |
LogiWheelHost
| Methode | Functie |
|---|
begin(cb = nullptr) | Start de USB host; optionele callback void(const LogiWheelInput&) wordt aangeroepen bij elke nieuwe meting. |
tick() | Moet in elke loop() worden aangeroepen — beheert de uitgestelde G923 PS→PC switch. |
connected() | Is er een herkend wiel aangesloten? |
latest() | Thread-safe snapshot van de laatste meting. |
setRpmLeds(0..6) | Licht N LED's op de G923 RPM-balk op (wordt genegeerd bij wielen zonder deze balk). |
pressed(in, LOGIWHEELBTN*) | Statische helper: is die specifieke knop ingesteld in in.buttons? |
De optionele callback draait in de achtergrondtaak van EspUsbHost — houd deze kort, of gebruik simpelweg latest() vanuit de loop. Er worden benoemde knopmaskers geleverd (zoals LOGIWHEELBTNX, TRIANGLE, LPADDLE, BACK, etc.) die bevestigd zijn op een G923 in PC-modus. Verifieer deze voor jouw specifieke wiel met de debug-dump.
Configuratie
Alle instellingen zijn -D build flags (overschrijf deze in je build, pas de bibliotheek zelf niet aan). Veelvoorkomende flags:
| Flag | Standaard | Betekenis |
|---|
LOGIWHEELSTEERUSABLE | 32767 | Ruwe counts aan weerszijden van het midden die mappen naar volledige uitslag ($\pm$1.0). Lager = kleinere draaiing bereikt volledige uitslag. |
LOGIWHEELSTEERDEADZONE | 300 | Ruwe counts rond het midden die worden genegeerd. |
LOGIWHEELSTEERINVERT | 0 | Zet op 1 als links/rechts omgekeerd zijn. |
LOGIWHEELPEDALDEADZONE | 10 | Speling aan het begin van de pedaalslag. |
LOGIWHEEL_SHIFTER | 0 | Zet op 1 om de versnelling van een Driving Force Shifter te decoderen. |
LOGIWHEEL_DEBUG | 0 | Zet op 1 om het ruwe HID-rapport te printen (voor kalibratie). |
LOGIWHEELOFFSTEERLO/HI, THROTTLE, BRAKE, CLUTCH | 4/5/6/7/8 | Report byte offsets — pas deze aan als een as verkeerd wordt uitgelezen. |
Kalibratie (de enige hardware-stap)
Als een as op jouw wiel verkeerd wordt uitgelezen, compileer dan één keer met -DLOGIWHEELDEBUG=1, open de Serial Monitor en bedien elke knop/as één voor één. De dump print alleen wanneer het rapport verandert, zodat je precies ziet welke byte beweegt. Stel vervolgens de bijbehorende LOGIWHEELOFF_* offset in. De mode-switch commando's en PID-lijst zijn al voor je geregeld.
Credits
- USB host laag: EspUsbHost door TANAKA Masayuki.
- Logitech native-mode commando's: Gedocumenteerd door de Linux
new-lg4ff driver en het GIMX-project; de G923 PS→PC switch spiegelt de usb_modeswitch entry voor 046d:c267.
- Oorsprong: Geëxtraheerd en gegeneraliseerd van een ESP32 arcade stuurwiel-controller.
Licentie
MIT — gebruik het waar je wilt; bronvermelding wordt gewaardeerd, geen garantie.
LogiWheelHost
Met deze tool kun je een racewiel uit de Logitech Driving Force-serie (G29, G923, G920, G27, G25, DFGT) uitlezen via een ESP32-S3 over USB host. De resulterende inputs zijn genormaliseerd: sturen loopt van -1 tot +1, pedalen van 0 tot 1, aangevuld met knoppen, de D-pad en optioneel de H-schakelpook.
De bibliotheek is MIT-gelicenseerd, 'header-only' en is gebouwd op de EspUsbHost-bibliotheek.
Kenmerken
- Genormaliseerde inputs: Sturen tussen -1..+1 en pedalen tussen 0..1; geen gedoe met ruwe bytes.
- Native-mode switch afgehandeld: Inclusief de lastige PlayStation → PC schakeling van de G923.
- Brede ondersteuning: Werkt met de volledige Driving Force-familie (G29 / G923 / G920 / G27 / G25 / DFGT / DFP).
- RPM LED-controle: Bediening van de RPM LED-balk op de G923 met één aanroep.
- Lichtgewicht: Header-only, slechts ongeveer één afhankelijkheid (EspUsbHost), MIT-licentie.
De native-mode switch: waarom dit nodig is
Logitech-stuurwielen streamen hun assen niet direct zodra ze zijn aangesloten. Ze starten in een beperkte modus die alleen neutrale of gecombineerde asdata rapporteert, totdat de host een specifiek HID-outputrapport verzendt om de afzonderlijke pedalen, volledige 16-bit besturing, alle knoppen en de schakelpook te ontgrendelen.
De G923 is nog complexer: in de standaard PlayStation-modus streamt het stuur alleen neutrale rapporten (het wacht op een PlayStation-authenticatie die een generieke host niet kan bieden) totdat het wordt omgeschakeld naar de PC ("Classic") modus.
Het uitzoeken van deze commando's is het moeilijkste deel. Deze bibliotheek bevat deze commando's per wiel, waardoor een G29 of G923 direct werkt: sluit hem aan op een ESP32-S3 en lees simpelweg de stuur-, gas- en remwaarden uit.
Ondersteunde stuurwielen
Alle wielen in de Logitech Driving Force-familie (VID 0x046D) worden ondersteund:
- G29
- G920
- G923 (PS/Xbox/PC)
- G25
- G27
- Driving Force Pro
- Driving Force GT
Andere wielen uit deze familie zullen waarschijnlijk ook werken; schakel de debug-dump in om dit te controleren.
Hardwarevereisten
- ESP32-S3: De native USB van dit board kan als host fungeren (een gewone ESP32 of C3 kan dit niet).
- Bedrading: De USB D+/D- van het wiel moet verbonden zijn met de native-USB D+/D- van de S3.
- Voeding: 5V moet worden toegevoerd aan de VBUS van het wiel, aangezien de S3 een wiel niet zelf kan voeden.
- Ground: Een gemeenschappelijke ground (massa) tussen de S3 en de 5V-voeding van het wiel.
Raadpleeg WIRING.md voor volledige details.
Installatie
- Installeer de afhankelijkheid (via Arduino IDE Library Manager of CLI):
arduino-cli lib install "EspUsbHost" (getest met versie 2.7.2)
- Installeer deze bibliotheek:
- Via Sketch → Include Library → Add .ZIP Library…
- Of plaats de map in je Arduino
libraries/ map.
- Of via CLI:
arduino-cli lib install --git-url https://github.com/botsofcog/LogiWheelHost
- IDE Instellingen: Selecteer een ESP32-S3 board en laat de USB Mode op de standaard OTG mode staan, zodat de native USB als host kan fungeren.
Snelstart
#include <LogiWheelHost.h>
LogiWheelHost wheel;
void setup() {
Serial.begin(115200);
wheel.begin(); // of wheel.begin(onInput) voor een callback
}
void loop() {
wheel.tick(); // beheert de G923 modus-schakeling
if (wheel.connected()) {
LogiWheelInput in = wheel.latest();
// in.steer -1.0 .. +1.0
// in.throttle / in.brake / in.clutch 0.0 .. 1.0
myServo.write(90 + (int)(in.steer * 90));
myMotor.setDuty(in.throttle - in.brake);
}
}
Zie examples/SerialMonitor voor een compleet voorbeeld dat alle inputs print en het gaspedaal spiegelt naar de RPM LED-balk van de G923.
API Referentie
LogiWheelInput
| Veld | Type | Betekenis |
|---|
steer | float | -1.0 volledig links … +1.0 volledig rechts (deadzone + invert toegepast) |
throttle, brake, clutch | float | 0.0 losgelaten … 1.0 volledig ingetrapt |
steerRaw | uint16_t | Ruwe 16-bit besturing (midden $\approx$ 32768) |
throttleRaw, brakeRaw, clutchRaw | uint8_t | Ruwe pedalen (idle 255) |
buttons | uint32_t | Ruw knop-bitveld (report[0..3]) |
hat | uint8_t | D-pad: 0=N, 2=E, 4=S, 6=W, 8=midden |
gear | int8_t | H-shifter versnelling (indien LOGIWHEEL_SHIFTER=1), anders UNKNOWN |
stampMs | uint32_t | millis() moment waarop deze meting arriveerde |
LogiWheelHost
| Methode | Functie |
|---|
begin(cb = nullptr) | Start de USB host; optionele callback void(const LogiWheelInput&) wordt aangeroepen bij elke nieuwe meting. |
tick() | Moet in elke loop() worden aangeroepen — beheert de uitgestelde G923 PS→PC switch. |
connected() | Is er een herkend wiel aangesloten? |
latest() | Thread-safe snapshot van de laatste meting. |
setRpmLeds(0..6) | Licht N LED's op de G923 RPM-balk op (wordt genegeerd bij wielen zonder deze balk). |
pressed(in, LOGIWHEELBTN*) | Statische helper: is die specifieke knop ingesteld in in.buttons? |
De optionele callback draait in de achtergrondtaak van EspUsbHost — houd deze kort, of gebruik simpelweg latest() vanuit de loop. Er worden benoemde knopmaskers geleverd (zoals LOGIWHEELBTNX, TRIANGLE, LPADDLE, BACK, etc.) die bevestigd zijn op een G923 in PC-modus. Verifieer deze voor jouw specifieke wiel met de debug-dump.
Configuratie
Alle instellingen zijn -D build flags (overschrijf deze in je build, pas de bibliotheek zelf niet aan). Veelvoorkomende flags:
| Flag | Standaard | Betekenis |
|---|
LOGIWHEELSTEERUSABLE | 32767 | Ruwe counts aan weerszijden van het midden die mappen naar volledige uitslag ($\pm$1.0). Lager = kleinere draaiing bereikt volledige uitslag. |
LOGIWHEELSTEERDEADZONE | 300 | Ruwe counts rond het midden die worden genegeerd. |
LOGIWHEELSTEERINVERT | 0 | Zet op 1 als links/rechts omgekeerd zijn. |
LOGIWHEELPEDALDEADZONE | 10 | Speling aan het begin van de pedaalslag. |
LOGIWHEEL_SHIFTER | 0 | Zet op 1 om de versnelling van een Driving Force Shifter te decoderen. |
LOGIWHEEL_DEBUG | 0 | Zet op 1 om het ruwe HID-rapport te printen (voor kalibratie). |
LOGIWHEELOFFSTEERLO/HI, THROTTLE, BRAKE, CLUTCH | 4/5/6/7/8 | Report byte offsets — pas deze aan als een as verkeerd wordt uitgelezen. |
Kalibratie (de enige hardware-stap)
Als een as op jouw wiel verkeerd wordt uitgelezen, compileer dan één keer met -DLOGIWHEELDEBUG=1, open de Serial Monitor en bedien elke knop/as één voor één. De dump print alleen wanneer het rapport verandert, zodat je precies ziet welke byte beweegt. Stel vervolgens de bijbehorende LOGIWHEELOFF_* offset in. De mode-switch commando's en PID-lijst zijn al voor je geregeld.
Credits
- USB host laag: EspUsbHost door TANAKA Masayuki.
- Logitech native-mode commando's: Gedocumenteerd door de Linux
new-lg4ff driver en het GIMX-project; de G923 PS→PC switch spiegelt de usb_modeswitch entry voor 046d:c267.
- Oorsprong: Geëxtraheerd en gegeneraliseerd van een ESP32 arcade stuurwiel-controller.
Licentie
MIT — gebruik het waar je wilt; bronvermelding wordt gewaardeerd, geen garantie.
Groetjes,