Where This Can Be Used

ONYX is a professional lighting control software used for concerts, theaters, broadcasting, and live events. It supports Open Sound Control (OSC), allowing external devices to trigger lighting playback actions over a network.

This project turns an ordinary USB keyboard or keypad into a dedicated ONYX controller. Instead of sending keyboard shortcuts to a PC, each key press is converted into an OSC command and transmitted directly over Ethernet.

Because the controller works independently of the computer keyboard, it can be installed anywhere on the same network as a compact playback controller.

Typical applications include:

• Live event playback control
• Theater cue triggering
• Broadcast automation
• Media installations
• Fixed control stations
• Backup playback controllers

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.

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.

Tags

W5500 • WIZnet • ESP32-S3 • USB Host • USB HID • OSC • ONYX • EthernetUDP • Playback Controller • Show Control • Lighting Control • Ethernet