Haply Inverse SDK

Le Haply Inverse SDK est une interface WebSocket + HTTP indépendante du langage permettant de communiquer avec les appareils Haply — l’ Inverse3, Inverse3x, Minverse, VerseGrip et Wireless VerseGrip. Il fonctionne comme un service local qui gère la détection des appareils, la communication série, la surveillance de la sécurité et la diffusion de l'état — votre application n'a donc qu'à communiquer en JSON via un socket.

Ses fonctionnalités sont les suivantes

• Détection et gestion des appareils — répertorie et configure automatiquement Haply connectés via une API REST HTTP.
• Diffusion en temps réel de l'état des appareils — transmet l'état des appareils à la fréquence des commandes haptiques (plusieurs kHz) via WebSockets.
• Traitement des commandes — exécute les commandes de force et de position avec une grande précision pour offrir un retour haptique précis.
• Fonctionnement en arrière-plan — s'exécute en tant que service local, assurant la disponibilité des appareils sans intervention de l'utilisateur.

Installer avec le Haply

Le moyen le plus simple de commencer est le Haply , une application de bureau qui vous permet d'installer, d'exécuter, de configurer, de tester et de surveiller vos Haply . Elle maintient le micrologiciel à jour, intègre le service Inverse et fournit des démos afin que vous puissiez vérifier votre matériel avant d'écrire la moindre ligne de code.

Hub Haply

Télécharger la dernière version du Haply Hub

Téléchargez et installez le Hub, branchez votre appareil, et le Hub vous guidera tout au long des mises à jour du micrologiciel. Une fois installé, le service Inverse s'exécute automatiquement en arrière-plan dès que le Hub est ouvert.

Vous préférez une installation autonome ?

Vous pouvez également installer une version spécifique du service Inverse en tant que service système (Windows) ou démon (Linux / macOS) sans passer par le Hub. Consultez la section « Exécution du service » pour obtenir le lien vers le programme d'installation et les instructions.

Exemple rapide

Connectez-vous au service, lisez la position du curseur du premier Inverse3, puis envoyez un message de maintien de connexion sans charge afin que le service continue à diffuser des trames d'état :

Python

import asyncio, json, websockets

async def main():
    # Connect to the Haply Inverse service WebSocket
    async with websockets.connect("ws://localhost:10001") as ws:
        # Read the first state frame to discover the device id
        first_state = json.loads(await ws.recv())
        device_id = first_state["inverse3"][0]["device_id"]

        # Build a zero-force keepalive command targeting that device
        keepalive = {"inverse3": [{
            "device_id": device_id,
            "commands": {"set_cursor_force": {"vector": {"x": 0, "y": 0, "z": 0}}}
        }]}

        # Realtime loop: one send per tick, then read the resulting state
        while True:
            await ws.send(json.dumps(keepalive))
            state = json.loads(await ws.recv())
            pos = state["inverse3"][0]["state"]["cursor_position"]
            print(f"pos: {pos}")

asyncio.run(main())

JavaScript (Node)

import WebSocket from 'ws'

// Connect to the Haply Inverse service WebSocket
const ws = new WebSocket('ws://localhost:10001')
let keepalive

ws.on('message', (msg) => {
  const state = JSON.parse(msg)
  if (!keepalive) {
    // Read the first state frame to discover the device id
    const deviceId = state.inverse3[0].device_id
    // Build a zero-force keepalive command targeting that device
    keepalive = JSON.stringify({
      inverse3: [
        {
          device_id: deviceId,
          commands: { set_cursor_force: { vector: { x: 0, y: 0, z: 0 } } },
        },
      ],
    })
    ws.send(keepalive)
    return
  }
  // Realtime loop: one send per tick, then read the resulting state
  ws.send(keepalive)
  console.log('pos:', state.inverse3[0].state.cursor_position)
})

C++ (nlohmann)

#include <external/libhv.h>
#include <nlohmann/json.hpp>

int main() {
    hv::WebSocketClient ws;
    nlohmann::json keepalive;

    ws.onmessage = [&](const std::string& msg) {
        auto state = nlohmann::json::parse(msg);
        if (keepalive.is_null()) {
            // Read the first state frame to discover the device id
            auto device_id = state["inverse3"][0]["device_id"];
            // Build a zero-force keepalive command targeting that device
            keepalive = {{"inverse3", nlohmann::json::array({{
                {"device_id", device_id},
                {"commands", {{"set_cursor_force",
                    {{"vector", {{"x", 0}, {"y", 0}, {"z", 0}}}}}}}
            }})}};
            ws.send(keepalive.dump());
            return;
        }
        // Realtime loop: one send per tick, then read the resulting state
        ws.send(keepalive.dump());
        auto pos = state["inverse3"][0]["state"]["cursor_position"];
        std::cout << "pos: " << pos << "\n";
    };
    // Connect to the Haply Inverse service WebSocket
    ws.open("ws://localhost:10001");
    std::cin.get();
}

C++ (optimisé)

Utilisation de Glaze — l'une des bibliothèques JSON les plus rapides au monde — pour la réflexion à la compilation. À des fréquences tactiles (plusieurs kHz), chaque microseconde consacrée à l'analyse de JSON est une microseconde soustraite à la boucle de contrôle ; c'est donc un aspect crucial. Déclarez la structure minimale que vous lisez et écrivez ; le reste est ignoré.

#include <external/libhv.h>
#include <glaze/glaze.hpp>

struct vec3 { float x{}, y{}, z{}; };
struct inverse_state { vec3 cursor_position; };
struct inverse_device { std::string device_id; inverse_state state; };
struct devices_message { std::vector<inverse_device> inverse3; };

struct set_cursor_force_cmd { vec3 vector; };
struct device_cmd { std::string device_id;
    struct { std::optional<set_cursor_force_cmd> set_cursor_force; } commands; };
struct commands_message { std::vector<device_cmd> inverse3; };

int main() {
    hv::WebSocketClient ws;
    commands_message keepalive;
    ws.onmessage = [&](const std::string& msg) {
        devices_message state{};
        if (glz::read_json(state, msg)) return;
        if (keepalive.inverse3.empty()) {
            // Read the first state frame to discover the device id
            auto device_id = state.inverse3[0].device_id;
            // Build a zero-force keepalive command targeting that device
            keepalive.inverse3.push_back({device_id});
            keepalive.inverse3[0].commands.set_cursor_force = set_cursor_force_cmd{};
            std::string out; (void)glz::write_json(keepalive, out);
            ws.send(out);
            return;
        }
        // Realtime loop: one send per tick, then read the resulting state
        std::string out; (void)glz::write_json(keepalive, out);
        ws.send(out);
        printf("pos: %f %f %f\n", state.inverse3[0].state.cursor_position.x,
               state.inverse3[0].state.cursor_position.y,
               state.inverse3[0].state.cursor_position.z);
    };
    // Connect to the Haply Inverse service WebSocket
    ws.open("ws://localhost:10001");
    std::cin.get();
}

Rouille

Exemple illustratif utilisant tokio-tungstenite + serde_json.

use futures_util::{SinkExt, StreamExt};
use serde_json::json;
use tokio_tungstenite::{connect_async, tungstenite::Message};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Connect to the Haply Inverse service WebSocket
    let (mut ws, _) = connect_async("ws://localhost:10001").await?;

    // Read the first state frame to discover the device id
    let first = match ws.next().await {
        Some(Ok(Message::Text(m))) => m,
        _ => anyhow::bail!("no initial state frame"),
    };
    let first_state: serde_json::Value = serde_json::from_str(&first)?;
    let device_id = first_state["inverse3"][0]["device_id"].as_str().unwrap();

    // Build a zero-force keepalive command targeting that device
    let keepalive = json!({
        "inverse3": [{
            "device_id": device_id,
            "commands": { "set_cursor_force": { "vector": { "x": 0, "y": 0, "z": 0 } } }
        }]
    }).to_string();

    // Realtime loop: one send per tick, then read the resulting state
    loop {
        ws.send(Message::Text(keepalive.clone())).await?;
        let msg = match ws.next().await {
            Some(Ok(Message::Text(m))) => m,
            _ => break,
        };
        let state: serde_json::Value = serde_json::from_str(&msg)?;
        println!("pos: {}", state["inverse3"][0]["state"]["cursor_position"]);
    }
    Ok(())
}

avertissement

Modifiez les valeurs de force avec précaution. Des valeurs de force élevées appliquées brusquement peuvent endommager l'appareil ou entraîner un comportement inattendu.

info

Consultez la page « Conventions JSON » pour connaître les règles relatives à l'enveloppe du message, aux ports et au type de contenu.

Autres exemples

Pour des tutoriels complets sur Python, C++ (nlohmann) et C++ (Glaze) — traitant du retour de force, du contrôle de position, des configurations multi-périphériques, de la configuration des supports et des bases, ainsi que de la diffusion d'événements —, consultez la page Tutoriels.