Gamepad Controller Support for Stellarium Remote Control#4813
Gamepad Controller Support for Stellarium Remote Control#4813kutaibaa-akraa wants to merge 17 commits intoStellarium:masterfrom
Conversation
added comprehensive gamepad controller support to the Stellarium Remote Control plugin, enabling users to control Stellarium using a wide range of popular game controllers. The implementation is based on the SDL Game Controller Database and supports over 20 different controller models from major manufacturers. webroot/ ├── js/ │ ├── ui/ │ │ └── gpcontroller.js (new) │ └── main.js (modified) ├── css/ │ └── gamepad.css (new) └── index.html (modified)
|
Trying to load the common RemoteControl web browser interface in Firefox, but it does not go beyond "Please wait, loading". Should it still work without any new controller? I just have a tiny Rii BT keyboard (actually I have trouble to connect via bluetooth, but its USB dongle works) which however works like any wireless keyboard. It might be nice to get the second "cursor key wheel" (showing volume and speed control for media playing) operational for Scenery3D, though. |
|
Right Stick (zooming) is not working |
Regarding the loading issue where the interface doesn't proceed beyond "Please wait, loading", could you please:
yes . please report your console. |
Loading issue is fixed now |
|
I confirm it loads again, and some test clicks in the existing UI still works. My Rii keyboard is not connected though, so I cannot test it with existing hardware. But I won't object merge as long as it does not break things. But @kutaibaa-akraa should be committed to support it for at least a year or so, and fix/finetune whatever bug reports come in. I will try some Android gamepad app... EDIT: DroidJoy did it. Tested a few minutes, seems to work well. I am not used to such devices, though, so details may evade me. |
To help diagnose your right stick issue, please send the following information: . From the console window (F12), find and paste these lines:
Example of required information: Full ID: 054c-0ce6-DualSense Wireless Controller
OS: windows
USB IDs: 054c:0ce6
Axes mapping: { leftX: 0, leftY: 1, rightX: 2, rightY: 5, l2: 3, r2: 4 }
When moving right stick UP: image zooms OUT (opposite of expected)
Operating System: Windows 11Open gpcontroller.jsLocate and open the file Find Your Device in the DatabaseSearch for the device name that appears in the UI. For example: // ========== Sony PlayStation 5 DualSense ==========
'sony_ps5_dualsense': {
id: 'sony_ps5_dualsense',
name: 'Sony PlayStation 5 DualSense Controller',
// ... other properties
axes: { leftX: 0, leftY: 1, rightX: 2, rightY: 5, l2: 3, r2: 4 },
// ...
},Modify the rightY ValueChange the Before: axes: { leftX: 0, leftY: 1, rightX: 2, rightY: 5, l2: 3, r2: 4 }After: axes: { leftX: 0, leftY: 1, rightX: 2, rightY: 3, l2: 3, r2: 4 }Save and RefreshSave the file and reload the Remote Control page. Why This WorksDifferent operating systems and browsers may read axes differently:
This manual adjustment lets you test which value works best for your specific device and operating system. |
|
All this technical info should please also go into the User Guide, section 13.5.3 (before Remote Control API). If you have trouble with LaTeX formatting we can surely help, but not with the detailed knowledge! However, also the DOM issue noted above must be fixed. |
|
It's a Defender Omega, which work as Microsoft Xbox 360 pad (idVendor=045e, idProduct=028e). Operating system is linux. In Remote Contgrol plugin it has device name: Microsoft Xbox 360 Controller (045e:028e). Changing the rightY value from 3 to 5 (or vice versa) does not effects. In Remote Control plugin Right Stick moves by horizontal, but not vertical. |
Hi alex-w, Thank you for the detailed information. This is very helpful. The issue is likely because on Linux, the axis mapping for your controller (which reports as an Xbox 360 controller) might be different from our current database entry. To find the correct mapping, could you please do a quick test?
This information will tell us the exact value that should be set for Once you provide these numbers, we can create a specific mapping for Linux users with this controller. Thanks for your help with debugging! |
|
Movements of Right Stick: Up/Down - Axis 3, Left/Right - Axis 2 |
|
OK, I found source of issue - this part of |
|
The button “Connect” isn’t working apparently |
Thank you, alex-w, for this detailed debugging and for finding the root cause. Your investigation into the axis mapping issue perfectly illustrates the core reason we moved away from the static database approach. You are absolutely right. The old code's attempt to apply OS-specific overrides for controllers (like the Xbox adjustment you pointed out) is brittle. It assumes we can predict how every browser and OS combination will enumerate the axes, which is impossible to maintain. Your discovery that the line The new approach using the raw browser Gamepad API is fundamentally different and, as you've just demonstrated, far more robust. Here's why:
Your finding that the static override was wrong and that the raw axis value Thank you again for your thorough testing and for helping us make the controller support more reliable for everyone. The next step would be to ensure the base mapping for your "Defender Omega" (recognized as an Xbox 360 controller) is correct in the generic database, using the raw values you've identified (Right X: Axis 2, Right Y: Axis 3). Please let me know if you encounter any other inconsistencies. The goal is for the "Live Input" panel to always show you exactly what the controller is doing, making any further configuration completely transparent. |
|
Subject: Gamepad Controller - Smooth Movement/Zoom Fix Hi Alex, For much smoother controller movement and zoom, please apply these two quick fixes: 1. File: Change timeout from // In function move(x, y) - line 38
// FROM:
}, 250); //repeat each 250ms to avoid Stellarium thinking the interface crashed
// TO:
}, 100); //repeat each 100ms2. File: // In fovServerUpdate() - line 60
fovTimeout = setTimeout(fovServerUpdate, 50);
// In fovServerUpdate() - line 74
fovTimeout = setTimeout(fovServerUpdate, 50);These changes eliminate the choppiness and provide a smooth, continuous movement and zoom experience with the gamepad. |
|
@kutaibaa-akraa everything works now, except [Scan] button (the device are connected after pressing any button) @gzotti what about changes of timeouts? |
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as off-topic.
This comment was marked as off-topic.
|
@kutaibaa-akraa oops, why you’re marked your latest comment as offtopic? It looks like great improvement for the feature… |
I will carry out these developments, but I want to verify them while ensuring they are ok 100%, and I will return to the report and suggestions I mentioned. |
Thank you for testing and for this feedback. The button behavior has been revised. In the initial implementation, the button was labeled "Connect" but its function was actually to scan for already-connected controllers rather than to establish a connection. This was misleading. In the final version, the button has been renamed to "Scan" and its functionality has been enhanced:
The updated code (version 2.5.0 I'll introduce it later) now properly reflects the button's purpose: it forces a device scan and refreshes the device list. The button is located in the status bar next to the connection indicator, providing a clear way to manually refresh the controller list if needed. |
Final Gamepad Controller Implementation - Ready for SubmissionSummary of Completed WorkI am now ready to submit the final, complete version of the gamepad controller feature. The code has been thoroughly tested and includes all the enhancements discussed: Key Improvements1. Scan Button ResolutionThe "Connect" button has been redesigned as a "Scan" button with full visual feedback. It now actively polls for connected controllers, displays a scanning animation, and shows the number of devices found. This resolves the previous issue where the button appeared non-functional. 2. Vibration Control EnhancementThe vibration feature has been expanded from a simple checkbox to a complete control system. Users can now enable/disable vibration and adjust intensity using a slider, with a test button to verify the effect before applying it to button presses. 3. Live Input MonitorA new live input panel provides real-time visibility into raw controller data. Users can see every button and axis value exactly as reported by the browser, making debugging and configuration transparent. This eliminates the need for external testing tools. 4. Expanded Action LibraryThe number of available Stellarium actions has been significantly increased, now covering educational presentation features including view directions, zoom levels, notable stars, deep sky objects, constellation highlighting, time jumps, and season demonstrations. 5. Profile Import/ExportComplete profile management allows users to export their button mappings and calibration settings as JSON files, and import them for backup, sharing between installations, or restoring configurations after changes. 6. Multi-Controller SupportThe system handles multiple controllers simultaneously, with independent profiles for each device. A device selector allows switching between connected controllers, and each device maintains its own mappings and calibration. 7. Standards ComplianceThe implementation fully adheres to the W3C Gamepad API standard, eliminating the brittle static database approach. This ensures compatibility with future browsers and controllers without requiring code updates. 8. Plugin Support ArchitectureThe system dynamically detects and integrates with Stellarium plugins (ArchaeoLines, Scenery3d, ExoPlanets, NavStars, MeteorShowers, Quasars, Pulsars). When a plugin is loaded, its actions automatically appear in the button customization dropdowns. When a plugin is not loaded, its actions and associated UI elements are removed, maintaining a clean interface. 9. Additional Features
Testing ConfirmationThe final code has been tested with:
Question for ReviewersShould I open a new pull request or update the existing #4813? Please advise on your preference. If you prefer a new PR, I will close this one and open a fresh one with the complete, final code. If you prefer to keep this PR, I will force-push the final version to the same branch. Either approach works for me. I am prepared to support this feature going forward as requested, and will address any bug reports that arise. Please let me know whether to update this PR or open a new one. Screenshots
Figuer: Gamepad tab with a connected PS5 controller showing the settings panel, live joystick preview, Live Input Monitor panel, and populated button customization area. |
Just update current PR |
|
It sounds really interesting, however we still have to finalize 26.1. We should keep this PR. I think, as it's one new feature, squash&merge will be the final strategy, or would you keep separate commits to trace some development phases? In the latter case, you should rebase and prepare the cleaned-up commits (if needed) and force-push. However, as said, I have no time before April to go into detailed views. You have edited index.html. Not sure if the new interfaces should also appear in the tablet-size tablet7in.html? (The tablet interface is more for presenters in front of a big screen, so not sure if the gamepad configs are relevant. ) |
Thank you for the feedback and for confirming the PR will be kept. I understand the timing constraints for 26.1. Regarding the tablet7in.html interface: I have now added the Gamepad Controller tab to it as well, following the same structure as index.html. The interface was tested using browser developer tools with device emulation (iPad) and by manually resizing the browser window. The layout adapts correctly to smaller screen sizes using the existing responsive CSS. I will keep this PR open and continue with the current branch. Please let me know if you would like me to rebase or squash the commits before the final merge. I am ready to support this feature going forward and will address any bug reports after release.
Figuer: Tested on Chrome with device emulation (iPad Pro). The Gamepad Controller tab is now included in the tablet7in.html interface and displays correctly. The layout adapts responsively to tablet screen dimensions while maintaining full functionality. |
Complete gamepad controller implementation v2.5.0 - Full W3C Gamepad API compliance - Live Input Monitor for real-time debugging - Enhanced Scan button with visual feedback - Improved responsiveness with optimized timeouts - Complete button customization interface - Profile import/export functionality - Responsive CSS matching Stellarium theme - Added tablet7in.html support
When a controller is disconnected, the Live Input Monitor previously continued to display stale button and axis values. This caused confusion as the data appeared frozen rather than showing the disconnected state. Changes: - Add null/undefined checks in updateLiveInputDisplay() to detect when no controller is connected - Display "No controller connected" message in Buttons, Axes, and Device Information panels when no active device exists - Call updateLiveInputDisplay() in setActiveDevice() when switching to null device - Call updateLiveInputDisplay() in gamepaddisconnected event handler - Add fallback messages in updateButtonsDisplay() and updateAxesDisplay() when gamepad data is unavailable This ensures the Live Input Monitor reflects the actual connection state, matching the behavior of the Button Customization panel which already clears when no device is connected.
The "search_hercules_cluster" action previously targeted the Hercules Galaxy Cluster (Abell 2151) instead of the intended globular cluster M13. This was confusing as M13 is the more commonly referenced object. Changes: - Add special case in handleSearchAction to map "hercules_cluster" to "M13" - Update display name to "Center on Star Cluster in Hercules (M13)" for clarity Now pressing the button correctly centers on the Great Hercules Globular Cluster (Messier 13) as expected.
Replaces instant camera jumps with smooth 3-second transitions for all view direction actions (North, South, East, West, Zenith, Nadir).
Previously used rc.postCmd("/api/main/view") which instantly changed the view direction. Now uses core.moveToAltAzi() with a duration parameter for gradual movement, matching the existing stelssc buttons in the web interface.
Changes:
- view_north: core.moveToAltAzi(0, 180, 3)
- view_south: core.moveToAltAzi(0, 0, 3)
- view_east: core.moveToAltAzi(0, 90, 3)
- view_west: core.moveToAltAzi(0, 270, 3)
- view_zenith: core.moveToAltAzi(90, 0, )
- view_nadir: core.moveToAltAzi(-90, 0, 3)
This provides a more natural and visually pleasing experience when navigating between cardinal directions during presentations.
… offset Replaces instant zoom and viewport offset changes with smooth 3-second transitions for all zoom levels and viewport offset presets. Previously used viewcontrol.setFOV() and propApi.setStelPropQueued() which changed values instantly. Now uses StelMovementMgr.zoomTo() and StelMovementMgr.moveViewport() with duration parameter for gradual movement, matching the existing stelssc buttons in the web interface. Changes: - Zoom levels: StelMovementMgr.zoomTo(value, 3) - All zoom presets (0.1° to 180°) now transition smoothly over 3 seconds - Viewport offset: StelMovementMgr.moveViewport(0, value, 3) - All offset presets (-50% to +100%) now transition smoothly over 3 seconds This provides a more natural and visually pleasing experience when adjusting zoom and viewport during presentations.
Adds Sun, Moon, Uranus, Neptune, and Pluto to the list of searchable solar system objects for the gamepad controller. Previously only Mercury, Venus, Mars, Jupiter, and Saturn were available. Now includes all major solar system bodies for comprehensive educational presentations. New objects: - Sun - Moon - Uranus - Neptune - Pluto All objects use the same search mechanism as existing planets, centering on the target with the configured selection mode.
Converts constellation highlight actions from one-shot to toggle mode. First press: isolates and highlights the selected constellation Second press: clears isolation and shows all constellations This provides more intuitive control during presentations, allowing users to easily toggle between isolated constellation views and the full sky view without needing a separate "clear" button. Changes: - Check current isolation state and selected object - If same constellation is already highlighted, clear it - Otherwise, apply highlight with isolation enabled - Maintains proper feedback notifications for both states
…UI layout Major improvements to Gamepad Controller module: 1. Live Input Monitor Enhancement: - Replaced simple grid with 4-column compact button layout for better space utilization - Added visual meter bars for axes display showing real-time analog values - Implemented color-coded feedback (green for positive, red for negative axes) - Added device information panel with OS and browser detection - Improved responsive design for mobile and tablet devices 2. Zoom Inversion Feature: - Added "Invert Y-Axis (Zoom stick)" checkbox for right stick zoom control - Implemented zoom inversion logic that affects both zoom behavior and canvas preview - Canvas now visually reflects inverted Y-axis movement while Live Input Monitor continues to show raw values - Added zoomInvertY setting to persistent storage 3. UI Layout Reorganization: - Restructured Joystick Preview section with cleaner separation - Added current direction display below left stick showing real-time movement direction (North, South, East, West, etc.) with speed indicator - Moved Current FOV display below right stick for consistent layout - Grouped axis inversion checkboxes together for better organization - Reduced overall spacing and padding for more compact interface - Improved responsive behavior across all screen sizes Files modified: - gamepad.css: Added styles for live input buttons, axis meters, joystick info panel, and responsive grid layouts - gpcontroller.js: Added zoomInvertY setting, updateCurrentDirection() method, enhanced updateButtonsDisplay() and updateAxesDisplay() with visual meters, modified updateStickPreview() to respect zoom inversion visually - index.html&tablet7in.html: Reorganized joystick preview section with direction display, added zoom invert checkbox, restructured live input panel layout Version: 2.5.0 → 2.6.0
Fix FOV synchronization between gamepad zoom control and main interface: - Add $viewFovSlider reference to update main FOV slider directly - Update view_fov_text immediately when zooming with gamepad - Extend zoom range to match viewcontrol.js (0.001389° to 360°) - Add zoomInvertY to persistent settings storage - Listen to fovChanged event for proper synchronization This resolves the issue where zooming with the right stick would cause choppy movement and desynchronization between the gamepad display and the main FOV slider/text in the View tab. Files modified: - webroot/js/ui/gpcontroller.js
Fix FOV display synchronization when using button mappings that modify zoom: - Update currentFov immediately when reset_zoom action is triggered - Ensure updateFovDisplay() updates both gamepad panel and main view tab - Synchronize view_fov_text and view_fov slider on every FOV change - Maintain proper FOV range (0.001389° to 360°) across all components - Add JSDoc documentation for init() function This resolves the issue where pressing a button mapped to "Reset zoom" would not update the FOV display in the gamepad panel or the main view tab. Files modified: - webroot/js/ui/gpcontroller.js
…sponsive design This commit introduces comprehensive UI improvements to the Gamepad Controller module, focusing on visual consistency with Stellarium's original styling, enhanced responsive behavior across all device sizes, and improved device information display. Key Improvements: **Styling & Visual Consistency (gamepad.css)** - Updated all text colors to match Stellarium's original style: headers, labels, and section titles now use black (#000000) for better readability - Maintained existing color scheme for action names and help text for visual hierarchy - Improved background consistency across all gamepad tabs to match main Stellarium theme - Enhanced button dropdown styling with proper optgroup and option colors **Device Information Enhancements (index.html & gpcontroller.js)** - Added button and axis count display in device info card showing actual hardware capabilities - Dynamic updates reflect real-time device specifications when controller is connected - Improved device identification with clear display of button/axis counts (format: "16 / 4") **Joystick Preview Layout (index.html)** - Reorganized joystick preview into proper two-column layout that remains side-by-side on tablets and larger screens (>700px) - Each joystick now contains its own inversion controls within its card: - Left stick: Invert X and Invert Y options - Right stick: Invert Y (Zoom stick) option - Improved canvas rendering with proper crosshair centering and accurate stick positioning - Added visual feedback for checkbox states with green accent when enabled **Canvas Rendering Fix (gpcontroller.js)** - Fixed updateStickPreview function to use actual canvas dimensions instead of CSS dimensions - Corrected crosshair and center point positioning for accurate joystick visualization - Added proper stick position clamping within canvas boundaries - Implemented radius calculation based on actual canvas size for consistent display - Dynamic update of button/axis counts in device info during polling **Comprehensive Responsive Design** - Desktop (1400px+): Optimized panel widths and font sizes - Standard screens (1025-1399px): Balanced layout with reduced spacing - Tablet landscape (769-1024px): Compact fonts and adjusted button groups - Tablet portrait (481-768px): Column-stacked layout with condensed spacing - Mobile phones (320-480px): Minimal padding, reduced font sizes for all elements **Slider & Control Improvements** - Reduced spacing between slider rows for compact display - Adjusted font sizes and min-widths for better small screen compatibility - Optimized vibration intensity row visibility and spacing - Improved checkbox groups with tighter spacing on mobile **Live Input Monitor Enhancements** - Consistent background styling matching main gamepad panel - Responsive button grid: 4 columns on desktop, 3 on medium, 2 on tablet, 1 on mobile - Adjusted font sizes and meter heights for better readability on all devices - Optimized device info display with column wrapping **Button Customization Panel** - Reduced internal spacing for more compact presentation - Adjusted dropdown font sizes for better readability - Improved button group headers and item spacing for small screens - Maintained dropdown styling with black text for options and optgroups **Calibration Section** - Consistent styling with black headers - Improved responsive layout for calibration buttons on mobile - Better spacing for calibration values grid This update ensures the Gamepad Controller tab now matches Stellarium's visual identity while providing a seamless experience across all devices from desktop monitors to mobile phones. Users can now see detailed device information including button and axis counts directly in the interface. Files modified: - index.html (joystick preview structure + device info enhancements) - gamepad.css (complete responsive styling overhaul) - gpcontroller.js (canvas rendering fix + button/axis count display) - tablet7in.html (optional tablet layout adjustments) Version: 2.6.0 Date: 2026-04-01







Gamepad Controller Support for Stellarium Remote Control
Overview
This PR adds comprehensive gamepad controller support to the Stellarium Remote Control plugin, enabling users to control Stellarium using a wide range of popular game controllers. The implementation is based on the SDL Game Controller Database and supports over 20 different controller models from major manufacturers.
Supported Devices (Database Included)
The controller database includes mappings for:
Sony PlayStation
Microsoft Xbox
Nintendo
Logitech
8BitDo
Razer
Steam
Generic
Features
Core Functionality
User Interface
Technical Features
Files Modified/Added
Testing Status
Tested and Verified
Mappings Included (Require Testing)
All other controller mappings are sourced from the SDL Game Controller Database and are theoretically correct, but require testing on actual hardware with different operating systems.
Known Limitations
Analog Triggers (L2/R2): Currently function as digital buttons only. Future enhancement could add analog support for velocity-based actions.
D-pad Implementation: Operates as separate buttons (standard behavior in most browsers). Some controllers may present D-pad as axes.
Platform Differences: Axis mappings may vary between Windows, Linux, and macOS. The database includes Windows-tested mappings; Linux/macOS users may need custom adjustments.
Browser Support: Requires browser with Gamepad API support (all modern browsers).
Future Enhancements
Installation Instructions
Usage Guide
Pull Request Checklist
Notes for Reviewers
This implementation focuses on stability and usability rather than complete universal compatibility. The controller database is included but only PS4/PS5 have been fully tested. Other mappings are provided as a foundation for community testing and future enhancement.
A future version could integrate the complete SDL database dynamically, but that requires more extensive cross-platform testing and a different architectural approach.
Testing Help Needed: If you have access to any of the listed controllers on Linux or macOS, please test and report any mapping issues.
Screenshots
Type of change
How Has This Been Tested?
Test Configuration:
Checklist: