Haply Inverse SDK

Le Haply Inverse SDK est une interface indépendante du langage WebSocket + HTTP pour les appareils haptiques Haply — les Inverse3, Inverse3x, Minverse, VerseGrip et Wireless VerseGrip. Il s'exécute en tant que 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, de sorte que votre application n'a qu'à communiquer avec JSON via un socket.

Ses fonctionnalités comprennent :

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

Installation à l'aide du concentrateur Haply

La manière la plus simple de commencer est d'utiliser le Haply Hub, une application de bureau permettant d'installer, d'exécuter, de configurer, de tester et de surveiller vos appareils Haply. Elle assure la mise à jour du micrologiciel, intègre le service Inverse et propose des démonstrations qui vous permettent de vérifier votre matériel avant d'écrire la moindre ligne de code.

Hub Haply

Télécharger la dernière version de l'Haply Hub

Téléchargez et installez le Hub, connectez 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 chaque fois que le Hub est ouvert.

Vous préférez une installation autonome ?

Vous pouvez également installer une version spécifique d'Inverse Service 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 à force nulle pour que le service continue à diffuser les 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é)

En utilisant Glaze — l'une des bibliothèques JSON les plus rapides au monde — pour la réflexion à la compilation. Aux fréquences haptiques (de l'ordre de plusieurs kHz), chaque microseconde consacrée à l'analyse du JSON est une microseconde volée à la boucle de contrôle, d'où l'importance de ce point. 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(())
}

attention

Modifiez les valeurs de force avec prudence. Des valeurs de force élevées et soudaines peuvent endommager l'appareil ou entraîner un comportement inattendu.

info

Consultez la page « Conventions JSON » pour en savoir plus sur l'enveloppe des messages, les ports et les règles relatives au type de contenu.

Plus d'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-appareils, de la configuration du montage et du repère de base, ainsi que du flux d'événements — consultez la page Tutoriels.