shawn/op-pedal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation for new debuggnig procedure and for Vite proxying of /var/config.json

Browse Source
This commit is contained in:
Robin E.R. Davies
2026-06-04 08:26:29 -04:00
parent 2156ca087f
commit dbf1acb0b2
2 changed files with 76 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Debugging.md
+76 -30
View File
@@ -2,17 +2,18 @@
PipPedal consists of the following components:
* A web application built using vite/React, found in the `vite` subdirectory.
* A web application built using vite/React, found in the `vite` project directory. The web application is built using the Vite build system as static content.
* `pipedald`
A web server, written in C++, serving a web socket, and pre-built HTML components from the React app.
All audio services are provided by the pipedald process.
A web server, written in C++, serving a web socket, which serves both static content built by the
Vite build system, and dynamic content generated at runtime by the C++ code. The pipedald process also manages the audio services, and provides a web socket interface for the web application to control the audio services, and to get status information about the audio services.
* `pipedaladmind`:
A service to execute operations that require root credentials on behalf of pipedald. (e.g. shutdown, reboot,
and pushing configuration changes).
and pushing configuration changes that require root credentials -- currently, configuration files for the
Wi-Fi hotspot which contain the Wi-Fi hotspot password).
* `pipedalconfig`:
@@ -29,24 +30,24 @@ You must stop the pipedald service before launching a debug instance of pipedald
or
pipedalconfig --stop #Stops the Jack service as well.
pipedalconfig --stop
Although not strictly necessary, you should probably add your login account to the pipedal_d group.
which also stops the pipedaladmind service.
You need to add your login account to the pipedal_d group.
sudo usermod -a -G pipedal_d *youruserid*
This will allow you to run `pipedald` under the debugger of your choice using the
same /etc/pipedal and /var/pipedal directories as an instance of `pipedal` running
under systemd. Note that when running under systemd, `pipedald` runs under an unprivileged
`pipedal_d` service account, and relies it's group (also `pipedal_d`) in order to access its
data files, and to communicate with the `pipedaladmin` service, which does run with root
privileges when `pipedald` needs to perform operations that do required root privileges (e.g. shutdown/reboot and starting and stopping WiFi services).
`pipedal_d` service account, and relies on its group (also `pipedal_d`) in order to access its
data files, and to communicate with the privileged `pipedaladmin` service (which also requires membership in
the `pipedal_d` group). The `pipedaladmin` service runs under with `root` credentials in order to perform
operations that require root privileges (e.g. shutdown/reboot and updating the password for the Wi-Fi hotspot
connection).
For what it's worth, `pipedaladmin` is virtually un-debuggable, because it does require root privileges to run.
If you really _must_ debug pipedaladmin, you can fire up a sudo instance of Visual Studio Code
and attach to the running daemon process. But running program as large as VS Code with root privileges
is a dangerous process, that VS Code firmly (and rightfully) complains about. And configuring
VSCode to run with root privileges as a painful process. Avoid if you can.
`pipedaladmin` is difficult to debug. The best way to do it is to start the service, and attach to the process in which it runs using the VSCode debugger. (Watch out for the prompt for root access that VSCode excentricly sends to the terminal window).
The pipedald service will run with or without the pipedaladmind service, but some operations (shutdown, reboot,
audio and Wi-Fi configuration changes) may fail if the pipedaladmind service is not running. Pipedal communicates
@@ -55,7 +56,7 @@ added your own account to the `pipedal_d` group, debug instances of `pipedald` w
In production, the pipedald web server serves the PiPedal web socket, as well as static HTML from the built
vite/React components. But while debugging, it is much more convenient to use the Vite debug server for
React sources, and configure pipedald to serve only the websocket.
React sources, and run a debug instance of `pipedald` to serve dyanmic content, and service websocket connections.
Note that a debug instance of `pipedald` cannot bind to port 80, since that requires either root privileges or
access to port 80 via `authd`. So you will have to configure the debug instance of `pipedald`'s web server to
@@ -68,38 +69,83 @@ you are debugging. However, when using the vite/react debug server, the PiPedal
use the pipedald web server on port 8080 to provide dynamic content (e.g. the web socket connect, and various
pieces of dynamic content served out of the `http://localhost:8080/var` URL and children thereof.
See the `sample_vscode_launch.json` file in the root project directory for an example of how to configure the VSCode
debugger to launch a debug instance of `pipedald'. (Or just copy the entire file to `.vscode/launch.json`). If you are using another debugger, the invocation you will need for pipedald is:
pipedald /etc/pipedal/config /etc/pipedal/react -port 0.0.0.0:8080
which runs pipedald with the same configuration and react web app sources as the systemd instance of pipedald, but with the web server bound to port 8080 instead of port 80. Earlier debug procedures pointed the two supplied directories to locations that provided debug configurations and content. But it has subsequently proven easier just to ensure use the same configuration files and data as a systemd instance of `pipedald` would use. You will need to ensure that the systemd configuration directories have been properly provisioned with the necessary configuration files and data first. You can do that either by running `./install.sh` after a successful builde, or by installing a recent debian package for PiPedal downloaded from the Github releases page of https://githumb.com/rerdavies/pipedal .
You may find it convenient to reconfigure the systemd instance of `pipedald` to bind to port 8080 as well.
That will allow the vite/react debug server to point clients to either a debug instance or the systemd instance of `pipedald`
depending, depending on which instance of pipedald is currently running. Run the following command to
depending, on which instance of pipedald is currently running. Run the following command to
make the systemd instance of `pipedald` bind to port 8080 instead of port 80:
pipedalconfig --install --port 8080
(which will also restart the `pipedald` service).
To start the web app debug server, from a shell, `cd` to the `./vite` directory, and run `npm run dev`. The
To start the Vite debug server, from a shell, `cd` to the `./vite` directory, and run `npm run dev` (or './debug.sh' which does the same thing.
Vite debug server will automatically detect any changes to web app sources, and rebuild them automatically (no build step required). Note that the `pipedald` service must be running in order for the web app to function properly, either
as a the `pipedald` service, or by running `pipedald` in a debugger.
Actual debugging is performed using the Chrome debugger (which is remarkably well integrated with Vite/React).
Actual debugging of the web client is performed using the Chrome debugger (which is remarkably well integrated with Vite/React).
You won't actually see changes to the version of the systemd version of the static web app until you
do a full _Release_ or _RelWithDebInfo_ build of PiPedal, followed by running `./install.sh` which pushes
the built react app in the location where the systemd version of `pipedald` serves static web content.
By default, the debug React app will attempt to contact the pipedald server on ws:*:8080 -- the address on which
the debug version of pipedald listens on. This can be reconfigured
in the file `react/src/public/var/config.json` if desired. If you connect to the the pipedald server port (port 80), pipedald intercepts requests for `http://./var/config.json` and points the react app at itself, so the file has no effect when running in production.
However, you can refresh the Vite-generated content by running:
The React app will display the message "Error: Failed to connect to the server", until you start the pipedald websocket server in the VSCode debugger. However, it's quite reasonable to point the react debug app at a systemd instance of the pipedald server instead, if you don't intend to debug C++ code.
```
cd ./vite
./build.sh # Full build of the react app.
./install.sh # Copy the built react app to the directory
# from which the systemd version of pipedal serves static content.
```
react/public/var/config.json:
{
...
# (PiPedald's port number. 80 for the production service, 8080 (by default) for
# pipedal running under a debugger.
"socket_server_port": 8080,
"socket_server_address": "*",
...
By default, the debug React app served by the Vite debug server will attempt to contact the pipedald server
on ws:*:8080 -- the address on which the debug version of pipedald listens on. This can be reconfigured
in the file `vite/vite.config.ts` if desired. Locate and edit the two URLS given in this section of the file:
vite/vite.config.ts:
```
...
server: {
proxy: {
'/resources': {
target: 'http://localhost:8080',
changeOrigin: false,
},
'^/var/(?!config\\.json$).*': {
target: 'http://localhost:8080',
changeOrigin: false,
},
}
}
...
```
The Vite debug server proxies requests to `http:/localhost:5173/var/*` and `http:/localhost:5173/resources/*` to the pipedald server on port 8080. The critical request from the web client is actually `http://localhost:5173/var/config.json`, the results of which contain, among other things, the address and port number of the `pipedald` web server. Once `config.json` has been downloaded, the client has the address it needs to make subsequent requests for non-static content and web socket connections directly to the `pipedald` web server instead of the Vite debug server.
The React app will display the message "Error: Failed to connect to the server", until you start the pipedald web server server in the VSCode debugger. However, it's quite reasonable to point the react debug app at a systemd instance of the pipedald server instead, if you don't intend to debug C++ code.
vite/vite.config.ts:
```
...
server: {
proxy: {
'/resources': {
target: 'http://localhost:80',
changeOrigin: false,
},
'^/var/(?!config\\.json$).*': {
target: 'http://localhost:80',
changeOrigin: false,
},
}
}
...
```
The original development for this app was done with Visual Studio Code. And it's probably easiest to go with the flow when building
vite/public/var/config.json
-12
View File
@@ -1,12 +0,0 @@
{
"socket_server_port": 8080,
"socket_server_address": "*",
"debug": true,
"max_upload_size": 536870912,
"fakeAndroid": false,
"ui_plugins": [],
"enable_auto_update": true,
"has_wifi_device": false,
"tone3000_A2_models": true,
"end": true
}