Autoblow JS SDK

This is a guide for the Autoblow JS SDK. This SDK is used to control the Autoblow devices in a node environment or in the browser.

Installation

npm install @xsense/autoblow-sdk

Usage

import * as Autoblow from "@xsense/autoblow-sdk";

const { vacuglide, ultra, vacupump } = await Autoblow.deviceInit("YOUR_DEVICE_TOKEN");
//deviceInit returns an object for the connected device type and throws if the device is not connected

if (vacuglide) await demoVacuglide(vacuglide);
if (ultra) await demoUltra(ultra);
if (vacupump) await demoVacupump(vacupump);

async function demoVacuglide(vacuglide: Autoblow.Vacuglide) {
  const state = await vacuglide.getState();
  console.log(state);

  const deviceInfo = await vacuglide.getInfo();
  console.log(deviceInfo);

  //We can handle the button presses events and make our app react to them
  vacuglide.deviceEvents.addEventListener("mode-button-pressed", event => {
    console.log("mode-button-pressed");
  });
}

async function demoUltra(ultra: Autoblow.Ultra) {
  const state = await ultra.getState();
  console.log(state);

  const deviceInfo = await ultra.getInfo();
  console.log(deviceInfo);

  //We can handle the button presses events and make our app react to them
  ultra.deviceEvents.addEventListener("pause-button-pressed", event => {
    console.log("pause-button-pressed");
  });
}

async function demoVacupump(vacupump: Autoblow.Vacupump) {
  const deviceInfo = await vacupump.getInfo();
  console.log(deviceInfo);

  //We can follow the live state: the pump streams it while state updates are enabled
  vacupump.onStateUpdateEvent(state => {
    console.log(state.operationalMode, state.currentVacuumKpa);
  });
  await vacupump.stateUpdatesSet(true);

  //Hold a gentle vacuum for 10 seconds. Vacuum is in kPa and negative (-60 to 0)
  await vacupump.manualSetTarget(-10);
  await vacupump.manualStart();
  await new Promise(resolve => setTimeout(resolve, 10000));

  //Stopping Manual keeps the current vacuum, so release it first by targeting 0 kPa
  await vacupump.manualSetTarget(0);
  await new Promise(resolve => setTimeout(resolve, 3000));
  await vacupump.manualStop();
}

SDK Reference

Common Methods (Both Ultra and Vacuglide)

deviceInit(token: string): Promise<DeviceInitResult>

Initialize the connection to the given device token.

Returns:

{
  deviceInfo: DeviceInfo;
  deviceToken: string;
  deviceType: "autoblow-ultra" | "vacuglide" | "vacupump";
  ultra?: Ultra;
  vacuglide?: Vacuglide;
  vacupump?: Vacupump;
}

Throws:

• DeviceNotConnectedError if device is not connected

getInfo(): Promise<DeviceInfo>

Returns the device information.

getState(): Promise<DeviceState>

Returns the current device state.

getStateCache(): DeviceState | null

Returns the cached device state without making a network request.

getConnectedCluster(): string | null

Returns the connected cluster string or null if not connected.

estimateLatency(noOfRequests?: number): Promise<number>

Estimates the latency of the device by sending a number of requests and calculating the average latency. If no number of requests is given, the default is 10.

Local Script Methods

localScriptList(): Promise<number[]>

Returns the list of loaded local scripts.

localScriptReplace(replacedLocalScriptIndex: number, newLocalScriptId: number): Promise<number[]> (Ultra)

localScriptReplace(replacedLocalScriptIndex: number, newLocalScriptUuid: string): Promise<number[]> (Vacuglide)

Replaces the local script at the given index. The Ultra takes the new script’s numeric ID; the Vacuglide takes its UUID.

localScriptSwap(scriptIndexA: number, scriptIndexB: number): Promise<number[]>

Swaps two local scripts at the given indices.

localScriptMove(fromIndex: number, toIndex: number): Promise<number[]>

Moves a local script from one index to another.

localScriptStart(): Promise<DeviceState>

Starts the local script.

localScriptStop(): Promise<DeviceState>

Stops the local script.

Sync Script Methods

syncScriptLoadToken(token: string): Promise<DeviceState>

Loads the sync script with the given sync token.

syncScriptUploadFunscriptUrl(funscriptUrl: string): Promise<DeviceState>

Downloads the funscript from the given url, converts it to a binary script that autoblow can play and uploads it onto the device.

syncScriptUploadFunscriptFile(funscript: Funscript): Promise<DeviceState>

Uploads the given funscript onto the device. The funscript should be a Funscript object.

syncScriptUploadCsvUrl(csvUrl: string): Promise<DeviceState>

Downloads the csv file from the given url, converts it to a binary script that autoblow can play and uploads it onto the device.

syncScriptUploadCsvFile(csvContent: string): Promise<DeviceState>

Uploads the given csv script onto the device. The csv content should be a string.

syncScriptStart(startTimeMs: number): Promise<DeviceState>

Starts the sync script at the specified time in milliseconds.

syncScriptStop(): Promise<DeviceState>

Stops the sync script.

syncScriptOffset(offsetTimeMs: number): Promise<DeviceState>

Sets the sync script offset time in milliseconds.

syncScriptLoop(loop: boolean): Promise<DeviceState>

Turns looping of the loaded sync script on or off.

Firmware Methods

firmwareUpdateStart(): Promise<true>

Starts a firmware update process.

Throws:

• Error if firmware update fails

firmwareUpdateInfo(): Promise<FirmwareInfo>

Returns the newest firmware release the device would be offered. Also available on the VacuPump.

Throws:

• ValidationError if the device is already up to date

Ultra-Specific Methods

localScriptSet(localScriptIndex: number, speedIndex: number): Promise<UltraDeviceState>

Sets the local script to the given index and speed index.

oscillateSet(speed: number, minY: number, maxY: number): Promise<UltraDeviceState>

Sets the oscillation speed and the oscillation range.

oscillateStart(): Promise<UltraDeviceState>

Starts the oscillation.

oscillateStop(): Promise<UltraDeviceState>

Stops the oscillation.

goToPosition(position: number, speed: number): Promise<GenericResult>

Moves the device to a specific position at the given speed. This method sends PUT /autoblow/goto and resolves with { success: true } when accepted by the API. If you need movement status, call getState() separately.

Ultra Events

• speed-up-button-pressed
• speed-down-button-pressed
• mode-button-pressed
• pause-button-pressed

VacuPump Video Sync Methods

VacuPump firmware 1.01 and newer plays video sync scripts made of pressure exercises instead of funscripts. See the VacuPump API for the script format.

syncScriptSupported(): boolean

True when the connected firmware advertised the sync_script capability. Check it before showing sync features.

syncScriptLoadToken(token: string): Promise<VacupumpDeviceState>

Loads a stored script on the device without starting playback. Resolves after the device finished downloading.

syncScriptUploadExercises(exercises: VacupumpSyncScriptExercise[]): Promise<VacupumpDeviceState>

Stores the exercises under a new token and loads them on the device.

syncScriptStart(startTimeMs: number): Promise<VacupumpDeviceState>

Starts, resumes or seeks to a video position. Re-sending the current position to correct drift is safe.

syncScriptStop(): Promise<VacupumpDeviceState>

Pauses playback and releases the vacuum; the script stays loaded.

syncScriptOffset(offsetTimeMs: number): Promise<VacupumpDeviceState>

Sets the sync offset within ±10000 ms. Positive means the device runs ahead of the video.

Vacuglide-Specific Methods

localScriptSet(localScriptIndex: number): Promise<VacuglideDeviceState>

Sets the local script to the given index.

valveStrokePlusSet(valveState: boolean): Promise<VacuglideDeviceState>

Controls the stroke plus valve state. If the valveState is true, the valve will be opened. If the valveState is false, the valve will be closed.

valveStrokeMinusSet(valveState: boolean): Promise<VacuglideDeviceState>

Controls the stroke minus valve state. If the valveState is true, the valve will be opened. If the valveState is false, the valve will be closed.

targetSpeedSet(targetSpeed: number): Promise<VacuglideDeviceState>

Sets the target speed for the device in percent. The value should be between 0 and 100.

targetSpeedStop(): Promise<VacuglideDeviceState>

Stops the target speed mode.

Vacuglide Events

• speed-plus-button-pressed
• speed-minus-button-pressed
• mode-button-pressed

Types

DeviceInfo

type DeviceInfo = {
  firmwareVersion: number;
  firmwareBranch: string;
  hardwareVersion: string;
  firmwareStatus: "UP_TO_DATE" | "UPDATE_AVAILABLE" | "UPDATE_REQUIRED";
  mac: string;
  deviceType: "autoblow-ultra" | "vacuglide" | "vacupump";
};

UltraDeviceState

type UltraDeviceState = {
  operationalMode: UltraOperationalMode;
  localScript: number;
  localScriptSpeed: number;
  motorTemperature: number;
  oscillatorTargetSpeed: number;
  oscillatorLowPoint: number;
  oscillatorHighPoint: number;
  syncScriptCurrentTime: number;
  syncScriptOffsetTime: number;
  syncScriptToken: string;
  syncScriptLoop: boolean;
};

VacuglideDeviceState

type VacuglideDeviceState = {
  operationalMode: VacuglideOperationalMode;
  localScript: number;
  targetSpeed: number;
  strokePlusValve: boolean;
  strokeMinusValve: boolean;
  syncScriptCurrentTime: number;
  syncScriptOffsetTime: number;
  syncScriptToken: string;
  syncScriptLoop: boolean;
};

Funscript

type Funscript = {
  metadata: { id: number; version: number };
  actions: { at: number; pos: number }[];
};

FirmwareInfo

type FirmwareInfo = {
  branch: string;
  firmwareVersion: number;
  hardwareVersion: string;
};

Error Handling

The SDK provides several custom error types:

• DeviceNotConnectedError: Thrown when device is not connected
• DeviceNotInitializedError: Thrown when device is not initialized
• DeviceTimeoutError: Thrown when device request times out
• ValidationError: Thrown when request validation fails
• DeviceCommandResultError: Thrown when device command fails

Notes

• The SDK uses a task queue system to manage requests efficiently
• Device state is cached locally to improve performance
• All methods return promises and can be used with async/await
• Event listeners are available for real-time device button press events
• The SDK automatically handles device type detection and returns the appropriate device instance