Web API documentation

Here's a quick run-down of what's going on in the web API for our HEG.

The model for my API was to create simple, modular code that could be recycled and reused, or added to very trivially. This is to encourage anybody with some tech savvy to go under the hood and make their own tweaks and additions, or wrap it in bigger third party applications (e.g. React, Chrome apps, other webview or JS apps). We also welcome anybody who wants to contribute modules to the public web API, the rule is it has to be lightweight, vanilla JS/CSS/HTML5, and as cross-platform as possible (minus Edge/IE as they are missing some updates). For using external modules like we demonstrated with ThreeJS, simply include it as a separate file and make the necessary changes to the webDemo.html page to call it, that way it won't interfere with the other modules. The web files are then placed in special C header files that wrap the whole HTML/CSS/JS in a way the ESP32 can flash on and load easily.

The web API is in several files.

HEGwebAPI.js - contains all utilities and is the main file.

And these are customized on top of it for our app:

webDemo.html

webDemoCSS.css

and threeApp.js

Also api.html, where the API javascript file is called but not initialized, this may have advantages for different remote streaming applications.

HEGwebAPI.js contains all of the necessary classes, with optional UI spawning options, to connect to the EventSource from the HEG, create the graph, and create the different feedback options.

The current main classes are:

HEGwebAPI

graphJS

circleJS

videoJS

audioJS

hillJS

as well as the conditional ThreeGlobe class which contains the threeJS demo.

All of the classes that draw something have the same basic layout so it's really easy to figure out how they were coded. We need to maintain a generic syntax for everything to make it super easy to integrate more features in and not confuse other coders. There's more we can do to generalize all of this, I am moving toward something that will be like a game console of sorts - if you've every seen any of those Atari emulators running on an ESP32 - but with web so all of the work is done client-side instead of relying on the ESP32's processor for anything but the data stream.

Below I will take you through setting up a mock session interface via code, this can be accomplished in the console or on a fresh page with the HEGwebAPI.js script included.

var session = new HEGwebAPI("http://192.168.4.1", defaultUI, parentId);

First we must set up a session. This class creates the Event Listener stream and all of the data structures you need to handle that data. It allows you to define whether you want a default UI or not as well as which element to append it to. Leaving the first field blank with "" will create an Event Listener at the file or server location rather than the address defined like above.

var graph = new graphJS(nPoints,color=[255,255,255,1],yscale,res=[1200,800], parentId, graphId, defaultUI);

Now we've created a simple line graph with custom size, color, resolution, and placement with our optional default UI options. You may enter "undefined" to use the default parameters for the graph options, other than the parentId and graphId. You can set defaultUI to false then call graph.createUI(parentId) to append the UI to a separate element than the graph's parent. The resolution will only control the webGL resolution while the actual size of the graph element on the screen is controlled in CSS or HTML.

var circle = new circleJS();

This creates a circle with default parameters on the page, again the window for this is controlled in CSS, and there are default IDs given to every element created so they can be customized easily.

Now we need to set up how the data is handled so that the incoming session data is propagated to the graph and visual classes. We do this by customizing the session.handleScore() function which is automatically called whenever data is received.

session.handleScore = function() {
  this.smaScore(this.ratio);     
  var score = this.smaSlope*0.01;     
  circle.onData(score);     
  this.scoreArr.push(
    this.scoreArr[this.scoreArr.length - 1] + score);
  graph.us = this.us[this.us.length - 1];                     
  g.ratio = this.slowSMA;          
  g.score = this.scoreArr[this.scoreArr.length - 1];     
  g.graphY1.shift();     
  g.graphY1.push(
    this.scoreArr[this.scoreArr.length - 1 - g.xoffset]);     
  g.graphY2.shift();   
  g.graphY2.push(
    this.slowSMAarr[this.slowSMAarr.length - 1 - g.xoffset]);
}

The HEGwebAPI class has a simple moving average-based scoring method that helps emphasize changes in the ratio smoothly. Here, the "this" variable is grabbing stored data in the session class, scoring it, then applying it to the Circle and the Graph array.

That's pretty much it! The HEG responds to POST actions. You can POST most of the single character text commands or you can post "session.host/startHEG" and "session.host/stopHEG" to turn it on and off. If you look at webDemo.html you will see I used this in more interesting ways. There are more UI functions which need to be defined manually, like the x-axis sliders for the graph and the visual layout of your page with containers for everything. You will see that the threeApp.js file is included conditionally if the device detects its online as well, and this demonstrates how easy it is to start adding all kinds of interesting functions onto the app once it's connected online. IoT, baby! Eventually I will be able to integrate these libs onto the chip itself (or you can if you build the firmware without OTA), using the 8MB or 16MB ESP32 options (or future iterations).

One note is if you add

parent.postMessage(this.ratio[this.ratio.length - 1],"*");

to the handleScore() function, you can now post the data through IFrames. This means the whole API can be called to a website and interacted with through another layer of web software if you wish. We are going to demonstrate how this benefits remote session and data collection abilities on our website. I'm also going to demonstrate the web app as a Chrome app, as this allows USB Serial communication.

More coming! We're still refining a few things and adding more generalized tools in but the format is pretty much set, hope anyone interested in the software side finds this useful.