Skip to content

REST API

What is it?

A REST API is a way to communicate with the ESP devices using HTTP requests. This is useful if you want to control the device from a computer or a mobile device.

We developed a REST API for this project so that we can control the devices more easily from our new app.

How to use it

REST API Client

Any REST API client can be used to communicate with the ESP devices. We recommend using Thunder Client to test the REST API, as it's free and is a vscode extension.

For basic GET requests, you can use your browser of choice.

Standard

The REST API follows the following standard:

txt
http://{device_name}.local:81/control/builtin/command/{endpoint}?{param}={value}&{param}={value}

For example, if the name of the device is esp32, you can connect to the device using http://esp32.local:81/control/builtin/command/<endpoint>.

Endpoints

Note

Any endpoint marked with ** is currently not implemented, and will be implemented in the future.

If you would like to help us implement these endpoints, please contact us.

We are also open to suggestions for new endpoints.

Note: Any endpoint that makes changes to the config will require a call to /save to write the changes to the flash. This is to prevent the flash from being written to too often, which can cause the flash to wear out. The device will write the changes to the flash and then restart itself after a call to /save.

The REST API has the following endpoints:

EndpointMethodDescription
/pingGETReturns the status of the device.
/saveGETWrites any changes to the flash.
/restartDeviceGETRestarts the ESP itself.
/restartCameraGETRestarts the camera.
/resetConfigGETClears the current config in memory and RAM
/getStoredConfigGETReturns a JSON object of the devices current config.
/setTxPowerPOSTSets the Transmission Power of the ESPs
/setDevicePOSTSets the OTA and mDNS settings
/setCameraPOSTSets all of the camera settings
/wifiPOSTAdds a new wifi network, or writes over an existing one
/wifiDELETEDeletes a wifi network **

Note

/wifi uses the POST method to add a new wifi network, and the DELETE method to delete a wifi network.

Params

The REST API has the following params:

Feature not a bug

All params for a given URL are required, even if you are not changing that params value.

If you do not supply a param, that param will be set to default settings.

URL params are passed in the URL as a query string, using the following format:

http://<device_name>.local:81/control/builtin/command/<endpoint>?<param>=<value>&<param>=<value>

/wifi

Note

We allow you to store up to 3 wifi networks in memory. If you try to add more than 3, the oldest network will be overwritten.

ParamDescription
ssidThe ssid of the network.
passwordThe password of the network.
networkNameThe unique name (given by you) to refer to that network in memory.
channelThe channel for the wifi network to broadcast on
only 1 - 14 are allowed.
powerThe Transmittion power of the ESP for that network config.
adhocWhether to enable AP mode or not.

Note - Transmission Power

You must follow the following format for the power param:

Using the following enum, you pass the number to the right of the = sign that corresponds with the power in dBm that you wish to use.

cpp
typedef enum {
    WIFI_POWER_19_5dBm = 78,// 19.5dBm
    WIFI_POWER_19dBm = 76,// 19dBm
    WIFI_POWER_18_5dBm = 74,// 18.5dBm
    WIFI_POWER_17dBm = 68,// 17dBm
    WIFI_POWER_15dBm = 60,// 15dBm
    WIFI_POWER_13dBm = 52,// 13dBm
    WIFI_POWER_11dBm = 44,// 11dBm
    WIFI_POWER_8_5dBm = 34,// 8.5dBm
    WIFI_POWER_7dBm = 28,// 7dBm
    WIFI_POWER_5dBm = 20,// 5dBm
    WIFI_POWER_2dBm = 8,// 2dBm
    WIFI_POWER_MINUS_1dBm = -4// -1dBm
} wifi_power_t;

/setDevice

ParamDescription
hostnameThe hostname for the ESP
used by OTA and mDNS.
serviceThe service to look for when scanning mDNS devices on the network
this should be set to openiristracker in order to look for EyeTrackVR devices
ota_passwordThe password for the OTA service.
ota_portThe port for the OTA service.
firmware_nameThe name of the binary file for OTA
depricated and will be removed

/setTxPower

Note

You must follow the following format for the txPower param:

Using the following enum, you pass the number to the right of the = sign.

cpp
typedef enum {
    WIFI_POWER_19_5dBm = 78,// 19.5dBm
    WIFI_POWER_19dBm = 76,// 19dBm
    WIFI_POWER_18_5dBm = 74,// 18.5dBm
    WIFI_POWER_17dBm = 68,// 17dBm
    WIFI_POWER_15dBm = 60,// 15dBm
    WIFI_POWER_13dBm = 52,// 13dBm
    WIFI_POWER_11dBm = 44,// 11dBm
    WIFI_POWER_8_5dBm = 34,// 8.5dBm
    WIFI_POWER_7dBm = 28,// 7dBm
    WIFI_POWER_5dBm = 20,// 5dBm
    WIFI_POWER_2dBm = 8,// 2dBm
    WIFI_POWER_MINUS_1dBm = -4// -1dBm
} wifi_power_t;
ParamDescription
txPowerThe power level to set.

Camera Params

ParamDescriptionValue Effect
vflipWhether to flip the frames vertically.0 or 1
framesizeA value between 0-7 indicating the frame resolution.Larger number - higher resolution.
hflipWhether to flip the frames horizontally.0 or 1
qualityThe JPEG quality level: 1-63?Smaller number = higher quality, more latency and less fps
brightnessThe agc_gain of the camera.Larger number = more bright.

Released under the MIT License.