1 · Introduction

SkinSync is a desktop utility that manages ESP32-based touchscreen devices. It lets you upload skins (background images) and hotspots (interactive regions) to one or many devices, organise them into loadouts, and forward touch events to scripts or AutoHotkey or acting as a virtual keyboard on your PC.

See Communication Modes & Menuing System for an overview of how devices interact with your computer and the differences between BLE Keyboard and App Monitoring modes.

• Connections: USB Serial • Wi-Fi • Bluetooth LE (including BLE Keyboard mode)
• Multi-skin Navigation: Devices can store bundles of skins that reference each other via hotspot commands – ideal for menu systems.
• Live Monitoring: Detect real-time touch events from devices and route them to apps.

2 · Communication Modes & Menuing System

Supported Communication Methods

• USB Serial – Direct, reliable connection for flashing firmware, uploading skins, and sending configuration data.
• Wi-Fi – Wireless management, skin uploads, and real-time monitoring when both PC and device are on the same network.
• Bluetooth Low Energy (BLE) – Two distinct modes: BLE Keyboard mode and BLE App Monitoring mode (see below). Note: Your PC must have Bluetooth hardware and drivers installed to use Bluetooth features.

Menuing System with Skins and Hotspots

• Skins are ZIP files containing a background image and a JSON file describing hotspots.
• Hotspots are interactive regions on a skin, each mapped to a command (e.g., launch an app, send a keystroke, switch skins).
• Loadouts are collections of devices and their assigned skins. Each device in a loadout can have multiple skins, enabling menu systems where hotspots can link to other skins, creating multi-level navigation.

Bluetooth Modes: BLE Keyboard vs. App Monitoring

• The ESP32 device acts as a standard Bluetooth keyboard.
• Pair it with your operating system like any wireless keyboard. Your PC must support Bluetooth.
• Touching a hotspot sends a keystroke directly to the OS.
• Use case: Control any application that accepts keyboard input. No need for the SkinSync app to be running.
• Limitations: Only supports sending keystrokes; hotspot actions are limited to keyboard events.

• The SkinSync app listens for touch events from devices via USB, Wi-Fi, or BLE (non-keyboard mode). Your PC must support Bluetooth to use BLE connections.
• When a hotspot is touched, the event and its command are sent to the app.
• The app can forward the command to AutoHotkey scripts, Python scripts, or other handlers.
• Use case: Flexible automation, launching programs, or custom workflows. Hotspots can trigger complex actions.
• Limitations: Requires the SkinSync app to be running and in monitoring mode; device and PC must be connected.

Summary Table

In summary: Use BLE Keyboard mode when you want your device to act as a wireless keyboard, sending keystrokes directly to your computer, independent of the SkinSync app. Use App Monitoring mode for maximum flexibility—forwarding touch events to scripts, launching programs, or integrating with automation tools, all managed through the SkinSync app.

2 · Installation & First-Run

1. Download the packaged installer (SkinSync_setup.exe).
2. Windows users: double-click SkinSync shortcut.
3. On first launch, SkinSync creates a %LOCALAPPDATA%\SkinSync workspace containing:
   loadouts, skins, known_devices, etc.
4. A tray icon () appears; double-click it any time to restore the window.

3 · Quick Start – Flashing Your First Device

1. Connect the ESP32 touchscreen via USB.
2. From the toolbar click “Setup a new device”.
3. Follow on-screen prompts; SkinSync flashes the firmware, reboots the device, and stores a .device profile.
4. Important: After setting up your device, you must create a Loadout before you can assign and upload skins to it.
5. From the main menu, click next to Loadout to create a new loadout. Enter a unique name.
6. Open your new loadout, then add your device to it using .
7. Now, you can assign a skin to your device within the loadout. You can create a new skin (which is a ZIP file containing an image and hotspots metadata) or import an existing one by placing its ZIP file in the skins/ subfolder. Shared skins will appear in the UI automatically.
8. With a device selected in the loadout, you can edit the hotspots for the assigned skin (note: you cannot edit the original skin file, only the assignment and hotspot configuration for the device in the loadout).
9. Press Sync Skin to upload the assigned skin and its hotspots to the device.
10. From the loadout view, you can also reboot devices, upload configs, or click Monitor devices to start listening for touch events, which will be forwarded according to the hotspot settings.

Note: Skins are portable ZIP files. You can share them with others, who can add them to their skins/ folder to make them appear in the UI.

4 · User Interface

States

The app switches UI layouts automatically using a built-in state-machine:

• Idle – device & loadout selection.
• DeviceSetup / DeviceConfig – wizard-style progress window with log feedback.
• LoadoutIdle – grid view of devices inside the current loadout.
• LoadoutDeviceScan – scanning/validation workflow.
• LoadoutDeviceListen – real-time monitor view.

Feedback Bar

A collapsible banner at the top shows hints, task progress and background logs. Toggle via View → Show/Hide feedback bar.

5 · Device Management

Adding a New Device

1. Click Device → New device setup or toolbar .
2. The wizard erases & flashes the correct binary from device_apps.
3. After success a .device file lands in known_devices.

Labelling a Device

Select a device then choose Device → Label selected device. This stores a friendly label in device_to_label_map.json and updates all dropdowns.

Wi-Fi Credentials

1. Select a device → Device → Send device Wi-Fi configs.
2. Enter SSID & password; SkinSync encrypts them (AES-CTR) and sends over USB.

Reboot / Update

Use toolbar buttons to push new configs or reboot selected/all devices.

6 · Skins & Hotspots

Skin Files

Skins are ZIP bundles stored in skins/ containing at least:

• image – background JPEG/PNG.
• hotspots – JSON list with x, y, width, height, command, target.

Hotspot Editor

1. Select a skin (or device+skin) → click Hotspots button.
2. Draw/resize hotspots on the canvas, edit properties in the side panel.
3. Double-click a target to browse for .exe or .ahk.
4. Press Save to embed hotspots into the skin file.

Uploading

With a device chosen, press Sync Skin. SkinSync picks the primary connection (USB → Wi-Fi → BLE) and falls back as needed.

7 · Loadouts

A loadout is a JSON file listing several devices and the skin assigned to each. Typical uses: multi-screen cockpits, stream decks, or store kiosks.

Creating

1. Click toolbar next to Loadout.
2. Enter a unique name; an empty loadout file is created.
3. Open the loadout, then use / to add or remove devices.

Scanning & Validation

When you select or rescan a loadout SkinSync:

• Checks each device is reachable via at least one connection.
• Optionally runs a full Bluetooth/Wi-Fi scan if mismatch detected.
• Displays status icons on each device panel (green/grey/red for Bluetooth, USB, Wi-Fi).

Saving & Backup

Press or Loadout → Save loadout. Deleted loadouts are moved to loadouts_deleted/ for safety.

8 · Monitoring & Touch Events

1. Open a loadout → click Monitor devices.
2. SkinSync listens on each connection, shows a live log in the Feedback Bar and highlights hotspots.
3. Touch events are forwarded to AutoHotkey scripts, executables, or other handlers you mapped in Hotspot Editor.
4. Stop monitoring with .

9 · Menu & Toolbar Reference

Main Menus (Idle State)

Loadout View Menus

When a loadout is open, the menu bar changes to provide loadout-specific options. These menus are distinct from the main (Idle) menus and are available only in the Loadout view:

• < Back – Return to the main (Idle) view.
• File
  • Device Code Files – Open firmware folder in Explorer/Finder.
  • Loadout Files – Open loadouts directory.
  • Skin Files – Open skins directory.
  • Exit – Prompt to save loadout then quit.
• Loadout
  • Save loadout – Save the current loadout and all device/skin assignments.
  • Rescan all devices – Scan all devices in the loadout to check their connection status (USB, Wi-Fi, BLE).
  • Monitor devices – Enter monitoring mode to listen for touch events from all devices in the loadout and forward them according to hotspot settings.
  • Delete Loadout – Move the current loadout to the loadouts_deleted/ folder for safety.

Separators are used to visually group related menu items. The Loadout view menus are context-sensitive and provide quick access to all actions relevant to managing devices and skins within a loadout.

Key Toolbar Buttons (Idle)

• Devices dropdown – pick any known device.
• Device Updates – open Device Config wizard.
• (next to Devices) – new device setup.
• Loadout dropdown – pick loadout.
• (next to Loadout) – new loadout.
• Skins dropdown – pick skin for editing.
• (next to Skins) – create blank skin.

Hotspot Editor Menus & Editing

The Hotspot Editor provides a dedicated interface for creating and editing interactive regions (hotspots) on a skin image. When you open the Hotspot Editor, the following menu options and editing features are available:

• Image Menu (when not editing a device in a loadout):
  • Import – Import a new background image for the skin.
• Hotspot Menu:
  • Add – Add a new hotspot to the skin.
  • Select Color – Choose the color used to outline hotspots.
  • Reset all from skin file – Restore hotspots to their original state from the skin file.
  • Copy to clipboard – Copy the current hotspot definitions to the clipboard.
  • Paste in hotspots – Paste hotspot definitions from the clipboard.
• Skin Menu (when editing or creating a skin):
  • Import – Import a skin file (ZIP) for editing.
  • Save – Save the current skin and its hotspots.
  • Explore – Open the skins folder in your file explorer.
• Device Menu (when editing a device in a loadout):
  • Send skin to device – Upload the current skin and hotspots to the device.
  • Send hotspots to device – Upload only the hotspot definitions to the device.
  • Reboot device – Reboot the connected device.
  • Listen to device – Start listening for touch events from the device (for testing hotspot mapping).
  • Stop listening to device – Stop listening for touch events.
  • Get SD card structure – Retrieve and display the file structure of the device's SD card.

Interactive Hotspot Editing

• Add Hotspots: Use the Hotspot menu to add new hotspots. Each hotspot appears as a rectangle over the skin image.
• Drag & Resize: Click and drag hotspots to move them over the image. Adjust their size using the width and height fields in the right panel.
• Configure Actions: For each hotspot, set properties such as:
  • Target – The file or script to launch (double-click to browse for a file).
  • Command – The command or argument to send when the hotspot is touched.
  • Title – An optional label for the hotspot.
• Test Hotspots: Use the Test button to simulate the hotspot action.
• Delete Hotspots: Remove unwanted hotspots with the Delete button.
• Visual Feedback: Hotspots are outlined on the image, and the currently selected hotspot is highlighted. You can also use keyboard shortcuts (Ctrl+Arrow keys) to fine-tune hotspot position and size.

This editor allows you to visually design interactive layouts, assign actions to each region, and ensure your device responds as intended when users touch different parts of the screen.

Shortcuts

Esc – closes modal dialogs
Ctrl + drag hotspot edges – fine resize
↑/↓/←/→ inside numeric fields – adjust by 1 pixel

10 · Troubleshooting

Device Not Detected

• Ensure the correct COM port is assigned (unplug & reconnect USB).
• Run Rescan all devices in Loadout view.
• Ensure Bluetooth is enabled and works with other Bluetooth devices.

Wi-Fi Upload Fails

• Make sure device and PC are on the same subnet.
• Re-send Wi-Fi credentials via USB.
• Ping the device IP listed in the Feedback Bar.
• If using a WIFI extender your device could be connecting to it and in some cases will not appear as available.

BLE Keyboard Pairing

• Select Bluetooth BLE keyboard mode for your device in the configuration options.
• Upload the configs to the device so it knows to operate in BLE keyboard mode.
• Upload your skins and hotspots to the device as usual.
• Pair the BLE touchscreen device to your operating system as a keyboard in the OS Bluetooth settings.
• Assign hotspots to send keystrokes as needed for the application you are using.

11 · About & Credits