Release Notes – Version 0.0.7

FocusTool 0.0.7 highlights:

ChamSys Console Support Beta: Support for ChamSys MagicQ consoles with OSC integration and built-in commands.
grandMA2 Stability: Major stability improvements with internal traffic controller to prevent freezes.
Performance & UI: Faster startup, improved zoom controls, and better keyboard layout.

🎮 ChamSys Console Support Beta

FocusTool now supports ChamSys MagicQ consoles (beta). Pan, Tilt, and attribute control via joysticks works reliably. You can send built-in commands (Previous Head, Next Head, Clear) and use the Quick Mapping overlay for attribute assignment.

OSC Integration: Update attributes via OSC commands.
Built-in Commands: Next Head, Previous Head, and Clear Programmer available as built-in actions.
Fixed Attribute Library: ChamSys uses a predefined, read-only attribute list (unlike MA2/MA3 where you can customize).
MagicQ Software Required: MagicQ PC app is required on your handheld device, set up as a remote viewer in session with your console.

🔧 grandMA2 Stability Improvements

An internal "traffic controller" has been added to prevent overload during heavy Telnet traffic, reducing freezes and lock-ups during long sessions. This results in a noticeably more stable experience during extended focus and programming sessions.

⚡ Performance, Web Remote & UI

Faster Startup: The application now starts faster with optimized loading.
Zoom Controls: The zoom slider for grandMA2 & grandMA3 (Web Remote) has been replaced with fixed buttons (65% / 100%) for more predictable behavior.
Keyboard Layout: In the Quick Mapping Overlay, the Cancel button has been moved to the left to prevent confusion and accidental input.

1. Introduction

Welcome to FocusTool – the professional software solution that revolutionizes how you control lighting equipment. Developed by YourLD & MAOSS, FocusTool bridges the gap between traditional console operation and modern, intuitive control methods.

What is FocusTool?

FocusTool is a precision focusing application that allows you to control your lighting fixtures using a handheld gaming console. By leveraging OSC (Open Sound Control) and Telnet, it provides integration with grandMA3, grandMA2, and ChamSys MagicQ consoles.

Screenshots: Click any image in this manual to view it larger.

Home screen overview (connection, values, event log, Web Remote button).

🎮 Gaming Controller Support

Works with all handheld Windows gaming consoles like the MSI Claw and Steam Deck for precise, analog movement control with customizable sensitivity and dead zones. (MSI Claw recommended)

🌐 OSC Communication

Industry-standard OSC protocol ensures reliable, low-latency communication with your lighting console.

⚙️ Fully Customizable

Remap buttons, adjust sensitivity curves, invert axes, and create multiple speed profiles to match your workflow.

📱 Integrated Web Remote

Launch grandMA3 Web Remote directly from FocusTool in a dedicated popup window for seamless operation.

🔄 Real-time Feedback

Live status updates, movement values, and comprehensive logging keep you informed of all operations.

💻 Portable Ready

Optimized for handheld PCs like MSI Claw and Steam Deck, turning them into portable focusing stations.

Key Benefits

Speed up your workflow: Analog control is faster and more intuitive than encoder wheels
Improved precision: Fine-tune movements with variable speed controls and boost functions
Reduced fatigue: Ergonomic controller design reduces strain during long programming sessions
Consistent experience: Same interface across grandMA3 and ChamSys platforms
Portable operation: Take your focusing setup anywhere with handheld PC compatibility

2. System Requirements

Minimum Requirements

Component	Minimum Requirement	Recommended
Operating System	Windows 10 (64-bit) / Linux (SteamOS)	Windows 11 (64-bit)
RAM	2 GB	2 GB or more
Storage	500 MB free space	500 MB free space
Display	1280x720 resolution	1920x1080 or higher
Controller	Windows Handheld Gaming Console	MSI Claw
Network	Ethernet or WiFi	Gigabit Ethernet

Tested Handheld Devices

MSI Claw: Highly recommended, optimized experience
Steam Deck: Good compatibility in SteamOS Gaming Mode
ASUS ROG Ally: Compatible with minor setup
GPD Win series: Basic compatibility

Network Requirements: FocusTool and your lighting console must be on the same network. Internet connection is only required for license activation and software updates.

3. Installation & First Setup

Download & Installation

Download FocusTool from the official website or your purchase confirmation email.
Extract or install the file:
• On Windows, extract the ZIP file to your desired location (e.g., C:\Program Files\FocusTool\) and run FocusTool.exe.
• On Linux / SteamOS, download FocusTool.bin and place it anywhere you like (e.g., your Desktop). Make it executable via Properties → Permissions → "Allow executing file as program", then double-click to start.
Ensure your handheld console is on and ready before launching FocusTool.
Run the application — on Windows, run as Administrator for the first launch; on Linux you may need to confirm execution the first time.

Steam Deck (SteamOS) — Mandatory Setup:

You must be in Desktop Mode to install and use FocusTool correctly.
In Desktop Mode, if you want the sticks and buttons to behave like a true Gamepad (not as a mouse), hold the Start button for a few seconds to switch to joystick control.
Without Desktop Mode and this Start-button toggle, controller input will not be mapped correctly and FocusTool will not function as intended.

MSI Claw – Mandatory Setup:

Make sure the MSI Claw is in Gaming Mode. Press the lower black button on the right side of the screen (one of the two small buttons) to open the MSI control overlay.
In the middle of this overlay you will see Control Mode. This must be set to Gamepad. If it shows something else (for example "Mouse"), Windows will not expose the controller as a gamepad and FocusTool cannot use it correctly.
If FocusTool shows Disconnected, your controller is not detected:
- First, double-check that the MSI Claw is really in Gaming Mode and that Control Mode = Gamepad in the overlay.
- If that is correct, your controller drivers may be missing or not loaded correctly. A full restart of the MSI Claw often fixes cases where Windows did not load the controller properly in Device Manager.
If pressing the lower black button does not show the MSI overlay at all, the MSI Claw firmware or tools are likely missing or outdated. Install the latest firmware and driver package from the MSI website:
https://www.msi.com/support/download → Handhelds → your MSI Claw model

Antivirus/Firewall Notice: Some antivirus software may falsely flag FocusTool. Add an exception for FocusTool.exe or FocusTool.bin in your antivirus and firewall to allow network communication.

First Launch Process & Interface

On first launch, a splash screen appears while FocusTool initializes. The main interface then opens with several tabs:

Tab	Purpose
Home	Main control interface, real-time values, and status information.
Controller Mapping	Customize button and axis assignments.
Settings	Network configuration, speed settings, and advanced preferences.
License	License activation and status information.
About & Updates	Version information and automatic updates.

Virtual Keyboard: On handhelds, you can simply click any input field or press F1 to open the built-in virtual keyboard.

Controller not detected? Ensure your handheld is in the correct mode (Desktop Mode + Gamepad on Steam Deck, Gaming Mode + Control Mode = Gamepad on MSI Claw), and that the OS sees the controller as a true gamepad before starting FocusTool.

4. License Activation

License tab (not activated yet) – enter Email + License Key.

License tab (activated) – shows active status and validity.

FocusTool requires a valid license for full functionality. Without an active license, OSC commands will not be sent to your console, effectively disabling the core functionality.

Activation Process

Navigate to the License tab in the main interface.
Enter your email address that was used during purchase.
Enter your license key exactly as provided (copy-paste recommended).
Click "Activate License" and wait for server verification.
Confirmation will appear if activation is successful.

Important License Information

Key License Facts:

One license per device: Each license is hardware-locked to one specific machine.
Internet required for Activation: Initial activation and periodic verification (every 90 days) need internet access.
Offline Grace Period: The application can operate fully offline for up to 90 days after its last successful online verification.
Automatic Checks: The software performs a quick, non-intrusive license verification check approximately every 30 minutes when an internet connection is available.

5. Network Configuration

Proper network setup is crucial for FocusTool to communicate with your lighting console. This section covers both OSC communication and Web Remote integration. A high-quality, powerful access point is essential for a stable and responsive connection. Using a subpar or consumer-grade router can lead to latency, delayed responses, or connection drops.

Basic Network Setup

Open the Settings tab in FocusTool.
Locate the network configuration section.
Configure OSC settings for your console.
Set up Web Remote (optional but recommended for grandMA3).
Save your settings and test connectivity.

OSC Configuration

Setting	Description	Example
OSC Target IP	IP address of your lighting console.	`192.168.1.100`
OSC Port	OSC input port on your console.	`9001` (grandMA3 default)
OSC Protocol	Select how FocusTool sends commands to the console.	`UDP` (default) / `TCP`

Console-Specific Settings

grandMA2 Configuration

grandMA2 uses Telnet communication. To enable Telnet on a grandMA2 console, follow these steps:

Navigate to: Setup → Global Settings → Telnet.
Set "Login Enabled" to enabled.
Navigate to: Setup → Global Settings → Remotes.
Set "Login Enabled" to enabled.

Important: You must enter your username and password (if applicable) in FocusTool's Settings tab under Network Configuration. FocusTool will use these credentials to authenticate with the grandMA2 console via Telnet.

Unlike grandMA3, grandMA2 connections are user-based, which means multiple FocusTool instances can operate on the same session simultaneously by logging in with different User Profiles.

grandMA3 Configuration

To enable OSC communication on a grandMA3 console, follow these steps precisely:

Navigate to: Setup → In & Out → OSC.
Add a new OSC configuration entry.
Configure the settings as follows:

Destination IP: Your Console's IP
Mode: UDP
Port: 9001 (or as configured in FocusTool)
Receive: Yes
Send: Yes
Receive Command: Yes
Send Command: Yes
Echo Input: Yes
Echo Output: Yes

Important: Make sure you Enable output and input. On grandMA3, OSC commands are currently handled by the session's Global Master user only (multi-user sessions: other users will not receive programmer updates from OSC yet). On grandMA2 this limitation does not apply because Telnet connections are user-based. Restart your console software after setting up OSC to ensure changes take effect.

ChamSys Configuration

Important: These OSC settings must be configured on the master desk console, not on your handheld device. To enable OSC communication on the master desk, follow these steps precisely:

On the master desk console, navigate to: Setup → Multi Console → Enable Remote Control and set it to [YES].
Navigate to: Setup → Network.
Configure the OSC settings as follows:

OSC Mode: Enable both TX and RX
TX & RX Port: Use the same port (e.g., 9000 or 9001)
OSC Tx IP: Set to 0

Important Notes:

ChamSys uses a fixed attribute library (read-only). Attributes are predefined by the MagicQ console and cannot be added or removed in FocusTool.
For complete functionality, you will need MagicQ installed and configured on your handheld device (see the ChamSys Setup section).

Custom OSC Commands: You can create custom commands from FocusTool to trigger MagicQ macros or other features. To set this up:

In MagicQ, go to: Macros → View Autom → Insert Autom
Select: Type OSC Message → Function Run Macro → F1 [Macro ID]
Other actions can also be attached to OSC messages.

You can then send these custom OSC commands from FocusTool using the OSC action type in Controller Mapping.

Web Remote Setup

ChamSys Users: ChamSys consoles do not have a built-in web remote in FocusTool. Instead, you should use MagicQ on your handheld device. See the ChamSys Setup section for detailed setup instructions.

The following settings apply to grandMA2 and grandMA3 consoles only:

Setting	Description	Example
Webremote IP	IP address for accessing the console's web interface.	`192.168.1.100`
Webremote Port	HTTP port for web remote access.	`8080` (grandMA3 default)

Confirm Your Connection: Before starting your session, always verify that you can access your console's web remote from the browser on your handheld device. This confirms that your network and access point are configured correctly.

Network Tip: Use static IP addresses for both your handheld PC and your console to ensure consistent connectivity. DHCP can cause IP addresses to change, which will break your configuration.

6. Controller Setup & Mapping

Controller Mapping tab – map buttons/actions, edit, delete, restore defaults.

The Controller Mapping tab is where you customize your controller layout to fit your workflow perfectly. You can assign console functions, custom commands, and internal app functions to any button.

Action Types Explained

Action Type	Description	Examples
Built-in Actions	A predefined list of common console and app functions.	Highlight, Solo, Next, Toggle Invert Pan, Quick Mapping.
OSC	Allows you to send any custom OSC command string. Tip: Commands now loop while holding the button.	`Group 1 At Full`, `Go+ Cue 1`
Attributes (Buttons)	Map a specific attribute directly to a button.	Assign a button to "Zoom (+)" or "Iris (-)" with Slow or Fast speed.

How to Create a Custom Mapping

Navigate to the Controller Mapping tab.
Click "Map New Action". The status will change to "Listening...".
Press the desired button or trigger on your controller. The new mapping will appear in the table.
Configure the action. Use the dropdowns to select an Action Type and its corresponding option.
Give it a custom name (optional, but helpful).
Click "Save Mapping Changes" at the bottom to store your setup.

OSC Looping: If you map a custom OSC command to a button, it will now automatically loop (Press = Start, Release = Stop). This is ideal for continuous commands like moving faders or encoders via OSC.

Quick Mapping & Attribute Control (Simultaneous Mode)

Simultaneous Mode allows you to control Pan/Tilt with the Right Stick while using the Left Stick for attributes like Zoom, Iris, or Focus.

The Quick Mapping Feature

The old "Set Axes" method has been replaced by Quick Mapping, a faster and more visual way to assign joystick axes.

1. Open Quick Mapping

You can open the Quick Mapping popup in two ways:

Bind a button: Map a controller button to the "Quick Mapping" Built-in action.
Web Remote Icon: Click the small "Quick Access" tool icon at the bottom of the Web Remote sidebar.

Note: The quick mapping popup only works in the Web Remote.

2. Assign Attributes

Once the popup is open:

Move an Axis: Move the joystick axis you want to assign (e.g., Left Stick Up/Down).
Select Attribute: A list appears. Click the attribute you want to control (e.g., Zoom).
Done! The axis is now mapped immediately.

Note: A preset is generated automatically. You must manually save it to keep it for future sessions.

Mapping Attributes to Buttons

You are no longer limited to joysticks for attributes. You can now map attributes directly to buttons (e.g., D-Pad Up for Zoom In, D-Pad Down for Zoom Out).

Direction: Choose Positive (+) or Negative (-).
Speed: Choose between Slow (precision) or Fast (coarse) movement.
Steps: Values change in steps of 1 for smooth digital control.

7. Settings & Customization

Settings → Control – joystick mode, invert buttons, slow/fast speed, boost multiplier.

Settings → Network – console type, OSC target IP/port, protocol (UDP/TCP), Web Remote login + zoom.

Settings → Axes Map – assign which stick/axis controls Pan/Tilt/Attributes (Simultaneous mode).

Settings → Attributes – manage custom attribute list (add/remove, combined attributes with +).

The Settings tab provides comprehensive control over FocusTool's behavior, from network configuration to movement sensitivity.

Movement & Control

Setting	Default Value	Description
Slow Speed	0.01	Base movement speed for precision work.
Fast Speed	0.05	Increased speed for quick movements.
Boost Multiplier	2.0	Speed increase when a boost button is held.
Joystick Mode	Individual	Choose between 'Individual' (Pan/Tilt only) and 'Simultaneous' (Pan/Tilt + Attributes).
Invert Pan / Tilt	Off	Reverse the movement direction for the respective axis.

Attribute Library (Simultaneous Mode)

This section is where you manage the list of attributes available for assignment to the joystick axes via Quick Mapping.

ChamSys Users: ChamSys consoles use a fixed attribute library that is read-only. Attributes are predefined by the ChamSys MagicQ console and cannot be added, removed, or modified in FocusTool. The attribute list is automatically populated with all available ChamSys attributes (Pan, Tilt, Zoom, Focus, Intensity, Color, Gobo, etc.) and is used directly in Quick Mapping and Controller Mapping.

Managing Your Attributes (grandMA2/MA3)

The Available Attributes list is your personal library of functions for grandMA2 and grandMA3 consoles.

Sorting: You can now Sort the attributes in this list for a better overview.
Add an Attribute: Type the grandMA3 attribute name (e.g., Shutter1) into the text box and click the '+' button.
Add Combined Attributes: To control multiple attributes at once, separate them with a + (e.g., Blade1A + Blade1B).
Remove an Attribute: Select an attribute from the list and click the '-' button.

This library populates the list used in the Quick Mapping popup.

8. Using FocusTool

Joystick Control Modes Explained

Individual Mode (Default)

Left Stick: Pan (X-axis)
Right Stick: Tilt (Y-axis)
Best for: Simple, direct Pan/Tilt control, similar to traditional console encoders.

Simultaneous Mode

Left Stick: Assigned Attribute (Y-axis) and Assigned Attribute (X-axis).
Right Stick: Pan + Tilt control.
Best for: Advanced users needing to adjust multiple parameters like Pan, Tilt, Zoom, and Focus at the same time.

On-the-Fly Workflow (Simultaneous Mode)

Using the new Quick Mapping feature, you can adapt your controller to the situation instantly:

Ensure you are in Simultaneous Mode.
Select your Fixtures using the Web Remote.
Trigger Quick Mapping: Press your mapped button or click the Quick Access icon in the Web Remote.
Move the Joystick Axis you want to assign (e.g., move Left Stick UP).
Select 'Zoom' from the popup list. The axis now controls Zoom immediately.
Repeat for other axes (e.g., Left Stick Left/Right for Focus).
Adjust your lights! You now have full control over Pan/Tilt (Right Stick) and Zoom/Focus (Left Stick).

9. Web Remote Integration

Launching Web Remote

Home tab – click "OPEN WEB REMOTE" to launch the Web Remote.

ChamSys Users: FocusTool does not include a built-in web remote for ChamSys consoles. Instead, ChamSys users need to use MagicQ on their handheld device alongside FocusTool. See the ChamSys Setup section for detailed setup instructions.

Ensure Web Remote settings are configured in the Settings tab (grandMA2/MA3 only).
Click "Open Webremote" on the Home tab (grandMA2/MA3 only).
A popup window opens (or a new browser tab on Linux when popups are disabled).

New Features:

Quick Access Icon: Located at the bottom of the sidebar, this opens the Quick Mapping popup.
Zoom Reset: Use the new buttons to quickly reset the Web Remote zoom level.

Steam Deck (SteamOS) Limitation: In Gaming Mode the Web Remote will not work. Switch to Desktop Mode to use the Web Remote and FocusTool reliably.

Linux / SteamOS: For compatibility, the integrated popup may be disabled and FocusTool will open the Web Remote in your default browser.

10. ChamSys Setup

Beta Feature: ChamSys support in FocusTool v0.0.7 is beta. We originally attempted to create an emulated MagicQ Remote app within FocusTool, but this approach was not reliable enough. Therefore, the MagicQ PC application is required on your handheld device and must be set up in session with the console as a remote viewer.

Overview

ChamSys MagicQ consoles work with FocusTool for joystick-based attribute control. To set up your ChamSys console for use with FocusTool, you need to download MagicQ and configure it on your handheld device.

Beta Status: Pan, Tilt, and other attribute control via joysticks works reliably.

Important - Fine Mode: Make sure Fine mode is disabled on your ChamSys console. Fine mode is not needed because FocusTool already sends 16-bit commands for precise attribute control.

Setup Process

Follow these steps to set up your ChamSys console with FocusTool:

Download MagicQ from the official ChamSys website (chamsys.co.uk/magicq).
Install and launch MagicQ on your handheld device.
Set up your handheld in session on the desk. Connect your handheld to the same network as your ChamSys console.
Choose Touch Interface in MagicQ settings to enable touch controls on your handheld device.
Configure OSC on the master desk (not on the handheld). On the master desk console, follow these steps as described in the Network Configuration section:
- Navigate to: Setup → Multi Console → Enable Remote Control and set it to [YES].
- Navigate to: Setup → Network.
- Enable both OSC TX and RX.
- Set TX & RX Port to the same port (e.g., 9000 or 9001).
- Set OSC Tx IP to 0.
Important: These OSC settings must be configured on the master desk console, not on your handheld device.
Configure FocusTool with your ChamSys console settings (see Network Configuration section for detailed OSC settings).

Setup Complete: Once MagicQ is configured on your handheld and OSC is enabled on the desk, you can use FocusTool for joystick control and attribute mapping. MagicQ on your handheld provides the full console interface for fixture selection, programming, and other advanced features.

Using MagicQ with FocusTool

After setup, you can use both applications together:

FocusTool: Handles joystick control, attribute mapping, and OSC commands for precise fixture control.
MagicQ: Provides fixture selection, programming interface, and console management on your handheld device.

Both applications communicate with your ChamSys console over the same network. Make sure both are configured correctly:

FocusTool: Configure the OSC Target IP and OSC Port in FocusTool's Settings tab (Network Configuration) to match your ChamSys console's IP address and the OSC port configured on the master desk. This allows FocusTool to send OSC commands to the ChamSys console.
ChamSys Console: Ensure OSC is properly configured on the master desk console according to the Network Configuration section (OSC TX and RX enabled, correct port settings, etc.).

OSC Limitations & Future Improvements

MagicQ currently does not provide sufficient OSC capabilities for certain commands. We hope that ChamSys will expand OSC support in the future, which would allow us to provide more comprehensive support for advanced features in FocusTool.

For commands like Highlight, Solo, or other advanced functions, you need to create a macro in MagicQ and trigger it via OSC from FocusTool. We highly recommend setting up these commands through FocusTool, as it significantly improves your workflow by keeping all controls accessible from your handheld device.

Custom Commands via Macros (e.g., Highlight)

To use commands like Highlight with FocusTool, you need to create a macro in MagicQ that can be triggered via OSC:

Step 1: Create the Macro in MagicQ

In MagicQ, navigate to: Macro → View Autom
Click Insert Autom to create a new automation
Set Type to: OSC Message
Set P1 to the OSC address you want to use, e.g.: /focustool/highlight
Set Function to: Run Macro
Set P2 to: F1 followed by your Macro ID (e.g., F1 1 for Macro 1)

Step 2: Configure FocusTool

In FocusTool, go to Controller Mapping
Select or add a button mapping
Set Action to: OSC
Enter the OSC address: /focustool/highlight
Save the mapping

When you press the mapped button, FocusTool sends the OSC message to MagicQ, which triggers the macro (e.g., Highlight).

Tip: You can create multiple macros for different functions (Solo, Lowlight, etc.) and trigger each one from a different button in FocusTool using unique OSC addresses.

11. Updates & Maintenance

About & Updates tab – version and update status / download button.

FocusTool includes a comprehensive update system to ensure you always have the latest features, bug fixes, and improvements.

Update Process

Navigate to About & Updates tab.
If an update is available, the "Download & Install Update" button will be enabled. Click it.
The update will download in the background (progress is shown on a progress bar).
Once downloaded, a popup will inform you that the application will close to run an update script.
After the updater finishes, you can start FocusTool again to use the new version.

Settings Preservation: Your custom mappings, network settings, and license are automatically preserved during updates.

12. Troubleshooting

This comprehensive troubleshooting section covers common issues and their solutions.

Controller Not Detected

🔌 Connection Issues

Symptoms: "Disconnected" status, no controller response.
Solutions:
• Ensure the handheld's controller is active and in Gaming Mode.
• Test the controller in other applications on the device.
• Restart FocusTool and your lighting console software.

OSC Communication Problems

🌐 No Response from Console

Symptoms: Commands appear in the log but no fixtures move.
Solutions:
• Verify OSC is enabled on the console with the correct IP and Port.
• Ensure your console user has rights to control attributes.
• Temporarily disable Windows Firewall to check if it's blocking communication.
• Restart your lighting console software. Sometimes the OSC service can hang.

Web Remote Popup doesn't work on Steam Deck

🖥️ Browser Fallback

Symptom: Clicking "Open Webremote" opens the system browser instead of a popup.
Solution:
• This is the expected and correct behavior on SteamOS/Linux for maximum compatibility. The functionality is the same.

My attribute is not available in Quick Mapping

📚 Missing from Library

Symptom: When opening Quick Mapping, your desired attribute is not in the list.
Solution:
• Go to the Settings tab and add the attribute to the "Available Attributes" list first. This list populates the Quick Mapping popup.

13. Support & Contact

How to contact us?

📧 Email

Contact: mitchel@yourld.nl

Before contacting us

To help us assist you more efficiently, please gather the following information:

FocusTool Version (from the 'About' tab)
License Email
Handheld Device Model (e.g., MSI Claw, Steam Deck)
Console Type & Software Version (e.g., grandMA3 onPC 1.9.7.0)
A clear description of the issue and any error messages.