🎮 ESP-NOW JoyBridge 🎮

Wirelessly transmit joystick commands from your computer to ESP32-based projects using ESP-NOW.

---

📖 Table of Contents

• 📖 Table of Contents
• 🎯 Project Objectives
• ✨ Key Features
• 🛠️ Project Components
  • ESP32 JoyBridge Firmware
  • JoyBridge Host
  • JoyBridge Receiver Library
• 📦 Installation
  • Installation via efr Tool
  • Manual Installation
    • Flashing Firmware
    • Running Host
  • Setup JoyBridge Receiver Library
  • Example Usage

---

🎯 Project Objectives

JoyBridge provides a simple, efficient, and reliable way to wirelessly send joystick commands to ESP32-based projects, such as MotorGo or other compatible platforms. It emphasizes ease of use, real-time responsiveness, and minimal resource usage.

✨ Key Features

• 🔧 Minimal Setup: Easily integrates with virtually any joystick.
• ⚡ Low Latency: Ultra-responsive joystick controls ideal for real-time applications.
• 🌿 Lightweight: Low CPU and memory footprint, perfect for resource-constrained environments.

🛠️ Project Components

JoyBridge consists of three main components:

ESP32 JoyBridge Firmware

• Receives joystick commands from a computer via serial.
• Broadcasts joystick data to connected ESP32 devices using ESP-NOW.
• Supports up to 10 simultaneous device connections (configurable in firmware).
• Optimized for the WaveShare ESP32-S3 1.47-inch Display Development Board, but compatible with any ESP32-S3 device (LED indicators may differ).

JoyBridge Host

• Python application using pygame to capture joystick input.
• Sends joystick data to the ESP32 bridge via serial.
• The --service-name option specifies the unique ESP-NOW service name. Connected devices use this name to discover and join the JoyBridge data stream. Customizing this helps avoid conflicts when running multiple bridges simultaneously. Default service name: JoystickService.

JoyBridge Receiver Library

• Arduino library for easily integrating joystick command reception into your ESP32 projects.
• Automatically handles service discovery, subscription, and data management.

📦 Installation

JoyBridge can be installed either via the efr CLI tool or manually.

Installation via efr Tool

Install JoyBridge quickly using the efr CLI tool:

efr plugins install joybridge

Flash firmware to your ESP32:

efr joybridge flash

Run the JoyBridge Host (optionally specifying your service name):

efr joybridge go --service-name MyJoystickService

Then proceed to Setup JoyBridge Receiver Library.

Manual Installation

Clone the JoyBridge repository:

git clone https://github.com/Every-Flavor-Robotics/esp-now-joybridge.git

The repository includes:

• joybridge_firmware: Firmware for the ESP32 JoyBridge.
• joybridge_host: Python Host.

Flashing Firmware

The joybridge_host is a uv project. Flash firmware:

cd esp-now-joybridge/joybridge_host
uv run main.py flash

Alternatively, manually flash using PlatformIO in the joybridge_firmware directory.

Running Host

Run the JoyBridge Host, optionally specifying a custom service name:

uv run main.py --service-name MyJoystickService

Then proceed to Setup JoyBridge Receiver Library.

Setup JoyBridge Receiver Library

Add the JoyBridge Receiver Library to your ESP32 project by updating your platformio.ini:

lib_deps =
    https://github.com/Every-Flavor-Robotics/esp-now-joybridge-receiver.git

Example Usage

Here's a minimal example demonstrating the JoyBridge Receiver usage:

#include <Arduino.h>
#include <joybridge_receiver.h>

JoyBridge::JoyBridgeReceiver receiver;

void setup()
{
  Serial.begin(115200);

  if (!receiver.begin("MyJoystickService"))
  {
    Serial.println("Receiver initialization failed!");
    while (true)
      delay(1000);
  }
}

void loop()
{
  receiver.loop();

  if (receiver.isConnected())
  {
    JoyBridge::JoystickData data = receiver.getJoystickData();
    Serial.println("Joystick Data Received:");
    Serial.printf(
        "A:%d B:%d X:%d Y:%d LB:%d RB:%d DU:%d DD:%d DL:%d DR:%d START:%d BACK:%d\n",
        data.a, data.b, data.x, data.y, data.lb, data.rb, data.dpad_up,
        data.dpad_down, data.dpad_left, data.dpad_right, data.start, data.back);
    Serial.printf("LT:%.2f RT:%.2f LX:%.2f LY:%.2f RX:%.2f RY:%.2f\n",
                  data.lt, data.rt, data.left_x, data.left_y, data.right_x, data.right_y);
  }
  else
  {
    Serial.println("Master not connected.");
  }

  delay(100);
}