INSEN API Reference

Complete documentation for the INSEN Professional Controller Interface. This API provides comprehensive access to controller data, MAKCU integration, and system configuration.

Current Version

v2.0.0 (Stable)

Protocol

Serial (115200 baud) + MAKCU (4Mbps)

Platform

ESP32-S3 (Arduino Framework)

Quick Start

Get up and running with the INSEN API in minutes. This guide covers the basic setup and your first API call.

1

Connect to Serial Port

Python 
import serial

# Connect to INSEN device
ser = serial.Serial('COM3', 115200, timeout=1)

# Send info command
ser.write(b"INFO\r\n")
response = ser.readline().decode().strip()
print(response)  # INSEN_FW_V2.0.0|BUILD_2025_11_06|MAKCU_COMPATIBLE
2

Monitor Controller Input

Python 
# Start input monitoring
ser.write(b"START_MONITOR\r\n")

while True:
    if ser.in_waiting > 0:
        line = ser.readline().decode().strip()
        if line.startswith(">>> INPUT|"):
            # Parse controller data
            parts = line.split('|')
            controller_id = int(parts[1])
            left_stick = parts[2]  # "x,y" format
            print(f"Controller {controller_id}: {left_stick}"))
3

Send MAKCU Commands

Python 
# Enable MAKCU passthrough
ser.write(b"SET_MAKCU_MODE 1\r\n")

# Controller input will now automatically 
# generate MAKCU commands like:
# km.move(10, -5)
# km.left()
# km.right()

Serial API Commands

Complete reference for all available serial commands. All commands are sent as ASCII text terminated with \r\n.

System Commands

INFO

Query

Get system information including firmware version, build date, and capabilities.

Request
INFO
Response
INSEN_FW_V2.0.0|BUILD_2025_11_06|MAKCU_COMPATIBLE|CONTROLLERS_4

STATUS

Query

Get current system status including connected controllers and MAKCU state.

Request
STATUS
Response
>>> STATUS|CONTROLLERS_ACTIVE_2|MAKCU_CONNECTED|POLLING_1000HZ|UPTIME_3600s

LIST

Query

List all connected controllers with their types and connection status.

Response
>>> CONTROLLER|0|XBOX_ONE|CONNECTED|WIRED
>>> CONTROLLER|1|PS5_DUALSENSE|CONNECTED|WIRELESS
>>> END_LIST

Configuration Commands

SET_POLLING_RATE <rate>

Config

Set controller polling rate. Valid values: 125, 250, 500, 1000 (Hz).

Request
SET_POLLING_RATE 1000
Response
>>> OK|POLLING_RATE_SET_1000HZ

SET_MAKCU_MODE <enable>

Config

Enable or disable MAKCU passthrough mode. When enabled, controller input generates MAKCU commands.

Request
SET_MAKCU_MODE 1
Response
>>> OK|MAKCU_MODE_ENABLED

Monitoring Commands

START_MONITOR

Stream

Start real-time controller input monitoring. Device will stream input data continuously.

Response Stream
>>> INPUT|0|1024,512|0,0|0,0|0x0000|0|100|1699276800
>>> INPUT|0|1030,510|0,0|0,0|0x0001|0|100|1699276801
Input Data Format
Field Description Range
Controller ID Controller identifier 0-3
Left Stick X,Y coordinates -32768 to 32767
Right Stick X,Y coordinates -32768 to 32767
Triggers Left,Right trigger 0-255
Buttons Button bitmask (hex) 0x0000-0xFFFF
D-Pad Direction value 0-8 (0=center)
Battery Battery level % 0-100
Timestamp Unix timestamp (ms) uint64_t

MAKCU Protocol Integration

INSEN provides seamless integration with MAKCU KM+ devices through optimized UART communication at 4Mbps for professional gaming performance.

Communication

  • 4Mbps UART (TX: GPIO43, RX: GPIO44)
  • Text-based command protocol
  • Automatic baud rate negotiation
  • Sub-millisecond response time

Command Format

  • ASCII text commands
  • Newline terminated (\n)
  • Parameter separation by commas
  • No acknowledgment required

MAKCU Commands

Complete reference for MAKCU KM+ protocol commands generated by INSEN controller input.

Mouse Movement

km.move(x, y)

Movement

Move mouse cursor by relative X,Y pixels. Generated from controller stick input.

Controller Input

Left stick movement

→
MAKCU Command
km.move(10, -5)
Conversion Algorithm
// Convert stick to mouse movement
int stick_x = controller.leftStick.x;  // -32768 to 32767
int stick_y = controller.leftStick.y;

// Apply sensitivity and deadzone
float sensitivity = 2.5f;
int deadzone = 8000;

if (abs(stick_x) > deadzone || abs(stick_y) > deadzone) {
    int mouse_x = (stick_x * sensitivity) / 1000;
    int mouse_y = (stick_y * sensitivity) / 1000;
    
    makcu.printf("km.move(%d, %d)\n", mouse_x, -mouse_y);
}

Mouse Clicks

km.left() / km.leftup()

Click

Left mouse button press and release. Mapped to controller A button.

Controller Button Press Command Release Command
A Button km.left() km.leftup()
B Button km.right() km.rightup()
X Button km.middle() km.middleup()

Scroll Wheel

km.scroll(direction)

Scroll

Scroll wheel movement. Generated from right stick Y-axis movement.

Right Stick Y

Up/Down movement

→
Scroll Commands
km.scroll(1)   # Scroll up
km.scroll(-1)  # Scroll down

Arduino Framework Integration

INSEN firmware is built on the Arduino framework for ESP32-S3, making it easy to customize and extend functionality.

Development Environment Setup

1. Install Arduino IDE with ESP32 Support

# Add ESP32 board manager URL:
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

# Install ESP32 boards package
# Tools > Board > Boards Manager > Search "ESP32" > Install

2. Install Required Libraries

// Required libraries (install via Library Manager)
#include "USB.h"           // ESP32 USB Host
#include "USBHIDGamepad.h" // HID Gamepad support
#include    // JSON parsing (optional)
#include           // Wi-Fi support (optional)

3. Board Configuration

Board ESP32-S3 Dev Module
CPU Frequency 240MHz (WiFi/BT)
Flash Size 4MB (32Mb)
Partition Scheme Default 4MB with spiffs
USB Mode Hardware CDC and JTAG

Core Classes

Overview of the main classes used in INSEN firmware for controller handling and MAKCU communication.

INSENController

Main Controller Class

Main class for handling USB controller connections and input processing.

Public Methods

bool begin()

Initialize USB Host and start controller detection.

void update()

Process controller input and update internal state. Call in main loop.

ControllerState getState(uint8_t id)

Get current state of specified controller.

bool isConnected(uint8_t id)

Check if controller is connected and active.

Example Usage

#include "INSENController.h"

INSENController controller;

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

void loop() {
    controller.update();
    
    if (controller.isConnected(0)) {
        ControllerState state = controller.getState(0);
        
        // Process left stick
        if (abs(state.leftStick.x) > 8000) {
            Serial.printf("Left stick X: %d\n", state.leftStick.x);
        }
        
        // Check A button
        if (state.buttons & BUTTON_A) {
            Serial.println("A button pressed");
        }
    }
    
    delay(1); // 1000Hz update rate
}

MAKCUInterface

MAKCU Communication

Handles UART communication with MAKCU devices and command generation.

Public Methods

bool begin(uint32_t baudRate)

Initialize UART communication with specified baud rate.

void sendMove(int x, int y)

Send mouse movement command to MAKCU.

void sendClick(MouseButton button, bool press)

Send mouse click command (press or release).

Example Usage

#include "MAKCUInterface.h"

MAKCUInterface makcu;

void setup() {
    makcu.begin(4000000); // 4Mbps
}

void processControllerInput(ControllerState state) {
    // Convert stick to mouse movement
    int mouseX = state.leftStick.x / 1000;
    int mouseY = state.leftStick.y / 1000;
    
    if (abs(mouseX) > 0 || abs(mouseY) > 0) {
        makcu.sendMove(mouseX, -mouseY);
    }
    
    // Handle button clicks
    static bool lastButtonA = false;
    bool currentButtonA = state.buttons & BUTTON_A;
    
    if (currentButtonA != lastButtonA) {
        makcu.sendClick(MOUSE_LEFT, currentButtonA);
        lastButtonA = currentButtonA;
    }
}

Performance Optimization

Guidelines and best practices for achieving optimal performance with INSEN firmware.

Polling Rate Optimization

Maximize controller polling rate for competitive gaming performance.

// Optimal task configuration for 1000Hz polling
void setup() {
    // Create high-priority task for controller processing
    xTaskCreatePinnedToCore(
        controllerTask,    // Task function
        "ControllerTask",  // Task name
        8192,             // Stack size
        NULL,             // Parameters
        10,               // Priority (high)
        NULL,             // Task handle
        1                 // Core 1 (dedicated)
    );
    
    // MAKCU communication on Core 0
    xTaskCreatePinnedToCore(
        makcuTask,
        "MAKCUTask",
        4096,
        NULL,
        9,                // Slightly lower priority
        NULL,
        0                 // Core 0
    );
}

void controllerTask(void *parameter) {
    TickType_t xLastWakeTime = xTaskGetTickCount();
    const TickType_t xFrequency = pdMS_TO_TICKS(1); // 1ms = 1000Hz
    
    for (;;) {
        controller.update();
        processControllerInput();
        
        // Maintain precise timing
        vTaskDelayUntil(&xLastWakeTime, xFrequency);
    }
}

Memory Optimization

Efficient memory usage for sustained high-performance operation.

Stack Allocation

Use stack variables for temporary data to avoid heap fragmentation.

Buffer Management

Pre-allocate buffers for UART communication to prevent dynamic allocation in critical paths.

Cache Optimization

Keep frequently accessed data in IRAM for faster access times.

Debugging & Troubleshooting

Tools and techniques for debugging INSEN firmware and resolving common issues.

Debug Output

Enable detailed logging for troubleshooting controller and MAKCU issues.

// Enable debug mode
#define INSEN_DEBUG 1

#if INSEN_DEBUG
  #define DEBUG_PRINT(x) Serial.print(x)
  #define DEBUG_PRINTLN(x) Serial.println(x)
  #define DEBUG_PRINTF(fmt, ...) Serial.printf(fmt, ##__VA_ARGS__)
#else
  #define DEBUG_PRINT(x)
  #define DEBUG_PRINTLN(x)
  #define DEBUG_PRINTF(fmt, ...)
#endif

// Usage in code
void processController() {
    DEBUG_PRINTF("Controller %d connected: %s\n", 
                 controllerId, 
                 isConnected ? "YES" : "NO");
}

Common Issues

Controller Not Detected

Symptoms: USB controller not recognized or enumerated

Solutions:

  • Check USB power supply (controllers need sufficient power)
  • Verify USB Host wiring (D+/D- connections)
  • Enable USB Host debugging in Arduino IDE
  • Try different controller types (wired vs wireless)

MAKCU Communication Failed

Symptoms: No response from MAKCU device or commands not working

Solutions:

  • Verify UART wiring (TX → RX, RX → TX, GND)
  • Check baud rate configuration (both devices must match)
  • Test with lower baud rate (115200) first
  • Monitor UART traffic with logic analyzer

High Input Latency

Symptoms: Delayed or inconsistent controller response

Solutions:

  • Increase polling rate to 1000Hz
  • Optimize task priorities and core assignment
  • Disable unnecessary features (Wi-Fi, Bluetooth)
  • Check for task delays in critical code paths