OSC-KEYPAD-ONYX

This project converts a USB keypad into a wired ONYX playback controller. An ESP32-S3 receives USB HID key events, maps them to ONYX OSC playback executors.

COMPONENTS Hardware components

WIZnet - W5500

x 1

PROJECT DESCRIPTION

Where This Can Be Used

ONYX supports Open Sound Control (OSC), allowing external devices to trigger playback actions over a network.

This project uses that capability to build a dedicated hardware controller from an ordinary USB keyboard or keypad. Instead of sending keyboard shortcuts to a PC, every supported key is translated into an OSC message and delivered directly to ONYX through Ethernet.

Because the controller operates independently of the host computer's keyboard input, it can be placed anywhere on the same Ethernet network and act as a compact playback interface.

Typical applications include:

Live event playback control
Theater cue triggering
Media installation control
Broadcast playback systems
Fixed control stations
Backup playback controllers

The project focuses on one task: converting physical key presses into ONYX playback commands with minimal software running on the controller itself.

System Block Diagram

USB Keypad / Keyboard
        │
        ▼
ESP32-S3 USB Host
        │
        ▼
USB HID Event Handler
        │
        ▼
Playback Executor Mapping
        │
        ▼
OSC Message Generator
        │
        ▼
EthernetUDP
        │
        ▼
W5500 Ethernet Module
        │
        ▼
Ethernet Network
        │
        ▼
ONYX Playback Executors

Architecture Overview

The firmware is organized into three independent layers.

The first layer handles USB HID communication and detects key press or release events.

The second layer converts HID keycodes into predefined ONYX playback executor addresses.

The final layer packages each command as an OSC message and sends it over Ethernet using UDP.

Separating these responsibilities keeps the input handling independent from network communication, making the project easier to extend or adapt to different keypad layouts.

What the Project Does

The ESP32-S3 runs as a USB host and continuously monitors a connected keyboard.

When a supported key changes state, the callback identifies the corresponding HID keycode and selects the matching ONYX playback executor.

For example, pressing one key generates:

OSCMessage msg("/Mx/playback/page2/0/go");

while another key produces:

OSCMessage msg("/Mx/playback/page2/31/go");

Several buttons also generate dedicated release events:

OSCMessage msg("/Mx/playback/page2/31/release");

Each message is immediately transmitted over UDP to ONYX on port 8000.

Unlike keyboard shortcut emulation, the firmware communicates directly with ONYX's OSC interface, allowing the keypad to function as a standalone Ethernet playback controller.

Where WIZnet Fits

The network interface is implemented with a W5500 Ethernet module connected over SPI.

The firmware initializes the Ethernet interface, assigns a static IP address, and opens a UDP socket used to transmit OSC messages.

Ethernet.init(10);
Ethernet.begin(mac[0], ip, dns, dns, subnet);

Udp.begin(consolePort);

The W5500 handles Ethernet communication while the ESP32-S3 focuses on USB processing and OSC message generation. This creates a clear separation between application logic and network transport.

Source Code Highlights

USB Host Event Processing

File: OSC-KEYPAD-ONYX.ino

void onKey(usb_transfer_t* transfer)

All keyboard activity enters the application through a single USB callback. The firmware compares the current HID report with the previous report to determine which key changed state.

This approach avoids polling individual keys and reacts only to actual input events.

Playback Executor Mapping

The project maps USB HID keycodes directly to ONYX playback executors.

For example:

case 0x3a:
    OSCMessage msg("/Mx/playback/page2/0/go");

case 0x10:
    OSCMessage msg("/Mx/playback/page2/30/go");

case 0x10:
    OSCMessage msg("/Mx/playback/page2/30/release");

Rather than emulating keyboard shortcuts, every supported key is associated with a specific OSC address understood by ONYX.

OSC Transmission

Udp.beginPacket(broadcastip, consolePort);

msg.send(Udp);

Udp.endPacket();

Each OSC command is broadcast over UDP to port 8000, allowing ONYX systems on the same network to receive playback commands immediately.

Ethernet Initialization

Ethernet.init(10);

Ethernet.begin(mac[0], ip, dns, dns, subnet);

The firmware configures the SPI Ethernet interface during startup using a static IP configuration before enabling UDP communication.

Software Flow

USB Key Press
      │
      ▼
USB HID Callback
      │
      ▼
Detect Changed Key
      │
      ▼
Find Playback Executor
      │
      ▼
Generate OSC Message
      │
      ▼
UDP Packet
      │
      ▼
W5500 Ethernet Module
      │
      ▼
ONYX Executes Playback

Engineering Highlights

Direct OSC Playback Control

Instead of simulating keyboard shortcuts, the firmware generates native ONYX OSC messages. This allows the keypad to communicate directly with the lighting software through its network interface.

HID-Based Playback Mapping

The firmware maps USB HID keycodes directly to playback executors, providing a straightforward relationship between physical buttons and ONYX functions.

Support for Press and Release Actions

Some playback buttons transmit both /go and /release OSC messages, enabling both momentary and persistent playback behavior depending on the assigned executor.

Modular Software Design

USB processing, playback mapping, and Ethernet communication are implemented as separate functional layers. This makes it relatively easy to replace the keypad, modify OSC mappings, or adapt the networking layer without redesigning the entire application.

Project	WIZnet Product	Why It's Similar
3D Joystick Controller	W5500	Reads physical input on an ESP32, converts it into OSC messages, and sends them over Ethernet. The closest architectural match to this USB HID → OSC controller.
ESP32 + W5500 (SPI)	W5500	Demonstrates SPI-based W5500 integration on ESP32-S3, providing the same Ethernet foundation used by this project.

Practical Tips / Pitfalls

Verify the USB keyboard is detected before troubleshooting OSC communication.
Confirm the ONYX OSC port matches the firmware configuration (default UDP 8000).
Ensure both devices are connected to the same Ethernet subnet when using broadcast mode.
Check SPI wiring, chip select, and reset connections if Ethernet initialization fails.
Keep playback executor mappings organized when expanding beyond the current 24-button layout.
Test both /go and /release actions when configuring temporary playback buttons.

FAQ

1. Why use a W5500 Ethernet module for this project?

The W5500 provides a wired Ethernet connection that allows the ESP32-S3 to send OSC commands directly to ONYX over UDP while keeping USB processing and network communication separate.

2. How does the ESP32-S3 communicate with the W5500?

The W5500 connects through SPI. During startup the firmware initializes the Ethernet interface with Ethernet.init() and Ethernet.begin(), then opens a UDP socket used for OSC transmission.

3. What role does W5500 play in the system?

The ESP32-S3 receives USB HID events and creates OSC messages. The W5500 is responsible for delivering those OSC packets over the Ethernet network to ONYX.

4. Can the keypad layout be customized?

Yes. The current firmware maps HID keycodes to OSC addresses using a switch statement. Replacing this with a configurable lookup table would make custom layouts significantly easier to maintain.

5. Can this project control functions other than playback?

Yes. Any ONYX feature that exposes an OSC endpoint can be triggered by generating the appropriate OSC address. The current firmware demonstrates playback executors, but the same approach can be extended to additional OSC commands.

Source

Repository

OSC-KEYPAD-ONYX

Primary Source Files

OSC-KEYPAD-ONYX.ino
defines.h
LICENSE

License

The Unlicense (Public Domain Dedication), according to the uploaded project analysis.

Wiznet makers