search

Cosmic-Chatter / Exhibitera

Free and open-source software for building and controlling museum exhibits.
MIT License
2 stars 1 forks source link

API Documentation Question #20

Open alexaverill opened 2 weeks ago

alexaverill commented 2 weeks ago

@forceflow1049 I was working through some of the API documentation and was wondering if you would be able to clarify the helperAddress under the Ping section on this page: https://exhibitera.org/api/

It looks like its pointing to the default port that the hub is using, so if it is just a mapping to the hub is it really a necessary field in the request from a client?

forceflow1049 commented 2 weeks ago

Hi @alexaverill, that's a good question. The answer has two parts. First, helperAddress gives the address of the Exhibitera Apps server, not Hub. ExApps runs a server to communicate with the browser instance, and that's the IP/port given. It's named the way for a legacy reason—what is today the Exhibitera Apps binary used to be called System Helper.

Now, you might still wonder why it is necessary, since, as you point out, Hub will know the addresses of its clients. The subtlety is that the IP address of the Ex Apps server (e.g., the helper) might not be the same as the IP address of the browser instance running the actual JavaScript app.

This might seem like a crazy edge case, but it's the situation when Exhibitera is used with a mobile device, most commonly an iPad. To run, say, Voting Kiosk on an iPad, you have to run Ex Apps on another PC and then point the iPad at that server. This is needed because Ex Apps (on the PC) stores the various media files needed by most apps.

A concrete example:

In this case, sendPing() will be received from the iPad (with a random IP), but if Hub wants to ask the app for a list of uploaded media, it needs the address of the helper PC (where Apps is running and the media is stored). Thus, the helperAddress field in sendPing() will contain 192.168.1.201:8000 (which Hub doesn't necessarily know about yet).

I'm sure this all sounds pointlessly complicated, which is probably fair. But it arises out of two facts surrounding the original creation of Exhibitera:

  1. Exhibitera should support tablets, since they are widely used in museums.
  2. I didn't want to write/maintain iOS/Android apps.

In theory, we could use something like Buildozer to build the Python app for both iOS/Android (and I've experimented with it before on other projects). But maintaining something in the app stores is beyond my level of commitment right now. And thus we are left with helperAddress ;)

alexaverill commented 2 weeks ago

Thanks for the explanation, that makes sense with the additional context, and honestly is an easier solution then trying to manage native apps for ios/android. It might be worth adding some of that context (or even just a link to your comment here) to the API documentation,

forceflow1049 commented 1 week ago

That's a good observation—the API docs need a tremendous amount of work...