REST

The REST API allows you to send a set of tween instructions to a device. This is a good option if you want to send fewer requests that execute a program of pulses, turning on and off etc, or your platform can't do websockets.

To send a program to a device, simply send a GET request to: https://vibhub.io/api?id=<device_id>&type=<type>&data=<json_data_here>

(HTTP is also accepted but should only be used if your app can't use SSL)

Query params explained:

Param	Type	Explanation
id	string	The deviceID you want to run the program on
type	string	The task to send. See Tasks below.
data	varies	Depends on the type, see below.

Don't forget to URL encode.

Types

vib

The "vib" task expects data to be a URL encoded array of objects with the following params:

Param	Default	Required	Type	Explanation
stages	N/A	Yes	Array	An array of stage objects to be tweened beetween. See below for stage objects
repeats	0	No	integer	Nr times the animation should repeat. 0 plays it once, 1 plays it twice etc. Use -1 for infinity
port	0	No	integer	Bitwise combination of ports to run the program on. 0x1 is the first port, 0x2 second and so forth. 0 or negative values will target ALL ports. Most devices handle this as a 16bit signed int, so you can use up to 15 ports on a device.
highres	false	No	boolean	When set, we will use all supported bits in the program. Check the "h" response in whois for max nr of bits the device supports.

Stages

The stage is an object containing tweening information for that stage of the program. It has the following properties:

Param	Default	Type	Explanation
i	0	integer/obj/boolean	A value between 0 and 255. Higher value = faster vibrations. Or false to use the previous value. Or a RandObject (see below).
d	0	integer/obj	Time in milliseconds to reach specified intensity. 0 = instant. Or a RandObject (see below).
e	"Linear.None"	string	A string denoting the tween.js easing type. See this example for the supported types.
r	0	integer/object	Repeats. 0 = play this stage once, 1 = play this stage twice and so forth. Or a RandObject (see below)
y	false	boolean/truthy/falsy value	Go back and forth. Requires repeats to work. Repeats of 1 goes back and forth once, repeats of 3 goes back and forth twice etc. An even number such as 2 will go forth, back, forth, and then start at forth on the next stage.

RandObject

A RandObject can be used in certain places of a vib call. It'll generate a random value. This value will be randomized at the start of each program loop, but not program stage loop.

Param	Default	Type	Explanation
min	0	integer	Min value to randomize
max	varying	integer	Max value to randomize. The default value for this depends on the stage param you put it in. i=255, d=10000, r=9
offset	0	integer	Adds an offset to the randomly generated value. Useful in yoyo type steps where you always want an odd number of repeats (combine with multi of 2).
multi	1	integer	Multiplies the random value by this. Useful together with offset to generate pulses going up and down n times

Example:

{"min":0, "max":3, "offset":1, "multi":2}

This is useful in repeats with yoyo, as it always generates an odd number. In practice, the above line means "generate 1-4 pulses."

Examples

Run a program on device id "JasTestBullet". The program resets the vibration level to 0, then goes up to 50% and down again 3 times, then resets back to 0. Request:

GET https://vibhub.io/api/?id=JasTestBullet&type=vib&data=[{"stages":[{"i":0,"d":0},{"i":50,"d":500,"r":5,"y":1},{"i":0,"d":0}]}]

Response:

{"message":"OK","success":true}

whois

Lets you get meta information about a connected device:

Examples

Request: GET https://vibhub.io/api/?id=JasTestBullet&type=whois&data=[]

Response:

{"message":{"numPorts":4,"version":"0.3.0","hwversion":"esp32","custom":"","capabilities":{"p":true,"ps":true,"vib":"true"}},"success":true}