EyeTrackVR-Docs/assets/firmware_guide_rest_api.md.302dda8a.lean.js
2025-05-31 01:42:54 +00:00

28 lines
22 KiB
JavaScript
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

import{_ as t,o as s,c as a,O as n}from"./chunks/framework.ece1a6f0.js";const h=JSON.parse('{"title":"REST API","description":"","frontmatter":{},"headers":[],"relativePath":"firmware_guide/rest_api.md","filePath":"firmware_guide/rest_api.md","lastUpdated":1718649805000}'),l={name:"firmware_guide/rest_api.md"};function o(r,e,p,c,i,d){return s(),a("div",null,e[0]||(e[0]=[n(`<h1 class="text-[var(--font-accent)]" id="rest-api" tabindex="-1">REST API <a class="header-anchor" href="#rest-api" aria-label="Permalink to &quot;REST API {.text-[var(--font-accent)]}&quot;"></a></h1><h2 id="what-is-it" tabindex="-1">What is it? <a class="header-anchor" href="#what-is-it" aria-label="Permalink to &quot;What is it?&quot;"></a></h2><p>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.</p><p>We developed a REST API for this project so that we can control the devices more easily from our new app.</p><h2 id="how-to-use-it" tabindex="-1">How to use it <a class="header-anchor" href="#how-to-use-it" aria-label="Permalink to &quot;How to use it&quot;"></a></h2><h3 id="rest-api-client" tabindex="-1">REST API Client <a class="header-anchor" href="#rest-api-client" aria-label="Permalink to &quot;REST API Client&quot;"></a></h3><p>Any REST API client can be used to communicate with the ESP devices. We recommend using <a href="https://www.thunderclient.com/" target="_blank" rel="noreferrer">Thunder Client</a> to test the REST API, as it&#39;s free and is a vscode extension.</p><p>For basic <code>GET</code> requests, you can use your browser of choice.</p><h3 id="standard" tabindex="-1">Standard <a class="header-anchor" href="#standard" aria-label="Permalink to &quot;Standard&quot;"></a></h3><p>The REST API follows the following standard:</p><div class="language-txt line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">txt</span><pre class="shiki material-theme-palenight"><code><span class="line"><span style="color:#babed8;">http://{device_name}.local:81/control/builtin/command/{endpoint}?{param}={value}&amp;{param}={value}</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br></div></div><blockquote><p>For example, if the name of the device is <code>esp32</code>, you can connect to the device using <code>http://esp32.local:81/control/builtin/command/&lt;endpoint&gt;</code>.</p></blockquote><h3 id="endpoints" tabindex="-1">Endpoints <a class="header-anchor" href="#endpoints" aria-label="Permalink to &quot;Endpoints&quot;"></a></h3><div class="info custom-block"><p class="custom-block-title">Note</p><p>Any endpoint marked with <code>**</code> is currently not implemented, and will be implemented in the future.</p><p>If you would like to help us implement these endpoints, please contact us.</p><p>We are also open to suggestions for new endpoints.</p><blockquote><p><strong>Note</strong>: Any endpoint that makes changes to the config will require a call to <code>/save</code> 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 <code>/save</code>.</p></blockquote></div><p>The REST API has the following endpoints:</p><table><thead><tr><th style="text-align:center;">Endpoint</th><th style="text-align:center;">Method</th><th style="text-align:center;">Description</th></tr></thead><tbody><tr><td style="text-align:center;">/ping</td><td style="text-align:center;">GET</td><td style="text-align:center;">Returns the status of the device.</td></tr><tr><td style="text-align:center;">/save</td><td style="text-align:center;">GET</td><td style="text-align:center;">Writes any changes to the flash.</td></tr><tr><td style="text-align:center;">/restartDevice</td><td style="text-align:center;">GET</td><td style="text-align:center;">Restarts the ESP itself.</td></tr><tr><td style="text-align:center;">/restartCamera</td><td style="text-align:center;">GET</td><td style="text-align:center;">Restarts the camera.</td></tr><tr><td style="text-align:center;">/resetConfig</td><td style="text-align:center;">GET</td><td style="text-align:center;">Clears the current config in memory and RAM</td></tr><tr><td style="text-align:center;">/getStoredConfig</td><td style="text-align:center;">GET</td><td style="text-align:center;">Returns a <em>JSON</em> object of the devices current config.</td></tr><tr><td style="text-align:center;">/setTxPower</td><td style="text-align:center;">POST</td><td style="text-align:center;">Sets the Transmission Power of the ESPs</td></tr><tr><td style="text-align:center;">/setDevice</td><td style="text-align:center;">POST</td><td style="text-align:center;">Sets the <code>OTA</code> and <code>mDNS</code> settings</td></tr><tr><td style="text-align:center;">/setCamera</td><td style="text-align:center;">POST</td><td style="text-align:center;">Sets all of the camera settings</td></tr><tr><td style="text-align:center;">/wifi</td><td style="text-align:center;">POST</td><td style="text-align:center;">Adds a new wifi network, or writes over an existing one</td></tr><tr><td style="text-align:center;">/wifi</td><td style="text-align:center;">DELETE</td><td style="text-align:center;">Deletes a wifi network <code>**</code></td></tr></tbody></table><div class="info custom-block"><p class="custom-block-title">Note</p><p><code>/wifi</code> uses the <code>POST</code> method to add a new wifi network, and the <code>DELETE</code> method to delete a wifi network.</p></div><h3 id="params" tabindex="-1">Params <a class="header-anchor" href="#params" aria-label="Permalink to &quot;Params&quot;"></a></h3><p>The REST API has the following params:</p><div class="danger custom-block"><p class="custom-block-title">Feature not a bug</p><p>All params for a given URL are required, even if you are not changing that params value.</p><p>If you do not supply a param, that param will be set to default settings.</p></div><p>URL params are passed in the URL as a query string, using the following format:</p><p><code>http://&lt;device_name&gt;.local:81/control/builtin/command/&lt;endpoint&gt;?&lt;param&gt;=&lt;value&gt;&amp;&lt;param&gt;=&lt;value&gt;</code></p><h4 id="wifi" tabindex="-1">/wifi <a class="header-anchor" href="#wifi" aria-label="Permalink to &quot;/wifi&quot;"></a></h4><div class="info custom-block"><p class="custom-block-title">Note</p><p>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.</p></div><table><thead><tr><th style="text-align:center;">Param</th><th style="text-align:center;">Description</th></tr></thead><tbody><tr><td style="text-align:center;"><code>ssid</code></td><td style="text-align:center;">The ssid of the network.</td></tr><tr><td style="text-align:center;"><code>password</code></td><td style="text-align:center;">The password of the network.</td></tr><tr><td style="text-align:center;"><code>networkName</code></td><td style="text-align:center;">The unique name (given by you) to refer to that network in memory.</td></tr><tr><td style="text-align:center;"><code>channel</code></td><td style="text-align:center;">The channel for the wifi network to broadcast on <br> only <code>1 - 14</code> are allowed.</td></tr><tr><td style="text-align:center;"><code>power</code></td><td style="text-align:center;">The Transmittion power of the ESP for that network config.</td></tr><tr><td style="text-align:center;"><code>adhoc</code></td><td style="text-align:center;">Whether to enable AP mode or not.</td></tr></tbody></table><div class="info custom-block"><p class="custom-block-title">Note - Transmission Power</p><p>You must follow the following format for the <code>power</code> param:</p><p>Using the following enum, you pass the <em>number</em> to the right of the <code>=</code> sign that corresponds with the power in <code>dBm</code> that you wish to use.</p><div class="language-cpp line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">cpp</span><pre class="shiki material-theme-palenight"><code><span class="line"><span style="color:#F78C6C;">typedef</span><span style="color:#BABED8;"> </span><span style="color:#C792EA;">enum</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">{</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_19_5dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">78</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 19.5dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_19dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">76</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 19dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_18_5dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">74</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 18.5dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_17dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">68</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 17dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_15dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">60</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 15dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_13dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">52</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 13dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_11dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">44</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 11dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_8_5dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">34</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 8.5dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_7dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">28</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 7dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_5dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">20</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 5dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_2dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">8</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 2dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_MINUS_1dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">-</span><span style="color:#F78C6C;">4</span><span style="color:#676E95;font-style:italic;">// -1dBm</span></span>
<span class="line"><span style="color:#89DDFF;">}</span><span style="color:#F07178;"> </span><span style="color:#FFCB6B;">wifi_power_t</span><span style="color:#89DDFF;">;</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br><span class="line-number">6</span><br><span class="line-number">7</span><br><span class="line-number">8</span><br><span class="line-number">9</span><br><span class="line-number">10</span><br><span class="line-number">11</span><br><span class="line-number">12</span><br><span class="line-number">13</span><br><span class="line-number">14</span><br></div></div></div><h4 id="setdevice" tabindex="-1">/setDevice <a class="header-anchor" href="#setdevice" aria-label="Permalink to &quot;/setDevice&quot;"></a></h4><table><thead><tr><th style="text-align:center;">Param</th><th style="text-align:center;">Description</th></tr></thead><tbody><tr><td style="text-align:center;"><code>hostname</code></td><td style="text-align:center;">The hostname for the ESP <br> used by <code>OTA</code> and <code>mDNS</code>.</td></tr><tr><td style="text-align:center;"><code>service</code></td><td style="text-align:center;">The service to look for when scanning <code>mDNS</code> devices on the network <br> this should be set to <code>openiristracker</code> in order to look for <code>EyeTrackVR</code> devices</td></tr><tr><td style="text-align:center;"><code>ota_password</code></td><td style="text-align:center;">The password for the <code>OTA</code> service.</td></tr><tr><td style="text-align:center;"><code>ota_port</code></td><td style="text-align:center;">The port for the <code>OTA</code> service.</td></tr><tr><td style="text-align:center;"><code>firmware_name</code></td><td style="text-align:center;">The name of the binary file for <code>OTA</code> <br> depricated and will be removed</td></tr></tbody></table><h4 id="settxpower" tabindex="-1">/setTxPower <a class="header-anchor" href="#settxpower" aria-label="Permalink to &quot;/setTxPower&quot;"></a></h4><div class="info custom-block"><p class="custom-block-title">Note</p><p>You must follow the following format for the <code>txPower</code> param:</p><p>Using the following enum, you pass the <em>number</em> to the right of the <code>=</code> sign.</p><div class="language-cpp line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">cpp</span><pre class="shiki material-theme-palenight"><code><span class="line"><span style="color:#F78C6C;">typedef</span><span style="color:#BABED8;"> </span><span style="color:#C792EA;">enum</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">{</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_19_5dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">78</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 19.5dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_19dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">76</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 19dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_18_5dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">74</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 18.5dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_17dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">68</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 17dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_15dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">60</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 15dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_13dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">52</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 13dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_11dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">44</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 11dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_8_5dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">34</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 8.5dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_7dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">28</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 7dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_5dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">20</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 5dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_2dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#F78C6C;">8</span><span style="color:#89DDFF;">,</span><span style="color:#676E95;font-style:italic;">// 2dBm</span></span>
<span class="line"><span style="color:#F07178;"> </span><span style="color:#BABED8;">WIFI_POWER_MINUS_1dBm</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">-</span><span style="color:#F78C6C;">4</span><span style="color:#676E95;font-style:italic;">// -1dBm</span></span>
<span class="line"><span style="color:#89DDFF;">}</span><span style="color:#F07178;"> </span><span style="color:#FFCB6B;">wifi_power_t</span><span style="color:#89DDFF;">;</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br><span class="line-number">6</span><br><span class="line-number">7</span><br><span class="line-number">8</span><br><span class="line-number">9</span><br><span class="line-number">10</span><br><span class="line-number">11</span><br><span class="line-number">12</span><br><span class="line-number">13</span><br><span class="line-number">14</span><br></div></div></div><table><thead><tr><th style="text-align:center;">Param</th><th style="text-align:center;">Description</th></tr></thead><tbody><tr><td style="text-align:center;"><code>txPower</code></td><td style="text-align:center;">The power level to set.</td></tr></tbody></table><h3 id="camera-params" tabindex="-1">Camera Params <a class="header-anchor" href="#camera-params" aria-label="Permalink to &quot;Camera Params&quot;"></a></h3><table><thead><tr><th style="text-align:center;">Param</th><th style="text-align:center;">Description</th><th style="text-align:center;">Value Effect</th></tr></thead><tbody><tr><td style="text-align:center;"><code>vflip</code></td><td style="text-align:center;">Whether to flip the frames vertically.</td><td style="text-align:center;">0 or 1</td></tr><tr><td style="text-align:center;"><code>framesize</code></td><td style="text-align:center;">A value between 0-7 indicating the frame resolution.</td><td style="text-align:center;">Larger number - higher resolution.</td></tr><tr><td style="text-align:center;"><code>hflip</code></td><td style="text-align:center;">Whether to flip the frames horizontally.</td><td style="text-align:center;">0 or 1</td></tr><tr><td style="text-align:center;"><code>quality</code></td><td style="text-align:center;">The JPEG quality level: 1-63?</td><td style="text-align:center;"><strong>Smaller</strong> number = higher quality, more latency and less fps</td></tr><tr><td style="text-align:center;"><code>brightness</code></td><td style="text-align:center;">The <code>agc_gain</code> of the camera.</td><td style="text-align:center;">Larger number = more bright.</td></tr></tbody></table>`,33)]))}const m=t(l,[["render",o]]);export{h as __pageData,m as default};