Docs improvements,

docs/Architecture.md

@@ -0,0 +1,53 @@
+### PiPedal Architecture
+
+The PiPedal client is a web application written in React Framework, using Typescript. The bulk of the application is static content
+compiled from TypeScript sources, using React Fraework tools. The static content is fetched from a web server hosted by the  `pipedald` service. Once loaded, the web application
+opens a web socket connection to the `pipedald` server. Dynamic content is fetched over the web socket. The web client controls the server application using asynchronous json messages that are exchanged over the web socket. Changes to the state of the server application are propagated to all connected web clients via events that are fired by the server application over the web socket. Changes to the UI are (for the most part) implemented by binding state in the  client-side PiPedalModel with state data in the React Framework view model.
+
+The PiPedal client is generated by compiling Typescript source to a static web application consisting of HTML and Javascript 
+using React Framework tools.
+
+The PiPedal server is written in C++. The server relies on an additional service, `pipedaladmind`, which provides
+privileged operations (e.g. shutdown, reboot, and configuration changes) for use by the main `pipedald` service
+which runs on a service account without privileges.
+
+See figure 1 for a diagram of the high-level architecture of PiPedal.
+
+![](img/Architecture.png)
+
+Fig 1. PiPedal Architecture.
+
+HTML connections to the server are made over port 80 in production, or port 8080 when debugging.
+
+When debugging React code, an instance of the React development servier must be started. The development server serves static content on port 3000. To 
+start the development server `cd` to the react directory, and run `./start`.
+Figure 2 shows the architecture of PiPedal when running with the React debug server.
+
+![](img/DebugArchitecture.png)
+
+Fig 2. PiPedal architecture when using the React development server.
+
+To debug React code, connect to the development server, on port 3000, with Chrome. To access the Chrome debugger, press F12. You should be able to browse the react source files from within the Chrome debugger. Load the typescript source file in the Chrome debugger. Once you have done that, you should be able to debug the Typescript code directly. Chrome will automaticallyt detect that it is connected to a React debug server, and will automatically download symbol and map files from the React development server.
+
+When using the React development server, the web client can be configured to make web socket connections to either a debug version of the server, with a web server at port 8080, or a production server, with a web server at port 80. When running with the React development server, edit 
+
+`react/public/var/config.json:`
+```
+{
+    "socket_server_port": 8080,
+    "socket_server_address": "*",
+    "debug": true,
+    "max_upload_size": 1048576,
+    "fakeAndroid": false,
+    "ui_plugins": []
+}
+```
+
+The `debug` value determines whether the web application will disable background context menus. Enabling context menus allows you to select the 'Inspect' menu item, which is useful when debuging HTML content.
+
+The `fakeAndroid` setting determines whether the web application will use touch-interface interactions instead of mouse-interface interactions. There are a number of subtle adaptations the web app makes to accomodate touch interfaces.
+
+Note that, when connecting directly to the pipedald web server on port 80, or port 8080, the web server intercepts all requests to documents in the `var` directory, including the `var/config.json` file, and instead returns data that reflects the configuration of the pipedald service. The contents of the `public/var` directory will be completely ignored. The `debug` setting will be true if the pipedald service is a Debug build, and will be false if the pipedald service is a Release build. The `fakeAndroid` setting will always be false.
+
+-----
+[<< How to Debug PiPedal](Debugging.md) | [Up](Documentation.md)

docs/BuildingPiPedalFromSource.md

@@ -1,6 +1,11 @@
+---
+page_icon: img/Compiling.jpg
+---
 ## Building PiPedal From Source
 
-PiPedal has only been tested on Raspbian, and Ubuntu, but should run with little or no modification on most Linux distributions. Pull requests to correct problems with building PiPedal on other versions of Linux are welcome. 
+{% include pageIcon.html %}
+
+PiPedal has only been tested on Raspberry Pi OS, and Ubuntu, but should run with little or no modification on most Linux distributions. Pull requests to correct problems with building PiPedal on other versions of Linux are welcome. 
 
 To build PiPedal, a Raspberry Pi 4B, with at least 4GB of memory is required (8GB recommended). You can build PiPedal from the command-line using CMake; but the project was originally build using
 Microsoft Visual Studio Code. If you use VSCode, you will almost definitely need to hav 8GB of RAM.

docs/Configuring.md

@@ -98,7 +98,7 @@ Wi-Fi Direct connections differ in a couple of ways from normal Wi-Fi connection
 - Wi-Fi Direct connections are backward compatible with Wi-Fi access points if you are using an older device. Look for the DIRECT-xx-YourDeviceName access point.
   But if you use a legacy connection, the connecting device cannot have a simultanous Wi-Fi router connection.
 
-If you use the PiPedal Android app (coming VERY soon - being pushed up for distribution now), the Android app will manage discovery and setting up of Wi-Fi direct connections to your Raspberry Pi device automatically.
+If you use the PiPedal Android app, the Android app will manage discovery and setting up of Wi-Fi direct connections to your Raspberry Pi device automatically; but you must complete the initial configuration using a direct web connection first.
      
 PC support for Wi-Fi Direct connections varies dramatically. Modern PCs support Wi-Fi Direct; but you may find it easier to communicate with PiPedal via your Wi-Fi router. Configure PiPedal to use a Wi-Fi connection as well as a Wi-Fi Direct access point (or connect an ethernet cable to your Raspberry Pi). Just remember to configure your phone to use a Wi-Fi Diret connection _before_ you take PiPedal out on a gig, because you won't have a Wi-Fi router then.
 
@@ -110,7 +110,7 @@ You _must_ select the correct country when setting up your Wi-Fi Direct connecti
 
 For best results, you should select Wi-Fi channel 1, 6 or 11 (referred to as the "Wi-Fi Direct Social Channels"). Doing so reduces the time it takes for other devices to discover the Raspberry Pi. While it is possible to use 5Ghz channels for Wi-Fi Direct, it may take some time for connecting devices to find your PiPedal device.
 
-Support for Apple/IOS devices: a client for Apple/IoS devices is in long-term development plans; but I don't own any Apple device on which to do development and testing. If you'd like to see an Apple/IOS client, your sponsorship would help. (The client performs discovery and set up of Wi-Fi direct connections, and relies on the Web interface after that. Not difficult. Just expensive.
+Support for Apple/IOS devices: a client for Apple/IoS devices is in long-term development plans; but I don't own any Apple device on which to do development and testing. If you'd like to see an Apple/IOS client, your sponsorship would help. (The client performs automatic discovery and set up of Wi-Fi direct connections, and relies on the Web interface after that. Not difficult to implement. Just expensive.)
 
 --------
 [<< Installing PiPedal](Installing.md)  | [Up](Documentation.md) | | [Choosing a USB Audio Adapter >>](ChoosingAUsbAudioAdapter.md)

docs/Debugging.md

@@ -1,4 +1,4 @@
-### How to Debug PiPedal.
+### How to Debug PiPedal
 
 PipPedal consists of the following components:
 
@@ -41,7 +41,7 @@ In production, the pipedald web server serves the PiPedal web socket, as well as
 react components. But while debugging, it is much more convenient to use the React debug server for 
 React sources, and configure pipedald to serve only the websocket. 
 
-To start the React debug server, from a shell, cd to the react directory, and run "./start". The react debug 
+To start the React debug server, from a shell, `cd` to the react directory, and run `./start`. The react debug 
 server will detect any changes to React sources, and rebuild them automatically (no build step required). 
 Actual debugging is performed using the Chrome debugger (which is remarkably well integrated with React).
 
@@ -54,10 +54,9 @@ files:
 
 followed by `sudo sysctl -p`. Note that VS Code and the React framework both need this change.
 
-By default, the React app will attempt to contact the pipedald server on ws:*:8080 -- the address on which
+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, pipedald intercepts requests for this file and 
-points the react app at itself, so the file has no effect when running in production. 
+in the file `react/src/public/var/config.json` if desired. If you connect to the the pipedald server port, pipedald intercepts requests for this file and  points the react app at itself, so the file has no effect when running in production. 
 
 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. It's quite reasonable to point the react debug app at a production instance of the pipedald server instead.
 
@@ -70,8 +69,7 @@ The React app will display the message "Error: Failed to connect to the server",
     }
 
 Setting socket_server_address to "*" configures the web app to reconnect using the host address the browser
-request used to connect to the web app. (e.g. 127.0.0.1, or pipedal.local, &c). If you choose to provide an explicit address,
-remember that it is to that address that the web browser will connect.
+request used to connect to the web app. (e.g. 127.0.0.1, pipedal.local, the address of the Wi-Fi Direct connection &c). If you choose to provide an explicit address, remember that it is to that address that the web browser will connect.
 
 The original development for this app was done with Visual Studio Code. Open the root project directory in
 Visual Studio Code, and it will detect the CMake build files, and configure itself appropriately. Wait for 
@@ -82,13 +80,16 @@ bottom of the Visual Studio Code window. Set the build variant to debug. Set the
 Click on the Build button to build the app. Click on the Debug button to launch a debugger.
 
 To get the debugger to launch and run correctly, you will need to set command-line parameters for pipedald. 
-Command-line arguments can be set in the file .vscode/settings.json: 
+Command-line arguments can be set in the file `.vscode/launch.json`: 
 
     {
         ...
         "cmake.debugConfig": {
             "args": [
-            "<projectdirectory>/debugConfig","<projectdirectory>/build/react/src/build",  "-port", "0.0.0.0:8080"
+                "<projectdirectory>/debugConfig",
+                "<projectdirectory>/build/react/src/build",
+                "-port",
+                "0.0.0.0:8080"
             ],
 
         ...
@@ -99,19 +100,14 @@ where `<projectdirectory>` is the root directory of the pipedal project.
 The default debug configuration for pipedal is configured to use /var/pipedal for storing working data files, 
 which allows it to share configuration with a production instance of pipedal. Be warned that the permissioning 
 for this folder is intricate. If you plan to use the data from a production server, get the production server 
-installed first so the permissions are set correctly. If you install a production instance later, remove the 
-entire directory before doing so, to ensure that none of the files in that directory are permissioned 
-incorrectly. 
+installed first so the permissions are set correctly.
+If you install a production instance later, remove the entire directory before doing so, to ensure that none 
+of the files in that directory are permissioned incorrectly. 
 
 You will need to add your userid to the pipedal_d group if you plan to share the /var/pipedal directory. 
      
      sudo usermod -a -G pipedal_d *youruserid*
 
-You will need to add your userid to the bluetooth group if you plan to debug Bluetooth onboarding code.
-
-    sudo usermod -a -G bluetooth *youruserid*
-
-
 Or you can avoid all of this, by configuring the debug instance to use a data folder in your home directory. Edit 
 `debugConfig/config.json`:
 
@@ -122,4 +118,4 @@ Or you can avoid all of this, by configuring the debug instance to use a data fo
     }
 
 -----
-[<< The Build System](TheBuildSystem.md) | [Up](Documentation.md)
+[<< The Build System](TheBuildSystem.md) | [Up](Documentation.md)  | [PiPedal Architecture >>](Architecture.md)

docs/Documentation.md

@@ -22,4 +22,7 @@
 #### [The Build Systems](TheBuildSystem.md)
 #### [How to Debug PiPedal](Debugging.md)
 
+ 
+
+#### [PiPedal Architecture](Architecture.md)
 

docs/Installing.md

@@ -1,18 +1,19 @@
 ---
-page_icon: img/Install3.jpg
+page_icon: img/Install4.jpg
 ---
 
+{% include pageIcon.html %}
+
 
 ## Installing PiPedal
 
-{% include pageIcon.html %}
 
 ### Install for Ubuntu <br/>or Raspberry Pi OS (64-bit)
 
 
 Download the most recent Debian (.deb) package for your platform:
 
-- [Raspberry Pi OS (64-bit) v1.0.15](https://github.com/rerdavies/pipedal/releases/download/v1.0.15/pipedal_1.0.15_arm64.deb)
+- [Ubuntu/Raspberry Pi OS (64-bit) v1.0.15](https://github.com/rerdavies/pipedal/releases/download/v1.0.15/pipedal_1.0.15_arm64.deb)
 
 Install the package by running 
 

docs/SystemRequirements.md

@@ -1,5 +1,5 @@
 ---
-page_icon: img/Requirements.jpg
+page_icon: img/Requirements2.jpg
 ---
 ## System Requirements
 

docs/TheBuildSystem.md

@@ -1,17 +1,20 @@
 ### The Build System
 
 PiPedal was developed using Visual Studio Code. Using Visual Studio Code to build PiPedal is recommended, but not required. The PiPedal
-build procedure uses CMake project files, which are supported by most major Integrated Development Environments.
+build procedure uses CMake project files, which are supported by most major Integrated Development Environments. You will probably 
+need at least 8Gb of memory to use Visual Studio Code. You can probably build PiPedal from the command-line using 2Gb. If you have 
+4Gb of memory, you may be able to build using Visual Studio Code remote compilation and remote debugging. If you try this, we would 
+be grateful if you could share your experience on the [PiPedal discussion pages](https://github.com/rerdavies/pipedal/discussions).
      
 If you open the PiPedal project as a folder in VS Code, Code will 
 detect the CMake configuration files, and automatically configure the project to use available toolchains. Once the VS Code CMake plugin (written by Microsoft,
-available through the plugins store) has configured itself, build commands and configuration options should appear on the bottom line of Visual Studio 
-Code. 
+available through the Code plugins store) has configured itself, build commands and configuration options should appear on the bottom status line of Visual Studio Code. 
 
 If you are not using Visual Studio Code, you can configure, build and install PiPedal using CMake build tools. For your convenience,
 the following shell scripts have been provided in the root of the project.
 
-    ./init    # Configure the CMake build (required if you change one of the CMakeList.txt files)
+    ./init    # Configure the CMake build (first time, or if you 
+              # have changed one of the CMakeList.txt files)
 
     ./mk   # Build all targets.
     

docs/UsingLv2Plugins.md

@@ -1,10 +1,14 @@
+---
+page_icon: img/Plugins.jpg
+---
 ## Using LV2 PLugins
 
+{% include pageIcon.html %}
 PiPedal uses LV2 audio plugins. There are literally thousands of freely available high-quality LV2 plugins that are suitable for use as guitar effects.
 
-By default, PiPedal comes with a few plugins from the ToobAmp plugin collection. You will probably want to install more.
+By default, PiPedal comes with a basic set of plugins from the ToobAmp plugin collection. You will probably want to install more.
 
-Here is a brief list of particularly recommend plugin collections.
+Here is a brief list of particularly recommended plugin collections.
 
 | Collection                      | To Install                            | Description      |
 |---------------------------------|---------------------------------------|------------------|

docs/WhichLv2PluginsAreSupported.md

@@ -11,7 +11,9 @@ following conditions:
 
 If you install new LV2 plugins, you will have to restart the PiPedal web service (or reboot the machine) to get them to show up in the web interface.
 
+```
    sudo pipedalconfig --restart
+```
 
 Although most LV2 plugins provide GUI interfaces, when running on a Linux desktop, the LV2 plugin standard is specifically designed to allow remote control 
 without using the provided desktop GUI interface. And all but a tiny minority of LV2 plugins (most of them analyzers, unfortunately) support this.