Set Input State on a Mapping in a Control Scheme

Expert Topic for experienced builders.

Big idea

Sets the input value of a mapping in a control scheme that has had its input type set to “REST API.”

In order to not require you to carefully monitor when you stream out data to be recorded, this API call is fairly permissive, and will not return an error if it receives an unknown identifier or receives data while not actively recorded. However, a warning will be added to the hardware log for each set input request that Bottango is unable to process when received. If you’re not seeing input come in the way you would expect, check the log and see if Bottango was unable to process the request.

Each request requires both an identifier and a value. When you create a mapping in a control scheme, and select “REST API” as the input type, in the configuration options for that mapping, you can enter a string identifier in the Bottango app. This defaults to “myIdentifier” but you can use any unique string you’d like for each mapping. Colliding identifiers are allowed, and if multiple mappings have the same identifier, each will be controlled by the incoming value independently.

Value should be a float between 0.0 and 1.0. Any value outside of that range or non float value will return an error. The parsing of the float value depends on the kind of part being controlled:

• Movement based parts (joints, motors, an axis of a pose blends, a color channel of a color event, etc) will 1:1 map the float to the expected movement of the part. 0.0 being the minimum range of motion and 1.0 the maximum.
• On Off events will treat any non 0.0 value that is less than 1.0 as on, and will treat 0.0 as off.
• Trigger events will treat any non 0.0 value that is less than 1.0 as a trigger event for each request received. 0.0 will be ignored.

You will only see the result of this control while actively recording (or in snapshot recording). While not recording, Bottango will ignore these requests, but not return an error as discussed above. After recording is complete, the collected input requests will be converted into keyframes on the animation timeline, the same as input from a gamepad, etc.

Caution

Heads up! The REST API runs on HTTP, with all the latency that implies. High throughput input streaming is not likely with this request, so manage your expectations. A higher throughput comms type is planned for input streaming in the future.

API

URI (PUT)

/ControlInput/

Request Parameters

string identifier
float value

Response Parameters

none

Example

Example_SetLiveControlInput.py

import requests
import json

port = 59224
baseUrl = 'http://localhost:{}/'.format(port)


requestUrl = baseUrl + 'ControlInput/'
try:
  requestParams = {}

  # set identifier for recording input
  requestParams['identifier'] = 'myIdentifier'    # Required, provide the string identifier for the input as set up in the input settings menu


  # set the current input value
  requestParams['value'] = 0.5            # Required, the value to set on the recording control
                            # Movement parts (Joint, Motor, pose blend axis, etc) expect a value between 0.0 and 1.0
                            # On Off events treat any non 0.0 value less than or equal to 1.0 as on, and 0.0 as off
                            # Trigger events treat any non 0.0 value less than or equal to 1.0 as a new trigger



  response = requests.put(requestUrl, json=requestParams)
  response.raise_for_status()

except requests.exceptions.RequestException as e:
  raise SystemExit(e)