X1 API Documentation

The X1 API provides an Inter-Process Communication (IPC) interface allowing third-party scripts/applications (e.g. Python, AutoHotkey) to send commands to the mouse via the X1 Control Panel.

The API is disabled by default. To use it, toggle "Enable X1 API" in the X1 options menu and restart the application to initialize the interface.

Depending on your operating system, connect to the following local endpoint:

Windows	Linux/macOS
\\.\pipe\swiftpoint.x1.v2.command	/tmp/swiftpoint.x1.v2.command

The interface follows a request-response pattern. For every command sent, the API will return one of the following:

1. OK: The command was executed successfully.
   
2. ERR <reason>: The command failed (e.g., ERR Invalid Argument).
   
3. A command specific response (eg. Profile Get, Profile List)

Commands:

The following commands are available in X1 API v2, introduced in X1 Control Panel 3.1.0.0. 

Command	Parameters	Description
Profile	Set <Name>	Switches to the specified profile (max 18 chars).
	Get	Returns the active profiles name.
	List	Returns a List of all X1 profiles, separated by newline character.
Vibrate	[Duration] [Strength]	Triggers haptic feedback. Duration in ms (default 70), Strength 0-100 (default 100).
DPI	[XValue] [YValue]	Sets mouse DPI to chosen value (rounded to supported DPI step). YValue parameter is optional.
IMU	Zero	Re-zeroes IMU's Pitch, Roll, and Yaw values.
RGB	Fixed #RRGGBB	Sets a static LED color using a hex code.
	HueRotation [Brightness] [Duration]	Starts a color cycle. Brightness (0-255), Duration in ms (0-65535).
	Off	Disables the LED.
	Override <True | False>	Set RGB Override to True to lock RGB state to the next RGB command you send.  Set RGB Override back to False to allow profiles and mappings to alter RGB mode.
OLED	Image <hex_data>	Displays a custom image. Requires 512 hex characters (256 bytes).
	Message <Text>	Displays a text string on the OLED (max 19 chars).
	<Blank | DPI | Profile | Force | Angles | Cube | Firmware | Battery>	Switches OLED to specific UI modes.
	Override <True | False>	Set OLED Override to True to lock OLED state to the next OLED command you send.  Set OLED Override back to False to allow profiles and mappings to alter OLED mode.

Example Scripts:

Sending Commands with AutoHotkey (Windows)

The following example function sends a command and reads the response. If the response is an error, it is displayed in a messagebox.

Check the "Example SendCommand Usage" section below for examples of how this can be used.

1. #Requires AutoHotkey v2.0
2. SendCommand(Command) {
   
3.     ; 1. Open pipe with Read/Write access (0xC0000000)
   
4.     hPipe := DllCall("CreateFile", "Str", "\\.\pipe\swiftpoint.x1.v2.command", "UInt", 0xC0000000, "UInt", 0, "Ptr", 0, "UInt", 3, "UInt", 0, "Ptr", 0, "Ptr")
   
5.     
   
6.     if (hPipe = -1) {
   
7.         ToolTip('Could not connect to the X1 API pipe.')
   
8.         SetTimer(() => ToolTip(), -3000)
   
9.         return
   
10.     }
    
11. 
    
12.     ; 2. Write the command
    
13.     buf := Buffer(StrPut(Command, "UTF-8"))
    
14.     StrPut(Command, buf, "UTF-8")
    
15.     DllCall("WriteFile", "Ptr", hPipe, "Ptr", buf.Ptr, "UInt", buf.Size - 1, "UIntP", &bytesWritten := 0, "Ptr", 0)
    
16. 
    
17.     ; 3. Read the response
    
18.     resBuf := Buffer(1024, 0)
    
19.     response := ""
    
20.     if DllCall("ReadFile", "Ptr", hPipe, "Ptr", resBuf.Ptr, "UInt", resBuf.Size, "UIntP", &bytesRead := 0, "Ptr", 0) {
    
21.         response := StrGet(resBuf, bytesRead, "UTF-8")
    
22.         
    
23.         ; 4. Only show MsgBox if response is NOT "OK" (ignoring the newline)
    
24.         if (Trim(response, " `n`r") != "OK") {
    
25.             MsgBox("API Error/Response: " . response)
    
26.         }
    
27.     }
    
28. 
    
29.     ; 5. Clean up
    
30.     DllCall("CloseHandle", "Ptr", hPipe)
    
31.     
    
32.     return response
    
33. }

Use the SendCommand function above to change mouse profile on keyboard key press and release.

1. ; On Left Shift Press, change profile to "Desktop-Shift". Then On Left Shift Release change profile to "Desktop"
2. *LShift:: {
   
3.     SendCommand("Profile Desktop-Shift")
   
4.     KeyWait "LShift"
   
5.     SendCommand("Profile Desktop")
   
6. }

Use the SendCommand function above to set DPI when a key is pressed, then change it back when it's released.

1. ; On F6 Press, change to DPI to 400. Then On F6 Release change DPI to 800
   
2. F6:: {
   
3.     SendCommand("DPI 400")
   
4.     KeyWait "F6"
   
5.     SendCommand("DPI 800")
   
6. }
   

Sending Commands with Python (Windows)

The following example function sends a command and reads the response.

Check the "Example SendCommand Usage" section below for examples of how this can be used.

1. import os
   
2. 
   
3. def SendCommand(command):
   
4.     pipe_path = r'\\.\pipe\swiftpoint.x1.v2.command'
   
5.     
   
6.     # Open the pipe for reading and writing
   
7.     pipe = os.open(pipe_path, os.O_RDWR)
   
8.     
9.     # Send the command
   
10.     os.write(pipe, (command + "\n").encode("utf-8"))
    
11.     
12.     # Read the response (1024 bytes)
    
13.     response_bytes = os.read(pipe, 1024)
    
14.     response = response_bytes.decode("utf-8").strip()
    
15.     print(response)
    
16.     
17.     os.close(pipe)
    

Sending Commands with Python (Linux/macOS)

The following example function sends a command and reads the response.

Check the "Example SendCommand Usage" section below for examples of how this can be used.

1. import socket
   
2. 
   
3. def SendCommand(command):
   
4.     # Standard Unix socket path
   
5.     socket_path = "/tmp/swiftpoint.x1.v2.command"
   
6.     
   
7.         # Create a Unix domain stream socket
   
8.         sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
   
9.         
   
10.         # Connect to the socket
    
11.         sock.connect(socket_path)
    
12.         
    
13.         # Send the command with a newline terminator
    
14.         sock.sendall((command + "\n").encode("utf-8"))
    
15.         
    
16.         # Receive the response
    
17.         response_bytes = sock.recv(1024)
    
18.         response = response_bytes.decode("utf-8").strip()
    
19.         print(response)
    
20.         
    
21.         sock.close()
    

Example SendCommand Usage

Once you've defined the SendCommand function in AutoHotKey or Python as shown above. You can use it to send commands in the format below. 

1. SendCommand("Profile Desktop")
2. SendCommand("Vibrate 70 100")
3. SendCommand("DPI 800")
4. SendCommand("RGB Fixed #00FF00")
5. SendCommand("RGB HueRotation 255 50")
6. SendCommand("RGB Override True")
7. SendCommand("OLED Message Hello World!")
8. SendCommand("OLED Battery")
9. SendCommand("OLED Override True")

OLED Image Command Notes and Examples

The OLED Image command works a bit differently to the other OLED modes. So there are a few things you should note when using it.

The image data sent to the mouse is only stored in the OLED's display buffer. So it's lost as soon as anything else is written into the display buffer. For example if a mouse mapping triggers an OLED command, or if the current display mode refreshes (Tilt/Force levels change).

So if you want your custom image to persist "OLED Override" must be set to True before sending the image data. This will display the image until the override is disabled, or the mouse is switched off. Even other OLED mode changes sent through the API will be ignored.

The OLED display draws far more power than any other component in the mouse. And the more lit pixels the more power it consumes.

So displaying an image with many white pixels will have a significant effect on the Z3 battery life. Leaving a static image on the display for long duration's will also eventually lead to burn in.

For these reasons it's recommended not to permanently display a static image on the OLED using this command.

Example OLED Image usage with the SendCommand function defined above:

Clear the display without disabling override:

SendCommand("OLED Image 0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000A000000000000000000000000000000000000000000000")

Display Swiftpoint Logo:

SendCommand("OLED Image 000000000000000000000000000000000000001f80000000000000fff0000000000003fffc000000000007fffe00000000000fffff00000000001fffff80000000003fffffc0000000003fffffc0000000007fe7ffe0000000007fe1ffe0000000007ff1ffe000000000ffe07ff000000000fff03ff000000000ffe01ff000000000ffe00ff000000000fff007f0000000007fe003e000000000ffe001e0000000007ff01fe0000000007fe01fe0000000003ff20fc0000000003fe60fc0000000001fff0780000000000fff87000000000007ff82000000000003ff80000000000000ffc00000000000001f4000000000000000000000000000000000000000")

• Related Articles

• Swiftpoint X1 Control Panel Beta Changelog

  3.1.0.76 Beta New Control Panel Features: Allows re-arranging and saving of mappings from simple modes show all view. Note that some mappings can't be moved (RGB, OLED, DPI). Warnings are displayed when swapping mappings between incompatible inputs, ...

• How to use the Z's Tilt and Pivot inputs for analog joystick control

  The Z operates as a DirectInput joystick. So its joystick outputs will only work natively in games with support for DirectInput. For games that only support XInput a third-party utility is required to translate DirectInput to XInput (e.g. X360ce). To ...

• Creating an Autoclicker

  One of the most popular requests we get with the X1 Control Panel is how to create an autoclicker macro, as shown in this video. You can also find a guide to this configuration on our YouTube channel here This is a brief guide on how to set that up ...

• Introduction to the Swiftpoint X1 Control Panel

  Intro The X1 Control Panel provides an easy-to-use interface for configuring mice in our Classic-grip Range. These include: Z, Z2 and Z3 Creator Tracer Installing the X1 Control Panel If you do not already have it installed, it is available for macOS ...

• X1 Control Panel Expert Mode Overview

  Welcome to the X1 Control Panels Expert Mode. The X1 Control Panel’s "Expert Mode" offers a more detailed and highly configurable interface, particularly useful for the creation of more complex profile mappings. Despite its name, Expert Mode is not ...