refresh doc/env-vars and add doc/devices

merliot · Jan 21, 2025 · 810794d · 810794d
1 parent 72cb380
commit 810794d
Show file tree

Hide file tree

Showing 5 changed files with 112 additions and 49 deletions.
diff --git a/pkg/device/docs/devices.html b/pkg/device/docs/devices.html
@@ -0,0 +1,44 @@
+<h2>DEVICES</h2>
+
+<p>JSON-encoded map of devices in the device tree.  The key is the device ID.  A device is the structure:</p>
+
+<pre class="code-snippet">
+type device struct {
+	Id           string
+	Model        string
+	Name         string
+	Children     []string  // child Ids
+	DeployParams template.HTML
+}
+</pre>
+
+<h4>Example</h4>
+
+<pre class="code-snippet">
+{
+	"qrcode1": {
+		"Id": "qrcode1",
+		"Model": "qrcode",
+		"Name": "QR Code",
+		"Children": null,
+		"DeployParams": "target=wioterminal"
+	},
+	"gps1": {
+		"Id": "gps1",
+		"Model": "gps",
+		"Name": "GPS",
+		"Children": null,
+		"DeployParams": "target=nano-rp2040"
+	},
+	"hub": {
+		"Id": "hub",
+		"Model": "hub",
+		"Name": "Hub",
+		"Children": [
+			"gps1",
+			"qrcode1",
+		],
+		"DeployParams": "target=x86-64\u0026port=8000"
+	}
+}
+</pre>
diff --git a/pkg/device/docs/env-vars.html b/pkg/device/docs/env-vars.html
@@ -1,6 +1,7 @@
 <h2>ENVIRONMENT VARIABLES</h2>
 
-<p>Use environment variables to set hub settings.</p>
+<p>When the hub starts, it will read run-time settings from the environment
+variables listed below.</p>
 
 <p>If running from Docker, use --env or -e:
 
@@ -10,27 +11,17 @@ <h2>ENVIRONMENT VARIABLES</h2>
 
 <pre class="cmd-line">$ DEMO=true go run ./cmd/</pre>
 
-<div class="">
+<div>
 	<h3 id="PORT">PORT</h3>
 	<p>Port on which the hub web server runs. Defaults to 8000.</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="DEVICES">DEVICES</h3>
 
-	<p>JSON-encoded map of devices in the device tree.  The key is the device ID.  A device is the structure:</p>
-
-	<pre class="code-snippet">
-type device struct {
-	Id           string
-	Model        string
-	Name         string
-	Children     []string  // child Ids
-	DeployParams template.HTML
-}
-	</pre>
-
-	<h4>Example</h4>
+	<p>DEVICES can be set to a JSON-encoded map of
+	<a href="/doc/devices">devices</a> in the device tree.  Here's an
+	example of a hub with two devices:</p>
 
 	<pre class="code-snippet">
 {
@@ -63,27 +54,29 @@ <h4>Example</h4>
 
 </div>
 
-<div class="">
-	<h3 id="DEVICES_FILES">DEVICES_FILE</h3>
-	<p>File path for JSON-encoded devices file, defaults to devices.json.
-	See DEVICES above for format of file.  If DEVICES is also given, then
-	DEVICES takes presedence over DEVICES_FILE.</p>
+<div>
+	<h3 id="DEVICES_FILE">DEVICES_FILE</h3>
+	<p>DEVICES_FILE is set to a file path for JSON-encoded <a href="/doc/devices">devices</a> file.
+	If DEVICES is also given, then DEVICES takes presedence over
+	DEVICES_FILE.  If neither DEVICES nor DEVICES_FILE are given, the
+	hub defaults to reading 'devices.json'.</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="USER">USER</h3>
-	<p>Username for authentication.  If non-blank, a new client
-	session will prompt for the user/passwd.  In addition, devices
-	will also use same user/passwd to authenticate to the hub.  The
-	authentication is done using HTTP Basic Authentication.</p>
+	<p>Username for authentication.  If non-blank, a new client session
+	will prompt for the user/passwd.  In addition, devices created from the
+	hub will also use same user/passwd to authenticate when they dial back
+	to the hub.  The authentication is done using
+	<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication">HTTP Basic Authentication.</a></p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="PASSWD">PASSWD</h3>
 	<p>Password for authentication.  Only valid if USER is non-blank</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="WIFI_SSIDS">WIFI_SSIDS</h3>
 
 	<p>Comma-separated list of WiFi SSIDs.  Each SSID in the list has a
@@ -103,55 +96,67 @@ <h3 id="WIFI_SSIDS">WIFI_SSIDS</h3>
 	passphrases are not visible).</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="WIFI_PASSPHRASES">WIFI_PASSPHRASES</h3>
 	<p>Comma-separated list of WiFi passphrases.  This list pairs
 	the passphrases with the SSIDs set in WIFI_SSIDS.</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="DIAL_URLS">DIAL_URLS</h3>
-	<p>Comma-separated URLs for dialing parent hub(s). (TODO not working at
-	the moment).</p>
+	<p>Comma-separated URLs for dialing parent hub(s).  These URLs will be
+	websocket connections in the format:</p>
+
+	<pre class="cmd-line text-wrap">
+ws://&lt;host&gt;:&lt;port&gt;/ws
+	</pre>
+
+	<p>or if using https:</p>
+
+	<pre class="cmd-line text-wrap">
+wss://&lt;host&gt;:&lt;port&gt;/ws
+	</pre>
+
+	<p>where host:port is the address of the parent hub.</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="PING_PERIOD">PING_PERIOD</h3>
 	<p>Client ping period, in seconds.  To keep the websocket connection
 	alive, the client (browser) uses htmx's ws-send to send a ping packet
 	back to the server (hub).  The default is 2.</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="BACKGROUND">BACKGROUND</h3>
 	<p>Background color: LIGHT or DARK.  Default is DARK.</p>
 </div>
 
 <h2>DEBUG ENVIRONMENT VARIABLES</h2>
 
-<div class="">
+<div>
 	<h3 id="LOG_LEVEL">LOG_LEVEL</h3>
 	<p>Set the hub logging level.  The options are "DEBUG", "INFO", "WARN",
 	and "ERROR", in that order.  The default is "INFO", meaning only
 	"INFO", "WARN", and "ERROR" would be logged.  Set to "DEBUG" to catch
 	additional debug info.</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="DEMO">DEMO</h3>
 	<p>Runs the hub in demo mode if set to "true".  In demo mode, all the
 	devices on the hub will run locally on the hub, simulating the devices.
 	Demo mode is handy for demos, but also for device developement and
 	testing.</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="SITE">SITE</h3>
 	<p>Runs the hub in site mode if set to "true".  Implies demo mode.
 	The hub and devices are locked (read-only) in site mode.</p>
 </div>
 
-<div class="">
+<div>
 	<h3 id="DEBUG_KEEP_BUILDS">DEBUG_KEEP_BUILDS</h3>
 	<p>If set to "true", keeps build artifacts for debugging.</p>
 </div>
diff --git a/pkg/device/docs/install.html b/pkg/device/docs/install.html
@@ -8,7 +8,10 @@ <h2>INSTALL GUIDE</h2>
 <p>If you have your own server, you can install your hub locally.  This is the
 more private choice.  The server doesn't have to be a huge system; a raspberry
 Pi is sufficient, as well as a laptop.  If you want to access the hub remotely,
-over the Internet, use <a target="_blank" href="https://tailscale.com">Tailscale</a>.</p>
+over the Internet, use <a target="_blank"
+href="https://tailscale.com">Tailscale</a>.  With Tailscale, your hub and
+devices are local, but you can access them from any device that's in the
+Tailnet, including your phone.</p>
 
 <p>If you don't have a server, you can "rent" one in the cloud to host your
 hub.  This is a less private choice because a third party is now hosting your
@@ -38,6 +41,13 @@ <h3>DOCKER</h3>
 $ sudo docker run -p 8000:8000 -v ./:/app merliot/hub
 </pre>
 
+<p>Add environment <a href="/doc/env-vars">variables</a> using -e option.  For
+example, to set a user/password on the hub:</p>
+
+<pre class="cmd-line text-wrap">
+$ sudo docker run -p 8000:8000 -v ./:/app -e USER=xxx -e PASSWD=yyy merliot/hub
+</pre>
+
 <h3>TAILSCALE</h3>
 
 <p>Use <a target="_blank" href="https://tailscale.com">Tailscale</a> to create
@@ -61,13 +71,14 @@ <h4>Koyeb (FREE)</h4>
 FREE using Koyeb's Free Forever offer.  You have to create an account on Koyeb.
 Click the one-click button below to create a hub instance on Koyeb.</p>
 
-<a href="https://app.koyeb.com/deploy?name=hub&type=docker&image=merliot%2Fhub&instance_type=free&regions=was&ports=8000;http;/">
+<a href="https://app.koyeb.com/deploy?name=hub&type=docker&image=merliot%2Fhub&instance_type=free&regions=was&ports=8000;http;/&env[LOG_LEVEL]=INFO&env[PING_PERIOD]=2&env[BACKGROUND]=&env[DEVICES]=&env[USER]=&env[PASSWD]=&env[WIFI_SSIDS]=&env[WIFI_PASSPHRASES]=">
 	<img class="m-8" src="https://www.koyeb.com/static/images/deploy/button.svg">
 </a>
 
-<p>Follow the prompts to install the hub.  You can add enviroment <a
-	href="/doc/env-vars">variables</a> to configure the hub.  The hub
-address will be something like:</p>
+<p>Follow the prompts to install the hub.  Adjust the enviroment
+<a href="/doc/env-vars">variables</a> as needed.</p>
+
+<p>The hub address will be something like:</p>
 
 <pre class="cmd-line">https://asquare-eloise-merliot-67e2796c.koyeb.app/</pre>
 
@@ -78,13 +89,15 @@ <h4>Digital Ocean ($5/month)</h4>
 <p>Run Merliot Hub on <a href="https://www.digitalocean.com/">Digital Ocean</a>.  It cost $5/month to run the hub.</p>
 
 <ol>
-  <li>Click the "Deploy to web app" button on the project page.</li>
-  <li>Under Service Provider, select "Docker Hub".</li>
-  <li>Repository is "merliot/hub". No tag. No credentials.</li>
+  <li>Click the "Deploy to web app" button on the project page</li>
+  <li>Under Create App, select "Container Image" tab and select "Docker Hub"</li>
+  <li>Enter "merliot/hub" for Repository</li>
+  <li>Enter "latest" for image tag
   <li>Edit the Service Resources:
     <ul>
-      <li>Resource Size and select the $5 VM with 512MB RAM.</li>
-      <li>Edit the Port to 8000.</li>
+      <li>Resource Size and select the $5 VM with 512MB RAM</li>
+      <li>Edit the Port to 8000</li>
+      <li>Edit the environment <a href="/doc/env-vars">variables</a></li>
     </ul>
   </li>
   <li>Create the Resource.</li>

diff --git a/pkg/device/page.go b/pkg/device/page.go
@@ -34,6 +34,7 @@ var docPages = []page{
 	{"", "GUIDES", ""},
 	{"quick-start", "QUICK START", "/doc/quick-start"},
 	{"install", "INSTALL GUIDE", "/doc/install"},
+	{"devices", "DEVICES", "/doc/devices"},
 	{"env-vars", "ENV VARS", "/doc/env-vars"},
 	{"faq", "FAQ", "/doc/faq"},
 

diff --git a/pkg/device/pkt.go b/pkg/device/pkt.go
@@ -11,7 +11,7 @@ const maxLength = 100 // Max length of packet string
 // NoMsg is an empty message type for PacketHandle's
 type NoMsg struct{}
 
-// Packet is the basic container for messages sent between devices.
+// Packet is the basic container for messages sent inner and between devices.
 type Packet struct {
 	// SessionId is the originating session id.  Empty means packet isn't
 	// pinned to any session.