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. |
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}