Skip to main content
Version: 3.5.x

HTTP

By default, the HTTP service starts on: http://localhost:10000.

The port can be changed in the service's configuration.

Overview​

This section documents the HTTP routes exposed by the service.

All routes below assume the default base URL: http://localhost:10000.

Version​

Method: GET
URL: http://localhost:10000/version

Response example:

{
  "build_time": "2024-08-07T16:01:53Z",
  "git_branch": "main",
  "git_describe": "3.0.0-2-gce34c39e",
  "git_hash": "ce34c39e",
  "git_tag": "3.0.0",
  "project_name": "haply-inverse-service",
  "project_version": "3.0.0.0"
}

Devices​

Method: GET
URL: http://localhost:10000/devices

Returns the current device inventory, including config, state, and status.

Response example:

{
  "inverse3": [
    {
      "device_id": "04BA",
      "config": { "...": "..." },
      "state": { "...": "..." },
      "status": { "...": "..." }
    }
  ]
}

Force Scale​

Method: POST
URL: http://localhost:10000/force_scale

Body example:

{
  "force_scale": 0.5
}

Response example:

{
  "ok": true
}

Gravity Compensation​

Method: POST
URL: http://localhost:10000/gravity_compensation

Body example:

{
  "device_id": "049D",
  "enable": true,
  "gravity_scaling_factor": 0.8
}

Response example:

{
  "ok": true
}

Torque scaling​

Method: POST
URL: http://localhost:10000/torque_scaling

Body example:

{
  "device_id": "049D",
  "enable": true
}

Response example:

{
  "ok": true
}

Device Handedness​

Method: POST
URL: http://localhost:10000/device_handedness

Body example:

{
  "device_id": "049D",
  "handedness": "right"
}

Response example:

{
  "ok": true
}

Save Configuration​

Only works with Inverse3 devices. Warning: Avoid saving the configuration too often, since there is a limited number of save that can be applied to any given device.

Method: POST
URL: http://localhost:10000/save_configuration

Body example:

{
  "device_id": "049D"
}

Response example:

{
  "ok": true
}

Serial Enable​

Enable or disable all serial communication. When serial is disabled, it is impossible to send commands to the devices.

Method: POST
URL: http://localhost:10000/serial_enable

Body example:

{
  "enable": true
}

Response example:

{
  "ok": true
}

Settings​

Settings endpoints are auto-generated for:

  • Listing all settings (including metadata)
  • Reading a single setting value
  • Applying settings (single or batch)
  • Resetting a key to its default value

All settings key references can be found here

Routes​

MethodRouteDescription
GET/settings/Get all settings keys, values, and metadata.
POST/settings/Batch apply multiple settings at once.
GET/settings/{key}Get the current value of a specific setting key.
POST/settings/{key}Apply a new value to a specific key.
DELETE/settings/{key}Reset a key to its default value.

Response shape​

GET /settings/ (all settings)​

Returns an object keyed by setting key. Each entry includes:

  • value: the current value
  • metadata: type + constraints + lock state

Example entries:

{
  "devices/detection/timeout": {
    "metadata": {
      "constraint": {
        "range": {
          "max": 15,
          "min": 1,
          "step": 0
        }
      },
      "locked": false,
      "type_hint": "INT"
    },
    "value": 5
  }
}

GET /settings/{key} (single setting)​

Returns only the value (no metadata) for the requested key.

Applying settings​

POST /settings/ (batch apply)​

Batch apply multiple keys at once.

Suggested body format: a JSON object mapping keys → values.

{
  "devices/detection/timeout": 5,
  "devices/detection/advanced/wvg_description_filter": ["Haply USB Transceiver", "Haply Handle"]
}

POST /settings/{key} (single apply)​

Apply a new value to a single key.

Suggested body format: either a raw JSON value or a wrapped value (prefer wrapping for clarity).

{
  "value": 5
}

Resetting settings​

DELETE /settings/{key}​

Resets the key back to its default value.

This is equivalent to “reset to default”.

Type hints​

The service deduces type_hint automatically. GENERIC is used as a fallback for complex types.

Supported hints:

  • BOOL
  • INT
  • FLOAT
  • STRING
  • VEC2
  • VEC3
  • VEC4
  • TRANSFORM
  • ARR_INT
  • ARR_FLOAT
  • ARR_STRING
  • GENERIC