EyeTrackVR-Docs/assets/firmware_guide_rest_api.md.93250538.js
2023-02-12 12:21:33 +00:00

31 lines
21 KiB
JavaScript

import{_ as s,o as e,c as t,h as n}from"./app.2da99dd5.js";const m=JSON.parse('{"title":"REST API","description":"","frontmatter":{},"headers":[{"level":2,"title":"What is it?","slug":"what-is-it","link":"#what-is-it","children":[]},{"level":2,"title":"How to use it","slug":"how-to-use-it","link":"#how-to-use-it","children":[{"level":3,"title":"REST API Client","slug":"rest-api-client","link":"#rest-api-client","children":[]},{"level":3,"title":"Standard","slug":"standard","link":"#standard","children":[]},{"level":3,"title":"Endpoints","slug":"endpoints","link":"#endpoints","children":[]},{"level":3,"title":"Params","slug":"params","link":"#params","children":[]},{"level":3,"title":"Camera Params","slug":"camera-params","link":"#camera-params","children":[]}]}],"relativePath":"firmware_guide/rest_api.md","lastUpdated":1676204369000}'),a={name:"firmware_guide/rest_api.md"},l=n(`<h1 class="text-[#ab5ac7]" id="rest-api" tabindex="-1">REST API <a class="header-anchor" href="#rest-api" aria-hidden="true">#</a></h1><h2 id="what-is-it" tabindex="-1">What is it? <a class="header-anchor" href="#what-is-it" aria-hidden="true">#</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-hidden="true">#</a></h2><h3 id="rest-api-client" tabindex="-1">REST API Client <a class="header-anchor" href="#rest-api-client" aria-hidden="true">#</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-hidden="true">#</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-palenight"><code><span class="line"><span style="color:#A6ACCD;">http://{device_name}.local:81/control/builtin/command/{endpoint}?{param}={value}&amp;{param}={value}</span></span>
<span class="line"><span style="color:#A6ACCD;"></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-hidden="true">#</a></h3><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 wifi 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</td></tr><tr><td style="text-align:center;">/wifi</td><td style="text-align:center;">GET</td><td style="text-align:center;">Returns a <em>JSON</em> object of all of the wifi networks</td></tr></tbody></table><h3 id="params" tabindex="-1">Params <a class="header-anchor" href="#params" aria-hidden="true">#</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-hidden="true">#</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-palenight"><code><span class="line"><span style="color:#F78C6C;">typedef</span><span style="color:#A6ACCD;"> </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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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>
<span class="line"></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-hidden="true">#</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-hidden="true">#</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-palenight"><code><span class="line"><span style="color:#F78C6C;">typedef</span><span style="color:#A6ACCD;"> </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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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:#A6ACCD;">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>
<span class="line"></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-hidden="true">#</a></h3><div class="tip custom-block"><p class="custom-block-title">Coming Soon</p><p>We are currently working on this section of documentation.</p></div>`,31),o=[l];function p(r,c,i,d,y,F){return e(),t("div",null,o)}const u=s(a,[["render",p]]);export{m as __pageData,u as default};